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

package/docs/guides/follow-a-run.md

@@ -0,0 +1,174 @@
+---
+title: "Follow a run"
+description: "Compose a sync client over a transport, subscribe to one run or a whole workspace, acknowledge entries only after applying them, and persist a cursor a restart can resume from."
+sidebar:
+  order: 1
+---
+
+This guide builds a follower: the side that reads. It assumes a host is already
+serving `SyncRpcs`, whether that is [`@smthrs/gateway`](/api/gateway) on
+`POST /sync` and `/sync/ws` or a host of your own.
+
+## Provide the client
+
+`SyncClient.layer` derives an RPC client from the ambient
+`RpcClient.Protocol`, so the composition supplies the protocol and the
+serialization:
+
+```ts
+import * as SyncClient from "@smthrs/sync/SyncClient"
+import * as Layer from "effect/Layer"
+import * as RpcClient from "effect/unstable/rpc/RpcClient"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+import type * as Socket from "effect/unstable/socket/Socket"
+
+export const clientLayer: Layer.Layer<SyncClient.SyncClient, never, Socket.Socket> = SyncClient.layer.pipe(
+  Layer.provide(RpcClient.layerProtocolSocket()),
+  Layer.provide(RpcSerialization.layerJson)
+)
+```
+
+Supply the socket that protocol runs over from your platform. A browser
+follower provides a WebSocket; a Node follower provides
+`@effect/platform-node`'s socket layer; a test provides the in-memory pair from
+[Test a follower](./test-a-follower.md).
+
+To tune the catch-up page size or the frame ceiling the client enforces on
+responses, build the service directly with `SyncClient.makeWith`, which
+validates both options and fails with `invalid_request` when one is not a
+positive safe integer:
+
+```ts
+import { SyncRpcs } from "@smthrs/sync/SyncRpcs"
+import * as Effect from "effect/Effect"
+import * as RpcClient from "effect/unstable/rpc/RpcClient"
+
+const makeClient = Effect.flatMap(
+  RpcClient.make(SyncRpcs),
+  (client) => SyncClient.makeWith({ client, bootstrapLimit: 512 })
+)
+```
+
+## Subscribe
+
+One call runs both phases. The stream starts with durable history and continues
+with live entries:
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import * as Stream from "effect/Stream"
+
+const runId = "build-42" as JournalEvent.RunId
+
+const entries = Effect.gen(function*() {
+  const sync = yield* SyncClient.SyncClient
+  return sync.subscribe({ scope: { _tag: "Run", runId }, cursors: [] })
+})
+```
+
+Pass `{ _tag: "Workspace" }` to follow every run the catalog lists and your
+credential covers. A workspace subscription reconciles its covered run set on
+every round, so a run created after it opened joins it.
+
+## Acknowledge only what you applied
+
+By default only a delivered bookmark advances as an entry is handed to the
+consumer. Supply `apply` to record separately tagged applied progress after
+the callback succeeds:
+
+```ts
+const followed = Effect.gen(function*() {
+  const sync = yield* SyncClient.SyncClient
+  return sync.subscribe({
+    scope: { _tag: "Run", runId },
+    cursors: [],
+    apply: (entry) => Effect.logInfo(`applied ${entry.eventType}@${entry.seq}`)
+  })
+})
+```
+
+A failure in `apply` fails the subscription with that entry unacknowledged, so
+the next subscription delivers it again. Make the callback idempotent:
+redelivery is what a retry looks like here.
+
+## Resume after a restart
+
+`(yield* client.progress).delivered` reports delivery bookmarks.
+`(yield* client.progress).applied` reports successfully applied positions, one
+entry per run, sorted by run id.
+Both maps are in memory. A durable consumer commits its projection and cursor
+together in its application transaction, then seeds a fresh client with that
+durable cursor after restart:
+
+```ts
+const resume = (
+  saved: ReadonlyArray<{ readonly runId: JournalEvent.RunId; readonly afterSeq: JournalEvent.Seq }>,
+  apply: NonNullable<SyncClient.SubscribeOptions["apply"]>
+) =>
+  Effect.gen(function*() {
+    const sync = yield* SyncClient.SyncClient
+    return sync.subscribe({ scope: { _tag: "Workspace" }, cursors: saved, apply })
+  })
+```
+
+The effective start position is the later of your cursor and the matching
+progress map: applied when `apply` is supplied, delivered otherwise. An earlier
+delivery-only subscription cannot skip unapplied history. Independent
+materializations and rebuilds use fresh clients with empty progress maps.
+
+## Present a credential
+
+A connection with no credential reads no non-branch run. Stamp every outgoing
+request with a workspace capability:
+
+```ts
+import * as SyncAuth from "@smthrs/sync/SyncAuth"
+import type * as WorkspaceShare from "@smthrs/sync/WorkspaceShare"
+
+const authorized = (capability: WorkspaceShare.WorkspaceCapability) =>
+  SyncClient.layer.pipe(Layer.provide(SyncAuth.layerClient(capability)))
+```
+
+To read a shared branch instead, pass that branch's capability on the
+subscription itself as `capability`. See
+[Authorize a connection](./authorize-a-connection.md).
+
+## Handle the failures that reach you
+
+The stream fails with `SyncError` or `SyncGapError`. Two cases have recovery paths:
+
+- `transport_failed` is retried under exponential backoff capped at five
+  seconds and only surfaces if the stream is otherwise ended.
+- `compacted` requires an explicit `onResync` handler to restore a checkpoint
+  and return its exact cursor before restarting. Without one it fails closed. See
+  [Handle a compacted run](./handle-a-compacted-run.md).
+
+Everything else is yours:
+
+| Failure              | What it means                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `SyncGapError`       | The server's frame started beyond the cursor you covered. History was missed; rebuild rather than retry. |
+| `unauthorized`       | No credential, a refused one, or a credential that expired while the subscription was open.              |
+| `protocol_violation` | The server's page or frame contradicted itself. No cursor moved.                                         |
+| `frame_too_large`    | A page or frame exceeded the client's frame ceiling.                                                     |
+| `closed`             | The server ended the subscription with a `Closed` frame.                                                 |
+
+[Troubleshooting](../troubleshooting.md) has the full code table with causes and
+fixes.
+
+## Tune the window
+
+`credit` bounds the frames one subscription round carries before the follow
+replenishes it by resubscribing. The default is 256, and the ceiling the wire
+allows is `SyncProtocol.maxSubscribeCredit`:
+
+```ts
+const narrow = Effect.gen(function*() {
+  const sync = yield* SyncClient.SyncClient
+  return sync.subscribe({ scope: { _tag: "Run", runId }, cursors: [], credit: 32 })
+})
+```
+
+Lower it only for a deliberate reason. A small window makes the round-trip cost
+proportional to traffic rather than to the window, which is what
+[Replay then follow](../concepts/replay-then-follow.md) explains.

package/docs/guides/handle-a-compacted-run.md

@@ -0,0 +1,158 @@
+---
+title: "Handle a compacted run"
+description: "Restore a checkpoint and return its exact cursor before replaying the remaining history."
+sidebar:
+  order: 5
+---
+
+A cursor below a run's compaction floor names deleted history. The server
+refuses it with `compacted` and `resync: { runId, checkpointSeq, generation }`.
+The client fails without moving its cursor unless you supply `onResync`.
+
+The handler must restore the missing prefix and return
+`{ runId, afterSeq }` for the snapshot actually applied. A newer snapshot can
+have a sequence above the reported floor. Returning the older floor after
+applying that snapshot would replay part of its state twice. The client binds
+the returned cursor to `resync.generation`, the run's history after any rewinds,
+so a fresh follower needs no earlier cursor to resume it.
+
+## Restore a remote public projection
+
+The host must configure `SyncServer.SnapshotSource` with a provider that selects
+only public state for the requested run, lineage, projection and schema version.
+All authorized readers of that run can fetch it. Narrower or private data needs
+its own authorization boundary. A raw `Journal.latestCheckpoint` passthrough is
+unsafe because execution checkpoints are intentionally unredacted.
+
+The client can fetch that projection in its recovery handler:
+
+```ts
+import type * as SyncClient from "@smthrs/sync/SyncClient"
+import type { SyncError } from "@smthrs/sync/SyncError"
+import type * as SyncProtocol from "@smthrs/sync/SyncProtocol"
+import * as Effect from "effect/Effect"
+
+const recoverPublic = <E>(
+  sync: SyncClient.Service,
+  identity: Pick<SyncProtocol.SnapshotRequest, "lineageId" | "projection" | "projectionVersion" | "capability">,
+  applySnapshot: (snapshot: SyncProtocol.Snapshot) => Effect.Effect<void, E>
+) =>
+(resync: SyncProtocol.Resync): Effect.Effect<SyncProtocol.RunCursor, SyncError | E> =>
+  Effect.gen(function*() {
+    const snapshot = yield* sync.snapshot({
+      ...identity,
+      protocolVersion: 1,
+      runId: resync.runId,
+      atLeastSeq: resync.checkpointSeq
+    })
+    const cursor = { runId: snapshot.runId, afterSeq: snapshot.seq }
+    yield* applySnapshot(snapshot)
+    return cursor
+  })
+```
+
+`snapshot` validates identity, version, sequence and byte limits; your callback
+must still decode the projection's application schema and transactionally apply
+its state and durable cursor. The handler fails with `snapshot`'s `SyncError`
+or with your callback's own error `E`, and the subscription carries either
+unchanged. A fetch alone never acknowledges missing history.
+The host must retain a snapshot covering the compaction floor. If the floor
+moves again before replay, recovery runs again for the newer floor.
+
+## Restore through an authorized local source
+
+A trusted local follower may alternatively read its execution checkpoint from
+the journal and supply its own application callback:
+
+```ts
+import { Journal } from "@smthrs/journal"
+import type * as SyncProtocol from "@smthrs/sync/SyncProtocol"
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+
+class CheckpointUnavailable extends Data.TaggedError("CheckpointUnavailable")<{
+  readonly message: string
+  readonly resync: SyncProtocol.Resync
+}> {}
+
+const recoverFromJournal = <E>(
+  journal: Journal.Service,
+  applySnapshot: (checkpoint: Journal.Checkpoint) => Effect.Effect<void, E>
+) =>
+(resync: SyncProtocol.Resync): Effect.Effect<SyncProtocol.RunCursor, CheckpointUnavailable | E> =>
+  Effect.gen(function*() {
+    const saved = yield* journal.latestCheckpoint(resync.runId).pipe(
+      Effect.mapError(() => new CheckpointUnavailable({ message: "Could not read the checkpoint", resync }))
+    )
+    if (
+      Option.isNone(saved) ||
+      saved.value.runId !== resync.runId ||
+      saved.value.seq < resync.checkpointSeq
+    ) {
+      return yield* Effect.fail(
+        new CheckpointUnavailable({ message: "No checkpoint covers the requested history", resync })
+      )
+    }
+    const checkpoint = saved.value
+    const cursor = { runId: checkpoint.runId, afterSeq: checkpoint.seq }
+    yield* applySnapshot(checkpoint)
+    return cursor
+  })
+```
+
+Pass the returned function as `onResync`. `CheckpointUnavailable` is the
+follower's own error, not a wire code, so the subscription reports it as a
+local restoration failure rather than as the server's `compacted` refusal. The
+required `applySnapshot` callback must actually decode and restore the
+projection; logging a checkpoint is not restoration. Validate its run/lineage
+and projection schema/version before using the state. Journal checkpoints are generic and intentionally
+unredacted: never expose raw execution checkpoints to a remote follower merely
+because that follower can read redacted history.
+
+For a durable projection, commit the restored state **and its durable cursor**
+in one application-owned transaction. On restart, seed a fresh sync client with
+that committed cursor. The sync client's cursor is only in memory; its
+interruption mask cannot make writes to separate stores atomic. Make recovery
+idempotent so a crash or a moving compaction floor can safely repeat it.
+
+Apply the same rule to every suffix entry: the `apply` callback must commit its
+projection changes and durable cursor together before returning. Keep the
+cursor with its run/lineage and projection version, so a cursor for one
+projection cannot skip the history needed by another. On restart, read that
+durable cursor, not a cursor cached separately before the crash.
+
+| Crash point                                                | Durable recovery                                                                  |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Between state and cursor writes, before transaction commit | Both writes roll back; restore the snapshot again.                                |
+| After snapshot commit, before `onResync` returns           | Seed the fresh client with the committed snapshot cursor; replay only its suffix. |
+| After an event commit, before `apply` returns              | Seed from that event's committed cursor; do not apply the event twice.            |
+
+These are application-store transaction guarantees. The sync client does not
+make arbitrary callbacks or external side effects exactly-once.
+
+The client validates the receipt's run and sequence before advancing. Missing,
+invalid, foreign-run or behind-floor receipts fail with the cursor unchanged.
+If compaction moves again before the next read, recovery runs again for the
+new floor.
+
+## Refuse when restoration is unavailable
+
+Omit `onResync` to preserve the original `compacted` refusal and cursor.
+A handler may also fail with its own error if its snapshot is missing,
+unauthorized, incompatible, or cannot be applied; the subscription fails with
+that error unchanged. Failed or interrupted application never acknowledges the
+deleted prefix.
+
+A browser or remote follower without a configured public snapshot source must
+not pretend to have rebuilt complete state. The RPC fails closed when the
+host has not provided the requested public projection.
+
+Returning the reported floor without restoring state would claim application
+of deleted history. Keep the typed `compacted` result when reconstruction is
+unavailable; clearing a projection does not recreate its missing prefix.
+
+## Related pages
+
+- [Compaction and resync](../concepts/compaction.md): scope and failure semantics.
+- [Checkpoints and compaction](/pkg/journal/concepts/compaction): journal retention.

package/docs/guides/list-workspace-runs.md

@@ -0,0 +1,120 @@
+---
+title: "List a workspace's runs"
+description: "Choose the run catalog a workspace subscription reconciles against: a fixed set, an in-process registry, or a poll of the durable run set another engine writes."
+sidebar:
+  order: 4
+---
+
+A workspace subscription serves the runs a `RunCatalog` lists. The catalog is
+supplied by the host rather than derived from the journal, because
+[`@smthrs/journal`](/api/journal) has no workspace-wide list or watch contract.
+This guide picks the right implementation.
+
+## The contract
+
+```ts
+import type * as RunCatalog from "@smthrs/sync/RunCatalog"
+```
+
+`list` is the authoritative run set. `changes` is a low-latency wake and
+nothing more: a subscriber that misses an announcement re-lists rather than
+losing state. A workspace subscription reconciles its covered set against
+`list` on every round, so a dropped notification costs latency and never state.
+
+`list` must name each run at most once. Every implementation here deduplicates,
+and `SyncServer` deduplicates again at the seam rather than trusting a host's
+catalog, because both fan-out paths key a run's served position by run id: a
+run named twice is read twice from the same position and its entries are served
+twice.
+
+Every implementation returns a fresh array from `list`, so a caller may retain
+and sort what it receives without disturbing another reader.
+
+## A fixed set
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import * as RunCatalogNs from "@smthrs/sync/RunCatalog"
+
+const fixed = RunCatalogNs.layerStatic(["build-42" as JournalEvent.RunId])
+```
+
+`changes` is empty, so nothing is ever announced. Use it when the covered set
+is known at composition time, and for tests. `RunCatalog.layerNoop` is
+`layerStatic([])`.
+
+## Runs this process creates
+
+`makeMemory` returns a catalog and the `register` function that grows it. A run
+is published exactly once, when it is first registered:
+
+```ts
+import * as Effect from "effect/Effect"
+
+const local = Effect.gen(function*() {
+  const { catalog, register } = yield* RunCatalogNs.makeMemory()
+  yield* register("build-43" as JournalEvent.RunId)
+  return catalog
+})
+```
+
+`RunCatalog.layerMemory` provides the same catalog when a composition needs the
+service and not the `register` function.
+
+The announcement feed slides at `RunCatalog.defaultChangesCapacity`
+announcements: registering never waits on a stalled subscriber and never grows
+the process on its behalf. A subscriber that falls further behind loses the
+oldest announcements and converges by re-listing.
+
+This catalog only ever hears about runs the same process registered. A follower
+composed against it never learns of a run another engine created.
+
+## Runs any engine creates
+
+`makePolling` re-reads a durable source on an interval.
+[`@smthrs/engine-store`](/api/engine-store) supplies that read as
+`RunCatalogRead`, over its own `flows_runs` table:
+
+```ts
+const durable = (read: Effect.Effect<ReadonlyArray<JournalEvent.RunId>>) =>
+  RunCatalogNs.layerPolling({ read, intervalMs: 1000 })
+```
+
+Anything that answers the same question works; the catalog holds no assumption
+about which. The interval defaults to `RunCatalog.defaultPollIntervalMs`, one
+second, and the read costs one bounded query per interval per composition, not
+per subscriber.
+
+Four behaviors are worth knowing before you rely on it:
+
+- **It primes itself before returning.** The first read a follower makes is
+  already current, and a workspace that cannot be read at all fails the
+  composition instead of serving an empty run set.
+- **A failed read is a warning and nothing else.** The previous view stands,
+  the interval holds, and no subscription attached to the catalog is torn down.
+  The warning is logged once per outage with the first failure's cause, and one
+  info line marks the read that ends it; the failed polls in between are silent.
+- **A run is announced once**, when it first appears. A run the read stops
+  naming, which is what retention collecting it looks like, leaves the view.
+  `list` is the workspace's run set, not a log of every run it ever had.
+- **The poll fiber belongs to the caller's scope.** Closing the scope stops it.
+
+Polling rather than waking is deliberate at 1.0.0-rc.0: there is no
+cross-process event delivery, so a follower learns of another engine's run by
+asking the workspace again, and the interval is the whole of the policy.
+
+## Choosing an interval
+
+The interval is how long a run can exist before a follower sees it. One second
+is short enough that a run appears in a dashboard while the operator is still
+looking at the command that started it, and long enough that an idle workspace
+is close to free. Lower it only when a real user is waiting on the difference,
+and remember that the workspace subscription's own `tailIntervalMs` is a second
+bound on the same latency.
+
+## Related pages
+
+- [Serve the read path](./serve-the-read-path.md): where the catalog is
+  provided.
+- [Coordinate two processes over one store](/pkg/engine-store/guides/coordinate-two-processes):
+  the durable read this catalog polls.

