@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/connections/protocol.d.ts

@@ -0,0 +1,441 @@
+import { Schema } from "effect";
+import { Entity } from "effect/cluster";
+import { Rpc } from "effect/rpc";
+import { ActorError, SessionEnded } from "../../errors/actor.ts";
+/**
+ * The framework connection member an event feed opens. It has no handler, and
+ * `$` can't start a declared member's tag, so it never collides with one.
+ */
+export declare const FEED_MEMBER = "$feed";
+/** The prefix of the framework connection member a query watch opens; the watched query's tag follows. */
+export declare const WATCH_PREFIX = "$watch:";
+/** The framework connection member that watches `query`. `$` can't start a declared member's tag, so it never collides with one. */
+export declare const watchMember: (query: string) => string;
+/** Whether `member` is a framework watch connection. */
+export declare const isWatchMember: (member: string) => boolean;
+/** The query a framework watch member watches. */
+export declare const watchedQuery: (member: string) => string;
+/** What one commit wrote: whether it changed state, and the event classes, tables, and blobs it wrote. */
+export declare const WriteSet: Schema.Struct<{
+    readonly state: Schema.Boolean;
+    readonly events: Schema.$Array<Schema.String>;
+    readonly tables: Schema.$Array<Schema.String>;
+    readonly blobs: Schema.$Array<Schema.String>;
+}>;
+/** What one commit wrote. */
+export type WriteSet = typeof WriteSet.Type;
+/** The frame an owner broadcasts to an actor's watches after each commit: the commit's version and its write set. */
+export declare const Committed: Schema.Struct<{
+    readonly version: Schema.String;
+    readonly writes: Schema.Struct<{
+        readonly state: Schema.Boolean;
+        readonly events: Schema.$Array<Schema.String>;
+        readonly tables: Schema.$Array<Schema.String>;
+        readonly blobs: Schema.$Array<Schema.String>;
+    }>;
+}>;
+/** A decoded `Committed` frame. */
+export type Committed = typeof Committed.Type;
+/** One committed feed event as its owner broadcasts it; `value` is the stored encoding. */
+export declare const FeedFrame: Schema.Struct<{
+    readonly tag: Schema.String;
+    readonly value: Schema.String;
+    readonly commandId: Schema.String;
+    readonly timestampMs: Schema.Finite;
+}>;
+/** A committed feed event as a holder receives it. */
+export type FeedFrame = typeof FeedFrame.Type;
+/** What an owner sends a holder over its ordered channel. */
+export declare const HolderItem: Schema.TaggedUnion<{
+    readonly End: Schema.TaggedStruct<"End", {
+        readonly connectionId: Schema.String;
+        readonly ended: typeof SessionEnded;
+    }>;
+    readonly Flushed: Schema.TaggedStruct<"Flushed", {
+        readonly through: Schema.String;
+    }>;
+    readonly Frame: Schema.TaggedStruct<"Frame", {
+        readonly member: Schema.String;
+        readonly to: Schema.$Array<Schema.String>;
+        readonly frame: Schema.String;
+        readonly event: Schema.optional<Schema.String>;
+        readonly stamp: Schema.Boolean;
+        readonly replay: Schema.optional<Schema.Boolean>;
+    }>;
+    readonly Progress: Schema.TaggedStruct<"Progress", {
+        readonly member: Schema.String;
+        readonly to: Schema.$Array<Schema.String>;
+        readonly job: Schema.String;
+        readonly jobId: Schema.String;
+        readonly attempt: Schema.Finite;
+        readonly seq: Schema.Finite;
+        readonly frame: Schema.String;
+    }>;
+    readonly ProgressEnd: Schema.TaggedStruct<"ProgressEnd", {
+        readonly jobId: Schema.String;
+    }>;
+    readonly Seal: Schema.TaggedStruct<"Seal", {}>;
+}>;
+/** One item of an ordered owner-to-holder message. */
+export type HolderItem = typeof HolderItem.Type;
+/** What a client of an open connection receives. */
+export declare const ClientMessage: Schema.TaggedUnion<{
+    readonly Frame: Schema.TaggedStruct<"Frame", {
+        readonly frame: Schema.String;
+        readonly cursor: Schema.optional<Schema.String>;
+        readonly event: Schema.optional<Schema.String>;
+    }>;
+    readonly Progress: Schema.TaggedStruct<"Progress", {
+        readonly job: Schema.String;
+        readonly jobId: Schema.String;
+        readonly attempt: Schema.Finite;
+        readonly seq: Schema.Finite;
+        readonly frame: Schema.String;
+    }>;
+    readonly Resync: Schema.TaggedStruct<"Resync", {
+        readonly after: Schema.UndefinedOr<Schema.String>;
+        readonly reason: Schema.Literal<"OwnerLost">;
+        readonly deadlineMs: Schema.Finite;
+    }>;
+    readonly ResyncReplayed: Schema.TaggedStruct<"ResyncReplayed", {}>;
+}>;
+/** A message a client of an open connection receives. */
+export type ClientMessage = typeof ClientMessage.Type;
+/** One ordered owner message to a holder: `seq` numbers it within its generation and `through` is the owner position it covers. */
+export declare const Deliver: Schema.Struct<{
+    readonly epoch: Schema.String;
+    readonly owner: Schema.String;
+    readonly ownerEpoch: Schema.String;
+    readonly ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly generation: Schema.String;
+    readonly seq: Schema.Finite;
+    readonly through: Schema.String;
+    readonly items: Schema.$Array<Schema.TaggedUnion<{
+        readonly End: Schema.TaggedStruct<"End", {
+            readonly connectionId: Schema.String;
+            readonly ended: typeof SessionEnded;
+        }>;
+        readonly Flushed: Schema.TaggedStruct<"Flushed", {
+            readonly through: Schema.String;
+        }>;
+        readonly Frame: Schema.TaggedStruct<"Frame", {
+            readonly member: Schema.String;
+            readonly to: Schema.$Array<Schema.String>;
+            readonly frame: Schema.String;
+            readonly event: Schema.optional<Schema.String>;
+            readonly stamp: Schema.Boolean;
+            readonly replay: Schema.optional<Schema.Boolean>;
+        }>;
+        readonly Progress: Schema.TaggedStruct<"Progress", {
+            readonly member: Schema.String;
+            readonly to: Schema.$Array<Schema.String>;
+            readonly job: Schema.String;
+            readonly jobId: Schema.String;
+            readonly attempt: Schema.Finite;
+            readonly seq: Schema.Finite;
+            readonly frame: Schema.String;
+        }>;
+        readonly ProgressEnd: Schema.TaggedStruct<"ProgressEnd", {
+            readonly jobId: Schema.String;
+        }>;
+        readonly Seal: Schema.TaggedStruct<"Seal", {}>;
+    }>>;
+}>;
+/** A decoded `Deliver`. */
+export type Deliver = typeof Deliver.Type;
+/** A holder's acknowledgment: `wrongEpoch` when it is not the holder the owner addressed, and the ids of addressed connections it does not hold. */
+export declare const Delivered: Schema.Struct<{
+    readonly wrongEpoch: Schema.Boolean;
+    readonly unknown: Schema.$Array<Schema.String>;
+}>;
+/** A decoded `Delivered`. */
+export type Delivered = typeof Delivered.Type;
+/**
+ * A runner's holder shard group, which only that runner is assigned. Cluster
+ * stores shard ids in 50 characters, so the group is a hash of the address.
+ */
+export declare const holderGroup: (address: {
+    readonly host: string;
+    readonly port: number;
+}) => string;
+/** The entity id addressing one holder incarnation, from its runner identity and epoch. */
+export declare const holderEntityId: (address: {
+    readonly holder: string;
+    readonly epoch: string;
+}) => string;
+/** The framework entity through which owners on other runners reach this runner's holder. */
+export declare const HolderEntity: Entity.Entity<"akter/Holder", Rpc.Rpc<"Deliver", Schema.Struct<{
+    readonly epoch: Schema.String;
+    readonly owner: Schema.String;
+    readonly ownerEpoch: Schema.String;
+    readonly ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly generation: Schema.String;
+    readonly seq: Schema.Finite;
+    readonly through: Schema.String;
+    readonly items: Schema.$Array<Schema.TaggedUnion<{
+        readonly End: Schema.TaggedStruct<"End", {
+            readonly connectionId: Schema.String;
+            readonly ended: typeof SessionEnded;
+        }>;
+        readonly Flushed: Schema.TaggedStruct<"Flushed", {
+            readonly through: Schema.String;
+        }>;
+        readonly Frame: Schema.TaggedStruct<"Frame", {
+            readonly member: Schema.String;
+            readonly to: Schema.$Array<Schema.String>;
+            readonly frame: Schema.String;
+            readonly event: Schema.optional<Schema.String>;
+            readonly stamp: Schema.Boolean;
+            readonly replay: Schema.optional<Schema.Boolean>;
+        }>;
+        readonly Progress: Schema.TaggedStruct<"Progress", {
+            readonly member: Schema.String;
+            readonly to: Schema.$Array<Schema.String>;
+            readonly job: Schema.String;
+            readonly jobId: Schema.String;
+            readonly attempt: Schema.Finite;
+            readonly seq: Schema.Finite;
+            readonly frame: Schema.String;
+        }>;
+        readonly ProgressEnd: Schema.TaggedStruct<"ProgressEnd", {
+            readonly jobId: Schema.String;
+        }>;
+        readonly Seal: Schema.TaggedStruct<"Seal", {}>;
+    }>>;
+}>, Schema.Struct<{
+    readonly wrongEpoch: Schema.Boolean;
+    readonly unknown: Schema.$Array<Schema.String>;
+}>, Schema.Never, never, never> | Rpc.Rpc<"Ping", Schema.Struct<{
+    epoch: Schema.String;
+}>, Schema.Boolean, Schema.Never, never, never>>;
+/** The fields that locate one connection: its actor, id, holder, and holder epoch. */
+export declare const ConnectionAddress: {
+    ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    connectionId: Schema.String;
+    holder: Schema.String;
+    holderEpoch: Schema.String;
+};
+/** The owner's answer to an open: the baseline it fixed, or the handler's declared failure. */
+export declare const Opened: Schema.TaggedUnion<{
+    readonly Failed: Schema.TaggedStruct<"Failed", {
+        readonly value: Schema.String;
+    }>;
+    readonly Opened: Schema.TaggedStruct<"Opened", {
+        readonly generation: Schema.String;
+        readonly owner: Schema.String;
+        readonly ownerEpoch: Schema.String;
+        readonly baseline: Schema.String;
+        readonly recovered: Schema.optional<Schema.Boolean>;
+    }>;
+}>;
+/** The owner's answer to an acknowledgment: accepted, or the session ended. */
+export declare const Acked: Schema.TaggedUnion<{
+    readonly Acked: Schema.TaggedStruct<"Acked", {
+        generation: Schema.String;
+        owner: Schema.String;
+        ownerEpoch: Schema.String;
+    }>;
+    readonly Closed: Schema.TaggedStruct<"Closed", {
+        readonly ended: typeof SessionEnded;
+    }>;
+}>;
+/** The owner's answer to a finished resync replay: accepted, or the session ended. */
+export declare const Replayed: Schema.TaggedUnion<{
+    readonly Closed: Schema.TaggedStruct<"Closed", {
+        readonly ended: typeof SessionEnded;
+    }>;
+    readonly Replayed: Schema.TaggedStruct<"Replayed", {
+        generation: Schema.String;
+        owner: Schema.String;
+        ownerEpoch: Schema.String;
+    }>;
+}>;
+/** What a stream subscription receives from the owner, after which the owner's errors follow. */
+export declare const StreamItem: Schema.TaggedUnion<{
+    readonly Done: Schema.TaggedStruct<"Done", {}>;
+    readonly Element: Schema.TaggedStruct<"Element", {
+        readonly value: Schema.String;
+    }>;
+    readonly Started: Schema.TaggedStruct<"Started", {
+        readonly owner: Schema.String;
+        readonly ownerEpoch: Schema.String;
+    }>;
+}>;
+/** A decoded `StreamItem`. */
+export type StreamItem = typeof StreamItem.Type;
+/** A stream handler's declared failure, encoded. */
+export declare const StreamFailed: Schema.TaggedStruct<"StreamFailed", {
+    readonly value: Schema.String;
+}>;
+/**
+ * Messages a holder or a stream subscriber sends an actor's owner; they
+ * bypass the command mailbox. A subscription is interruptible, so a
+ * subscriber that stops ends the handler on the owner.
+ */
+export declare const connectionsEntity: (name: string) => Entity.Entity<`${string}/Connections`, Rpc.Rpc<"Close", Schema.Struct<{
+    ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    connectionId: Schema.String;
+    holder: Schema.String;
+    holderEpoch: Schema.String;
+    cause: typeof SessionEnded;
+}>, Schema.Void, typeof ActorError, never, never> | Rpc.Rpc<"Frame", Schema.Struct<{
+    ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    connectionId: Schema.String;
+    holder: Schema.String;
+    holderEpoch: Schema.String;
+    seq: Schema.Finite;
+    frame: Schema.String;
+    authorizedUntil: Schema.Finite;
+    commands: Schema.Struct<{
+        readonly secret: Schema.String;
+        readonly seq: Schema.Finite;
+        readonly issuedAt: Schema.Finite;
+        readonly expiresAt: Schema.Finite;
+    }>;
+}>, Schema.TaggedUnion<{
+    readonly Acked: Schema.TaggedStruct<"Acked", {
+        generation: Schema.String;
+        owner: Schema.String;
+        ownerEpoch: Schema.String;
+    }>;
+    readonly Closed: Schema.TaggedStruct<"Closed", {
+        readonly ended: typeof SessionEnded;
+    }>;
+}>, typeof ActorError, never, never> | Rpc.Rpc<"Open", Schema.Struct<{
+    ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    connectionId: Schema.String;
+    holder: Schema.String;
+    holderEpoch: Schema.String;
+    member: Schema.String;
+    caller: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"User", {
+        readonly subject: Schema.NonEmptyString;
+    }>, Schema.TaggedStruct<"Anonymous", {}>, Schema.TaggedStruct<"System", {
+        readonly source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription"]>;
+        readonly ref: Schema.optional<Schema.Struct<{
+            readonly tenant: Schema.NonEmptyString;
+            readonly actor: Schema.NonEmptyString;
+            readonly id: Schema.NonEmptyString;
+        }>>;
+        readonly onBehalfOf: Schema.optional<Schema.Struct<{
+            readonly subject: Schema.NonEmptyString;
+        }>>;
+        readonly mint: Schema.optional<Schema.Struct<{
+            readonly commandId: Schema.String;
+            readonly ordinal: Schema.Int;
+        }>>;
+    }>]>;
+    params: Schema.String;
+    commands: Schema.Struct<{
+        readonly secret: Schema.String;
+        readonly seq: Schema.Finite;
+        readonly issuedAt: Schema.Finite;
+        readonly expiresAt: Schema.Finite;
+    }>;
+}>, Schema.TaggedUnion<{
+    readonly Failed: Schema.TaggedStruct<"Failed", {
+        readonly value: Schema.String;
+    }>;
+    readonly Opened: Schema.TaggedStruct<"Opened", {
+        readonly generation: Schema.String;
+        readonly owner: Schema.String;
+        readonly ownerEpoch: Schema.String;
+        readonly baseline: Schema.String;
+        readonly recovered: Schema.optional<Schema.Boolean>;
+    }>;
+}>, typeof ActorError, never, never> | Rpc.Rpc<"Progress", Schema.Struct<{
+    ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    jobId: Schema.String;
+    job: Schema.String;
+    attempt: Schema.Finite;
+    seq: Schema.Finite;
+    leaseUntil: Schema.Finite;
+    frame: Schema.String;
+}>, Schema.Void, Schema.Never, never, never> | Rpc.Rpc<"ProgressClosed", Schema.Struct<{
+    ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    jobId: Schema.String;
+    attempt: Schema.Finite;
+}>, Schema.Void, Schema.Never, never, never> | Rpc.Rpc<"Resync", Schema.Struct<{
+    ref: Schema.Struct<{
+        readonly tenant: Schema.NonEmptyString;
+        readonly actor: Schema.NonEmptyString;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    connectionId: Schema.String;
+    holder: Schema.String;
+    holderEpoch: Schema.String;
+    after: Schema.optional<Schema.String>;
+    authorizedUntil: Schema.Finite;
+}>, Schema.TaggedUnion<{
+    readonly Closed: Schema.TaggedStruct<"Closed", {
+        readonly ended: typeof SessionEnded;
+    }>;
+    readonly Replayed: Schema.TaggedStruct<"Replayed", {
+        generation: Schema.String;
+        owner: Schema.String;
+        ownerEpoch: Schema.String;
+    }>;
+}>, typeof ActorError, never, never> | Rpc.Rpc<"Subscribe", Schema.Struct<{
+    member: Schema.String;
+    caller: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"User", {
+        readonly subject: Schema.NonEmptyString;
+    }>, Schema.TaggedStruct<"Anonymous", {}>, Schema.TaggedStruct<"System", {
+        readonly source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription"]>;
+        readonly ref: Schema.optional<Schema.Struct<{
+            readonly tenant: Schema.NonEmptyString;
+            readonly actor: Schema.NonEmptyString;
+            readonly id: Schema.NonEmptyString;
+        }>>;
+        readonly onBehalfOf: Schema.optional<Schema.Struct<{
+            readonly subject: Schema.NonEmptyString;
+        }>>;
+        readonly mint: Schema.optional<Schema.Struct<{
+            readonly commandId: Schema.String;
+            readonly ordinal: Schema.Int;
+        }>>;
+    }>]>;
+    input: Schema.String;
+    authorizedUntil: Schema.Finite;
+}>, import("effect/rpc/RpcSchema").Stream<Schema.TaggedUnion<{
+    readonly Done: Schema.TaggedStruct<"Done", {}>;
+    readonly Element: Schema.TaggedStruct<"Element", {
+        readonly value: Schema.String;
+    }>;
+    readonly Started: Schema.TaggedStruct<"Started", {
+        readonly owner: Schema.String;
+        readonly ownerEpoch: Schema.String;
+    }>;
+}>, Schema.Union<readonly [typeof ActorError, Schema.TaggedStruct<"StreamFailed", {
+    readonly value: Schema.String;
+}>]>>, Schema.Never, never, never>>;

