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

package/dist/esm/BranchProtocol.js

@@ -0,0 +1,323 @@
+/**
+ * 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"));
+/**
+ * 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"));
+/**
+ * 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"));
+/**
+ * Schema for the access a share capability grants.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const Access = Schema.Literals(["read", "write"]);
+/**
+ * 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) => `${branchRunPrefix}${branchId}`;
+/** 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) => {
+    if (!runId.startsWith(branchRunPrefix))
+        return null;
+    const rest = runId.slice(branchRunPrefix.length);
+    return rest.length === 0 ? null : rest;
+};
+/**
+ * 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) => `flows/branch-command/${commandId}`;
+/**
+ * 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 = 0;
+/**
+ * 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("@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("@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("@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("@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)
+});
+/**
+ * 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)
+});
+/**
+ * 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)
+});
+/**
+ * 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("@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 });
+/**
+ * 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("@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("@smthrs/sync/BranchProtocol/CommandReceipt")({
+    branchId: BranchId,
+    commandId: CommandId,
+    status: Schema.Literals(["admitted", "duplicate"]),
+    seq: JournalEvent.Seq
+}) {
+}
+//# sourceMappingURL=BranchProtocol.js.map

package/dist/esm/BranchProtocol.js.map

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

package/dist/esm/BranchRpcs.d.ts

@@ -0,0 +1,177 @@
+/**
+ * The branch collaboration wire contract: the RPC projection of the write
+ * and presence paths that complement the read-only {@link SyncRpcs}.
+ *
+ * Authorization has two stages. Opening a branch is the bootstrap: no
+ * capability can exist yet, so `CreateBranch` requires an authenticated
+ * workspace principal supplied by the group's {@link SyncAuth} middleware,
+ * and its handler refuses any other principal.
+ *
+ * Every later procedure carries its own share capability and authorizes
+ * through {@link BranchShare}: past the bootstrap the capability IS the
+ * credential, and cross-branch or expired capabilities are refused by the
+ * same service boundary the in-process callers use.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
+import { CommandReceipt, Participant, ShareCapability } from "./BranchProtocol.ts";
+import { SyncError } from "./SyncError.ts";
+import { SyncAuth } from "./SyncRpcs.ts";
+/**
+ * Maximum lifetime the branch bootstrap may mint.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const maximumBranchTtlMs: number;
+/**
+ * Schema for a request to open a new shared branch.
+ *
+ * The RPC authentication middleware must establish the workspace principal
+ * before the handler mints the first write capability.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const CreateBranchPayload: Schema.Struct<{
+    readonly ttlMs: Schema.Int;
+}>;
+/**
+ * A request to open a new shared branch.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CreateBranchPayload = typeof CreateBranchPayload.Type;
+/**
+ * Schema for the freshly opened branch and its owner capability.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const CreateBranchResponse: Schema.Struct<{
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly capability: typeof ShareCapability;
+}>;
+/**
+ * The freshly opened branch and its owner capability.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CreateBranchResponse = typeof CreateBranchResponse.Type;
+/**
+ * Schema for a request to mint a share link for a branch.
+ *
+ * The presenting capability must hold write access to the branch — only a
+ * collaborator can invite one — and the minted link never outlives the
+ * capability it was minted from.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const MintSharePayload: Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+    readonly ttlMs: Schema.Int;
+}>;
+/**
+ * A request to mint a share link for a branch.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type MintSharePayload = typeof MintSharePayload.Type;
+/**
+ * Schema for one roster emission on a branch watch stream.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const RosterFrame: Schema.Struct<{
+    readonly participants: Schema.$Array<typeof Participant>;
+}>;
+/**
+ * One roster emission on a branch watch stream.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RosterFrame = typeof RosterFrame.Type;
+/**
+ * The remote procedures of branch collaboration.
+ *
+ * The capability-bearing payloads ARE the `BranchProtocol` request schemas the
+ * branch services take, not copies of them. Four wire payloads used to
+ * re-declare the message their service already owned, and the announce copy
+ * had already drifted: it accepted `displayName: ""` where the service
+ * requires a non-empty name, so a wire-legal announce reached a `Participant`
+ * constructor and threw a defect outside the declared `SyncError` channel.
+ * Naming one schema on both sides makes that drift impossible rather than
+ * fixed once, and keeps this group free of the services themselves.
+ *
+ * @category groups
+ * @since 0.1.0
+ */
+export declare const BranchRpcs: RpcGroup.RpcGroup<Rpc.Rpc<"Branch.CreateBranch", Schema.Struct<{
+    readonly ttlMs: Schema.Int;
+}>, Schema.Struct<{
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly capability: typeof ShareCapability;
+}>, typeof SyncError, typeof SyncAuth, never> | Rpc.Rpc<"Branch.MintShare", Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+    readonly ttlMs: Schema.Int;
+}>, typeof ShareCapability, typeof SyncError, typeof SyncAuth, never> | Rpc.Rpc<"Branch.Submit", Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly submission: typeof import("./BranchProtocol.ts").CommandSubmission;
+}>, typeof CommandReceipt, typeof SyncError, typeof SyncAuth, never> | Rpc.Rpc<"Branch.Announce", Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly participantId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/ParticipantId">;
+    readonly displayName: Schema.NonEmptyString;
+    readonly cursor: Schema.NullOr<typeof import("./BranchProtocol.ts").Cursor>;
+    readonly sessionId: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly kind: Schema.optionalKey<Schema.Literals<readonly ["person", "agent"]>>;
+    readonly where: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"file">;
+        readonly path: Schema.NonEmptyString;
+        readonly line: Schema.optionalKey<Schema.Int>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"terminal">;
+        readonly id: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"step">;
+        readonly label: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"branch">;
+    }>]>>;
+    readonly watching: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly for_member: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly agentKind: Schema.optionalKey<Schema.Literals<readonly ["smithers", "coding", "reviewer", "claude-code", "codex", "external"]>>;
+    readonly via: Schema.optionalKey<Schema.Literals<readonly ["ssh", "terminal", "cli"]>>;
+    readonly runId: Schema.optionalKey<Schema.NonEmptyString>;
+}>, typeof Participant, typeof SyncError, typeof SyncAuth, never> | Rpc.Rpc<"Branch.Leave", Schema.Struct<{
+    readonly participantId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/ParticipantId">;
+    readonly sessionId: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly capability: typeof ShareCapability;
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly sourcesReady: Schema.optionalKey<Schema.Boolean>;
+}>, Schema.Null, typeof SyncError, typeof SyncAuth, never> | Rpc.Rpc<"Branch.Roster", Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly sourcesReady: Schema.optionalKey<Schema.Boolean>;
+}>, Schema.$Array<typeof Participant>, typeof SyncError, typeof SyncAuth, never> | Rpc.Rpc<"Branch.PresenceOn", Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly sourcesReady: Schema.optionalKey<Schema.Boolean>;
+}>, Schema.Literals<readonly ["unknown", "present", "empty"]>, typeof SyncError, typeof SyncAuth, never> | Rpc.Rpc<"Branch.WatchRoster", Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly sourcesReady: Schema.optionalKey<Schema.Boolean>;
+}>, import("effect/unstable/rpc/RpcSchema").Stream<Schema.Struct<{
+    readonly participants: Schema.$Array<typeof Participant>;
+}>, typeof SyncError>, Schema.Never, typeof SyncAuth, never>>;
+//# sourceMappingURL=BranchRpcs.d.ts.map

