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

package/dist/esm/BranchProtocol.d.ts

@@ -0,0 +1,415 @@
+/**
+ * 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 Schema from "effect/Schema";
+/**
+ * Schema for the identifier of one collaboratively edited branch.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const BranchId: Schema.brand<Schema.NonEmptyString, "@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 declare const ParticipantId: Schema.brand<Schema.NonEmptyString, "@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 declare const CommandId: Schema.brand<Schema.NonEmptyString, "@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 declare const Access: Schema.Literals<readonly ["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 declare const branchRunId: (branchId: BranchId) => JournalEvent.RunId;
+/**
+ * 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 declare const branchOfRunId: (runId: JournalEvent.RunId) => BranchId | null;
+/**
+ * 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 declare const commandSourceId: (commandId: CommandId) => 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 declare const commandSourceSeq: 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 declare const CommandEvent = "flows/branch/command";
+declare const ShareClaims_base: Schema.Class<ShareClaims, Schema.Struct<{
+    readonly kid: Schema.NonEmptyString;
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly capabilityId: Schema.NonEmptyString;
+    readonly access: Schema.Literals<readonly ["read", "write"]>;
+    readonly issuedAtMs: Schema.Int;
+    readonly expiresAtMs: Schema.Int;
+}>, {}>;
+/**
+ * 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 declare class ShareClaims extends ShareClaims_base {
+}
+declare const ShareCapability_base: Schema.Class<ShareCapability, Schema.Struct<{
+    readonly claims: typeof ShareClaims;
+    readonly signature: Schema.String;
+}>, {}>;
+/**
+ * Schema for a signed, expiring, branch-scoped share capability.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare class ShareCapability extends ShareCapability_base {
+}
+declare const Cursor_base: Schema.Class<Cursor, Schema.Struct<{
+    readonly cardId: Schema.NonEmptyString;
+    readonly offset: Schema.Int;
+}>, {}>;
+/**
+ * Schema for a participant's caret inside one embedded card.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare class Cursor extends Cursor_base {
+}
+/**
+ * BranchCard-compatible display coordinates; paths are metadata only.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.1
+ */
+export declare const PresenceWhere: 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">;
+}>]>;
+declare const Participant_base: Schema.Class<Participant, Schema.Struct<{
+    readonly leaseExpiresAtMs: Schema.Int;
+    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>;
+    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 Cursor>;
+}>, {}>;
+/**
+ * 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 declare class Participant extends Participant_base {
+}
+/**
+ * Schema for a capability-bearing request for one branch's roster.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const RosterRequest: Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    /** Only the authenticated host adapter consumes this readiness assertion. */
+    readonly 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 declare const LeaveRequest: 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">;
+    /** Only the authenticated host adapter consumes this readiness assertion. */
+    readonly sourcesReady: Schema.optionalKey<Schema.Boolean>;
+}>;
+/**
+ * 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 declare const Announcement: 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 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>;
+}>;
+/**
+ * One participant's announcement of itself on a branch.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Announcement = typeof Announcement.Type;
+declare const CommandSubmission_base: Schema.Class<CommandSubmission, Schema.Struct<{
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly commandId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/CommandId">;
+    readonly participantId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/ParticipantId">;
+    readonly name: Schema.NonEmptyString;
+    readonly args: Schema.String;
+    readonly target: Schema.String;
+}>, {}>;
+/**
+ * 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 declare class CommandSubmission extends CommandSubmission_base {
+}
+/**
+ * Schema for a capability-bearing command submission.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const SubmitRequest: Schema.Struct<{
+    readonly capability: typeof ShareCapability;
+    readonly submission: typeof CommandSubmission;
+}>;
+/**
+ * A capability-bearing command submission.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SubmitRequest = typeof SubmitRequest.Type;
+declare const CommandEventPayload_base: Schema.Class<CommandEventPayload, Schema.Struct<{
+    readonly commandId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/CommandId">;
+    readonly participantId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/ParticipantId">;
+    readonly name: Schema.NonEmptyString;
+    readonly args: Schema.withDecodingDefaultKey<Schema.String, never>;
+    readonly target: Schema.withDecodingDefaultKey<Schema.String, never>;
+    readonly capabilityId: Schema.withDecodingDefaultKey<Schema.String, never>;
+}>, {}>;
+/**
+ * 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 declare class CommandEventPayload extends CommandEventPayload_base {
+}
+/**
+ * The command that appends a collaborative chat message.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const SayCommand = "branch.say";
+declare const CommandReceipt_base: Schema.Class<CommandReceipt, Schema.Struct<{
+    readonly branchId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/BranchId">;
+    readonly commandId: Schema.brand<Schema.NonEmptyString, "@smthrs/sync/BranchProtocol/CommandId">;
+    readonly status: Schema.Literals<readonly ["admitted", "duplicate"]>;
+    readonly seq: Schema.brand<Schema.Int, "@smthrs/journal/JournalEvent/Seq">;
+}>, {}>;
+/**
+ * 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 declare class CommandReceipt extends CommandReceipt_base {
+}
+export {};
+//# sourceMappingURL=BranchProtocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BranchProtocol.d.ts","sourceRoot":"","sources":["../../src/BranchProtocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,YAAY,MAAM,8BAA8B,CAAA;AAE5D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,6EAAmF,CAAA;AAExG;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,kFAAwF,CAAA;AAElH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,8EAAoF,CAAA;AAE1G;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,MAAM,6CAAqC,CAAA;AAExD;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,QAAQ,KAAG,YAAY,CAAC,KACP,CAAA;AAKvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,YAAY,CAAC,KAAK,KAAG,QAAQ,GAAG,IAIpE,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,GAAI,WAAW,SAAS,KAAG,YAAY,CAAC,QACN,CAAA;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAAY,CAAC,SAAuC,CAAA;AAEnF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,yBAAyB,CAAA;;;;;;;;;AAElD;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,SAAQ,gBAO/B;CAAG;;;;;AAEL;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,oBAGnC;CAAG;;;;;AAEL;;;;;GAKG;AACH,qBAAa,MAAO,SAAQ,WAG1B;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;IASxB,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgBF;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,gBAO/B;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;IAGxB,6EAA6E;;EAE7E,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;IAlBvB,6EAA6E;;EAsB7E,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;EAOvB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;;;;;;;;;AAEnD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,sBASrC;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;EAAgF,CAAA;AAE1G;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;;;;;;;;;AAErD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,SAAQ,wBASvC;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,UAAU,eAAe,CAAA;;;;;;;AAEtC;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,mBAKlC;CAAG"}