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

package/docs/concepts/compaction.md

@@ -0,0 +1,144 @@
+---
+title: "Compaction and resync"
+description: "What a compacted refusal means, how the client resumes from the checkpoint the server names, and why the entries below that checkpoint are a real hole the consumer must fill."
+---
+
+Compaction deletes a run's journal entries below a checkpoint. A cursor under
+that floor names history that no longer exists, so the read cannot be served
+and cannot be served later either.
+
+`@smthrs/journal` owns the mechanism, including when a checkpoint is written
+and what it may summarize; see
+[Checkpoints and compaction](/pkg/journal/concepts/compaction). This page is
+about what the sync boundary does with it.
+
+## The refusal names where to resume
+
+The server maps the journal's compacted failure onto its own `compacted` code
+and attaches a `Resync` of `{ runId, checkpointSeq, generation }`. `checkpointSeq`
+is the compaction floor: the checkpoint's state subsumes every entry at or below
+it, so a follower must restore a snapshot covering that sequence before
+resuming. Its cursor then names the snapshot actually applied, which may be
+newer. `generation` is the run's history after any rewinds; a restored cursor
+that omits its own generation is bound to this one.
+
+`compacted` is its own code rather than an `unknown` because it is the one
+recoverable failure here. Folding it into `unknown` cost the checkpoint, and
+with it every path back: the client retries only `transport_failed`, so the
+subscription died and every resubscribe from the same cursors died identically.
+A whole-workspace subscription then died over a single compacted run.
+
+The run id comes from the call site rather than from the journal error. The
+journal error carries only a sequence, and a workspace read fans out over many
+runs, so without the id a follower could not tell which cursor to move.
+
+`Resync` rides on `SyncError` as one optional field rather than as a new frame
+variant or a new procedure. A follower that never meets a compacted run sees no
+change at all. `Sync.Snapshot` separately fetches an explicitly public,
+versioned and lineage-bound projection when the host provides one.
+
+## Recovery requires an explicit handler
+
+`SyncClient.subscribe` fails closed by default. An `onResync` handler must
+restore the missing prefix and return `{ runId, afterSeq }` for the snapshot
+actually applied. Only then does the client advance and read the suffix.
+The receipt must name the requested run and cover the reported floor.
+
+These cases stay failures on purpose:
+
+- A `compacted` error carrying no `Resync` has no resume point to apply.
+- A target outside the subscription's run scope is refused before the hook runs.
+- A missing handler, failed application, or invalid receipt cannot acknowledge history.
+- A checkpoint at or below what the subscription already covers cannot move the
+  cursor forward, so retrying would re-read the same refusal forever. That is
+  the same non-convergence rule that refuses an incomplete catch-up page which
+  makes no progress.
+
+## The hole is real
+
+:::warning
+The resync moves a cursor, not state. The entries below `checkpointSeq` are
+gone from the journal. A consumer must fetch and apply a public snapshot or
+restore an authorized local checkpoint before claiming to have rebuilt that prefix.
+:::
+
+`SubscribeOptions.onResync` is the seam a consumer fills the hole through. It
+runs **before** the cursor moves and must return a valid restored cursor. A failure leaves the cursor
+where it was and fails the subscription, so nothing is skipped behind the
+consumer's back.
+
+What a consumer does there depends on what it is holding:
+
+- A remote follower fetches a configured public projection with `sync.snapshot`,
+  validates its application schema, applies it, and returns its exact cursor.
+- A trusted Node follower can also read the prefix out of band with
+  `journal.latestCheckpoint(runId)` and applies `checkpoint.state`, then
+  continues from the sync stream.
+- A follower that cannot restore the prefix fails
+  the hook, and the subscription fails with the cursor unmoved.
+
+Durable consumers own the transaction that commits snapshot state and their
+durable cursor together. This client's in-memory cursor is not a cross-store
+transaction. A moving compaction floor may require another idempotent restore.
+Raw journal checkpoints are unredacted execution state. `SnapshotSource` is
+an explicit public-projection boundary, not a passthrough for those checkpoints.
+Provider failures and defects are logged at warning level with their original
+cause. The caller receives `not_found` without provider details. Interruption
+remains interruption.
+
+## Retention and rebuilding
+
+The protocol transfers a complete snapshot value. It does not hand out a
+checkpoint reference that might expire between lookup and fetch. A provider
+must capture its selected public state before yielding it, then let the server
+detach and validate the response. Collecting a provider cache after capture
+cannot invalidate those transferred bytes. A newer compaction can still
+invalidate the suffix cursor; the next read returns `compacted` and recovery
+fetches and applies a newer snapshot.
+
+Before compacting, durably checkpoint every projection whose history the host
+claims is recoverable. Keep that authoritative checkpoint until a newer complete
+checkpoint covers it. The journal's fenced compaction transaction retains its
+floor checkpoint and allocation entry while collecting older checkpoints and
+events. A disposable public-snapshot cache can then be dropped and rebuilt from
+that checkpoint plus retained history. Deleting both the checkpoint and the
+compacted prefix destroys authority and cannot be repaired by sync.
+
+`ProjectionRebuild.integration.test.ts` exercises 17-, 33-, and 257-entry
+histories with independent full-history expectations. It drops the consumer's
+branch and workspace projection tables and the public snapshot cache, kills
+each rebuilding consumer with SIGKILL inside its transaction, then reopens
+SQLite and reconstructs identical state. The 17-entry case ends exactly at its
+compaction floor. A second case collects snapshots during transfer and advances
+the floor before suffix replay. The workspace projection is an application
+example authorized with production `WorkspaceShare` middleware.
+
+`WorkspaceShare` itself is an HMAC capability authority, not a journal
+projection. Its signing keys, credential lifetime, and access grants are not
+rebuildable from public history. Branch presence is likewise an ephemeral lease.
+These must not be included in claims about disposable history projections.
+
+An older client without a recovery handler receives the typed
+`compacted` result with its `resync` target and unchanged progress. A missing
+public provider returns `not_found`; incompatible identities or versions are
+refused. Neither response authorizes skipping the missing prefix.
+
+[Handle a compacted run](../guides/handle-a-compacted-run.md) is the
+task-shaped version, with the hook written out.
+
+## Compaction is opt-in
+
+Without a compaction policy on the journal layer, no entry is ever deleted and
+no follower ever meets this code. That is the default. The code path matters
+anyway, because the day a workspace enables compaction is the day the
+difference between a follower that catches up and one that never can becomes
+visible, and by then the follower is already deployed.
+
+## Related pages
+
+- [Checkpoints and compaction](/pkg/journal/concepts/compaction) in
+  `@smthrs/journal`: what a checkpoint is and how a floor advances.
+- [Scopes and cursors](./scopes-and-cursors.md): what the cursor being moved
+  means.
+- [Troubleshooting](../troubleshooting.md): the `compacted` symptom and what to
+  change.

