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

package/docs/api.md

@@ -0,0 +1,328 @@
+---
+title: "API reference"
+description: "Every public export of @smthrs/sync: the wire protocol, the read-path RPC group, the fail-closed server, the replay-then-follow client, the run catalog, the two capability authorities, and the branch collaboration modules."
+---
+
+```ts
+import { JournalEvent } from "@smthrs/journal"
+import { RunCatalog, SyncClient, SyncServer } from "@smthrs/sync"
+import { Effect, Layer } from "effect"
+
+const serverLayer = SyncServer.layer.pipe(Layer.provide(RunCatalog.layerStatic([])))
+
+const follow = Effect.gen(function*() {
+  const sync = yield* SyncClient.SyncClient
+  return sync.subscribe({ scope: { _tag: "Run", runId: "build-42" as JournalEvent.RunId }, cursors: [] })
+})
+```
+
+## Entry points
+
+| Import                         | Source                                                                                                                         | Platform |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| `@smthrs/sync`                 | [src/index.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/sync/src/index.ts)                     | any      |
+| `@smthrs/sync/test/TestSync`   | [src/test/TestSync.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/sync/src/test/TestSync.ts)     | Node     |
+| `@smthrs/sync/test/TestSocket` | [src/test/TestSocket.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/sync/src/test/TestSocket.ts) | any      |
+
+The root is browser safe, and the package's own bundle check holds it that
+way. The signing paths call Web Crypto directly for that reason, so one module
+serves Node and the browser. `TestSync.layerTest` binds the Node SQLite test
+journal, which is why it is a separate subpath.
+
+## Authorization
+
+Fail closed along two boundaries, both consulted per request:
+
+- **Branch runs.** A run whose id maps to a shared branch is visible only when
+  the request's share capability verifies for that branch. An explicitly scoped
+  branch read without one fails; a workspace listing excludes the branch runs
+  the caller's capability does not cover. Without a `BranchShare` in scope
+  every branch run is closed.
+- **Non-branch runs and workspace listings.** Visible only to the workspace
+  principal (`SyncPrincipal`), whose default is anonymous. Over RPC,
+  `SyncAuth.layer` establishes that principal by verifying the
+  `WorkspaceShare` capability presented in the `flows-sync-workspace` header.
+  A header that is present but malformed, forged, expired, or signed by an
+  unknown key is refused outright rather than downgraded to anonymity.
+
+A SUBSCRIPTION is additionally bounded in time. It is authorized once, when it
+opens, so the signed expiry travels with the identity (`SyncPrincipal.Workspace.expiresAtMs`,
+or the branch capability's own `expiresAtMs`) and the stream ends with
+`unauthorized` when that moment arrives. An in-process owner that provides
+`SyncPrincipal` itself presented no credential and has no deadline.
+
+Both authorities sign a length-prefixed encoding of their claims under
+HMAC-SHA-256, led by a scheme label, so neither's signature can be replayed as
+the other's under a shared secret. Length prefixes count UTF-8 bytes, and a
+claim set that does not survive UTF-8 (an unpaired surrogate) is refused with
+`invalid_request` rather than signed. Secrets are `Redacted` on both sides and
+must be at least 32 bytes of UTF-8, or the keyring is refused with
+`invalid_request`. Both carry a `kid` inside the signed claims, so keys rotate without
+invalidating capabilities minted under a retired one. Each authority takes its
+own keyring: `BranchShare.layerConfig` reads `SMITHERS_SYNC_BRANCH_SECRET` and
+`SMITHERS_SYNC_BRANCH_KEY_ID`, `WorkspaceShare.layerConfig` reads
+`SMITHERS_SYNC_SECRET` and `SMITHERS_SYNC_KEY_ID`.
+
+Both authorities decode their mint request before signing it, so an empty id
+or a non-positive `ttlMs` from an in-process caller is refused with
+`invalid_request` rather than crashing the operation. `BranchCommands.submission`
+returns an `Effect` for the same reason: a command name the schema forbids is a
+refusal, not a throw.
+
+## Bounds
+
+The bounds cap what is in flight at once: entries per page, frames per
+subscription, journal reads open per workspace subscription, bytes per frame.
+What one follower holds open is therefore a function of the configured bound,
+not of how far behind it has fallen. Two things still scale with the workspace.
+A workspace subscription keeps a served position for every run it has ever
+covered, including a run the catalog later drops, so its bookkeeping is O(runs
+covered). A catalog-wide round, which runs at open, on an announcement, and
+once per `tailIntervalMs`, reads one page and two generations per covered run,
+so its work is O(runs listed) with `concurrency` reads open at a time. A wake
+for an entry committed in this process reads only the runs it named. Size
+`concurrency` and `tailIntervalMs` for the catalog, not only for the follower.
+
+| Bound                                            | Default                                         | What it caps                                                                                                                                                                   |
+| ------------------------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SyncProtocol.maxReadLimit`                      | 1024                                            | Entries one `Sync.Read` may ask for. Over the limit is refused at the wire; an in-process caller is clamped.                                                                   |
+| `SyncProtocol.maxSubscribeCredit`                | 4096                                            | Frames one `Sync.Subscribe` may hold open. Zero is refused rather than served as an empty stream.                                                                              |
+| `SyncServer.Options.concurrency`                 | `SyncServer.defaultConcurrency` (64)            | Journal reads one workspace subscription holds open at once. A round reads one bounded page per run it visits, so a busy run wakes the next round instead of holding its slot. |
+| `SyncServer.Options.tailIntervalMs`              | `SyncServer.defaultTailIntervalMs` (1000)       | Milliseconds a workspace subscription waits before revisiting every covered run when nothing wakes it, and the longest that local wakes may defer that catalog-wide round.     |
+| `SyncServer.Options.maxFrameBytes`               | `SyncProtocol.defaultMaxFrameBytes` (2 MiB)     | Summed encoded entries of one read page or subscription frame.                                                                                                                 |
+| `SyncClient.SubscribeOptions.credit`             | `SyncClient.defaultCredit` (256)                | Frames one subscription round carries before the follow replenishes the window by resubscribing from its acknowledged cursors.                                                 |
+| `SyncClient.Options.bootstrapLimit`              | `SyncClient.defaultBootstrapLimit` (256)        | Entries one catch-up page asks for.                                                                                                                                            |
+| `BranchCommands.Options.maxCommandBytes`         | `BranchCommands.defaultMaxCommandBytes` (1 MiB) | Encoded size of one command submission, refused before anything is appended.                                                                                                   |
+| `BranchCommands.Options.ledgerCapacity`          | `BranchCommands.defaultLedgerCapacity` (4096)   | Receipts one branch keeps in memory. The journal's producer identity is the durable dedupe, so an evicted receipt costs a round trip and never correctness.                    |
+| `BranchCommands.Options.hydrationLimit`          | `BranchCommands.defaultHydrationLimit` (4096)   | Entries one branch's first-touch hydration reads before it stops, so a long history is not charged to the next writer's latency. What the walk misses, the journal answers.    |
+| `BranchCommands.Options.branchIdleMs`            | `BranchCommands.defaultBranchIdleMs` (24 h)     | Untouched time before a branch's in-memory state is dropped. The next submission re-hydrates it from the journal, as after a restart.                                          |
+| `BranchPresence.PresenceOptions.maxParticipants` | `BranchPresence.defaultMaxParticipants` (256)   | Participants one branch may hold at once; a further announce is refused with `backpressure`.                                                                                   |
+| `RunCatalog.MemoryOptions.changesCapacity`       | `RunCatalog.defaultChangesCapacity` (1024)      | Announcements a stalled `changes` subscriber may fall behind by; the oldest slide out.                                                                                         |
+| `RunCatalog.PollingOptions.intervalMs`           | `RunCatalog.defaultPollIntervalMs` (1000)       | Milliseconds between reads of the durable run set: one bounded query per interval per composition, not per subscriber.                                                         |
+| `BranchPresence.PresenceOptions.changesCapacity` | `BranchPresence.defaultChangesCapacity` (256)   | Roster notifications a stalled `changes` subscriber may fall behind by; the oldest slide out.                                                                                  |
+
+Every numeric option is validated where it enters. A policy belongs to the
+constructor that takes it: `SyncServer.makeLiveWith`, `BranchCommands.makeLiveWith`,
+`SyncClient.makeWith`, `BranchPresence.makeMemory`, `RunCatalog.makeMemory` and
+`RunCatalog.makePolling`, plus the `layerWith`, `layerMemory` and `layerPolling`
+layers over them, fail with `invalid_request` when a value is not a positive
+safe integer, so a bad policy fails the composition instead of quietly
+disabling the comparison it configures. The plain `make`, `makeLive` and
+`layer` forms carry the defaults, which are valid by construction, and cannot
+fail on a policy. A count a REQUEST carries rather than a policy, meaning
+`Sync.Read`'s `limit` and `SyncClient.SubscribeOptions.credit`, is checked
+where the request is built.
+
+Both change feeds slide rather than block: a publisher never waits on a stalled
+subscriber and never grows the process on its behalf. Neither feed is a source
+of truth. `RunCatalog.list` and `BranchPresence.list` are the authoritative
+state, and every reader re-lists on a cadence of its own: a workspace
+subscription reconciles its covered run set against `RunCatalog.list` on every
+round, and a roster watch re-lists once per `BranchPresence` lease, capped at one second. A dropped
+notification therefore costs latency and never state.
+
+## Read path
+
+`SyncServer.Service` has `read(request)`, `subscribe(request)`, and `snapshot(request)`.
+`makeLiveWith(options)` and `layerWith(options)` take the `Options` policy
+above; `makeLive` and `layer` use the defaults. The live layer requires
+`Journal` and `RunCatalog`.
+
+`SyncServer.SnapshotSource` is an optional host service with
+`read(SnapshotRequest): Effect<Snapshot, SyncError>`. It provides only public
+projections, never raw unredacted execution checkpoints. The server authorizes
+the run/branch before invoking it, checks expiry before returning data, and
+refuses missing providers. Providers must select the exact requested lineage,
+projection and version and retain state covering the requested sequence.
+
+`SyncClient.Service.snapshot(request)` fetches that projection through
+`Sync.Snapshot` without applying state or advancing cursors. `SnapshotRequest`
+and `Snapshot` in `SyncProtocol` carry protocol version 1, run/lineage identity,
+projection name/version, minimum or actual sequence, and response JSON state.
+Both ends validate identities and the full response's encoded UTF-8 byte limit
+using `maxFrameBytes`. Invalid or stale state is refused, not coerced or skipped.
+
+`SyncClient.Service.progress` returns `SyncProtocol.Progress`: two cursor sets,
+`delivered` and `applied`. `delivered` is a delivery bookmark only. `applied`
+advances only after successful application or restoration; an applying subscription
+uses the shared applied map when choosing its start position. Use one client
+per projection and persist projection state and its cursor in one transaction.
+
+A read shares its page across the runs it covers and stops at the first of three
+bounds: the request's `limit`, the frame ceiling, or the durable tail of every
+covered run, which is the only case that reports `done: true`. Every covered run
+takes a share of the budget before any run takes a second helping, and the
+budget the shares leave unspent is offered back in run order, so a run with a
+backlog takes the larger part of a page but never all of it. Filling in run
+order instead let a producer that stayed one page ahead take every slot of every
+page, so `done` never became true and a bootstrapping follower never reached the
+runs behind it. The frame ceiling is a page budget rather than a verdict on the
+read, so a page whose entries sum past it reports `done: false`; only a SINGLE
+entry whose own encoded size exceeds the ceiling is refused with
+`frame_too_large`, because no page can ever carry it.
+
+Cursors are unique per run. A request that names one run twice is refused with
+`invalid_request` on both `read` and `subscribe`, because the read position and
+the echoed response state would otherwise disagree about where the page began.
+
+## Follow path
+
+`SyncClient.SyncClient` is the browser-safe service tag; `SyncClient.Sync` is
+its deprecated former name. `make({ client })` adapts an Effect RPC client and
+`layer` derives that client from `RpcClient.Protocol`.
+A subscription replays through `Sync.Read` until the server reports `done`,
+then follows through `Sync.Subscribe` in credit windows, replenishing each
+window by resubscribing from its matching delivered or applied progress.
+
+A frame or 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 run represented in a `Sync.Read` page's entries must have exactly one
+cursor with an explicit generation matching the request, 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.
+
+Transport, authentication, and reconnect are handled here rather than left to
+the application. A live follow that loses its transport reconnects under
+exponential backoff capped at five seconds, resuming from the subscription's
+progress; gaps, authorization refusals, and server closes propagate to the
+consumer instead of retrying.
+
+A delivery bookmark names what was delivered. `SubscribeOptions.apply`
+additionally records `progress.applied`: the callback runs to success before
+that cursor moves, so a failed application is retried by the next applying
+subscription. A delivery-only subscription cannot acknowledge application.
+
+`apply` and `onResync` fail with the consumer's own error types, and
+`subscribe` returns `Stream<Entry, SyncError | SyncGapError | EApply | EResync>`.
+A consumer failure keeps its own type, so it never borrows a wire code and
+never passes `SyncError.is`.
+
+## Compaction and resync
+
+Compaction deletes a run's entries below a checkpoint, so a cursor under that
+floor names history that no longer exists. The server maps the journal's
+`compacted` failure onto its own code with the run id the read was issued for,
+and `SyncError.resync` carries `{ runId, checkpointSeq, generation }`. The client
+fails closed unless `onResync` restores a snapshot and returns its
+`{ runId, afterSeq }`. It validates that receipt before advancing to the actual
+restored sequence, in the refusal's generation unless the receipt names its own. A
+checkpoint at or below what the subscription already covers cannot move the
+cursor forward, so it stays a failure rather than a retry of the same refusal.
+
+:::warning
+The resync moves a cursor, not state. The entries below `checkpointSeq` are
+gone from the journal. `SyncClient.snapshot` can fetch a configured public
+projection, but does not apply it. `SubscribeOptions.onResync` is the seam a consumer fills that hole
+through: it runs BEFORE the cursor moves and must return a valid restored cursor, so a failure leaves
+the cursor where it was and nothing is skipped silently. A Node follower reads
+the prefix from `Journal.latestCheckpoint(runId)` and applies it. With no handler,
+the original refusal is preserved. A consumer that cannot restore the prefix
+must not return an applied receipt for it. Durable consumers must commit snapshot state and
+their durable cursor in their own transaction; the client cursor is in memory.
+:::
+
+## Errors
+
+`ErrorCode` includes `unsupported` (since 1.0.0) for unavailable host
+operations or presence transport; it does not mean an empty roster.
+
+`SyncError` carries a stable `code` from `ErrorCode`, a `message`, an optional
+bounded `cause` string, and a `resync` that is set only on `compacted`.
+`SyncGapError` reports a server interval that starts beyond the client's
+covered cursor.
+
+`cause` is a STRING and never the host object that failed. `SyncError` is the
+declared error schema of every RPC in both groups, so what it carries reaches a
+remote follower that may hold nothing but a branch share link: a journal
+failure crosses as its stable journal code, never as the driver's own sentence,
+and the public message names the run rather than the storage fault.
+
+`SyncError.is` is a structural check: the tag, a declared `code`, a string
+`message`, and a `resync` only alongside `compacted`. It deliberately does not
+require the prototype, because every value that reaches it has crossed a
+boundary that rebuilds it.
+
+## Branch collaboration
+
+`BranchPresence.Service.presenceOn(request)` (since 1.0.0) returns
+`"unknown" | "present" | "empty"`, authorizing read access first. It stays
+`unknown` for one configured `leaseMs` after startup so live participants can
+re-announce, and while any required heartbeat source is unavailable. Treat
+`unknown` as present for safe-idle decisions.
+
+`PresenceOptions.sourcesReady(branchId)` (since 1.0.0) supplies an
+`Effect<boolean>` readiness check for authorization, revocation, bridge and
+session sources. It defaults to unavailable.
+
+`BranchPresence.makeNoop()` and `layerNoop` fail announce, leave and list with
+`unsupported`; `presenceOn` returns `unknown`. Consequently
+`BranchServer` roster reads and watches also fail with `unsupported` under
+`layerNoop`, rather than reporting an empty roster.
+
+A branch is one shared live document whose durable state is exactly one journal
+run (`BranchProtocol.branchRunId`), so multiplayer reuses the canonical `seq`,
+cursors, gap detection, and resumable follow rather than introducing a second
+source of truth. Presence is a lease and is never journalled. Commands are
+admitted through a client-minted idempotency key whose exactly-once constraint
+is the journal's own producer identity, so two servers racing one command
+collide durably inside the write transaction.
+
+`BranchRpcs` is the wire group and `BranchServer.layerHandlers` projects the
+branch services onto it. The payload schemas ARE the service schemas, so the
+wire and the services cannot drift about what a legal message is.
+
+:::warning
+Branch collaboration ships unserved at 1.0.0-rc.0.
+[`@smthrs/gateway`](/api/gateway) mounts `SyncRpcs` on `POST /sync` and
+`/sync/ws`; nothing outside this package's own tests mounts `BranchRpcs`, so
+the seven branch procedures have no integration against a real gateway yet.
+Treat the branch modules as a library surface pending a host, not as a served
+endpoint.
+:::
+
+## Test helpers
+
+| Export                                                               | Source                                                                                                                         | Notes                                                  |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
+| `TestSync.layerTest`, `layerTrustAllAsOwner`, `layerNoop`, `connect` | [src/test/TestSync.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/sync/src/test/TestSync.ts)     | a real server and client over an in-memory socket pair |
+| `TestSocket.makePair`, `Pair`, `TestFaults`, `FrameFilter`           | [src/test/TestSocket.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/sync/src/test/TestSocket.ts) | fault-injecting socket pair                            |
+
+Subscription fan-out is held to budgets, not only to frame assertions. The
+package's soak suite runs five concurrent workspace subscribers and requires an
+identical frame set from each, drains 200 subscribe and complete cycles and
+requires every per-run journal stream to be released afterwards, and soaks 200
+five-subscriber rounds under a retained-heap budget. A regression that retains
+per-subscriber state satisfies every frame assertion elsewhere, so those are
+the checks that catch it.
+
+The optional [long soak tier](./guides/run-a-long-soak.md) adds repeated
+post-warmup resource samples, growth slopes, real TCP reconnects, on-disk
+compaction and checkpoint retention, and a stalled subscriber. It writes a
+machine-verifiable JSON artifact; ordinary PR gates do not start a timed run.
+
+### Rewind generations
+
+`ReadRequest` and `SubscribeRequest` carry `protocolVersion: 1`. The server
+refuses a missing or different version with typed `protocol_violation`.
+Server cursors and entry frames always carry a nonnegative `generation`,
+including zero; a client refuses missing response generations with the same
+error before delivery. Persisted request cursors may omit generation for zero.
+Persist the returned
+generation alongside `afterSeq`. A mismatch raises `lineage_changed` before
+sequence deduplication. Server errors carry
+`rewind: { runId, generation, afterSeq }`, where `afterSeq` is the archive
+boundary (`-1` for a full reset). Rebuild the projection from the current
+retained history through that boundary, create a fresh client, and resume from
+that position. Idle subscriptions check generations at
+`tailIntervalMs`, as well as around journal reads.
+
+## Presence coordinates
+
+`BranchProtocol.PresenceWhere` validates file coordinates (a nonempty path and
+optional positive integer line), a terminal id, a step label, or a branch.
+`Participant.where` is optional so recorded frames without coordinates decode.
+A Leave with `sessionId` removes that seat; without it, Leave removes every seat
+for the participant, after verifying ownership of all matching seats.

package/docs/concepts/authorization.md

@@ -0,0 +1,117 @@
+---
+title: "Authorization"
+description: "The two fail-closed boundaries of the read path, the workspace principal and the branch capability that cross them, and why a subscription carries its own expiry."
+---
+
+Authorization in `@smthrs/sync` fails closed along two boundaries, and both are
+consulted on every request. Neither has a trusted pass-through: code that never
+authenticates reads nothing.
+
+## Boundary one: non-branch runs and workspace listings
+
+Every run whose id does not map to a branch is visible only to the workspace
+principal. `SyncPrincipal` is a `Context.Reference` whose default value is
+`SyncPrincipal.anonymous`, which is what makes the default posture closed
+rather than open. A workspace-scoped request and a run-scoped request for an
+engine run are both refused with `unauthorized` for an anonymous caller.
+
+There are exactly two ways to become the workspace principal:
+
+- **Over a transport.** `SyncAuth.layer` verifies the `WorkspaceShare`
+  capability presented in the `flows-sync-workspace` request header and
+  installs the resulting principal. A request with no header runs as anonymous.
+  A header that is present but malformed, forged, expired, or signed by an
+  unknown key is refused outright rather than downgraded to anonymity, because
+  presenting a credential is a claim and a false claim is not the same thing as
+  no claim.
+- **In process.** A caller that already owns the journal provides
+  `SyncPrincipal.layerWorkspace(capabilityId)` itself. That is the sanctioned
+  bypass, and it is never a transport's to take.
+
+Every decode failure of the header folds to the same `unauthorized` refusal, so
+the header is not a parsing oracle for an attacker probing its shape.
+
+## Boundary two: branch runs
+
+A run whose id carries the branch prefix is visible only when the request's own
+`capability` verifies for that branch through `BranchShare`. The capability
+travels in the request payload, not in a header, because a share link is a
+per-branch credential rather than a per-connection one.
+
+The two boundaries compose rather than override each other:
+
+- An explicitly scoped branch read with no capability fails.
+- A workspace listing excludes the branch runs the caller's capability does not
+  cover, so one share link never leaks another branch's log.
+- With no `BranchShare` service in scope at all, every branch run is closed.
+- A connection holding only a branch share link can never read an engine run,
+  because that is boundary one's question and the link does not answer it.
+
+## What a capability is
+
+Both authorities mint the same shape: a claim set plus an HMAC-SHA-256
+signature over a length-prefixed canonical encoding of it, compared in constant
+time. A capability names one subject, one access level (`read` or `write`), and
+one expiry. The holder cannot widen it because widening changes the claims and
+therefore the signature.
+
+Three details make that hold up:
+
+- **Length prefixes.** Without them a subject id ending in the separator could
+  be re-cut into a different, still validly signed claim set. Prefixes count
+  UTF-8 bytes, and a claim set that does not survive UTF-8 encoding, such as
+  one carrying an unpaired surrogate, is refused with `invalid_request` rather
+  than signed.
+- **A scheme label leading the encoding.** A branch signature can never verify
+  as a workspace signature, even if one secret is misconfigured into both
+  authorities.
+- **`Redacted` secrets.** A keyring never holds a plain string, so a log, a
+  span, or an inspection of the options object cannot render it.
+
+Both authorities carry a `kid` inside the signed claims. The verifier both
+selects the right key and refuses a capability whose key name was swapped after
+minting, which is what lets a deployment rotate keys while capabilities minted
+under a retired key are still outstanding. The keyrings are separate:
+`BranchShare.layerConfig` provisions the branch authority from
+`SMITHERS_SYNC_BRANCH_SECRET` and `SMITHERS_SYNC_BRANCH_KEY_ID`, so rotating
+one credential leaves the other's outstanding capabilities alone. See
+[Authorize a connection](../guides/authorize-a-connection.md).
+
+## A subscription carries its own deadline
+
+A signed expiry is this package's only revocation mechanism, and a subscription
+is not a sequence of requests. It is authorized once, at open, and then
+streams. Without a deadline travelling with the identity, a holder of an
+expired capability could keep reading for as long as it declined to disconnect.
+
+So the expiry is on the principal itself, as
+`SyncPrincipal.Workspace.expiresAtMs`, or on the branch capability's own
+`expiresAtMs`, and the stream ends with `unauthorized` when that moment
+arrives. An in-process owner that provided `SyncPrincipal` directly presented no
+credential, so its `expiresAtMs` is `Infinity` and no deadline applies.
+
+## Two stages on the branch side
+
+Opening a branch is a bootstrap: no capability for it can exist yet.
+`Branch.CreateBranch` therefore requires an authenticated workspace principal
+supplied by the same `SyncAuth` middleware, and its handler refuses any other
+principal. Every later branch procedure carries its own capability and
+authorizes through `BranchShare`, so past the bootstrap the capability is the
+credential.
+
+`Branch.MintShare` requires write access to the branch, so only a collaborator
+can invite one, and the minted link never outlives the capability it was minted
+from. The handler rechecks the parent expiry after generating the child ID.
+It passes the parent's absolute expiry as `BranchShare.mint`'s
+`maxExpiresAtMs`; the authority clamps the requested TTL against that ceiling
+using the clock read that sets `issuedAtMs`. If the ceiling has elapsed,
+minting fails with `unauthorized`.
+
+## Related pages
+
+- [Authorize a connection](../guides/authorize-a-connection.md): minting,
+  presenting, and rotating a workspace capability.
+- [Branch collaboration](./branches.md): what a branch capability authorizes
+  beyond reading.
+- [Troubleshooting](../troubleshooting.md): the `unauthorized` symptoms and
+  what each one means.

package/docs/concepts/branches.md

@@ -0,0 +1,195 @@
+---
+title: "Branch collaboration"
+description: "A branch is one shared live document whose durable state is exactly one journal run: how commands are admitted exactly once, why presence is never journalled, and what the projection guarantees."
+---
+
+:::warning
+Branch collaboration ships unserved at 1.0.0-rc.0.
+[`@smthrs/gateway`](/api/gateway) mounts `SyncRpcs` on `POST /sync` and
+`/sync/ws`; nothing outside this package's own tests mounts `BranchRpcs`, so
+the seven branch procedures have no integration against a real host yet. Treat
+these modules as a library surface pending a host, not as a served endpoint.
+:::
+
+A branch is one shared live document that several people edit at once. It has
+no store of its own. Its durable state is exactly one journal run, and
+`BranchProtocol.branchRunId` is the only mapping:
+
+```ts
+import * as BranchProtocol from "@smthrs/sync/BranchProtocol"
+
+const branchId = "design-review" as BranchProtocol.BranchId
+const runId = BranchProtocol.branchRunId(branchId)
+```
+
+That single decision is what the rest of the design rests on. Every replication
+guarantee the read path already provides carries over unchanged: the canonical
+per-run `seq`, exclusive cursors, gap detection, resumable follow. Multiplayer
+introduces no second source of truth, and a branch is followed with the same
+`SyncClient.subscribe` call any other run is followed with.
+
+`BranchProtocol.branchOfRunId` reverses the mapping, and returns `null` for a
+run that is not a branch. The bare prefix with nothing after it is a non-branch
+run rather than a branch with an empty id, because `BranchId` is a branded
+non-empty string and branding `""` would hand a value the brand forbids to
+`share.verify`.
+
+## Commands are admitted exactly once
+
+Three things look identical from the server's side: an optimistic client
+re-sending after a timeout, a reconnecting client flushing its outbox, and two
+people pressing the same button at once. All three must produce exactly one
+durable command.
+
+The client mints a `CommandId` once per user intent and reuses it across
+optimistic application, retransmission, and concurrent submission. That is what
+makes it an idempotency key rather than a correlation id.
+
+The constraint is durable, not process-local. Every append carries the journal
+producer identity `(branch run, commandSourceId(commandId), commandSourceSeq)`,
+which the journal enforces inside its own write transaction. Two independently
+constructed servers racing the same command therefore collide in the journal:
+one appends, and the other receives a duplicate receipt or an idempotency
+conflict and resolves the canonical sequence by replaying the branch.
+
+`commandSourceSeq` is fixed at 0 and supplied explicitly. Letting the journal
+allocate a sequence would hand a resubmission after a lost response a fresh
+identity, and therefore a second durable append.
+
+A `CommandReceipt` reports `admitted` or `duplicate`, and both are successes.
+`duplicate` names the canonical sequence the original submission already
+occupies, so a retransmitting client settles its optimistic row instead of
+executing the command twice.
+
+`BranchCommands` keeps an in-memory receipt ledger, a per-branch admission
+permit, and a replay cursor. All three are a fast path: they answer known
+duplicates without a journal write and keep a restarted server from
+re-executing history. Correctness never depends on them, which is what makes it
+safe to bound them. See the ledger, hydration, and command size bounds in the
+[API reference](../api.md).
+
+## One event type, one decoder
+
+A branch journal has exactly one durable event shape,
+`BranchProtocol.CommandEvent`. Chat messages, edits, and flow launches are all
+commands, so the projection has exactly one decoder. `branch.say` is the
+command that appends a chat message; a command's `target` names the shared
+field it durably edits and is `""` for one that only appends.
+
+A command's `participantId` is whatever the submitting client claimed.
+`BranchCommands.submit` stamps the verified `capabilityId` of the share
+capability that sent it onto the durable payload, and the projection carries it
+on every message, applied command, and field. Attribute a command by its
+`capabilityId`; a row admitted before the field existed decodes it as `""`.
+
+Sync admission and command hydration validate known command records before
+advancing progress. Malformed commands and foreign run/branch identities fail
+typed; they cannot become a partial hydration or a new durable write. Hydration
+stages a bounded receipt map and commits it with the replay cursor only after
+all pages in that replay succeed. Existing decoding defaults for absent `args`
+and `target` remain in force. Malformed retained records require explicit
+repair by their authority; this package never rewrites them or silently treats
+them as successful commands.
+
+`BranchProjection.apply` and `project` are pure folds over admitted canonical
+records, not admission APIs. Their convergence rules permit redelivery and
+reordering of that canonical set. Use the validated sync read path before
+folding transport or host input. The read path rejects malformed known records
+before those pure folds can ignore them.
+
+## Presence is a lease, and is never journalled
+
+A roster is a lease table. Every announcement extends a lease, and a
+participant that stops announcing, because the tab closed or the process died,
+ages out without anyone reporting the disconnect. An announcement is idempotent
+and the same shape serves join, heartbeat, and cursor movement, so a client that
+reconnects simply announces again.
+
+Writing presence to the journal would make "who was looking at this" part of the
+durable, replayable history of a run. That is both unbounded and wrong:
+replaying a branch must not resurrect a stranger's caret.
+
+Announcing requires write access, so a read-only share link may watch the roster
+but never appears on it, and a shared read link cannot be used to impersonate a
+collaborator. A live participant is bound to the verified `capabilityId` that
+first announced it: an announce or leave for that `participantId` under any
+other capability is refused with `unauthorized` until the lease lapses, so one
+write link cannot rename, move, or evict another link's participant. Holders of
+the same link share its `capabilityId` and are not told apart. A branch holds at most
+`BranchPresence.defaultMaxParticipants` participants at once; a further announce
+is refused with `backpressure`.
+
+`BranchPresence.list` is authoritative and `changes` is only a low-latency wake.
+Each announcement or list drops that branch's expired leases and sweeps up to
+16 branch rosters for expired participants, deleting empty maps. The sweep
+resumes where the previous call stopped, so activity on other branches reclaims
+abandoned rosters. An idle registry retains expired storage until activity
+resumes; no timer fiber is needed. Both operations return detached participant
+and cursor values, so callers cannot mutate the stored roster through a result.
+
+A watcher re-lists once per lease as well as on every change, because a lapsed
+lease publishes nothing: a watch driven by change events alone would never
+observe the last participant leaving.
+
+## The projection converges
+
+`BranchProjection` folds journal entries into what two people looking at the
+same branch must agree on: the message timeline, the applied commands, and the
+current value of each durably edited field.
+
+The fold is order-independent over the canonical entry set, which makes
+convergence a property rather than a hope. Any two clients that have applied the
+same set of entries hold the same state, whatever order their transports
+delivered frames in and however many times a frame arrived. Three guards do the
+work:
+
+- an entry from another branch's run is ignored, so a mis-routed frame cannot
+  leak into a projection;
+- an entry already folded, whether the cursor tip redelivered or a command id
+  already applied, is ignored, so an at-least-once transport cannot double-apply
+  a user action;
+- an entry below the cursor whose command was never applied is folded into its
+  canonical `seq` position, so out-of-order delivery converges instead of
+  permanently dropping the late entry.
+
+Two durable edits of the same field are resolved by highest canonical sequence,
+with a lexicographic `participantId` tie-break. The rule is deliberately not
+wall-clock based: client clocks disagree, and a merge rule that depends on them
+is not deterministic.
+
+## The wire group
+
+`BranchRpcs` carries seven procedures: `Branch.CreateBranch`,
+`Branch.MintShare`, `Branch.Submit`, `Branch.Announce`, `Branch.Leave`,
+`Branch.Roster`, and `Branch.WatchRoster`. `BranchServer.layerHandlers` projects
+the branch services onto them. Five procedures forward to the service that owns
+their boundary and add nothing: `Branch.Submit` to `BranchCommands`,
+`Branch.Announce`, `Branch.Leave`, `Branch.Roster`, and `Branch.WatchRoster`
+to `BranchPresence`. For those, an in-process caller and a remote caller face
+the same rules.
+
+Two procedures enforce policy in the adapter itself, on top of what
+`BranchShare` checks:
+
+- `Branch.CreateBranch` refuses any principal that is not an authenticated
+  workspace with `unauthorized` before it mints the first capability;
+- `Branch.MintShare` verifies the presented capability for write access to the
+  branch, refuses an expired parent with `unauthorized`, and passes the parent's
+  expiry as `maxExpiresAtMs` so the child never outlives it.
+
+`BranchShare.mint` performs none of those checks. It decodes its request, so a
+malformed id or ttl is refused with `invalid_request`, but an in-process host
+that mints through the service directly must gate the principal and the parent
+capability itself or it hands out branches and links the wire would refuse.
+
+The payload schemas **are** the service schemas rather than copies of them, so
+the wire and the services cannot drift about what a legal message is.
+
+For the two-stage authorization the group uses, see
+[Authorization](./authorization.md).
+
+## Related pages
+
+- [Authorization](./authorization.md): what a branch capability grants and how
+  it is checked.
+- [API reference](../api.md): every branch export, with its bounds and defaults.