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

package/CHANGELOG.md

@@ -0,0 +1,208 @@
+# @smthrs/sync
+
+## Unreleased
+
+### Security
+
+- **Breaking.** `BranchShare` and `WorkspaceShare` keyrings refuse a signing
+  secret shorter than 32 bytes of UTF-8 with `invalid_request`. One observed
+  capability let an attacker search a short secret offline and forge
+  capabilities.
+- `BranchPresence` binds a live participant to the `capabilityId` that
+  announced it. Another capability's announce or leave for that participant is
+  refused with `unauthorized` until the lease lapses.
+- `BranchCommands.submit` stamps the verified `capabilityId` on the durable
+  command payload, and `BranchProjection` carries it on every message, command,
+  and field, so a command is attributed to the capability that sent it rather
+  than to the `participantId` the client claimed.
+- **Breaking.** `TestSync.layerWorkspaceAuth` is renamed
+  `TestSync.layerTrustAllAsOwner` so a composition that trusts every
+  connection as the owner says so where it is wired.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added workspace authentication: the `SyncAuth` RPC middleware and its
+  header-verifying implementation, the `WorkspaceShare` capability authority
+  over a `Redacted` keyring with `kid` rotation, and the per-request
+  `SyncPrincipal` whose default is anonymous.
+- Added compaction recovery: `SyncProtocol.Resync`, the `compacted` error code
+  and `SyncError.resync`, and the client-side resync that moves a run's cursor
+  to the checkpoint and restarts instead of dying.
+- Added `SubscribeOptions.onResync`, the seam a consumer restores checkpoint
+  state through. It runs before the cursor moves and must succeed, so a
+  follower that cannot fill the hole fails rather than skipping it silently.
+- Added `SubscribeOptions.apply`, which advances a cursor only after the
+  consumer has applied the entry, so `RunCursor` can mean what its schema says.
+- Added the bounded workspace fan-out: `SyncServer.Options.concurrency` and
+  `tailIntervalMs`, plus `RunCatalog.makePolling` for the durable run set a
+  workspace follower learns from.
+- Added request limits `SyncProtocol.maxReadLimit` and `maxSubscribeCredit`,
+  the branch ledger bound `BranchCommands.defaultLedgerCapacity`, and the
+  roster bound `BranchPresence.defaultMaxParticipants`.
+- Added golden wire vectors: the encoded form of every frame variant, a read
+  response, a command receipt, the capability header, and both authorities'
+  signatures are frozen as literals, so a renamed field or a changed signing
+  encoding fails a test rather than a deployed follower.
+
+### Changed
+
+- **Breaking.** `SyncError.cause` is a bounded string rather than
+  `Schema.Unknown`. It is the declared error schema of every RPC, so it now
+  carries a rendering instead of the host object that failed; a journal
+  failure crosses as its stable journal code and never as the driver's own
+  message.
+- **Breaking.** `BranchShare.makeHmac` and `layerHmac` take a `Redacted`
+  keyring rather than a single secret, `ShareClaims` carries the signing `kid`,
+  and the branch scheme signs a scheme label, now `v2`, so a branch signature
+  can no longer be replayed as a workspace signature under a shared secret and
+  the branch secret rotates the way the workspace secret already did: the
+  retired key stays in the keyring until its links expire. `BranchShare`
+  gained `layerConfig`, which reads `SMITHERS_SYNC_BRANCH_SECRET` and
+  `SMITHERS_SYNC_BRANCH_KEY_ID`. Outstanding branch capabilities do not verify
+  under this release.
+- **Breaking.** The client's service tag is `SyncClient.SyncClient`, keyed
+  `@smthrs/sync/SyncClient`, matching every other service module.
+  `SyncClient.Sync` stays as a deprecated alias of the same tag for one
+  release.
+- **Breaking.** `SubscribeOptions.apply` and `onResync` fail with the
+  consumer's own error types, and `subscribe` returns
+  `Stream<Entry, SyncError | SyncGapError | EApply | EResync>`. A consumer's
+  transaction failure no longer has to borrow a wire code such as `unknown` or
+  `compacted`, so it can no longer be mistaken for a transport or protocol
+  failure or pass `SyncError.is`.
+- **Breaking.** `SyncProtocol.Progress` is
+  `{ delivered: WorkspaceCursor, applied: WorkspaceCursor }`. The
+  `DeliveredProgress` and `AppliedProgress` tagged wrappers are removed: they
+  never sat in a union, so their tags discriminated nothing. `Service.cursors`
+  is removed; read `progress.delivered` instead.
+- **Breaking.** `BranchCommands.submission` returns
+  `Effect<CommandSubmission, SyncError>`. It decodes the fields it fills in, so
+  a command name the schema forbids is the same typed refusal `submit` returns
+  one call later rather than a throw at the caller.
+- `BranchShare.mint` and `WorkspaceShare.mint` decode their request before
+  signing it. An empty `branchId` or `capabilityId` and a `ttlMs` of `0` or
+  `NaN` are refused with `invalid_request`; `ttlMs: 0` used to mint an
+  already-expired capability, and the others died where the declared type
+  promises a `SyncError`. `Branch.CreateBranch` decodes the id its `BranchIds`
+  port yields instead of branding it, so a host id source returning `""`
+  refuses rather than crashing the handler.
+- Both authorities verify through one pipeline, `shareSigner.verifyClaims`, so
+  the signature check, the expiry boundary, and the read-only refusal cannot
+  drift apart between them. `ShareHardening` asserts each against both.
+- **Breaking.** A subscription's `credit` must be between 1 and
+  `maxSubscribeCredit`, and a read's `limit` at most `maxReadLimit`. A cursor
+  set that names one run twice is refused with `invalid_request`.
+- **Breaking.** `BranchRpcs`'s submit, announce, leave, and roster payloads are
+  the service schemas rather than copies of them, so `displayName: ""` is a
+  typed wire refusal instead of a defect raised inside the presence service.
+- **Breaking.** The branch request schemas `SubmitRequest`, `Announcement`,
+  `RosterRequest`, and `LeaveRequest` live in `BranchProtocol` beside every
+  other branch wire shape, so `BranchRpcs` no longer imports the command ledger
+  or the presence registry. `BranchCommands.SubmitRequest`, the three
+  `BranchPresence` request schemas, and the `BranchRpcs` aliases
+  `SubmitPayload`, `AnnouncePayload`, `LeavePayload`, and `RosterPayload` are
+  removed. `BranchProtocol.CommandIdentity` is removed: the ledger reads a
+  command's id from the payload admission already decoded.
+- **Breaking.** `makeLiveWith`, `layerWith`, and `BranchPresence.layer` fail
+  with `invalid_request` when an option is not a positive safe integer.
+  `BranchPresence.Service` gained `leaseMs`.
+- A workspace subscription woken by an entry committed in this process reads
+  only the runs that entry named, rather than re-listing the catalog and
+  reading one page per covered run. The catalog-wide round still runs at open,
+  on an announcement, and once per `tailIntervalMs`, so removals, generation
+  changes, and other processes' writes are reconciled as before. The bounds
+  documentation now separates what a follower holds open, which the bounds
+  cap, from its per-run positions and per-round work, which scale with the
+  runs it covers.
+- A branch admitted after a workspace subscription opened ends the stream at
+  that branch's own expiry: the expiry interrupt re-arms when reconciliation
+  lowers the deadline, and a page checks the deadline before it emits, so a
+  journal read that spans the expiry serves nothing past it and a stalled read
+  cannot hold the subscription open.
+- An open subscription ends with `unauthorized` when the capability that
+  authorized it expires. Authorization was one-shot at open, so a share-link
+  holder could read past its own expiry by staying connected. That now covers a
+  branch a workspace subscription discovers AFTER it opened: reconciliation
+  carries the admitting capability's expiry into the subscription's deadline
+  rather than reducing the admission to a yes.
+- Catch-up paging defers its cursor snapshot, so every page past the first asks
+  from where the previous one ended instead of repeating the previous request.
+- Catch-up pages are validated the way live frames already were: scope,
+  per-run ordering, progress past the requested cursor, and cursor uniqueness,
+  refused as `protocol_violation` before any cursor moves.
+- A workspace subscription reconciles its covered run set against
+  `RunCatalog.list` every round, so a run the catalog gains becomes visible
+  without an announcement and a run it stops naming is no longer queried.
+- A workspace tail reads one bounded page per run per round, so a permanently
+  busy run wakes the next round instead of holding its fan-out slot.
+- A read shares its `limit` across the runs it covers before any run takes a
+  second helping. Filling in run order 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 server deduplicates `RunCatalog.list` at the seam. A host catalog that
+  named one run twice had it read twice from the same served position, so a
+  read page carried its entries twice and a subscription opened two concurrent
+  tails of it emitting identical frames.
+- `BranchCommands` keys its ledger and permit per branch, and `BranchPresence`
+  keys its roster per branch, so ids sharing a delimiter no longer collide and
+  one branch's replay no longer stalls another's writes.
+- `BranchCommands.replay` ends its walk on an empty page, matching the guard
+  the workspace tail already carried.
+- An admission conflict on a command whose receipt the bounded ledger has
+  already evicted reads the branch's durable history for it, so it is reported
+  as the duplicate it is instead of as a journal contradicting its own conflict
+  report.
+- `Branch.MintShare` refuses a parent capability that expired mid-request
+  rather than minting a link that can never authorize.
+- `BranchShare` and `WorkspaceShare` verify from a snapshot taken at entry, so
+  claims cannot widen while Web Crypto is in flight.
+- Share claims are refused with `invalid_request` when they do not survive
+  UTF-8, and length prefixes count UTF-8 bytes rather than UTF-16 units.
+- `encodedByteLength` is total: a value with no JSON text costs the bytes
+  `null` occupies, and a value JSON refuses measures as infinite so it trips
+  every ceiling rather than throwing.
+- `branchOfRunId` returns `null` for the bare branch prefix instead of
+  branding an empty string as a `BranchId`.
+- `RunCatalog.layerStatic` answers `list` with a fresh array, matching the
+  other implementations.
+- `BranchShare.makeNoop` and `WorkspaceShare.makeNoop` fail `mint` instead of
+  dying, matching their declared type and the rest of the package.
+- `SyncError.is` validates the code, the message, and the `resync` invariant
+  rather than trusting a bare tag, and answers rather than raising when a
+  field it reads throws.
+- `SubscribeOptions.credit` and `SyncClient.make`'s `bootstrapLimit` are
+  refused locally with `invalid_request` when they exceed the wire maxima. A
+  value only the wire schema rejected surfaced as a transport failure and the
+  follow retried it under backoff forever.
+- `SyncError.message` is bounded like `cause`, and a journal failure's rendered
+  code is bounded too, so no host string can be the largest thing an error
+  carries.
+- A journal failure whose code this boundary also declares crosses as that
+  code: `journal_closed` as `closed`, `queue_overflow` as `backpressure`, and
+  `decode_failed` as itself, on the read path and the branch write path alike.
+  Collapsing every code but `compacted` into `unknown` threw away a
+  classification the wire already carried, so a follower could not tell a
+  shut-down journal from an unexplained fault. A code with no counterpart here
+  stays `unknown`, and the journal's own message stays refused.
+- `apply` and `onResync` are handed values the committed position is
+  snapshotted from, so a consumer callback can no longer choose the cursor it
+  is being handed an entry for.
+- `Branch.WatchRoster` compares rosters by an injective rendering and
+  deduplicates its initial emission, so a change the old delimiter-joined key
+  hid is emitted and an unchanged roster is not sent twice.
+- `HeartbeatFrame` is documented as reserved: no server emits one, so a client
+  must not wait for it.
+- Documentation is package-owned and generated: `docs/pages/api/sync.md` and
+  the protocol section of `docs/pages/concepts/sync.md` come from this
+  package's JSDoc and `docs/`.
+
+## [0.1.0] - 2026-08-05
+
+### Added
+
+- Added the workspace read-path sync protocol with its server, client, and
+  run catalog.
+- Added the shared branch protocol, presence, projection, commands, share, and
+  RPCs, with authorization enforced on the server.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# @smthrs/sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://smithers-sync.smithers.sh
+
+Browser-safe, read-only replication of canonical
+[`@smthrs/journal`](https://journal.smithers.sh) entries. It defines the wire
+protocol, the RPC group, the server, and the replay-then-follow client.
+
+The read path, `SyncRpcs` served by `SyncServer` and followed by `SyncClient`,
+never writes to a journal, so a follower cannot corrupt what it reads.
+`BranchCommands` is the separate write surface: it appends admitted branch
+commands to a branch's journal run after verifying a write-scoped
+`BranchShare` capability.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+`effect` is a peer dependency at exactly `4.0.0-rc.115`. Two copies of `effect`
+in one program are two sets of service tags, so a client built against one copy
+cannot be provided to a program holding the other.
+
+Node.js 26.4.0 or later, or a browser with Web Crypto. The package ships as
+both ESM and CommonJS with TypeScript declarations.
+
+## Follow a run
+
+One `subscribe` call replays a run's durable history and then follows it live,
+through a single stream:
+
+```ts
+import type { JournalEvent } from "@smthrs/journal"
+import * as SyncClient from "@smthrs/sync/SyncClient"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Stream from "effect/Stream"
+import * as RpcClient from "effect/unstable/rpc/RpcClient"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+
+const runId = "build-42" as JournalEvent.RunId
+
+export const follow = Effect.gen(function*() {
+  const sync = yield* SyncClient.SyncClient
+  yield* sync.subscribe({ scope: { _tag: "Run", runId }, cursors: [] }).pipe(
+    Stream.runForEach((entry) => Effect.logInfo(`${entry.seq} ${entry.eventType}`))
+  )
+})
+
+export const clientLayer = SyncClient.layer.pipe(
+  Layer.provide(RpcClient.layerProtocolSocket()),
+  Layer.provide(RpcSerialization.layerJson)
+)
+```
+
+The socket that protocol runs over comes from your platform: a WebSocket in a
+browser, `@effect/platform-node`'s socket layer in Node. Pass
+`{ _tag: "Workspace" }` instead of a run scope to follow every run the server
+lists and your credential covers.
+
+The serving side is `SyncServer` over a journal and a run catalog.
+[`@smthrs/gateway`](https://gateway.smithers.sh) already mounts it on
+`POST /sync` and `/sync/ws`, so a follower against a Smithers gateway writes
+only the code above.
+
+`Read` pages durable entries, then the client subscribes from exclusive per-run
+cursors. A non-contiguous journal sequence is valid; `SyncGapError` means the
+server skipped beyond the interval covered by the client's cursor.
+
+`sync.progress` reports two cursor sets: `delivered` holds delivery bookmarks,
+and `applied` holds what successful `apply` or `onResync` callbacks
+acknowledged. Those callbacks fail with your own error types, which the
+subscription's error channel carries unchanged. Persist state and its cursor
+together inside those callbacks. An applying subscriber never skips entries
+merely because an earlier subscriber received them.
+
+## Authorization
+
+Authorization is fail-closed along two boundaries, and both are consulted on
+every request. Branch runs authorize through the branch share capability
+carried in each request (`BranchShare`); a share link grants exactly its
+branch's run. Non-branch runs and workspace listings authorize through the
+authenticated workspace principal (`SyncPrincipal`, default anonymous), which
+`SyncAuth.layer` establishes over RPC by verifying the `WorkspaceShare`
+capability presented in the `flows-sync-workspace` request header. A connection
+with no valid credential is refused every non-branch read.
+
+Both authorities take `Redacted` keyrings, lead their signed encoding with a
+scheme label, and carry a rotation-ready `kid` inside the signed claims. An
+open subscription ends with `unauthorized` when the credential that opened it
+expires, because a stream authorized once at open is otherwise the one thing a
+signed expiry cannot revoke. See
+[Authorization](https://smithers-sync.smithers.sh/concepts/authorization/).
+
+## Branch collaboration
+
+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; every branch operation after
+`Branch.CreateBranch` authorizes through a signed, expiring, branch-scoped
+share capability.
+
+The native gateway mounts the existing branch presence RPCs at `POST /branch`
+when its authenticated runtime bridge is configured. The Go install resolves
+membership, branch and socket session before forwarding; this host adapter uses
+the same `BranchPresence` lease roster. Branch commands and share-link bootstrap
+remain unserved on that mount. See
+[Branch collaboration](https://smithers-sync.smithers.sh/concepts/branches/).
+
+## Bounds
+
+Every in-flight surface is bounded: entries per page, frames per subscription,
+journal reads open per workspace subscription, bytes per frame. What one
+follower holds open is a function of the configured bound, not of how far
+behind it has fallen. Bookkeeping and periodic work still scale with the
+workspace: a workspace subscription keeps a position for every run it has
+covered, and its catalog-wide round, once per `tailIntervalMs` or on an
+announcement, reads one page per listed run under the concurrency bound. A
+wake for a local append reads only the run it named. Every numeric option is
+validated where it enters: a value that is not a positive safe integer fails
+the constructor with `invalid_request` rather than quietly disabling the
+comparison it configures.
+The table of bounds and defaults is in the
+[API reference](https://smithers-sync.smithers.sh/reference/api/#bounds).
+
+Both change feeds slide rather than block, and neither 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, so a dropped notification costs
+latency and never state.
+
+## Rewinds and cursor generations
+
+`RunCursor` and `EntriesFrame` carry a `generation`. Server responses always
+include it, zero included, and a client refuses one that omits it; a persisted
+request cursor may omit it for generation zero. SQL journals persist it
+independently of sequence numbers. Rewind increments it atomically with
+truncation, so a follower at 100 cannot silently discard a replacement entry at
+51 after rewinding to 50.
+
+Both reads and subscriptions fail with `SyncError.code = "lineage_changed"`
+when generations differ. Live run and workspace subscriptions also check while
+idle, within `tailIntervalMs`. This failure is terminal: rebuild the projection
+from the current retained history through the archive boundary, create a fresh
+sync client, and resume from the server error's
+`rewind: { runId, generation, afterSeq }`. For `afterSeq: -1`, omit the cursor
+to replay the entire current history. Keep the generation with every persisted
+cursor. Compaction recovery remains separate.
+
+Append-only journal adapters may omit `Journal.Service.generation`. Any adapter
+that truncates or replaces history must implement it and advance the generation
+in its truncation transaction. Upgrade sync clients and servers together;
+older clients cannot detect generation changes. See
+[Rewind generations](https://smithers-sync.smithers.sh/reference/api/#rewind-generations).
+
+## Public API
+
+The root exports these namespaces, also available from matching
+`@smthrs/sync/*` subpaths. The
+[API reference](https://smithers-sync.smithers.sh/reference/api/) documents
+each one.
+
+| Namespace          | What it owns                                                                                                    |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `SyncError`        | `ErrorCode`, `SyncError` with the structural guard `SyncError.is`, and terminal `SyncGapError`.                 |
+| `SyncProtocol`     | Scopes, cursors, `Resync`, request and response schemas, frames, and the size and request limits.               |
+| `SyncRpcs`         | The read-path RPC group (`Sync.Read`, `Sync.Subscribe`, `Sync.Snapshot`) and the `SyncAuth` middleware service. |
+| `SyncAuth`         | Implementations of that middleware: `layer`, `layerClient`, and the header codec.                               |
+| `SyncPrincipal`    | The per-request identity reference, its constructors, and `layerWorkspace` for in-process owners.               |
+| `WorkspaceShare`   | The workspace capability authority over a `Redacted` keyring with `kid` rotation.                               |
+| `RunCatalog`       | The workspace run set a subscription reconciles against, in-memory, polling, and static forms.                  |
+| `SyncServer`       | The read-path implementation, its policy, and `layerHandlers`.                                                  |
+| `SyncClient`       | The browser-safe replay-then-follow client and its subscription options.                                        |
+| `BranchProtocol`   | The branch vocabulary: ids, claims, capabilities, submissions, receipts, and the run-id mapping.                |
+| `BranchShare`      | The branch capability authority over a `Redacted` keyring with `kid` rotation.                                  |
+| `BranchIds`        | The port branch and capability ids are minted through.                                                          |
+| `BranchCommands`   | Idempotent command admission onto a branch's journal run.                                                       |
+| `BranchPresence`   | The ephemeral, lease-expiring roster.                                                                           |
+| `BranchProjection` | The fold from branch commands to a document view.                                                               |
+| `BranchRpcs`       | The branch collaboration wire group.                                                                            |
+| `BranchServer`     | The handler layer that projects the branch services onto that group.                                            |
+
+Public test subpaths are `@smthrs/sync/test/TestSocket` (`FrameFilter`,
+`TestFaults`, `Pair`, `makePair`) and `@smthrs/sync/test/TestSync`
+(`layerTest`, `layerTrustAllAsOwner`, `layerNoop`, `connect`).
+
+## Documentation
+
+- [Installation](https://smithers-sync.smithers.sh/installation/)
+- [Quickstart](https://smithers-sync.smithers.sh/quickstart/)
+- [Scopes and cursors](https://smithers-sync.smithers.sh/concepts/scopes-and-cursors/)
+- [Replay then follow](https://smithers-sync.smithers.sh/concepts/replay-then-follow/)
+- [Authorization](https://smithers-sync.smithers.sh/concepts/authorization/)
+- [Follow a run](https://smithers-sync.smithers.sh/guides/follow-a-run/)
+- [Serve the read path](https://smithers-sync.smithers.sh/guides/serve-the-read-path/)
+- [Wire protocol](https://smithers-sync.smithers.sh/protocol/)
+- [API reference](https://smithers-sync.smithers.sh/reference/api/)
+- [Troubleshooting](https://smithers-sync.smithers.sh/troubleshooting/)
+- [Optional long soak](docs/guides/run-a-long-soak.md)
+
+## License
+
+MIT

package/dist/cjs/BranchCommands.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Idempotent admission of collaborative commands onto a branch document.
+ *
+ * Three different 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 — and all three must
+ * produce exactly one durable command. The client-minted `commandId` is the
+ * idempotency key for all three.
+ *
+ * The exactly-once constraint is durable, not process-local: every append
+ * carries the producer identity `(branch run, commandSourceId(commandId),
+ * commandSourceSeq)`, which the journal enforces inside its own write
+ * transaction. Two independently constructed servers that race the same
+ * command therefore collide in the journal — one appends, the other receives
+ * a duplicate receipt or an idempotency conflict and resolves the canonical
+ * sequence by replaying the branch (audit finding F-14). The in-memory
+ * ledger, permit, and replay cursor are a fast path only: they answer known
+ * duplicates without a journal write and keep a restarted server from
+ * re-executing history, but correctness never depends on them.
+ *
+ * @since 0.1.0
+ */
+import { Journal } from "@smthrs/journal";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Scope from "effect/Scope";
+import { type BranchId, type CommandId, CommandReceipt, CommandSubmission, SubmitRequest } from "./BranchProtocol.ts";
+import * as BranchShare from "./BranchShare.ts";
+import { SyncError } from "./SyncError.ts";
+/**
+ * Branch command admission operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly submit: (request: SubmitRequest) => Effect.Effect<CommandReceipt, SyncError>;
+}
+declare const BranchCommands_base: Context.ServiceClass<BranchCommands, "@smthrs/sync/BranchCommands", Service>;
+/**
+ * The branch command ledger.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class BranchCommands extends BranchCommands_base {
+}
+/**
+ * Constructs a command ledger that admits nothing.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides a command ledger that admits nothing.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<BranchCommands>;
+/**
+ * Receipts one branch keeps in memory before the oldest are evicted.
+ *
+ * The ledger is a fast path: it answers a known duplicate without a journal
+ * write, and losing an entry costs a round trip, never correctness, because
+ * the journal's own producer identity is the durable exactly-once constraint
+ * and returns a `Duplicate` receipt for a command already admitted. Retaining
+ * one receipt per command forever meant a process serving a hundred branches
+ * of a hundred thousand commands held ten million of them, so the fast path
+ * is bounded and the durable path is what makes it safe to bound.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultLedgerCapacity = 4096;
+/**
+ * Inclusive UTF-8 JSON submission ceiling. The separate sync entry ceiling
+ * leaves room for the durable envelope around every admitted command.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxCommandBytes: number;
+/**
+ * Milliseconds a branch may have no active submissions before its in-memory state is
+ * dropped.
+ *
+ * The receipt ledger is bounded per branch; this bounds the branches. A
+ * dropped branch re-hydrates on its next submission exactly as it does after
+ * a restart, so eviction costs a journal read, never correctness. The default
+ * is the longest lifetime a branch capability may carry, so a branch is only
+ * dropped once every capability minted at its last touch can have expired.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultBranchIdleMs: number;
+/**
+ * Entries one branch's first-touch hydration reads before it stops.
+ *
+ * Hydration is the only full history read that ever sat on the WRITE path: the
+ * first submission a process makes to a branch paged that branch's whole
+ * durable log, 256 entries at a time, while holding the branch's admission
+ * permit, before its own append was attempted. A hundred-thousand-entry branch
+ * therefore charged its next writer four hundred journal reads for a fast path
+ * that keeps four thousand receipts.
+ *
+ * The budget defaults to {@link defaultLedgerCapacity} because hydration
+ * cannot seed more receipts than the ledger holds: everything a longer walk
+ * records displaces something the same walk already recorded. What the extra
+ * reads buy is a FRESHER selection — the tail of history rather than its head
+ * — and the price is an unbounded wait on somebody's write. This trades that
+ * back: the walk stops, the cursor stays where it stopped, and a later replay
+ * continues forward from there.
+ *
+ * A branch longer than the budget starts with a partly cold fast path and
+ * nothing else. Correctness never rested on the ledger: the journal's producer
+ * identity is the durable exactly-once constraint, an exact retry receives a
+ * `Duplicate` receipt carrying the canonical sequence, and an
+ * `idempotency_conflict` is resolved by a read of the whole history that the
+ * ledger's own bound already made necessary.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultHydrationLimit = 4096;
+/**
+ * Admission policy.
+ *
+ * The default caps one encoded command submission at 1 MiB, one branch's
+ * in-memory receipt ledger at {@link defaultLedgerCapacity} commands, and one
+ * branch's first-touch hydration at {@link defaultHydrationLimit} entries.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    /**
+     * Largest encoded journal entry followers accept. Defaults to
+     * {@link SyncProtocol.defaultMaxFrameBytes}. Configure the server and client
+     * with the same or a larger ceiling. Admission reserves the full durable
+     * envelope, including generated sequence and timestamp fields, before writing.
+     */
+    readonly maxFrameBytes?: number | undefined;
+    /**
+     * Largest encoded command submission admitted, in bytes. Defaults to
+     * {@link defaultMaxCommandBytes}.
+     */
+    readonly maxCommandBytes?: number | undefined;
+    /**
+     * Receipts one branch keeps in memory before the oldest are evicted.
+     * Defaults to {@link defaultLedgerCapacity}.
+     */
+    readonly ledgerCapacity?: number | undefined;
+    /**
+     * Entries one branch's first-touch hydration reads before it stops.
+     * Defaults to {@link defaultHydrationLimit}.
+     */
+    readonly hydrationLimit?: number | undefined;
+    /**
+     * Milliseconds a branch may have no active submissions before its in-memory state is
+     * dropped. Defaults to {@link defaultBranchIdleMs}.
+     */
+    readonly branchIdleMs?: number | undefined;
+}
+/**
+ * Constructs the journal-backed branch command ledger under an explicit
+ * policy. The caller scope owns cached states and their idle-expiration timers.
+ *
+ * A submission whose encoded form exceeds the command ceiling is refused with
+ * `frame_too_large` before anything is appended, so one oversized `args`
+ * cannot enter the branch journal and poison every follower that replays it.
+ *
+ * First-touch hydration reads at most `hydrationLimit` entries, so the length
+ * of a branch's history is not charged to the next writer's latency; see
+ * {@link defaultHydrationLimit} for why the fast path may be seeded partially
+ * without any effect on what the ledger admits.
+ *
+ * Every option is validated as a positive safe integer at construction: the
+ * TypeScript type says `number`, and `NaN` silently disabled the ceiling it
+ * was compared against.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeLiveWith: (options?: Options) => Effect.Effect<Service, SyncError, Journal.Journal | BranchShare.BranchShare | Scope.Scope>;
+/**
+ * Constructs the journal-backed branch command ledger with default policy.
+ * The caller scope owns cached states and their idle-expiration timers.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeLive: Effect.Effect<Service, never, Journal.Journal | BranchShare.BranchShare | Scope.Scope>;
+/**
+ * Provides the journal-backed branch command ledger.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<BranchCommands, never, Journal.Journal | BranchShare.BranchShare>;
+/**
+ * Provides the journal-backed branch command ledger under an explicit policy.
+ * Fails with `invalid_request` when an option is not a positive safe integer.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerWith: (options: Options) => Layer.Layer<BranchCommands, SyncError, Journal.Journal | BranchShare.BranchShare>;
+/**
+ * Builds a submission, filling in the fields a plain command never sets, and
+ * refusing a field the schema forbids with a `SyncError` rather than a defect.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const submission: (fields: {
+    readonly branchId: BranchId;
+    readonly commandId: CommandId;
+    readonly participantId: CommandSubmission["participantId"];
+    readonly name: string;
+    readonly args?: string;
+    readonly target?: string;
+}) => Effect.Effect<CommandSubmission, SyncError>;
+export {};
+//# sourceMappingURL=BranchCommands.d.ts.map