package/docs/concepts/replay-then-follow.md

@@ -0,0 +1,129 @@
+---
+title: "Replay then follow"
+description: "The two phases of a sync subscription: bounded catch-up pages until the durable tail, then credit windows of live frames, and the bounds and validation that hold at each step."
+---
+
+A subscription has two phases and one cursor set. First it replays durable
+history through `Sync.Read`, page by page, until the server reports it reached
+the tail. Then it follows through `Sync.Subscribe`. `SyncClient.subscribe`
+performs both and presents them as a single stream of entries, so a consumer
+never sees the switch.
+
+## Phase one: pages until `done`
+
+`Sync.Read` takes a scope, a cursor set, and a `limit`, and returns entries
+plus the cursor set the page served through. A page stops at the first of three
+bounds:
+
+- the request's `limit`, capped at `SyncProtocol.maxReadLimit`;
+- the frame ceiling, `SyncServer.Options.maxFrameBytes`, which defaults to
+  2 MiB of summed encoded entries;
+- the durable tail of every covered run.
+
+Only the third reports `done: true`, and that is the signal to switch to the
+follow.
+
+The frame ceiling is a budget on the page, not a verdict on the read. The
+server serves entries until the next one would cross it, then returns
+`done: false` so the client asks for the rest. The single case that fails is
+one entry whose own encoded size exceeds the ceiling, refused with
+`frame_too_large`, because no page can ever carry it.
+
+### Why a page is shared, not filled in order
+
+A workspace read offers each covered run a share of the page before offering
+unused budget back to runs that still have entries. Both passes prioritize the
+least advanced supplied cursor, with run ID breaking ties. Runs without a
+cursor come first. Cursor values set scheduling priority only; sequences still
+order entries within their own run.
+
+A count or byte budget can end a page before every run gets a share. Reusing the
+returned cursors changes the next page's priority: served runs advance, while
+unserved runs keep their priority. A continuously readable run cannot indefinitely
+hold a slot ahead of another pending run. Empty runs spend no entry budget.
+This requires no server-side session and does not depend on cursor array order.
+
+Fair service does not guarantee `done`: a producer that continuously outpaces
+catch-up can keep the follower in this phase. Every pending run still receives
+service; a single page need not contain every run.
+
+## Phase two: credit windows
+
+`Sync.Subscribe` takes the same scope and cursors plus a `credit` count.
+`credit` is a hard limit on frames that subscription may emit, enforced by the
+server. It is not a sliding acknowledgement window, and there is no `Ack`
+procedure.
+
+A follower that wants more frames resubscribes from its current subscription
+progress. `SyncClient` does exactly that, once per window, defaulting to
+`SyncClient.defaultCredit` of 256 frames.
+
+The number is a real trade. At `credit: 1` the window closes after every single
+entry, so following a run that emits a hundred entries costs a hundred
+subscribe round trips, each one a fresh cursor snapshot and a fresh server-side
+fan-out. Replenishing a window 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.
+
+## What a frame says
+
+An `Entries` frame carries one run's entries plus the interval the server
+covered: `runId`, `fromSeq`, `toSeq`. The interval describes what the server
+looked at, not what it carried, because dropped admissions leave legitimate
+holes inside it.
+
+`fromSeq` is what gap detection compares against the cursor. A frame whose
+`fromSeq` starts more than one past the client's cursor is a real gap and fails
+the subscription with `SyncGapError`. A frame that merely omits sequences
+inside its own interval is ordinary traffic.
+
+No frame carries a cursor. The client tracks its own.
+
+A `Closed` frame is terminal and ends the subscription with the `closed` code.
+The `Heartbeat` variant is reserved: no server in this package emits one, so a
+client must not wait for one. It stays in the union so adding it later is not a
+wire break, and so a third-party client written against the schema already
+ignores it. Keepalive is a transport concern here, because a heartbeat would
+spend the subscription's credit.
+
+## Server responses are admitted, never trusted
+
+Both phases validate before any cursor moves. A schema-valid page or frame can
+still contradict itself, and applying one would corrupt the client's
+bookkeeping. The client refuses:
+
+- a page or frame whose summed encoded entries exceed `maxFrameBytes`, with
+  `frame_too_large`;
+- an entry for a run the request's scope excludes;
+- entries that repeat or reorder a sequence within one run;
+- an entry at or below the cursor the request carried;
+- an entry outside a frame's own declared interval;
+- a response that echoes one run's cursor twice.
+
+Each of the last five is a `protocol_violation`. The strictly-above-the-cursor
+rule is also what makes catch-up converge: a page that carries entries but
+moves no cursor would be re-read forever. An incomplete page with no entries at
+all is refused for the same reason rather than retried.
+
+## Reconnecting
+
+A live follow that loses its transport reconnects under exponential backoff
+capped at five seconds, resuming from the subscription's progress, and the
+schedule resets once entries flow again. Only `transport_failed` retries. Gaps,
+authorization refusals, and server closes propagate to the consumer, because
+none of them is fixed by trying again. Delivery-only subscriptions resume from
+delivered bookmarks; applying subscriptions resume from applied progress.
+An unrelated defect or interruption accompanying a disconnect stays terminal,
+with its complete cause preserved.
+
+Transport, authentication, and reconnect all live in this package rather than
+in the application. A follower that had to implement them would have to
+re-derive the cursor rules above to do it safely.
+
+## Related pages
+
+- [Scopes and cursors](./scopes-and-cursors.md): what the cursor a phase
+  resumes from means.
+- [Compaction and resync](./compaction.md): the one refusal that is recoverable
+  rather than terminal.
+- [Wire protocol](../protocol.md): the exact message shapes both phases use.