package/dist/esm/BranchRpcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchRpcs.d.ts","sourceRoot":"","sources":["../../src/BranchRpcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAIL,cAAc,EAEd,WAAW,EAEX,eAAe,EAEhB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAsB,CAAA;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;EAK9B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;EAG/B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,IAAI,CAAA;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;EAI3B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;EAEtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6DAqBD,CAAA"}

package/dist/esm/BranchRpcs.js

@@ -0,0 +1,103 @@
+/**
+ * The branch collaboration wire contract: the RPC projection of the write
+ * and presence paths that complement the read-only {@link SyncRpcs}.
+ *
+ * Authorization has two stages. Opening a branch is the bootstrap: no
+ * capability can exist yet, so `CreateBranch` requires an authenticated
+ * workspace principal supplied by the group's {@link SyncAuth} middleware,
+ * and its handler refuses any other principal.
+ *
+ * Every later procedure carries its own share capability and authorizes
+ * through {@link BranchShare}: past the bootstrap the capability IS the
+ * credential, and cross-branch or expired capabilities are refused by the
+ * same service boundary the in-process callers use.
+ *
+ * @since 0.1.0
+ */
+import * as Schema from "effect/Schema";
+import { Rpc, RpcGroup } from "effect/unstable/rpc";
+import { Access, Announcement, BranchId, CommandReceipt, LeaveRequest, Participant, RosterRequest, ShareCapability, SubmitRequest } from "./BranchProtocol.js";
+import { SyncError } from "./SyncError.js";
+import { SyncAuth } from "./SyncRpcs.js";
+/**
+ * Maximum lifetime the branch bootstrap may mint.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const maximumBranchTtlMs = 24 * 60 * 60 * 1000;
+/**
+ * Schema for a request to open a new shared branch.
+ *
+ * The RPC authentication middleware must establish the workspace principal
+ * before the handler mints the first write capability.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const CreateBranchPayload = Schema.Struct({
+    ttlMs: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(maximumBranchTtlMs))
+});
+/**
+ * Schema for the freshly opened branch and its owner capability.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const CreateBranchResponse = Schema.Struct({
+    branchId: BranchId,
+    capability: ShareCapability
+});
+/**
+ * Schema for a request to mint a share link for a branch.
+ *
+ * The presenting capability must hold write access to the branch — only a
+ * collaborator can invite one — and the minted link never outlives the
+ * capability it was minted from.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const MintSharePayload = Schema.Struct({
+    capability: ShareCapability,
+    access: Access,
+    ttlMs: Schema.Int.check(Schema.isGreaterThan(0))
+});
+/**
+ * Schema for one roster emission on a branch watch stream.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const RosterFrame = Schema.Struct({
+    participants: Schema.Array(Participant)
+});
+/**
+ * The remote procedures of branch collaboration.
+ *
+ * The capability-bearing payloads ARE the `BranchProtocol` request schemas the
+ * branch services take, not copies of them. Four wire payloads used to
+ * re-declare the message their service already owned, and the announce copy
+ * had already drifted: it accepted `displayName: ""` where the service
+ * requires a non-empty name, so a wire-legal announce reached a `Participant`
+ * constructor and threw a defect outside the declared `SyncError` channel.
+ * Naming one schema on both sides makes that drift impossible rather than
+ * fixed once, and keeps this group free of the services themselves.
+ *
+ * @category groups
+ * @since 0.1.0
+ */
+export const BranchRpcs = RpcGroup.make(Rpc.make("Branch.CreateBranch", {
+    payload: CreateBranchPayload,
+    success: CreateBranchResponse,
+    error: SyncError
+}), Rpc.make("Branch.MintShare", { payload: MintSharePayload, success: ShareCapability, error: SyncError }), Rpc.make("Branch.Submit", { payload: SubmitRequest, success: CommandReceipt, error: SyncError }), Rpc.make("Branch.Announce", { payload: Announcement, success: Participant, error: SyncError }), Rpc.make("Branch.Leave", { payload: LeaveRequest, success: Schema.Null, error: SyncError }), Rpc.make("Branch.Roster", {
+    payload: RosterRequest,
+    success: Schema.Array(Participant),
+    error: SyncError
+}), Rpc.make("Branch.PresenceOn", {
+    payload: RosterRequest,
+    success: Schema.Literals(["unknown", "present", "empty"]),
+    error: SyncError
+}), Rpc.make("Branch.WatchRoster", { payload: RosterRequest, success: RosterFrame, error: SyncError, stream: true })).middleware(SyncAuth);
+//# sourceMappingURL=BranchRpcs.js.map