package/docs/guides/run-a-long-soak.md

@@ -0,0 +1,80 @@
+---
+title: "Run the optional long soak"
+description: "Execute and verify repeated resource-growth samples across TCP reconnects, compaction, retention and a stalled sync consumer."
+---
+
+Ordinary package gates keep the bounded `ServerSoak.test.ts` tests. The timed
+tier is off until `SMITHERS_SOAK_MINUTES` is set. Run from the sync package:
+
+```sh
+SMITHERS_SOAK_MINUTES=60 \
+SMITHERS_SOAK_ARTIFACT=/tmp/sync-soak/node26.json \
+pnpm exec vitest run test/ServerLongSoak.test.ts --maxWorkers=1 --coverage.enabled=false
+node test/fixtures/verify-soak.ts /tmp/sync-soak/node26.json 60
+```
+
+The focused timed tier does not replace the full package coverage gate. It
+spawns the same Node executable with `--expose-gc`. Supported pinned lane
+runtimes are Node 26.4.0 and 26.10.0. Minutes must be finite and within 1..720.
+The artifact path is required. For a bounded local rehearsal use 3 minutes,
+and label the receipt as local bounded evidence.
+
+The workload uses an on-disk SQLite journal and schema-aware NDJSON RPC over
+loopback TCP. Each cycle appends eight entries and opens four concurrent
+connections. Each consumer reconstructs the complete count and checks its
+applied cursor. A separate workspace consumer stalls inside `apply` for the
+whole measurement. Journal changes are also held unread to measure their
+bounded queue. Compaction advances a checkpoint while retaining 32 history
+rows, collects superseded checkpoints, and repeatedly triggers snapshot
+recovery in reconnecting clients. This exercises retention of history and
+checkpoints, not whole-run deletion or retention of externally stored blobs.
+
+## Artifact verifier contract
+
+`test/soakArtifact.ts` defines schema version 1. CI must run the independent
+`verify-soak.ts` command and fail on missing, malformed, incomplete, or failed
+artifacts. The exit code of the workload is also required; a JSON file alone
+is not a passing job. Preserve stdout/stderr and the JSON even on failure.
+
+Required top-level fields:
+
+| Field                     | Contract                                                                                                                                                       |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schemaVersion`, `status` | `1` and `complete` for a passing receipt; failure is explicit.                                                                                                 |
+| `runtime`                 | Exact Node version, platform, architecture.                                                                                                                    |
+| `candidate`               | Git head, dirty flag, SHA-256 over sorted sync source paths and bytes. A dirty local receipt is not immutable release certification.                           |
+| `workload`                | Requested minutes, seed `20260904`, warmup `20000` ms, sampling interval `10000` ms.                                                                           |
+| `samples`                 | At least five strictly increasing post-warmup checkpoints, continued useful work, no sample gap over 30 seconds, final sample at or beyond requested duration. |
+| `slopes`                  | Ordinary least-squares regression of every metric against elapsed minutes. The verifier recomputes these values.                                               |
+| `cleanup`                 | Zero active journal reads, pending writes, stalled subscribers and connected TCP sockets after scope release.                                                  |
+| `failure`                 | Diagnostic reason when the run fails.                                                                                                                          |
+
+Every sample must carry elapsed time, cycle count, emitted events, connections,
+compactions, retained event/checkpoint counts, stalled-subscriber count, and
+all metrics below. Memory is measured after explicit GC. Handles come from
+Node's `_getActiveHandles`; connected sockets are actual `net.Socket` handles.
+Queues measure outstanding journal reads/writes, socket readable/writable
+bytes, and the stalled journal notification subscription. These are named
+observed queues, not a claim to inspect every runtime-internal RPC queue.
+
+| Metric                                                             | Maximum positive slope per minute |
+| ------------------------------------------------------------------ | --------------------------------- |
+| Retained heap                                                      | 1 MiB                             |
+| RSS                                                                | 4 MiB                             |
+| Open handles, connected sockets                                    | 0.5 each                          |
+| Active journal reads, pending writes, queued journal notifications | 1 each                            |
+| Queued socket bytes                                                | 64 KiB                            |
+| Database bytes, WAL bytes                                          | 1 MiB each                        |
+
+The verifier also requires at most 40 retained events, exactly one retained
+checkpoint, exactly one stalled subscriber during sampling, zero pending
+writes at checkpoints, and bounded journal notifications. SQLite's normal WAL
+policy remains active; samples do not truncate the WAL to manufacture a flat
+curve. The thresholds are provisional regression budgets, not a production
+capacity or latency guarantee. Run the scheduled tier on a controlled host
+and retain at least 30 days of artifacts for baseline comparison.
+
+The scheduled owner should run a fresh 60-minute job on each pinned Node
+version, serially or on separate workers, without a cached test result. A
+three-minute local success verifies the harness and its bounded observation;
+it does not close the hours-long leak campaign or certify remote CI execution.

package/docs/guides/serve-the-read-path.md

@@ -0,0 +1,146 @@
+---
+title: "Serve the read path"
+description: "Compose SyncServer over a journal and a run catalog, mount the RPC group on a transport with its authentication middleware, and set the policy that bounds one follower's cost."
+sidebar:
+  order: 2
+---
+
+This guide builds the serving side. A host that already runs
+[`@smthrs/gateway`](/api/gateway) has this done: the gateway mounts `SyncRpcs`
+on `POST /sync` and `/sync/ws`. Build it yourself when you are embedding the
+read path in a host of your own.
+
+## Compose the server
+
+`SyncServer.layer` requires a `Journal` and a `RunCatalog`, and nothing else:
+
+```ts
+import * as RunCatalog from "@smthrs/sync/RunCatalog"
+import * as SyncServer from "@smthrs/sync/SyncServer"
+import * as Layer from "effect/Layer"
+
+const serverLayer = SyncServer.layer.pipe(
+  Layer.provide(RunCatalog.layerStatic([]))
+)
+```
+
+The journal is still required, and the composition supplies it: in production
+that is `@smthrs/journal`'s `SqlJournal` over
+[`@smthrs/database`](/api/database). The catalog is the workspace's run set;
+`layerStatic([])` serves a workspace with no runs, which is what a run-scoped
+deployment wants. For a catalog that learns of runs another engine created, see
+[List a workspace's runs](./list-workspace-runs.md).
+
+Provide `BranchShare` as well if any run in the workspace is a shared branch.
+Without it in scope, every branch run is closed.
+
+## Mount the RPC group
+
+`SyncServer.layerHandlers` projects the service onto the wire. It is a thin
+projection with no policy of its own, so the handlers and an in-process caller
+face the same rules:
+
+```ts
+import { SyncRpcs } from "@smthrs/sync/SyncRpcs"
+import * as RpcServer from "effect/unstable/rpc/RpcServer"
+
+const mount = RpcServer.layer(SyncRpcs, { disableFatalDefects: true }).pipe(
+  Layer.provide(SyncServer.layerHandlers),
+  Layer.provideMerge(RpcServer.layerProtocolHttp({ path: "/sync" }))
+)
+```
+
+Mount both protocols against the same handlers when clients read a page over
+the request path and follow over a socket. Pointing them at two servers would
+let the two halves disagree.
+
+## Supply the authentication middleware
+
+`SyncRpcs` is bound to the `SyncAuth` middleware tag, so serving it requires an
+implementation. The production one verifies the capability header:
+
+```ts
+import * as SyncAuth from "@smthrs/sync/SyncAuth"
+import * as WorkspaceShare from "@smthrs/sync/WorkspaceShare"
+
+const authorized = SyncAuth.layer.pipe(Layer.provide(WorkspaceShare.layerConfig))
+```
+
+Without a middleware-installed principal every request runs as anonymous and
+every non-branch read is refused. That is the fail-closed default, not a
+misconfiguration to work around. See
+[Authorize a connection](./authorize-a-connection.md) for minting and rotation,
+and [Authorization](../concepts/authorization.md) for why the two boundaries
+are shaped this way.
+
+## Read in process, without a transport
+
+A caller that already owns the journal skips the wire and provides the
+principal directly:
+
+```ts
+import * as SyncPrincipal from "@smthrs/sync/SyncPrincipal"
+import * as Effect from "effect/Effect"
+
+const page = Effect.gen(function*() {
+  const server = yield* SyncServer.SyncServer
+  return yield* server.read({ protocolVersion: 1, scope: { _tag: "Workspace" }, cursors: [], limit: 100 })
+}).pipe(Effect.provide(SyncPrincipal.layerWorkspace("host")))
+```
+
+That is the only sanctioned bypass of the header check, and it is never a
+transport's to take. An in-process owner presented no credential, so nothing
+can expire under it and its subscriptions have no deadline.
+
+## Set the policy
+
+`SyncServer.layerWith` takes the read-path policy. Every field defaults, and
+every field is validated as a positive safe integer at construction, so a bad
+value fails loudly instead of quietly disabling the bound it configures:
+
+```ts
+const tuned = SyncServer.layerWith({
+  maxFrameBytes: 512 * 1024,
+  concurrency: 32,
+  tailIntervalMs: 250
+})
+```
+
+| Option           | Default | What it bounds                                                                                         |
+| ---------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `maxFrameBytes`  | 2 MiB   | Summed encoded entries of one read page or subscription frame.                                         |
+| `concurrency`    | 64      | Journal reads one workspace subscription holds open at once.                                           |
+| `tailIntervalMs` | 1000    | Milliseconds a workspace subscription waits before revisiting every covered run when nothing wakes it. |
+
+`concurrency` bounds what one follower costs without bounding what it sees: the
+workspace tail visits every covered run each round, so a run past the bound
+waits one round for a slot rather than being starved.
+
+`tailIntervalMs` is the freshness policy for runs another process owns, not for
+runs written beside the follower. An entry this process commits is published on
+`Journal.changes` and wakes the round at once. A run-scoped subscription follows
+one journal stream directly and keeps that stream's wake.
+
+## What the server refuses
+
+- A request whose cursor set names one run twice, with `invalid_request`.
+- A single entry whose own encoded size exceeds `maxFrameBytes`, with
+  `frame_too_large`. A page that merely sums past the ceiling is truncated and
+  reports `done: false` instead.
+- Every non-branch read for an anonymous caller, with `unauthorized`.
+- A subscription whose credential has expired, which ends the stream with
+  `unauthorized`.
+
+A journal failure crosses as its stable journal code with a constant public
+message. The driver's own sentence stays on the server, because a follower may
+hold nothing but a share link and a SQLite message routinely carries SQL text,
+table names, and constraint identifiers.
+
+## Related pages
+
+- [List a workspace's runs](./list-workspace-runs.md): the catalog this server
+  reconciles against.
+- [Authorize a connection](./authorize-a-connection.md): the credential the
+  middleware verifies.
+- [Test a follower](./test-a-follower.md): a real server and client over an
+  in-memory socket.