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

package/src/BranchProjection.ts

@@ -0,0 +1,308 @@
+/**
+ * The branch document projection: journal entries folded into what two people
+ * looking at the same branch must agree on.
+ *
+ * The fold is order-independent over the canonical entry set, which is what
+ * makes convergence a property rather than a hope: any two clients that have
+ * applied the same set of entries hold the same state, regardless of the
+ * order their transports delivered frames in or how many times a frame
+ * arrived.
+ *
+ * Three guards do all the work, and each is a production invariant:
+ *
+ * - entries from another branch's run are ignored, so a mis-routed frame can
+ *   never leak into a projection;
+ * - an entry already folded — the cursor tip redelivered, or a command id
+ *   already applied — is ignored, so an at-least-once transport cannot
+ *   double-apply a user action and a reconnect replays no side effects;
+ * - an entry below the cursor whose command was never applied is folded into
+ *   its canonical `seq` position, so out-of-order delivery converges on the
+ *   same document instead of permanently dropping the late entry.
+ *
+ * @since 0.1.0
+ */
+
+import * as JournalEvent from "@smthrs/journal/JournalEvent"
+import * as HashSet from "effect/HashSet"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import {
+  BranchId,
+  branchRunId,
+  CommandEvent,
+  CommandEventPayload,
+  CommandId,
+  ParticipantId,
+  SayCommand
+} from "./BranchProtocol.ts"
+
+/**
+ * One collaborative chat message in the branch timeline.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Message = Schema.Struct({
+  seq: JournalEvent.Seq,
+  commandId: CommandId,
+  participantId: ParticipantId,
+  /** The verified share capability that submitted the message. */
+  capabilityId: Schema.String,
+  text: Schema.String
+})
+/**
+ * The value form of {@link Message}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Message = typeof Message.Type
+
+/**
+ * One command applied to the branch document.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const AppliedCommand = Schema.Struct({
+  seq: JournalEvent.Seq,
+  commandId: CommandId,
+  participantId: ParticipantId,
+  /** The verified share capability that submitted the command. */
+  capabilityId: Schema.String,
+  name: Schema.NonEmptyString,
+  args: Schema.String,
+  target: Schema.String
+})
+/**
+ * The value form of {@link AppliedCommand}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type AppliedCommand = typeof AppliedCommand.Type
+
+/**
+ * The current winning value of one durably edited shared field.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Field = Schema.Struct({
+  target: Schema.NonEmptyString,
+  value: Schema.String,
+  seq: JournalEvent.Seq,
+  participantId: ParticipantId,
+  /** The verified share capability that wrote the winning value. */
+  capabilityId: Schema.String
+})
+/**
+ * The value form of {@link Field}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Field = typeof Field.Type
+
+/**
+ * The projected state of one branch document.
+ *
+ * `seq` is the highest journal sequence folded in and is exactly the cursor a
+ * client resumes from.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const State = Schema.Struct({
+  branchId: BranchId,
+  seq: Schema.Int.check(Schema.isGreaterThanOrEqualTo(-1)),
+  messages: Schema.Array(Message),
+  commands: Schema.Array(AppliedCommand),
+  fields: Schema.Array(Field)
+})
+/**
+ * The value form of {@link State}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type State = typeof State.Type
+
+/**
+ * The empty projection of a branch, whose cursor is "nothing applied".
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const empty = (branchId: BranchId): State => ({
+  branchId,
+  seq: -1,
+  messages: [],
+  commands: [],
+  fields: []
+})
+
+/**
+ * The conflict policy for two durable edits of the same field.
+ *
+ * Highest canonical sequence wins. Within a branch the sequence is a total
+ * order assigned by the journal, so this is already decisive; the
+ * lexicographic `participantId` tie-break exists so the policy stays total if
+ * a future deployment ever merges two sequence domains. It is deliberately not
+ * wall-clock based — client clocks disagree, and a merge rule that depends on
+ * them is not deterministic.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const resolveField = (existing: Field | undefined, candidate: Field): Field => {
+  if (existing === undefined) return candidate
+  if (candidate.seq !== existing.seq) return candidate.seq > existing.seq ? candidate : existing
+  return candidate.participantId > existing.participantId ? candidate : existing
+}
+
+/**
+ * Inserts one item into a sequence-ordered array at its canonical position.
+ *
+ * Canonical sequences are unique within a run, so an equal-sequence collision
+ * is unrepresentable here: dedup happens before insertion.
+ */
+const insertBySeq = <Item extends { readonly seq: JournalEvent.Seq }>(
+  items: ReadonlyArray<Item>,
+  item: Item
+): Array<Item> => {
+  const last = items[items.length - 1]
+  if (last === undefined || last.seq <= item.seq) return [...items, item]
+  let low = 0
+  let high = items.length
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2)
+    if (items[middle]!.seq <= item.seq) low = middle + 1
+    else high = middle
+  }
+  const result = items.slice()
+  result.splice(low, 0, item)
+  return result
+}
+
+// Cache by the immutable command array so cursor-only updates share the index.
+// Persistent sets let independent continuations share history without changing
+// an older state's deduplication. Restored states build their index on first use.
+const commandIds = new WeakMap<ReadonlyArray<AppliedCommand>, HashSet.HashSet<CommandId>>()
+const indexCommands = (commands: ReadonlyArray<AppliedCommand>): HashSet.HashSet<CommandId> => {
+  const cached = commandIds.get(commands)
+  if (cached !== undefined) return cached
+  const index = HashSet.fromIterable(commands.map((command) => command.commandId))
+  commandIds.set(commands, index)
+  return index
+}
+
+const decodeCommand = Schema.decodeUnknownOption(CommandEventPayload)
+
+/**
+ * Folds one journal entry into a branch projection.
+ *
+ * Redelivery and out-of-order delivery are told apart by identity, not by
+ * position: the cursor tip redelivered and a command id already applied are
+ * no-ops, while a below-cursor entry never applied is folded into canonical
+ * order. Non-command entries only raise the cursor, so re-applying one is
+ * idempotent by construction.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const apply = (state: State, entry: JournalEvent.Entry): State => {
+  if (entry.runId !== branchRunId(state.branchId) || entry.seq === state.seq) return state
+  const advanced = entry.seq < state.seq ? state : { ...state, seq: entry.seq }
+  if (entry.eventType !== CommandEvent) return advanced
+  const decoded = decodeCommand(entry.payload)
+  if (Option.isNone(decoded)) return advanced
+  const commandSubmission = decoded.value
+  const ids = indexCommands(state.commands)
+  if (HashSet.has(ids, commandSubmission.commandId)) return advanced
+  const command: AppliedCommand = { ...commandSubmission, seq: entry.seq }
+  const messages = commandSubmission.name === SayCommand
+    ? insertBySeq(state.messages, {
+      seq: entry.seq,
+      commandId: commandSubmission.commandId,
+      participantId: commandSubmission.participantId,
+      capabilityId: commandSubmission.capabilityId,
+      text: commandSubmission.args
+    })
+    : state.messages
+  const fields = commandSubmission.target === ""
+    ? state.fields
+    : (() => {
+      const candidate: Field = {
+        target: commandSubmission.target,
+        value: commandSubmission.args,
+        seq: entry.seq,
+        participantId: commandSubmission.participantId,
+        capabilityId: commandSubmission.capabilityId
+      }
+      const winner = resolveField(
+        state.fields.find((field) => field.target === commandSubmission.target),
+        candidate
+      )
+      return [...state.fields.filter((field) => field.target !== commandSubmission.target), winner]
+        .sort((left, right) => left.target < right.target ? -1 : 1)
+    })()
+  const commands = insertBySeq(state.commands, command)
+  commandIds.set(commands, HashSet.add(ids, command.commandId))
+  return { ...advanced, messages, commands, fields }
+}
+
+/**
+ * Folds a whole entry stream into a branch projection.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export const project = (branchId: BranchId, entries: Iterable<JournalEvent.Entry>): State => {
+  const runId = branchRunId(branchId)
+  let seq = -1
+  const ids = new Set<CommandId>()
+  const commands: Array<AppliedCommand> = []
+  const messages: Array<Message> = []
+  const fields = new Map<string, Field>()
+  for (const entry of entries) {
+    if (entry.runId !== runId || entry.seq === seq) continue
+    seq = Math.max(seq, entry.seq)
+    if (entry.eventType !== CommandEvent) continue
+    const decoded = decodeCommand(entry.payload)
+    if (Option.isNone(decoded)) continue
+    const submission = decoded.value
+    if (ids.has(submission.commandId)) continue
+    ids.add(submission.commandId)
+    commands.push({ ...submission, seq: entry.seq })
+    if (submission.name === SayCommand) {
+      messages.push({
+        seq: entry.seq,
+        commandId: submission.commandId,
+        participantId: submission.participantId,
+        capabilityId: submission.capabilityId,
+        text: submission.args
+      })
+    }
+    if (submission.target !== "") {
+      const candidate: Field = {
+        target: submission.target,
+        value: submission.args,
+        seq: entry.seq,
+        participantId: submission.participantId,
+        capabilityId: submission.capabilityId
+      }
+      fields.set(submission.target, resolveField(fields.get(submission.target), candidate))
+    }
+  }
+  commands.sort((left, right) => left.seq - right.seq)
+  messages.sort((left, right) => left.seq - right.seq)
+  commandIds.set(commands, HashSet.fromIterable(ids))
+  return {
+    branchId,
+    seq,
+    commands,
+    messages,
+    fields: Array.from(fields.values()).sort((left, right) => left.target < right.target ? -1 : 1)
+  }
+}

package/src/BranchProtocol.ts

@@ -0,0 +1,411 @@
+/**
+ * The branch collaboration contract: a branch is one shared live document.
+ *
+ * A branch has no store of its own. Its durable state is exactly one journal
+ * run — `branchRunId` is the only mapping — so every replication guarantee the
+ * rest of this package already provides (canonical per-run `seq`, exclusive
+ * cursors, gap detection, resumable follow) carries over unchanged, and
+ * multiplayer never introduces a second source of truth.
+ *
+ * Ephemeral collaboration state (presence, cursors) deliberately has no
+ * representation here beyond the wire shapes: it is leased, never journalled.
+ *
+ * @since 0.1.0
+ */
+
+import * as JournalEvent from "@smthrs/journal/JournalEvent"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/**
+ * Schema for the identifier of one collaboratively edited branch.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const BranchId = Schema.NonEmptyString.pipe(Schema.brand("@smthrs/sync/BranchProtocol/BranchId"))
+
+/**
+ * Identifier of one collaboratively edited branch.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type BranchId = typeof BranchId.Type
+
+/**
+ * Schema for the identifier of one connected client.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const ParticipantId = Schema.NonEmptyString.pipe(Schema.brand("@smthrs/sync/BranchProtocol/ParticipantId"))
+
+/**
+ * Identifier of one connected client.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ParticipantId = typeof ParticipantId.Type
+
+/**
+ * Schema for a client-minted command identifier.
+ *
+ * The identifier is minted once per user intent and reused across optimistic
+ * application, retransmission, and concurrent submission, which is what makes
+ * it the idempotency key rather than a correlation id.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const CommandId = Schema.NonEmptyString.pipe(Schema.brand("@smthrs/sync/BranchProtocol/CommandId"))
+
+/**
+ * Client-minted command identifier used as the idempotency key.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CommandId = typeof CommandId.Type
+
+/**
+ * Schema for the access a share capability grants.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Access = Schema.Literals(["read", "write"])
+
+/**
+ * The access a share capability grants.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Access = typeof Access.Type
+
+/**
+ * The journal run backing a branch document.
+ *
+ * The prefix keeps branch runs from colliding with engine runs in the same
+ * workspace journal, and makes the mapping reversible for tooling.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const branchRunId = (branchId: BranchId): JournalEvent.RunId =>
+  `${branchRunPrefix}${branchId}` as JournalEvent.RunId
+
+/** The one prefix {@link branchRunId} writes and {@link branchOfRunId} reads. */
+const branchRunPrefix = "flows/branch/"
+
+/**
+ * The branch a journal run belongs to, or `null` for a non-branch run.
+ *
+ * The bare prefix is a non-branch run, not a branch with an empty id.
+ * `BranchId` is a branded `NonEmptyString`, so branding `""` would produce a
+ * value the brand forbids and hand it to `share.verify` as the branch under
+ * authorization. Refusing it here keeps the brand's promise true everywhere
+ * downstream of this function.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const branchOfRunId = (runId: JournalEvent.RunId): BranchId | null => {
+  if (!runId.startsWith(branchRunPrefix)) return null
+  const rest = runId.slice(branchRunPrefix.length)
+  return rest.length === 0 ? null : rest as BranchId
+}
+
+/**
+ * The journal producer identity of one admitted command.
+ *
+ * `(runId, sourceId, sourceSeq)` is the journal's own durable idempotency
+ * key. Deriving the source from the client-minted `commandId` — with the
+ * fixed {@link commandSourceSeq} — turns that key into the branch's
+ * exactly-once admission constraint: two server instances racing the same
+ * command collide inside the journal's own transaction, so one appends and
+ * the other reads back the canonical sequence, instead of both appending
+ * (audit finding F-14). The branch run id already scopes the key, so equal
+ * command ids on different branches never collide.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const commandSourceId = (commandId: CommandId): JournalEvent.SourceId =>
+  `flows/branch-command/${commandId}` as JournalEvent.SourceId
+
+/**
+ * The fixed producer sequence of an admitted command.
+ *
+ * A command's identity lives entirely in {@link commandSourceId}, so its
+ * producer sequence is always 0. It must be supplied explicitly: letting the
+ * journal allocate would hand a resubmission after a lost response sequence 1,
+ * a fresh identity, and therefore a second durable append.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const commandSourceSeq: JournalEvent.SourceSeq = 0 as JournalEvent.SourceSeq
+
+/**
+ * The single durable event type a branch document is built from.
+ *
+ * Chat, edits, and flow launches are all commands, so the branch journal has
+ * exactly one event shape and the projection has exactly one decoder.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const CommandEvent = "flows/branch/command"
+
+/**
+ * Schema for the claims a share capability carries.
+ *
+ * `kid` names the key that signed the claims and is itself signed, so a
+ * verifier both selects the right key out of a rotating keyring and refuses a
+ * capability whose key name was swapped after minting. It matches
+ * `WorkspaceShare.WorkspaceClaims`: the two authorities are one scheme, and a
+ * branch link that could not survive a secret rotation was the only place they
+ * differed.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class ShareClaims extends Schema.Class<ShareClaims>("@smthrs/sync/BranchProtocol/ShareClaims")({
+  kid: Schema.NonEmptyString,
+  branchId: BranchId,
+  capabilityId: Schema.NonEmptyString,
+  access: Access,
+  issuedAtMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  expiresAtMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+}) {}
+
+/**
+ * Schema for a signed, expiring, branch-scoped share capability.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class ShareCapability extends Schema.Class<ShareCapability>("@smthrs/sync/BranchProtocol/ShareCapability")({
+  claims: ShareClaims,
+  signature: Schema.String
+}) {}
+
+/**
+ * Schema for a participant's caret inside one embedded card.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class Cursor extends Schema.Class<Cursor>("@smthrs/sync/BranchProtocol/Cursor")({
+  cardId: Schema.NonEmptyString,
+  offset: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+}) {}
+
+/**
+ * BranchCard-compatible display coordinates; paths are metadata only.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.1
+ */
+export const PresenceWhere = Schema.Union([
+  Schema.Struct({
+    kind: Schema.Literal("file"),
+    path: Schema.NonEmptyString,
+    line: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0)))
+  }),
+  Schema.Struct({ kind: Schema.Literal("terminal"), id: Schema.NonEmptyString }),
+  Schema.Struct({ kind: Schema.Literal("step"), label: Schema.NonEmptyString }),
+  Schema.Struct({ kind: Schema.Literal("branch") })
+])
+
+// Optional fields preserve decoding of recorded branch-protocol frames.
+const presenceFields = {
+  sessionId: Schema.optionalKey(Schema.NonEmptyString),
+  kind: Schema.optionalKey(Schema.Literals(["person", "agent"])),
+  where: Schema.optionalKey(PresenceWhere),
+  watching: Schema.optionalKey(Schema.NonEmptyString),
+  for_member: Schema.optionalKey(Schema.NonEmptyString),
+  agentKind: Schema.optionalKey(
+    Schema.Literals(["smithers", "coding", "reviewer", "claude-code", "codex", "external"])
+  ),
+  via: Schema.optionalKey(Schema.Literals(["ssh", "terminal", "cli"])),
+  runId: Schema.optionalKey(Schema.NonEmptyString)
+}
+
+/**
+ * Schema for one live participant on a branch.
+ *
+ * `leaseExpiresAtMs` is the whole lifetime contract: presence is a lease, so a
+ * client that disconnects without saying so disappears on its own.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class Participant extends Schema.Class<Participant>("@smthrs/sync/BranchProtocol/Participant")({
+  branchId: BranchId,
+  participantId: ParticipantId,
+  displayName: Schema.NonEmptyString,
+  cursor: Schema.NullOr(Cursor),
+  ...presenceFields,
+  leaseExpiresAtMs: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+}) {}
+
+/**
+ * Schema for a capability-bearing request for one branch's roster.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const RosterRequest = Schema.Struct({
+  capability: ShareCapability,
+  branchId: BranchId,
+  /** Only the authenticated host adapter consumes this readiness assertion. */
+  sourcesReady: Schema.optionalKey(Schema.Boolean)
+})
+
+/**
+ * A capability-bearing request for one branch's roster.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RosterRequest = typeof RosterRequest.Type
+
+/**
+ * Schema for a capability-bearing request to drop one participant.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const LeaveRequest = Schema.Struct({
+  ...RosterRequest.fields,
+  participantId: ParticipantId,
+  sessionId: Schema.optionalKey(Schema.NonEmptyString)
+})
+
+/**
+ * A capability-bearing request to drop one participant.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type LeaveRequest = typeof LeaveRequest.Type
+
+/**
+ * Schema for one participant's announcement of itself on a branch.
+ *
+ * The same shape serves join, heartbeat, and cursor movement: an announcement
+ * is idempotent, so a client that reconnects simply announces again.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Announcement = Schema.Struct({
+  ...presenceFields,
+  capability: ShareCapability,
+  branchId: BranchId,
+  participantId: ParticipantId,
+  displayName: Schema.NonEmptyString,
+  cursor: Schema.NullOr(Cursor)
+})
+
+/**
+ * One participant's announcement of itself on a branch.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Announcement = typeof Announcement.Type
+
+/**
+ * Schema for one submitted command or flow invocation.
+ *
+ * Every user action on a shared branch arrives here first — chat messages are
+ * the `branch.say` command, renames are `branch.rename`, and a flow launch is
+ * that flow's own name. `target` names the shared field a command durably
+ * edits and is `""` for commands that only append.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class CommandSubmission extends Schema.Class<CommandSubmission>(
+  "@smthrs/sync/BranchProtocol/CommandSubmission"
+)({
+  branchId: BranchId,
+  commandId: CommandId,
+  participantId: ParticipantId,
+  name: Schema.NonEmptyString,
+  args: Schema.String,
+  target: Schema.String
+}) {}
+
+/**
+ * Schema for a capability-bearing command submission.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const SubmitRequest = Schema.Struct({ capability: ShareCapability, submission: CommandSubmission })
+
+/**
+ * A capability-bearing command submission.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SubmitRequest = typeof SubmitRequest.Type
+
+/**
+ * The durable payload stored for an admitted command.
+ *
+ * Distinct from the wire request: `args` and `target` carry decoding defaults,
+ * so a row written before those fields existed still decodes rather than
+ * failing the whole ledger rebuild.
+ *
+ * `capabilityId` is the verified id of the share capability that submitted the
+ * command, stamped by `BranchCommands.submit` and never read from the client.
+ * `participantId` is whatever the client claimed, so attribute a command to
+ * its `capabilityId`. A row admitted before the field existed decodes with
+ * `""`, which no capability can carry.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class CommandEventPayload extends Schema.Class<CommandEventPayload>(
+  "@smthrs/sync/BranchProtocol/CommandEventPayload"
+)({
+  commandId: CommandId,
+  participantId: ParticipantId,
+  name: Schema.NonEmptyString,
+  args: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(""))),
+  target: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(""))),
+  capabilityId: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed("")))
+}) {}
+
+/**
+ * The command that appends a collaborative chat message.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const SayCommand = "branch.say"
+
+/**
+ * Schema for the outcome of admitting a command.
+ *
+ * `duplicate` is a success, not a failure: it reports the canonical sequence
+ * the original submission already occupies so a retransmitting client can
+ * settle its optimistic row instead of executing the command twice.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export class CommandReceipt extends Schema.Class<CommandReceipt>("@smthrs/sync/BranchProtocol/CommandReceipt")({
+  branchId: BranchId,
+  commandId: CommandId,
+  status: Schema.Literals(["admitted", "duplicate"]),
+  seq: JournalEvent.Seq
+}) {}