package/docs/concepts/scopes-and-cursors.md

@@ -0,0 +1,135 @@
+---
+title: "Scopes and cursors"
+description: "What a sync request covers, what a cursor means, why journal sequences have holes, and the difference between an entry that was delivered and one that was applied."
+---
+
+Every sync request answers two questions: which runs does it cover, and where
+in each of them does it start. The first is a scope. The second is a cursor
+set.
+
+## A scope is one run or the whole workspace
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import type * as SyncProtocol from "@smthrs/sync/SyncProtocol"
+
+const workspace: SyncProtocol.Scope = { _tag: "Workspace" }
+const oneRun: SyncProtocol.Scope = { _tag: "Run", runId: "build-42" as JournalEvent.RunId }
+```
+
+A run scope names exactly one run. A workspace scope covers every run the
+`RunCatalog` lists and the caller is authorized to read, and it reconciles that
+set on every round, so a run created after the subscription opened joins it.
+
+`SyncProtocol.covers(scope, runId)` is the predicate both ends use, so a client
+validating a server's page asks the same question the server asked when it
+built it.
+
+## A cursor is per run, and exclusive
+
+`RunCursor` is `{ runId, afterSeq, generation }`. A `WorkspaceCursor` is an
+array of them. `generation` names the run's current history: a rewind
+increments it, and sequence order is meaningful only within one generation.
+Server cursors always carry it; a persisted request cursor may omit it for
+generation zero. Persist it with `afterSeq`, because a cursor whose generation
+differs from the run's fails with `lineage_changed`. See
+[Rewind generations](../api.md#rewind-generations).
+
+`afterSeq` means "entries after this number". It never means "expect the next
+number to be exactly one greater".
+
+That distinction is not a detail. Journal sequences legitimately have holes: an
+admission the journal dropped leaves a number nothing was ever written at. A
+follower that treats a missing number as corruption stalls on ordinary traffic.
+Gap detection therefore compares the server's declared covered interval against
+the cursor, not the entry sequences against each other. See
+[Replay then follow](./replay-then-follow.md) for where that comparison lives.
+
+## One cursor per run, or the request is refused
+
+A cursor set that names one run twice is ambiguous about where the read starts,
+so both `Sync.Read` and `Sync.Subscribe` refuse it with `invalid_request`
+rather than picking one. `SyncProtocol.duplicateCursorRunId` is the check, and
+the client applies it to the server's echoed cursors as well: a response that
+names a run twice is a `protocol_violation`.
+
+The schema cannot express uniqueness, so the rule is stated once and enforced
+at every boundary that could break it.
+
+## Delivered and applied are different claims
+
+`RunCursor` is an exclusive transport bookmark. The server's response cursors
+and `progress.delivered` describe delivery, and never acknowledge application.
+`client.progress` reports `SyncProtocol.Progress`, two cursor sets:
+
+- `delivered` records transport delivery.
+- `applied` records successful `apply` or `onResync` callbacks.
+
+Both are `WorkspaceCursor` values; the field name carries the distinction.
+Delivery-only subscriptions leave applied progress empty. Use
+`SubscribeOptions.apply` to acknowledge materialization:
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import * as Effect from "effect/Effect"
+
+const apply = (entry: JournalEvent.Entry): Effect.Effect<void> =>
+  Effect.logInfo(`applied ${entry.eventType} at ${entry.seq}`)
+```
+
+The callback runs to success before the cursor moves. It fails with the
+consumer's own error type, which the subscription's error channel carries
+unchanged. A failure fails the subscription with that entry unacknowledged, so
+the next subscription from `client.progress`'s applied cursors delivers it
+again. Redelivery is what a retry is here, so the callback must be idempotent.
+
+Use it whenever the consumer writes somewhere durable. Leave it off when the
+consumer is a view that is rebuilt on reconnect anyway.
+
+## The client's effective cursor is the later of two
+
+A `SyncClient` keeps separate delivered and applied maps. An applying
+subscription uses the later of the caller's cursor and the shared applied
+cursor. A delivery-only subscription uses shared delivered progress. Earlier
+delivery cannot fast-forward an applying consumer past unapplied entries.
+One client instance belongs to one materialization; independent projections
+must use independent clients even when they read the same run.
+
+Both halves matter. A caller that restored its own progress from durable
+storage is never regressed and never re-receives entries it has already
+materialized. A caller behind its matching shared progress map is fast-forwarded.
+Failed application can redeliver the unapplied entry; consumers must be idempotent.
+
+To rebuild a projection from an earlier position, construct a fresh client. Its
+progress maps are empty, so the caller's cursor is the only one there is.
+
+## Persisting a cursor
+
+`client.progress` returns canonical sets with one entry per run, sorted by run
+id. Its applied positions advance only after application succeeds. Fetching a
+snapshot does not move either set:
+
+```ts
+import * as SyncClient from "@smthrs/sync/SyncClient"
+import * as Effect from "effect/Effect"
+
+const checkpoint = Effect.flatMap(
+  SyncClient.SyncClient,
+  (sync) => Effect.map(sync.progress, (progress) => progress.applied)
+)
+```
+
+For durable recovery, the callback must commit state and its cursor in the
+same application transaction. Reading progress later and writing a separate
+cursor file is not that transaction. Seed a fresh client from the durable
+transaction's cursor after restart. Supply cursors only for state already
+restored; an input bookmark is the caller's assertion, not proof of application.
+
+## Related pages
+
+- [Replay then follow](./replay-then-follow.md): how the two phases use these
+  cursors, and what bounds a page.
+- [Compaction and resync](./compaction.md): what happens when a cursor names
+  history the journal has deleted.
+- [Follow a run](../guides/follow-a-run.md): the task-shaped version of this
+  page.