package/dist/esm/BranchRpcs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchRpcs.js","sourceRoot":"","sources":["../../src/BranchRpcs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The branch collaboration wire contract: the RPC projection of the write\n * and presence paths that complement the read-only {@link SyncRpcs}.\n *\n * Authorization has two stages. Opening a branch is the bootstrap: no\n * capability can exist yet, so `CreateBranch` requires an authenticated\n * workspace principal supplied by the group's {@link SyncAuth} middleware,\n * and its handler refuses any other principal.\n *\n * Every later procedure carries its own share capability and authorizes\n * through {@link BranchShare}: past the bootstrap the capability IS the\n * credential, and cross-branch or expired capabilities are refused by the\n * same service boundary the in-process callers use.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\nimport { Rpc, RpcGroup } from \"effect/unstable/rpc\"\nimport {\n  Access,\n  Announcement,\n  BranchId,\n  CommandReceipt,\n  LeaveRequest,\n  Participant,\n  RosterRequest,\n  ShareCapability,\n  SubmitRequest\n} from \"./BranchProtocol.ts\"\nimport { SyncError } from \"./SyncError.ts\"\nimport { SyncAuth } from \"./SyncRpcs.ts\"\n\n/**\n * Maximum lifetime the branch bootstrap may mint.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const maximumBranchTtlMs = 24 * 60 * 60 * 1000\n\n/**\n * Schema for a request to open a new shared branch.\n *\n * The RPC authentication middleware must establish the workspace principal\n * before the handler mints the first write capability.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const CreateBranchPayload = Schema.Struct({\n  ttlMs: Schema.Int.check(\n    Schema.isGreaterThan(0),\n    Schema.isLessThanOrEqualTo(maximumBranchTtlMs)\n  )\n})\n\n/**\n * A request to open a new shared branch.\n *\n * @category models\n * @since 0.1.0\n */\nexport type CreateBranchPayload = typeof CreateBranchPayload.Type\n\n/**\n * Schema for the freshly opened branch and its owner capability.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const CreateBranchResponse = Schema.Struct({\n  branchId: BranchId,\n  capability: ShareCapability\n})\n\n/**\n * The freshly opened branch and its owner capability.\n *\n * @category models\n * @since 0.1.0\n */\nexport type CreateBranchResponse = typeof CreateBranchResponse.Type\n\n/**\n * Schema for a request to mint a share link for a branch.\n *\n * The presenting capability must hold write access to the branch — only a\n * collaborator can invite one — and the minted link never outlives the\n * capability it was minted from.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const MintSharePayload = Schema.Struct({\n  capability: ShareCapability,\n  access: Access,\n  ttlMs: Schema.Int.check(Schema.isGreaterThan(0))\n})\n\n/**\n * A request to mint a share link for a branch.\n *\n * @category models\n * @since 0.1.0\n */\nexport type MintSharePayload = typeof MintSharePayload.Type\n\n/**\n * Schema for one roster emission on a branch watch stream.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const RosterFrame = Schema.Struct({\n  participants: Schema.Array(Participant)\n})\n\n/**\n * One roster emission on a branch watch stream.\n *\n * @category models\n * @since 0.1.0\n */\nexport type RosterFrame = typeof RosterFrame.Type\n\n/**\n * The remote procedures of branch collaboration.\n *\n * The capability-bearing payloads ARE the `BranchProtocol` request schemas the\n * branch services take, not copies of them. Four wire payloads used to\n * re-declare the message their service already owned, and the announce copy\n * had already drifted: it accepted `displayName: \"\"` where the service\n * requires a non-empty name, so a wire-legal announce reached a `Participant`\n * constructor and threw a defect outside the declared `SyncError` channel.\n * Naming one schema on both sides makes that drift impossible rather than\n * fixed once, and keeps this group free of the services themselves.\n *\n * @category groups\n * @since 0.1.0\n */\nexport const BranchRpcs = RpcGroup.make(\n  Rpc.make(\"Branch.CreateBranch\", {\n    payload: CreateBranchPayload,\n    success: CreateBranchResponse,\n    error: SyncError\n  }),\n  Rpc.make(\"Branch.MintShare\", { payload: MintSharePayload, success: ShareCapability, error: SyncError }),\n  Rpc.make(\"Branch.Submit\", { payload: SubmitRequest, success: CommandReceipt, error: SyncError }),\n  Rpc.make(\"Branch.Announce\", { payload: Announcement, success: Participant, error: SyncError }),\n  Rpc.make(\"Branch.Leave\", { payload: LeaveRequest, success: Schema.Null, error: SyncError }),\n  Rpc.make(\"Branch.Roster\", {\n    payload: RosterRequest,\n    success: Schema.Array(Participant),\n    error: SyncError\n  }),\n  Rpc.make(\"Branch.PresenceOn\", {\n    payload: RosterRequest,\n    success: Schema.Literals([\"unknown\", \"present\", \"empty\"]),\n    error: SyncError\n  }),\n  Rpc.make(\"Branch.WatchRoster\", { payload: RosterRequest, success: RosterFrame, error: SyncError, stream: true })\n).middleware(SyncAuth)\n"]}