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

package/dist/esm/BranchIds.js

@@ -0,0 +1,61 @@
+/**
+ * The source of freshly minted branch and capability identifiers.
+ *
+ * Minting an id is nondeterminism against the host, so it enters through a
+ * port like every other host effect: `BranchServer.layerHandlers` asks
+ * this service for the ids it puts on the wire instead of calling a global
+ * generator, which is what lets a deterministic composition — a test, a
+ * replayed transcript, a deployment that derives ids from its own namespace —
+ * supply its own without touching the handlers.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+/**
+ * The branch identifier source.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class BranchIds extends Context.Service()("@smthrs/sync/BranchIds") {
+}
+/**
+ * Constructs the default source: Web Crypto UUIDs.
+ *
+ * Web Crypto is used directly, as it is for the share signature in
+ * `BranchShare`, so the same module runs in the browser and on node.
+ * A branch id is not itself an authorization — every operation still
+ * authorizes through a signed capability — but an unguessable id keeps a
+ * branch from being enumerated, which is why the default stays with a
+ * cryptographic generator rather than `Random`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeWebCrypto = () => BranchIds.of({ fresh: Effect.sync(() => crypto.randomUUID()) });
+/**
+ * Provides {@link makeWebCrypto}.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.sync(BranchIds)(makeWebCrypto);
+/**
+ * Provides a deterministic counter, `<prefix>-1`, `<prefix>-2`, and so on.
+ * For tests and reproducible transcripts only — the ids are guessable.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerSequential = (prefix) => Layer.sync(BranchIds)(() => {
+    let sequence = 0;
+    return BranchIds.of({
+        fresh: Effect.sync(() => {
+            sequence += 1;
+            return `${prefix}-${sequence}`;
+        })
+    });
+});
+//# sourceMappingURL=BranchIds.js.map

package/dist/esm/BranchIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchIds.js","sourceRoot":"","sources":["../../src/BranchIds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAarC;;;;;GAKG;AACH,MAAM,OAAO,SAAU,SAAQ,OAAO,CAAC,OAAO,EAAsB,CAAC,wBAAwB,CAAC;CAAG;AAEjG;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAY,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,CAAA;AAE3G;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAA2B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,aAAa,CAAC,CAAA;AAEjF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAc,EAA0B,EAAE,CACxE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE;IACzB,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,OAAO,SAAS,CAAC,EAAE,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YACtB,QAAQ,IAAI,CAAC,CAAA;YACb,OAAO,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAA;QAChC,CAAC,CAAC;KACH,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The source of freshly minted branch and capability identifiers.\n *\n * Minting an id is nondeterminism against the host, so it enters through a\n * port like every other host effect: `BranchServer.layerHandlers` asks\n * this service for the ids it puts on the wire instead of calling a global\n * generator, which is what lets a deterministic composition — a test, a\n * replayed transcript, a deployment that derives ids from its own namespace —\n * supply its own without touching the handlers.\n *\n * @since 0.1.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\n\n/**\n * Identifier minting operations.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service {\n  /** A fresh, unguessable identifier. Never returns the same value twice. */\n  readonly fresh: Effect.Effect<string>\n}\n\n/**\n * The branch identifier source.\n *\n * @category services\n * @since 0.1.0\n */\nexport class BranchIds extends Context.Service<BranchIds, Service>()(\"@smthrs/sync/BranchIds\") {}\n\n/**\n * Constructs the default source: Web Crypto UUIDs.\n *\n * Web Crypto is used directly, as it is for the share signature in\n * `BranchShare`, so the same module runs in the browser and on node.\n * A branch id is not itself an authorization — every operation still\n * authorizes through a signed capability — but an unguessable id keeps a\n * branch from being enumerated, which is why the default stays with a\n * cryptographic generator rather than `Random`.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeWebCrypto = (): Service => BranchIds.of({ fresh: Effect.sync(() => crypto.randomUUID()) })\n\n/**\n * Provides {@link makeWebCrypto}.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<BranchIds> = Layer.sync(BranchIds)(makeWebCrypto)\n\n/**\n * Provides a deterministic counter, `<prefix>-1`, `<prefix>-2`, and so on.\n * For tests and reproducible transcripts only — the ids are guessable.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerSequential = (prefix: string): Layer.Layer<BranchIds> =>\n  Layer.sync(BranchIds)(() => {\n    let sequence = 0\n    return BranchIds.of({\n      fresh: Effect.sync(() => {\n        sequence += 1\n        return `${prefix}-${sequence}`\n      })\n    })\n  })\n"]}