package/docs/guides/authorize-a-connection.md

@@ -0,0 +1,174 @@
+---
+title: "Authorize a connection"
+description: "Provision a workspace share authority, mint a capability, present it from a client, rotate signing keys without invalidating outstanding links, and reach a shared branch instead."
+sidebar:
+  order: 3
+---
+
+A sync connection reads a workspace's non-branch runs only when it presents a
+verified `WorkspaceShare` capability. This guide provisions the authority,
+mints a capability, and gets it onto the wire.
+
+## Provision the authority from configuration
+
+`WorkspaceShare.layerConfig` reads one secret and one key name from the
+environment:
+
+```ts
+import * as WorkspaceShare from "@smthrs/sync/WorkspaceShare"
+
+const shareLayer = WorkspaceShare.layerConfig
+```
+
+| Variable               | Meaning                                                                                                  |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `SMITHERS_SYNC_SECRET` | The HMAC signing secret, read as `Redacted` so it is never logged. Required; at least 32 bytes of UTF-8. |
+| `SMITHERS_SYNC_KEY_ID` | The key name recorded in every capability's claims. Defaults to `primary`.                               |
+
+There is deliberately no default secret. A deployment that configures neither
+name fails to construct the authority, and the read path stays closed.
+
+## Mint a capability
+
+`mint` takes the id you will audit by, the access level, and a lifetime in
+milliseconds:
+
+```ts
+import * as Effect from "effect/Effect"
+
+const mint = Effect.gen(function*() {
+  const share = yield* WorkspaceShare.WorkspaceShare
+  return yield* share.mint({
+    capabilityId: "dashboard-session-7",
+    access: "read",
+    ttlMs: 60 * 60 * 1000
+  })
+})
+```
+
+The result carries its claims and their signature. `capabilityId` is what
+identifies the credential in a span or an audit trail; it is not a secret and
+it is not the signature.
+
+`verify` is the other half, and it is the single place a refusal happens. It
+checks the signature in constant time, then that the key name is known, then
+the expiry, then that the access asked for is covered. Every refusal is
+`unauthorized` with a distinct message.
+
+## Present it from a client
+
+`SyncAuth.layerClient` stamps every outgoing request from a generated RPC
+client with the capability:
+
+```ts
+import * as SyncAuth from "@smthrs/sync/SyncAuth"
+import * as SyncClient from "@smthrs/sync/SyncClient"
+import * as Layer from "effect/Layer"
+
+const authorized = (capability: WorkspaceShare.WorkspaceCapability) =>
+  SyncClient.layer.pipe(Layer.provide(SyncAuth.layerClient(capability)))
+```
+
+A client written against the wire rather than against `SyncClient` sets the
+header itself. The name is `SyncAuth.capabilityHeader`, which is
+`flows-sync-workspace`, and the value is the unpadded base64url of the
+schema-encoded capability JSON:
+
+```ts
+const header = Effect.gen(function*() {
+  const share = yield* WorkspaceShare.WorkspaceShare
+  const capability = yield* share.mint({ capabilityId: "cli", access: "read", ttlMs: 60_000 })
+  return yield* SyncAuth.encodeCapability(capability)
+})
+```
+
+`SyncAuth.decodeCapability` is the inverse. Every malformation folds to the
+same `unauthorized` refusal, so the header cannot be used as a parsing oracle.
+
+## Rotate a signing key
+
+A capability's claims carry the `kid` of the key that signed them, and the
+`kid` is itself signed. Build the authority over a keyring to add a new active
+key while capabilities minted under the retired one are still outstanding:
+
+```ts
+import * as Config from "effect/Config"
+import * as Layer from "effect/Layer"
+
+const rotated = Layer.unwrap(
+  Effect.gen(function*() {
+    const keyring: WorkspaceShare.Keyring = {
+      activeKid: "2026-q1",
+      keys: [
+        { kid: "2026-q1", secret: yield* Config.Redacted("SYNC_SECRET_CURRENT") },
+        { kid: "2025-q4", secret: yield* Config.Redacted("SYNC_SECRET_RETIRED") }
+      ]
+    }
+    return WorkspaceShare.layerHmac(keyring)
+  })
+)
+```
+
+`Config.Redacted` reads each secret without ever rendering it. An unset
+variable fails the layer with a `ConfigError` naming it, so the read path
+stays closed.
+
+New capabilities are signed with `activeKid`. Capabilities naming any key in
+`keys` still verify. Drop the retired key once its longest outstanding
+lifetime has passed.
+
+Every key is imported when the authority is constructed, so a misconfigured
+keyring fails there rather than at the first request. A malformed keyring
+fails with `invalid_request`:
+
+- an `activeKid` that names no key in the ring;
+- a `kid` listed twice;
+- a secret holding an unpaired surrogate, which UTF-8 would fold into the
+  same key bytes as a different secret;
+- a secret shorter than 32 bytes of UTF-8. Every capability carries its
+  claims and signature in the clear, so one observed capability lets an
+  attacker search a short secret offline and then forge capabilities.
+  Generate one with `openssl rand -base64 32`.
+
+A secret Web Crypto refuses to import fails with `unknown` instead, because
+the refusal is the platform's rather than the request's. The error's `cause`
+carries the rejection text.
+
+## Close the door entirely
+
+`WorkspaceShare.layerNoop` mints nothing and verifies nothing. Both operations
+**fail** with `unauthorized` rather than dying, so a consumer handling
+`SyncError` gets a refusal where the type promised one. Wire it when a
+deployment deliberately offers no workspace sharing, such as a local CLI whose
+only reader is in process.
+
+## Reach a shared branch instead
+
+A branch capability is a different credential with a different authority. It
+travels in the request payload rather than in a header, because it names one
+branch rather than one connection:
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import type * as BranchProtocol from "@smthrs/sync/BranchProtocol"
+
+const followBranch = (capability: BranchProtocol.ShareCapability, runId: JournalEvent.RunId) =>
+  Effect.gen(function*() {
+    const sync = yield* SyncClient.SyncClient
+    return sync.subscribe({ scope: { _tag: "Run", runId }, cursors: [], capability })
+  })
+```
+
+Mint one through `BranchShare`, whose `mint` takes a `branchId` alongside the
+same `capabilityId`, `access`, and `ttlMs`. A connection holding only a branch
+link still reads no engine run: that is the other boundary, and the link does
+not answer it.
+
+## Related pages
+
+- [Authorization](../concepts/authorization.md): why there are two boundaries
+  and what a signed expiry does to an open subscription.
+- [Serve the read path](./serve-the-read-path.md): where the middleware is
+  installed.
+- [Troubleshooting](../troubleshooting.md): each `unauthorized` symptom and its
+  cause.