package/dist/runtime/connections/protocol.js

@@ -0,0 +1,222 @@
+import { Schema } from "effect";
+import { ClusterSchema, Entity } from "effect/cluster";
+import { Rpc } from "effect/rpc";
+import { ActorError, SessionEnded } from "../../errors/actor.js";
+import { ActorRef, Caller } from "../../identity/caller.js";
+import { hash64 } from "../storage/platform.js";
+/**
+ * The framework connection member an event feed opens. It has no handler, and
+ * `$` can't start a declared member's tag, so it never collides with one.
+ */
+export const FEED_MEMBER = "$feed";
+/** The prefix of the framework connection member a query watch opens; the watched query's tag follows. */
+export const WATCH_PREFIX = "$watch:";
+/** The framework connection member that watches `query`. `$` can't start a declared member's tag, so it never collides with one. */
+export const watchMember = (query) => `${WATCH_PREFIX}${query}`;
+/** Whether `member` is a framework watch connection. */
+export const isWatchMember = (member) => member.startsWith(WATCH_PREFIX);
+/** The query a framework watch member watches. */
+export const watchedQuery = (member) => member.slice(WATCH_PREFIX.length);
+/** What one commit wrote: whether it changed state, and the event classes, tables, and blobs it wrote. */
+export const WriteSet = Schema.Struct({
+    state: Schema.Boolean,
+    events: Schema.Array(Schema.String),
+    tables: Schema.Array(Schema.String),
+    blobs: Schema.Array(Schema.String),
+});
+/** The frame an owner broadcasts to an actor's watches after each commit: the commit's version and its write set. */
+export const Committed = Schema.Struct({ version: Schema.String, writes: WriteSet });
+/** One committed feed event as its owner broadcasts it; `value` is the stored encoding. */
+export const FeedFrame = Schema.Struct({
+    tag: Schema.String,
+    value: Schema.String,
+    commandId: Schema.String,
+    timestampMs: Schema.Finite,
+});
+/** What an owner sends a holder over its ordered channel. */
+export const HolderItem = Schema.TaggedUnion({
+    Frame: {
+        member: Schema.String,
+        to: Schema.Array(Schema.String),
+        frame: Schema.String,
+        event: Schema.optional(Schema.String),
+        stamp: Schema.Boolean,
+        replay: Schema.optional(Schema.Boolean),
+    },
+    Flushed: { through: Schema.String },
+    End: { connectionId: Schema.String, ended: SessionEnded },
+    Seal: {},
+    /** Executor progress: replaces an undelivered frame of the same job, never closes a session. */
+    Progress: {
+        member: Schema.String,
+        to: Schema.Array(Schema.String),
+        job: Schema.String,
+        jobId: Schema.String,
+        attempt: Schema.Finite,
+        seq: Schema.Finite,
+        frame: Schema.String,
+    },
+    /** The job's route or settle committed: undelivered progress of it is discarded. */
+    ProgressEnd: { jobId: Schema.String },
+});
+/** What a client of an open connection receives. */
+export const ClientMessage = Schema.TaggedUnion({
+    Frame: {
+        frame: Schema.String,
+        cursor: Schema.optional(Schema.String),
+        event: Schema.optional(Schema.String),
+    },
+    Resync: {
+        after: Schema.UndefinedOr(Schema.String),
+        reason: Schema.Literal("OwnerLost"),
+        deadlineMs: Schema.Finite,
+    },
+    ResyncReplayed: {},
+    Progress: {
+        job: Schema.String,
+        jobId: Schema.String,
+        attempt: Schema.Finite,
+        seq: Schema.Finite,
+        frame: Schema.String,
+    },
+});
+/** One ordered owner message to a holder: `seq` numbers it within its generation and `through` is the owner position it covers. */
+export const Deliver = Schema.Struct({
+    epoch: Schema.String,
+    owner: Schema.String,
+    ownerEpoch: Schema.String,
+    ref: ActorRef,
+    generation: Schema.String,
+    seq: Schema.Finite,
+    through: Schema.String,
+    items: Schema.Array(HolderItem),
+});
+/** A holder's acknowledgment: `wrongEpoch` when it is not the holder the owner addressed, and the ids of addressed connections it does not hold. */
+export const Delivered = Schema.Struct({
+    wrongEpoch: Schema.Boolean,
+    unknown: Schema.Array(Schema.String),
+});
+const HOLDER_SEPARATOR = "|";
+/**
+ * A runner's holder shard group, which only that runner is assigned. Cluster
+ * stores shard ids in 50 characters, so the group is a hash of the address.
+ */
+export const holderGroup = (address) => `h${BigInt.asUintN(64, hash64(`${address.host}:${address.port}`)).toString(36)}`;
+/** The entity id addressing one holder incarnation, from its runner identity and epoch. */
+export const holderEntityId = (address) => `${address.holder}${HOLDER_SEPARATOR}${address.epoch}`;
+/** The framework entity through which owners on other runners reach this runner's holder. */
+export const HolderEntity = Entity.make("akter/Holder", [
+    Rpc.make("Deliver", { payload: Deliver, success: Delivered }),
+    Rpc.make("Ping", { payload: { epoch: Schema.String }, success: Schema.Boolean }),
+]).annotate(ClusterSchema.ShardGroup, (entityId) => entityId.split(HOLDER_SEPARATOR)[0]);
+/** The fields that locate one connection: its actor, id, holder, and holder epoch. */
+export const ConnectionAddress = {
+    ref: ActorRef,
+    connectionId: Schema.String,
+    holder: Schema.String,
+    holderEpoch: Schema.String,
+};
+const Commands = Schema.Struct({
+    secret: Schema.String,
+    seq: Schema.Finite,
+    issuedAt: Schema.Finite,
+    expiresAt: Schema.Finite,
+});
+/** The activation that answered: its fencing generation and its runner's holder identity. */
+const OwnerIdentity = {
+    generation: Schema.String,
+    owner: Schema.String,
+    ownerEpoch: Schema.String,
+};
+/** The owner's answer to an open: the baseline it fixed, or the handler's declared failure. */
+export const Opened = Schema.TaggedUnion({
+    Opened: { ...OwnerIdentity, baseline: Schema.String, recovered: Schema.optional(Schema.Boolean) },
+    Failed: { value: Schema.String },
+});
+/** The owner's answer to an acknowledgment: accepted, or the session ended. */
+export const Acked = Schema.TaggedUnion({
+    Acked: OwnerIdentity,
+    Closed: { ended: SessionEnded },
+});
+/** The owner's answer to a finished resync replay: accepted, or the session ended. */
+export const Replayed = Schema.TaggedUnion({
+    Replayed: OwnerIdentity,
+    Closed: { ended: SessionEnded },
+});
+/** What a stream subscription receives from the owner, after which the owner's errors follow. */
+export const StreamItem = Schema.TaggedUnion({
+    /** The activation that runs the handler; a second one means the request was sent again. */
+    Started: { owner: Schema.String, ownerEpoch: Schema.String },
+    Element: { value: Schema.String },
+    /** The handler's stream ended by itself. */
+    Done: {},
+});
+/** A stream handler's declared failure, encoded. */
+export const StreamFailed = Schema.TaggedStruct("StreamFailed", { value: Schema.String });
+/**
+ * Messages a holder or a stream subscriber sends an actor's owner; they
+ * bypass the command mailbox. A subscription is interruptible, so a
+ * subscriber that stops ends the handler on the owner.
+ */
+export const connectionsEntity = (name) => Entity.make(`${name}/Connections`, [
+    Rpc.make("Open", {
+        payload: {
+            ...ConnectionAddress,
+            member: Schema.String,
+            caller: Caller,
+            params: Schema.String,
+            commands: Commands,
+        },
+        success: Opened,
+        error: ActorError,
+    }).annotate(ClusterSchema.Uninterruptible, true),
+    Rpc.make("Frame", {
+        payload: {
+            ...ConnectionAddress,
+            seq: Schema.Finite,
+            frame: Schema.String,
+            authorizedUntil: Schema.Finite,
+            commands: Commands,
+        },
+        success: Acked,
+        error: ActorError,
+    }).annotate(ClusterSchema.Uninterruptible, true),
+    Rpc.make("Close", {
+        payload: { ...ConnectionAddress, cause: SessionEnded },
+        error: ActorError,
+    }).annotate(ClusterSchema.Uninterruptible, true),
+    Rpc.make("Resync", {
+        payload: {
+            ...ConnectionAddress,
+            after: Schema.optional(Schema.String),
+            authorizedUntil: Schema.Finite,
+        },
+        success: Replayed,
+        error: ActorError,
+    }).annotate(ClusterSchema.Uninterruptible, true),
+    Rpc.make("Progress", {
+        payload: {
+            ref: ActorRef,
+            jobId: Schema.String,
+            job: Schema.String,
+            attempt: Schema.Finite,
+            seq: Schema.Finite,
+            leaseUntil: Schema.Finite,
+            frame: Schema.String,
+        },
+    }).annotate(ClusterSchema.Uninterruptible, true),
+    Rpc.make("ProgressClosed", {
+        payload: { ref: ActorRef, jobId: Schema.String, attempt: Schema.Finite },
+    }).annotate(ClusterSchema.Uninterruptible, true),
+    Rpc.make("Subscribe", {
+        payload: {
+            member: Schema.String,
+            caller: Caller,
+            input: Schema.String,
+            authorizedUntil: Schema.Finite,
+        },
+        success: StreamItem,
+        error: Schema.Union([ActorError, StreamFailed]),
+        stream: true,
+    }),
+]);

package/dist/runtime/connections/reads.d.ts

@@ -0,0 +1,24 @@
+import type { WriteSet } from "./protocol.ts";
+/**
+ * What one rerun of a watched query read, as the recorder saw it: whether it
+ * touched `state` (all keyed state counts as one), and the event classes,
+ * tables, and blobs it named. `group` and `caller` note reads the commit signal
+ * cannot cover or that make the result depend on who asked.
+ */
+export interface ReadSet {
+    state: boolean;
+    readonly events: Set<string>;
+    readonly tables: Set<string>;
+    readonly blobs: Set<string>;
+    group: boolean;
+    caller: boolean;
+}
+/** A read set that has recorded nothing. */
+export declare const emptyReadSet: () => ReadSet;
+/** Whether a commit that wrote `writes` may have changed the result of a query that read `reads`. */
+export declare const invalidates: {
+    (reads: ReadSet): (writes: WriteSet) => boolean;
+    (writes: WriteSet, reads: ReadSet): boolean;
+};
+/** The read that makes a query unwatchable, named for the refusal; undefined when every read is supported. */
+export declare const unsupportedRead: (reads: ReadSet) => "The query reads its placement group, which has no commit signal per actor" | undefined;