package/dist/esm/BranchPresence.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Ephemeral presence and cursors for one shared branch.
+ *
+ * Presence is deliberately NOT journalled. A roster is a lease table: every
+ * announcement extends a lease, and a participant that stops announcing —
+ * because the tab closed, the network dropped, or the process died — ages out
+ * without anyone reporting the disconnect. Writing presence to the journal
+ * would make "who was looking at this" part of the durable, replayable history
+ * of a run, which is both unbounded and wrong: replaying a branch must not
+ * resurrect a stranger's caret.
+ *
+ * Every operation authorizes through {@link BranchShare}, so a capability for
+ * one branch can neither read nor write another branch's roster. A live
+ * participant is bound to the capability that announced it: announcing or
+ * leaving under that `participantId` with any other capability is refused
+ * with `unauthorized` until the lease lapses.
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { type Announcement, type BranchId, type LeaveRequest, Participant, type RosterRequest } from "./BranchProtocol.ts";
+import * as BranchShare from "./BranchShare.ts";
+import { SyncError } from "./SyncError.ts";
+/**
+ * Ephemeral branch presence operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service {
+    readonly announce: (announcement: Announcement) => Effect.Effect<Participant, SyncError>;
+    readonly leave: (request: LeaveRequest) => Effect.Effect<void, SyncError>;
+    /**
+     * One branch's live roster, as a fresh array of detached participants and
+     * cursors. Reading drops expired leases and advances a cross-branch sweep.
+     */
+    readonly list: (request: RosterRequest) => Effect.Effect<ReadonlyArray<Participant>, SyncError>;
+    /**
+     * Returns `unknown` for one lease after host startup or while a required
+     * heartbeat source is unavailable; otherwise reports `present` or `empty`.
+     *
+     * @since 1.0.0
+     */
+    readonly presenceOn: (request: RosterRequest) => Effect.Effect<"unknown" | "present" | "empty", SyncError>;
+    readonly changes: Stream.Stream<BranchId>;
+    /**
+     * How long one announcement keeps a participant on the roster, in
+     * milliseconds.
+     *
+     * A lease lapses without anyone reporting it, and nothing publishes on
+     * `changes` when it does, so a watcher cannot learn of the last
+     * participant's departure from the change feed alone. It re-lists on this
+     * cadence capped at one second, bounding how long an expired lease stays visible.
+     */
+    readonly leaseMs: number;
+}
+declare const BranchPresence_base: Context.ServiceClass<BranchPresence, "@smthrs/sync/BranchPresence", Service>;
+/**
+ * The branch presence registry.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class BranchPresence extends BranchPresence_base {
+}
+/**
+ * The lease {@link makeNoop} reports. It holds no one, so the value only has
+ * to be a positive number a watcher can build a re-list cadence from.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultLeaseMs = 30000;
+/**
+ * Constructs an unavailable presence registry.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides an unavailable presence registry.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<BranchPresence>;
+/**
+ * The policy one presence registry runs under. Every field defaults, and
+ * {@link makeMemory} and {@link layerWith} validate what a caller supplies.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface PresenceOptions {
+    /**
+     * How long an announcement keeps a participant on the roster, in
+     * milliseconds. Defaults to {@link defaultLeaseMs}.
+     */
+    readonly leaseMs?: number | undefined;
+    /**
+     * Roster changes a stalled {@link Service.changes} subscriber may fall
+     * behind by. Defaults to {@link defaultChangesCapacity}.
+     */
+    readonly changesCapacity?: number | undefined;
+    /**
+     * Participants one branch may hold at once. Defaults to
+     * {@link defaultMaxParticipants}.
+     */
+    readonly maxParticipants?: number | undefined;
+    /**
+     * Host readiness, including authorization, revocation, bridge and session
+     * sources. Defaults to unavailable.
+     *
+     * @since 1.0.0
+     */
+    readonly sourcesReady?: ((branchId: BranchId) => Effect.Effect<boolean>) | undefined;
+}
+/**
+ * Roster changes a stalled {@link Service.changes} subscriber may fall behind
+ * by before the oldest are dropped.
+ *
+ * Presence is a lease table, and `changes` only says that some branch's roster
+ * moved: a follower answers it with `list`. Holding an unbounded backlog for a
+ * subscriber that has stopped pulling would let one abandoned watcher retain
+ * every announcement the process has seen since. A subscriber that falls
+ * further behind than this bound loses the oldest notifications and re-lists;
+ * because every notification is answered by a fresh `list`, dropping one never
+ * loses roster state.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultChangesCapacity = 256;
+/**
+ * Participants one branch may hold at once.
+ *
+ * A roster is unbounded fan-out in two directions: it is walked on every
+ * `list`, and `Branch.Roster` returns it whole, which no frame ceiling covers.
+ * Nothing caps how many distinct `participantId`s one write capability may
+ * announce, so without this a single share link could pin an arbitrary number
+ * of `Participant` objects until their leases expired. Two hundred and fifty
+ * six is far above any real collaborative session; a further announce is
+ * refused with `backpressure`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultMaxParticipants = 256;
+/**
+ * Constructs the in-memory, lease-expiring presence registry.
+ *
+ * Announcing requires write access: a read-only share link may watch the
+ * roster but never appears on it, so a shared read link cannot be used to
+ * impersonate a collaborator. A live participant belongs to the capability
+ * that announced it, so another write link can neither overwrite nor evict it.
+ * Holders of one link share its `capabilityId` and stay indistinguishable.
+ *
+ * The roster is keyed by branch and then by participant, so listing one branch
+ * costs that branch plus a bounded sweep of other branches, and no two
+ * branches can share a slot. One flat key built by concatenation collided
+ * for valid branded ids, which let one announcement overwrite another branch's
+ * participant.
+ *
+ * The change feed slides at {@link defaultChangesCapacity}: announcing never
+ * waits on a stalled watcher, and never grows the process on its behalf.
+ *
+ * Fails with `invalid_request` when an option is not a positive safe integer.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeMemory: (options?: PresenceOptions) => Effect.Effect<Service, SyncError, BranchShare.BranchShare>;
+/**
+ * Provides the in-memory, lease-expiring presence registry under the default
+ * policy, which is valid by construction and so cannot fail.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<BranchPresence, never, BranchShare.BranchShare>;
+/**
+ * Provides the in-memory, lease-expiring presence registry under an explicit
+ * policy. Fails with `invalid_request` when an option is not a positive safe
+ * integer, so a bad policy fails the composition rather than an announcement.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerWith: (options: PresenceOptions) => Layer.Layer<BranchPresence, SyncError, BranchShare.BranchShare>;
+export {};
+//# sourceMappingURL=BranchPresence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BranchPresence.d.ts","sourceRoot":"","sources":["../../src/BranchPresence.ts"],"names":[],"mappings":"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"}

package/dist/esm/BranchPresence.js

@@ -0,0 +1,361 @@
+/**
+ * Ephemeral presence and cursors for one shared branch.
+ *
+ * Presence is deliberately NOT journalled. A roster is a lease table: every
+ * announcement extends a lease, and a participant that stops announcing —
+ * because the tab closed, the network dropped, or the process died — ages out
+ * without anyone reporting the disconnect. Writing presence to the journal
+ * would make "who was looking at this" part of the durable, replayable history
+ * of a run, which is both unbounded and wrong: replaying a branch must not
+ * resurrect a stranger's caret.
+ *
+ * Every operation authorizes through {@link BranchShare}, so a capability for
+ * one branch can neither read nor write another branch's roster. A live
+ * participant is bound to the capability that announced it: announcing or
+ * leaving under that `participantId` with any other capability is refused
+ * with `unauthorized` until the lease lapses.
+ *
+ * @since 0.1.0
+ */
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { Cursor, Participant, PresenceWhere } from "./BranchProtocol.js";
+import * as BranchShare from "./BranchShare.js";
+import { positiveInt } from "./internal/PolicyOptions.js";
+import { SyncError } from "./SyncError.js";
+/**
+ * The branch presence registry.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class BranchPresence extends Context.Service()("@smthrs/sync/BranchPresence") {
+}
+const unavailable = new SyncError({ code: "unsupported", message: "Branch presence is unavailable" });
+/**
+ * The lease {@link makeNoop} reports. It holds no one, so the value only has
+ * to be a positive number a watcher can build a re-list cadence from.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const defaultLeaseMs = 30_000;
+/**
+ * Constructs an unavailable presence registry.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (overrides = {}) => BranchPresence.of({
+    announce: () => Effect.fail(unavailable),
+    leave: () => Effect.fail(unavailable),
+    list: () => Effect.fail(unavailable),
+    presenceOn: () => Effect.succeed("unknown"),
+    changes: Stream.empty,
+    leaseMs: defaultLeaseMs,
+    ...overrides
+});
+/**
+ * Provides an unavailable presence registry.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.succeed(BranchPresence, makeNoop());
+const heldByAnother = (participantId) => new SyncError({
+    code: "unauthorized",
+    message: `Participant ${participantId} is held by another share capability`
+});
+/**
+ * Roster changes a stalled {@link Service.changes} subscriber may fall behind
+ * by before the oldest are dropped.
+ *
+ * Presence is a lease table, and `changes` only says that some branch's roster
+ * moved: a follower answers it with `list`. Holding an unbounded backlog for a
+ * subscriber that has stopped pulling would let one abandoned watcher retain
+ * every announcement the process has seen since. A subscriber that falls
+ * further behind than this bound loses the oldest notifications and re-lists;
+ * because every notification is answered by a fresh `list`, dropping one never
+ * loses roster state.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const defaultChangesCapacity = 256;
+/**
+ * Participants one branch may hold at once.
+ *
+ * A roster is unbounded fan-out in two directions: it is walked on every
+ * `list`, and `Branch.Roster` returns it whole, which no frame ceiling covers.
+ * Nothing caps how many distinct `participantId`s one write capability may
+ * announce, so without this a single share link could pin an arbitrary number
+ * of `Participant` objects until their leases expired. Two hundred and fifty
+ * six is far above any real collaborative session; a further announce is
+ * refused with `backpressure`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const defaultMaxParticipants = 256;
+const defaults = {
+    leaseMs: defaultLeaseMs,
+    changesCapacity: defaultChangesCapacity,
+    maxParticipants: defaultMaxParticipants,
+    sourcesReady: () => Effect.succeed(false)
+};
+/**
+ * Constructs the in-memory, lease-expiring presence registry.
+ *
+ * Announcing requires write access: a read-only share link may watch the
+ * roster but never appears on it, so a shared read link cannot be used to
+ * impersonate a collaborator. A live participant belongs to the capability
+ * that announced it, so another write link can neither overwrite nor evict it.
+ * Holders of one link share its `capabilityId` and stay indistinguishable.
+ *
+ * The roster is keyed by branch and then by participant, so listing one branch
+ * costs that branch plus a bounded sweep of other branches, and no two
+ * branches can share a slot. One flat key built by concatenation collided
+ * for valid branded ids, which let one announcement overwrite another branch's
+ * participant.
+ *
+ * The change feed slides at {@link defaultChangesCapacity}: announcing never
+ * waits on a stalled watcher, and never grows the process on its behalf.
+ *
+ * Fails with `invalid_request` when an option is not a positive safe integer.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeMemory = (options = {}) => Effect.flatMap(Effect.all({
+    leaseMs: positiveInt("BranchPresence.PresenceOptions.leaseMs", options.leaseMs, defaults.leaseMs),
+    changesCapacity: positiveInt("BranchPresence.PresenceOptions.changesCapacity", options.changesCapacity, defaults.changesCapacity),
+    maxParticipants: positiveInt("BranchPresence.PresenceOptions.maxParticipants", options.maxParticipants, defaults.maxParticipants)
+}), (resolved) => makeResolved({ ...resolved, sourcesReady: options.sourcesReady ?? defaults.sourcesReady }));
+/** The registry over an already-validated policy. */
+const makeResolved = ({ changesCapacity, leaseMs, maxParticipants, sourcesReady }) => Effect.gen(function* () {
+    const startedAtMs = yield* Clock.currentTimeMillis;
+    const share = yield* BranchShare.BranchShare;
+    const roster = new Map();
+    const changes = yield* PubSub.sliding(changesCapacity);
+    const expire = (branchId, nowMs) => {
+        const branch = roster.get(branchId);
+        if (branch === undefined)
+            return undefined;
+        for (const [participantId, seat] of branch) {
+            if (seat.participant.leaseExpiresAtMs <= nowMs)
+                branch.delete(participantId);
+        }
+        if (branch.size === 0) {
+            roster.delete(branchId);
+            return undefined;
+        }
+        return branch;
+    };
+    // Each announce/list advances through at most 16 branch maps. Their
+    // participant counts are capped, so unrelated activity reclaims abandoned
+    // rosters without scanning the entire registry in a single request.
+    let sweepCursor = roster.keys();
+    const sweep = (nowMs) => {
+        for (let index = 0; index < 16; index++) {
+            const next = sweepCursor.next();
+            if (next.done) {
+                sweepCursor = roster.keys();
+                break;
+            }
+            expire(next.value, nowMs);
+        }
+    };
+    const seatKey = (request) => JSON.stringify([request.participantId, request.sessionId ?? ""]);
+    const copyWhere = (where) => ({ ...where });
+    const detach = (participant) => new Participant({
+        ...participant,
+        ...(participant.where === undefined ? {} : { where: copyWhere(participant.where) }),
+        cursor: participant.cursor === null ? null : new Cursor(participant.cursor)
+    });
+    /**
+     * Drop this branch's expired leases and advance cleanup of other branches.
+     * Abandoned maps are reclaimed as announce/list calls advance the sweep;
+     * an idle registry keeps them until activity resumes. Results are detached
+     * from storage, including each participant's cursor.
+     */
+    const live = (branchId, nowMs) => {
+        sweep(nowMs);
+        const branch = expire(branchId, nowMs);
+        if (branch === undefined)
+            return [];
+        // Map entries have distinct seat keys, so compared seats cannot be equal.
+        return Array.from(branch.values(), (seat) => detach(seat.participant)).sort((left, right) => seatKey(left) < seatKey(right) ? -1 : 1);
+    };
+    /**
+     * Copy a request out of the caller's object before the first await.
+     *
+     * `share.verify` awaits Web Crypto between authorizing `branchId` and the
+     * roster access that follows. The request objects are plain structs the
+     * in-process caller still holds, so reading them again after the await let
+     * a caller move `branchId` (or the participant identity) onto a branch the
+     * capability never authorized. Matches the claim snapshot in `BranchShare`.
+     */
+    const detachRoster = (request) => ({
+        capability: request.capability,
+        branchId: request.branchId
+    });
+    const detachLeave = (request) => ({
+        ...detachRoster(request),
+        participantId: request.participantId,
+        ...(request.sessionId === undefined ? {} : { sessionId: request.sessionId })
+    });
+    const detachAnnouncement = (request) => {
+        const suppliedCursor = request.cursor;
+        const cursor = suppliedCursor === null
+            ? null
+            : typeof suppliedCursor === "object"
+                ? { cardId: suppliedCursor.cardId, offset: suppliedCursor.offset }
+                : { cardId: undefined, offset: undefined };
+        return {
+            ...detachLeave(request),
+            displayName: request.displayName,
+            cursor,
+            ...(request.kind === undefined ? {} : { kind: request.kind }),
+            ...(request.where === undefined ? {} : { where: copyWhere(request.where) }),
+            ...(request.watching === undefined ? {} : { watching: request.watching }),
+            ...(request.for_member === undefined ? {} : { for_member: request.for_member }),
+            ...(request.agentKind === undefined ? {} : { agentKind: request.agentKind }),
+            ...(request.via === undefined ? {} : { via: request.via }),
+            ...(request.runId === undefined ? {} : { runId: request.runId })
+        };
+    };
+    const announce = Effect.fn("BranchPresence.announce")(function* (supplied) {
+        const detached = detachAnnouncement(supplied);
+        yield* Effect.annotateCurrentSpan({
+            branchId: detached.branchId,
+            participantId: detached.participantId
+        });
+        const claims = yield* share.verify(detached.capability, {
+            branchId: detached.branchId,
+            access: "write"
+        });
+        // The wire schema IS `Announcement`, so a remote caller cannot reach
+        // here with an empty name. An in-process caller can, and `Participant`
+        // requires a `NonEmptyString`: without this the constructor threw a
+        // defect out of an operation whose type promises a `SyncError`.
+        if (detached.displayName.length === 0) {
+            return yield* Effect.fail(new SyncError({ code: "invalid_request", message: "A participant's display name must not be empty" }));
+        }
+        if (detached.where !== undefined && !Schema.is(PresenceWhere)(detached.where)) {
+            return yield* Effect.fail(new SyncError({ code: "invalid_request", message: "Invalid presence location" }));
+        }
+        if (detached.sessionId !== undefined && detached.sessionId.length === 0) {
+            return yield* Effect.fail(new SyncError({ code: "invalid_request", message: "Invalid presence session" }));
+        }
+        let cursor = null;
+        if (detached.cursor !== null) {
+            const { cardId, offset } = detached.cursor;
+            if (typeof cardId !== "string" || cardId.length === 0) {
+                return yield* Effect.fail(new SyncError({ code: "invalid_request", message: "A cursor's card ID must not be empty" }));
+            }
+            if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0) {
+                return yield* Effect.fail(new SyncError({ code: "invalid_request", message: "A cursor's offset must be a nonnegative safe integer" }));
+            }
+            cursor = new Cursor({ cardId, offset });
+        }
+        const announcement = { ...detached, cursor };
+        const nowMs = yield* Clock.currentTimeMillis;
+        // Run-out leases are dropped before the cap is judged, so a branch that
+        // has simply been busy over time is never refused for a stale roster.
+        live(announcement.branchId, nowMs);
+        const branch = roster.get(announcement.branchId) ?? new Map();
+        const held = branch.get(seatKey(announcement));
+        // A session suffix must not bypass the existing participant ownership
+        // fence. The host may bind multiple sessions to one actor capability.
+        const foreignActor = Array.from(branch.values()).some((seat) => seat.participant.participantId === announcement.participantId && seat.capabilityId !== claims.capabilityId);
+        if (foreignActor || (held !== undefined && held.capabilityId !== claims.capabilityId)) {
+            return yield* Effect.fail(heldByAnother(announcement.participantId));
+        }
+        if (held === undefined && branch.size >= maxParticipants) {
+            return yield* Effect.fail(new SyncError({
+                code: "backpressure",
+                message: `Branch ${announcement.branchId} already holds ${maxParticipants} participants`
+            }));
+        }
+        const participant = new Participant({
+            branchId: announcement.branchId,
+            participantId: announcement.participantId,
+            displayName: announcement.displayName,
+            cursor: announcement.cursor,
+            ...(announcement.sessionId === undefined ? {} : { sessionId: announcement.sessionId }),
+            ...(announcement.kind === undefined ? {} : { kind: announcement.kind }),
+            ...(announcement.where === undefined ? {} : { where: announcement.where }),
+            ...(announcement.watching === undefined ? {} : { watching: announcement.watching }),
+            ...(announcement.for_member === undefined ? {} : { for_member: announcement.for_member }),
+            ...(announcement.agentKind === undefined ? {} : { agentKind: announcement.agentKind }),
+            ...(announcement.via === undefined ? {} : { via: announcement.via }),
+            ...(announcement.runId === undefined ? {} : { runId: announcement.runId }),
+            leaseExpiresAtMs: nowMs + leaseMs
+        });
+        branch.set(seatKey(announcement), { participant, capabilityId: claims.capabilityId });
+        roster.set(announcement.branchId, branch);
+        yield* PubSub.publish(changes, announcement.branchId);
+        return detach(participant);
+    });
+    const leave = Effect.fn("BranchPresence.leave")(function* (supplied) {
+        const request = detachLeave(supplied);
+        yield* Effect.annotateCurrentSpan({ branchId: request.branchId, participantId: request.participantId });
+        const claims = yield* share.verify(request.capability, { branchId: request.branchId, access: "write" });
+        const branch = expire(request.branchId, yield* Clock.currentTimeMillis);
+        if (branch !== undefined) {
+            const keys = request.sessionId === undefined
+                ? [...branch].filter(([, seat]) => seat.participant.participantId === request.participantId)
+                    .map(([key]) => key)
+                : [seatKey(request)];
+            for (const key of keys) {
+                const held = branch.get(key);
+                if (held !== undefined && held.capabilityId !== claims.capabilityId) {
+                    return yield* Effect.fail(heldByAnother(request.participantId));
+                }
+            }
+            for (const key of keys)
+                branch.delete(key);
+            if (branch.size === 0)
+                roster.delete(request.branchId);
+        }
+        yield* PubSub.publish(changes, request.branchId);
+    });
+    const list = Effect.fn("BranchPresence.list")(function* (supplied) {
+        const request = detachRoster(supplied);
+        yield* Effect.annotateCurrentSpan({ branchId: request.branchId });
+        yield* share.verify(request.capability, { branchId: request.branchId, access: "read" });
+        return live(request.branchId, yield* Clock.currentTimeMillis);
+    });
+    const presenceOn = Effect.fn("BranchPresence.presenceOn")(function* (supplied) {
+        const request = detachRoster(supplied);
+        yield* share.verify(request.capability, { branchId: request.branchId, access: "read" });
+        const nowMs = yield* Clock.currentTimeMillis;
+        if (nowMs - startedAtMs < leaseMs || !(yield* sourcesReady(request.branchId)))
+            return "unknown";
+        return live(request.branchId, nowMs).length === 0 ? "empty" : "present";
+    });
+    return BranchPresence.of({ announce, leave, list, presenceOn, changes: Stream.fromPubSub(changes), leaseMs });
+});
+/**
+ * Provides the in-memory, lease-expiring presence registry under the default
+ * policy, which is valid by construction and so cannot fail.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.effect(BranchPresence, makeResolved(defaults));
+/**
+ * Provides the in-memory, lease-expiring presence registry under an explicit
+ * policy. Fails with `invalid_request` when an option is not a positive safe
+ * integer, so a bad policy fails the composition rather than an announcement.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerWith = (options) => Layer.effect(BranchPresence, makeMemory(options));
+//# sourceMappingURL=BranchPresence.js.map