@rikalabs/akter 0.1.0-alpha.0

package/dist/serve/sessions/socket.d.ts

@@ -0,0 +1,56 @@
+import { Effect } from "effect";
+import { Socket } from "effect/socket";
+import type { ServedConnection } from "../../actor/served.ts";
+import { ActorError } from "../../errors/actor.ts";
+import { type ActorRef } from "../../identity/caller.ts";
+import { type Holder } from "../../runtime/connections/holder.ts";
+import type { Authenticated } from "../auth.ts";
+/** Sockets one runner holds between their upgrade and their `hello`. */
+export declare const MAX_AWAITING_HELLO = 1000;
+/** What `socketSession` needs to run one upgraded socket. */
+interface SessionOptions {
+    /** The upgraded socket. */
+    readonly socket: Socket.Socket;
+    /** The served connection member the session belongs to. */
+    readonly connection: ServedConnection;
+    /** Opens and drives the connection on the actor's owner. */
+    readonly holder: Holder;
+    /** The actor the session's connection belongs to, in the authenticated tenant. */
+    readonly ref: (tenant: string) => ActorRef;
+    /** The principal the upgrade request's own credential proved, if it carried one. */
+    readonly upgrade: Authenticated | undefined;
+    /** Authenticates a frame credential, or, with `undefined`, the upgrade request as it is. */
+    readonly authenticate: (credential: string | undefined) => Effect.Effect<Authenticated, ActorError>;
+    /** Authenticates a `reauthenticate` frame's credential. */
+    readonly reauthenticate: (credential: string) => Effect.Effect<Authenticated, ActorError>;
+    /** Frees the socket's place among those awaiting `hello`; runs once. */
+    readonly greeted: Effect.Effect<void>;
+}
+/**
+ * Runs one upgraded connection socket until it ends: `hello`, the holder's
+ * open, then member frames both ways with the holder's control messages in
+ * their own envelope, renewal of the credential before it expires, and an
+ * `end` message and close code as the session's last words.
+ *
+ * Ordering and guarantees:
+ * - `hello` comes first; nothing is authenticated or woken before it decodes.
+ * - Only text messages are read. Each is bounded as a whole, so a frame inside
+ *   it is too, and an unknown `t` fails to decode; both end the session.
+ * - However the session stops, even by interruption when the server drops the
+ *   socket or shuts down, the holder closes the connection and the owner its
+ *   row. Once close publishes the ended session, cleanup cannot be interrupted
+ *   by the outbound reader finishing first, or the durable row would remain.
+ * - A failed write means the peer is gone; it ends the session like a close.
+ * - Frames carry cursors only when the holder stamped them; `stampCursor:
+ *   false` has none. Executor progress has its own message, never `frame`, and
+ *   no cursor: it is not replayed.
+ * - Backpressure: the socket is not read while the holder has a full window of
+ *   frames in flight.
+ * - Identity never changes mid-session, and a bound credential also names its
+ *   session, which never changes either; a different caller reconnects. A
+ *   refused renewal ends the session at the holder, which reports it.
+ * - The client is asked for a fresh credential ahead of the current one's
+ *   expiry; a renewal that arrives before it was asked for moves the next ask.
+ */
+export declare const socketSession: (options: SessionOptions) => Effect.Effect<void, never, import("effect/Scope").Scope>;
+export {};

package/dist/serve/sessions/socket.js

@@ -0,0 +1,212 @@
+import { Data, DateTime, Effect, Match, Option, Predicate, Queue, Result, Schema, Stream, } from "effect";
+import { Socket } from "effect/socket";
+import { ActorError, SessionEnded, Unauthorized } from "../../errors/actor.js";
+import { callerKey } from "../../identity/caller.js";
+import { MAX_INBOUND_BYTES } from "../../runtime/connections/holder.js";
+import { ClientMessage } from "../../runtime/connections/protocol.js";
+import { ClientWireMessage, ServerWireMessage } from "../../protocol/frames.js";
+import { actorErrorBody, closeCodeOf } from "../../protocol/wire.js";
+import { invalidInput, undecodable } from "../wire.js";
+/** How long a socket may wait after its upgrade for `hello`. */
+const HELLO_TIMEOUT_MS = 10_000;
+/** Sockets one runner holds between their upgrade and their `hello`. */
+export const MAX_AWAITING_HELLO = 1_000;
+/** Renewal is asked for this long before a credential expires, or at half its life if sooner. */
+const REAUTHENTICATE_LEAD_MS = 60_000;
+/** Binary messages are refused with this close code. */
+const UNSUPPORTED_DATA = 1003;
+/** An inbound message over the frame limit closes with this code. */
+const MESSAGE_TOO_BIG = 1009;
+/** A declared `open` failure closes with this code. */
+const DECLARED_FAILURE = 4400;
+const utf8 = new TextEncoder();
+const encodeServerMessage = Schema.encodeEffect(Schema.fromJsonString(ServerWireMessage));
+const decodeClientMessage = Schema.decodeUnknownEffect(Schema.fromJsonString(ClientWireMessage));
+/** A progress frame as the effect's progress schema encoded it, as the JSON value a client reads. */
+const progressFrame = Schema.decodeEffect(Schema.fromJsonString(Schema.Json));
+/** Ends a session: the `end` message's error and the close code after it. */
+class Refusal extends Data.TaggedError("Refusal") {
+}
+const refuse = (error, code = closeCodeOf(error.reason)) => new Refusal({ error, code });
+const decodeFailed = () => refuse(invalidInput("decode"));
+const expiryOf = (authenticated) => authenticated.expiresAt === undefined
+    ? undefined
+    : DateTime.toEpochMillis(authenticated.expiresAt);
+/** Whether two credentials name the same tenant, caller, and, when bound, session. */
+const samePrincipal = (left, right) => left.tenant === right.tenant &&
+    callerKey(left.caller) === callerKey(right.caller) &&
+    left.binding?.session === right.binding?.session;
+const differentIdentity = () => refuse(ActorError.make({ reason: Unauthorized.make({ code: "invalid_credentials" }) }));
+const isHello = (message) => message.t === "hello";
+/**
+ * Runs one upgraded connection socket until it ends: `hello`, the holder's
+ * open, then member frames both ways with the holder's control messages in
+ * their own envelope, renewal of the credential before it expires, and an
+ * `end` message and close code as the session's last words.
+ *
+ * Ordering and guarantees:
+ * - `hello` comes first; nothing is authenticated or woken before it decodes.
+ * - Only text messages are read. Each is bounded as a whole, so a frame inside
+ *   it is too, and an unknown `t` fails to decode; both end the session.
+ * - However the session stops, even by interruption when the server drops the
+ *   socket or shuts down, the holder closes the connection and the owner its
+ *   row. Once close publishes the ended session, cleanup cannot be interrupted
+ *   by the outbound reader finishing first, or the durable row would remain.
+ * - A failed write means the peer is gone; it ends the session like a close.
+ * - Frames carry cursors only when the holder stamped them; `stampCursor:
+ *   false` has none. Executor progress has its own message, never `frame`, and
+ *   no cursor: it is not replayed.
+ * - Backpressure: the socket is not read while the holder has a full window of
+ *   frames in flight.
+ * - Identity never changes mid-session, and a bound credential also names its
+ *   session, which never changes either; a different caller reconnects. A
+ *   refused renewal ends the session at the holder, which reports it.
+ * - The client is asked for a fresh credential ahead of the current one's
+ *   expiry; a renewal that arrives before it was asked for moves the next ask.
+ */
+export const socketSession = Effect.fnUntraced(function* (options) {
+    const { connection, holder } = options;
+    const writer = yield* options.socket.writer;
+    const reader = yield* options.socket.reader.pipe(Effect.option);
+    if (Option.isNone(reader))
+        return;
+    let finished = false;
+    let buffered = [];
+    const write = (message) => encodeServerMessage(message).pipe(Effect.orDie, Effect.flatMap(writer.write));
+    const send = (message) => Effect.suspend(() => (finished ? Effect.void : write(message)));
+    const finish = (error, code) => Effect.suspend(() => {
+        if (finished)
+            return Effect.void;
+        finished = true;
+        return write({ t: "end", error }).pipe(Effect.andThen(writer.write(new Socket.CloseEvent(code))), Effect.ignore);
+    });
+    const finishWith = (refusal) => actorErrorBody(refusal.error).pipe(Effect.flatMap((body) => finish(body, refusal.code)));
+    const nextRaw = Effect.suspend(() => {
+        const head = buffered.shift();
+        if (head !== undefined)
+            return Effect.succeed(head);
+        return reader.value.pull.pipe(Effect.map((batch) => {
+            buffered = batch.slice(1);
+            return batch[0];
+        }));
+    });
+    const parse = (raw) => Effect.gen(function* () {
+        if (!Predicate.isString(raw))
+            return yield* refuse(invalidInput("decode"), UNSUPPORTED_DATA);
+        if (utf8.encode(raw).byteLength > MAX_INBOUND_BYTES)
+            return yield* refuse(ActorError.make({ reason: SessionEnded.make({ cause: "Defect", resync: false }) }), MESSAGE_TOO_BIG);
+        return yield* decodeClientMessage(raw).pipe(Effect.mapError((error) => error.pipe(undecodable, refuse)));
+    });
+    const hello = yield* nextRaw.pipe(Effect.timeoutOption(HELLO_TIMEOUT_MS), Effect.flatMap(Option.match({ onNone: () => Effect.fail(decodeFailed()), onSome: parse })), Effect.filterOrFail(isHello, decodeFailed), Effect.ensuring(options.greeted), Effect.result);
+    if (Result.isFailure(hello)) {
+        if (Predicate.isTagged(hello.failure, "Refusal"))
+            yield* finishWith(hello.failure);
+        return;
+    }
+    const opened = yield* Effect.gen(function* () {
+        const proved = hello.success.authorization === undefined
+            ? undefined
+            : yield* options.authenticate(hello.success.authorization).pipe(Effect.mapError(refuse));
+        if (proved !== undefined &&
+            options.upgrade !== undefined &&
+            !samePrincipal(proved, options.upgrade))
+            return yield* differentIdentity();
+        const principal = proved ??
+            options.upgrade ??
+            (yield* options.authenticate(undefined).pipe(Effect.mapError(refuse)));
+        const params = yield* connection
+            .openParams(hello.success.params)
+            .pipe(Effect.mapError((error) => error.pipe(undecodable, refuse)));
+        const held = yield* holder
+            .open({
+            ref: options.ref(principal.tenant),
+            member: connection.tag,
+            caller: principal.caller,
+            params,
+            expiresAt: expiryOf(principal),
+        })
+            .pipe(Effect.catchTag("OpenRejected", (rejected) => connection.openFailure(rejected.value).pipe(Effect.orDie, Effect.flatMap((error) => finish(error, DECLARED_FAILURE)), Effect.andThen(Effect.fail(undefined)))), Effect.mapError((error) => (error === undefined ? undefined : refuse(error))));
+        return { held, principal };
+    }).pipe(Effect.result);
+    if (Result.isFailure(opened)) {
+        if (opened.failure !== undefined)
+            yield* finishWith(opened.failure);
+        return;
+    }
+    const { held, principal } = opened.success;
+    const close = Effect.uninterruptible(held.close);
+    const shutdown = refuse(ActorError.make({ reason: SessionEnded.make({ cause: "HolderShutdown", resync: true }) }));
+    yield* Effect.addFinalizer(() => finishWith(shutdown).pipe(Effect.andThen(close)));
+    let expiresAt = expiryOf(principal);
+    const renewed = yield* Queue.sliding(1);
+    const gone = Effect.sync(() => {
+        finished = true;
+    }).pipe(Effect.andThen(close));
+    const opening = send({
+        t: "open",
+        connectionId: held.connectionId,
+        baseline: connection.stampCursor ? held.cursor : undefined,
+        reauthenticateBy: expiresAt,
+    });
+    const wire = ClientMessage.match({
+        Frame: (message) => connection.serverFrame(message.frame).pipe(Effect.orDie, Effect.map((frame) => ({
+            t: "frame",
+            frame,
+            cursor: message.cursor,
+            event: message.event,
+        }))),
+        Resync: (message) => Effect.succeed({
+            t: "resync",
+            after: connection.stampCursor ? message.after : undefined,
+            reason: message.reason,
+            deadline: message.deadlineMs,
+        }),
+        ResyncReplayed: () => Effect.succeed({ t: "resyncReplayed" }),
+        Progress: (message) => progressFrame(message.frame).pipe(Effect.orDie, Effect.map((frame) => ({
+            t: "progress",
+            job: message.job,
+            jobId: message.jobId,
+            attempt: message.attempt,
+            seq: message.seq,
+            frame,
+        }))),
+    });
+    const outbound = held.messages.pipe(Stream.runForEach((message) => wire(message).pipe(Effect.flatMap(send))), Effect.matchEffect({
+        onFailure: (error) => Predicate.isTagged(error, "SocketError") ? gone : error.pipe(refuse, finishWith),
+        onSuccess: () => finish(undefined, 1000),
+    }));
+    const renew = (credential) => Effect.gen(function* () {
+        const fresh = yield* options.reauthenticate(credential).pipe(Effect.mapError(refuse));
+        if (!samePrincipal(fresh, principal))
+            return yield* differentIdentity();
+        const next = expiryOf(fresh);
+        const accepted = yield* held.reauthenticate(next).pipe(Effect.as(true), Effect.orElseSucceed(() => false));
+        if (!accepted)
+            return;
+        expiresAt = next;
+        yield* send({ t: "reauthenticated", by: next });
+        yield* Queue.offer(renewed, undefined);
+    });
+    const handle = Match.type().pipe(Match.discriminatorsExhaustive("t")({
+        frame: (message) => connection.clientFrame(message.frame).pipe(Effect.mapError((error) => error.pipe(undecodable, refuse)), Effect.tap(() => held.writable), Effect.flatMap((frame) => held.send(frame).pipe(Effect.ignore))),
+        resyncDone: () => held.resyncDone,
+        reauthenticate: (message) => renew(message.authorization),
+        hello: () => Effect.fail(decodeFailed()),
+    }));
+    const inbound = nextRaw.pipe(Effect.flatMap(parse), Effect.flatMap(handle), Effect.forever, Effect.catchTag("Refusal", (refusal) => finishWith(refusal).pipe(Effect.andThen(close))), Effect.catch(() => close));
+    const reauthenticate = Effect.gen(function* () {
+        while (true) {
+            const deadline = expiresAt;
+            if (deadline === undefined)
+                return yield* Effect.never;
+            const now = yield* holder.now;
+            const askAt = Math.min(deadline - REAUTHENTICATE_LEAD_MS, now + (deadline - now) / 2);
+            const early = yield* Queue.take(renewed).pipe(Effect.timeoutOption(Math.max(0, askAt - now)));
+            if (Option.isSome(early))
+                continue;
+            yield* send({ t: "reauthenticate", by: deadline });
+            yield* Queue.take(renewed);
+        }
+    }).pipe(Effect.catchTag("SocketError", () => gone));
+    yield* opening.pipe(Effect.andThen(Effect.raceAll([outbound, inbound, reauthenticate])), Effect.catchTag("SocketError", () => gone));
+});

package/dist/serve/sessions/sse.d.ts

@@ -0,0 +1,27 @@
+import { Effect, Schema, Stream } from "effect";
+import { ActorError } from "../../errors/actor.ts";
+/** A comment line this often keeps idle proxies from closing a quiet response. */
+export declare const KEEPALIVE_MS = 15000;
+/**
+ * One SSE message: `event` and JSON `data`, and `id` when the protocol gives
+ * the message a position. A message without `id` writes no `id` line, so a
+ * standard reader sees it inherit the previous one.
+ */
+export declare const message: ({ event, data, id, }: {
+    readonly event: string;
+    readonly data: Schema.Json;
+    readonly id?: string | undefined;
+}) => Effect.Effect<string, never, never>;
+/** The JSON of an encoded member output, as a live runtime frame carries it: `null` for none. */
+export declare const valueJson: (encoded: string) => Effect.Effect<string | number | boolean | Schema.JsonArray | Schema.JsonObject | null, never, never>;
+/** What ended a live session: an `ActorError`, or a declared failure in its encoded form. */
+export type SessionFailure = ActorError | {
+    readonly failure: string;
+};
+/** The body a session's `end` carries for `error`, as a served response would. */
+export declare const failureJson: (error: SessionFailure) => Effect.Effect<Schema.Json>;
+/**
+ * SSE text as bytes, with a `: keepalive` comment every `KEEPALIVE_MS` while
+ * `messages` is open; the response ends when `messages` does.
+ */
+export declare const withKeepalive: <E>(messages: Stream.Stream<string, E>) => Stream.Stream<Uint8Array<ArrayBufferLike>, E, never>;

package/dist/serve/sessions/sse.js

@@ -0,0 +1,26 @@
+import { Effect, Schema, Stream } from "effect";
+import { Sse } from "effect/encoding";
+import { ActorError } from "../../errors/actor.js";
+import { actorErrorBody } from "../../protocol/wire.js";
+/** A comment line this often keeps idle proxies from closing a quiet response. */
+export const KEEPALIVE_MS = 15_000;
+const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Json));
+const decodeJson = Schema.decodeEffect(Schema.fromJsonString(Schema.Json));
+const decodeValue = Schema.decodeEffect(Schema.fromJsonString(Schema.Struct({ value: Schema.optionalKey(Schema.Json) })));
+/**
+ * One SSE message: `event` and JSON `data`, and `id` when the protocol gives
+ * the message a position. A message without `id` writes no `id` line, so a
+ * standard reader sees it inherit the previous one.
+ */
+export const message = ({ event, data, id, }) => encodeJson(data).pipe(Effect.orDie, Effect.map((text) => Sse.encoder.write(Sse.Event.make({ id, event, data: text }))));
+/** The JSON of an encoded member output, as a live runtime frame carries it: `null` for none. */
+export const valueJson = (encoded) => decodeValue(encoded).pipe(Effect.orDie, Effect.map(({ value }) => value ?? null));
+/** The body a session's `end` carries for `error`, as a served response would. */
+export const failureJson = (error) => Schema.is(ActorError)(error)
+    ? actorErrorBody(error)
+    : decodeJson(error.failure).pipe(Effect.orDie);
+/**
+ * SSE text as bytes, with a `: keepalive` comment every `KEEPALIVE_MS` while
+ * `messages` is open; the response ends when `messages` does.
+ */
+export const withKeepalive = (messages) => messages.pipe(Stream.merge(Stream.tick(KEEPALIVE_MS).pipe(Stream.drop(1), Stream.map(() => ": keepalive\n\n")), { haltStrategy: "left" }), Stream.encodeText);

package/dist/serve/sessions/stream.d.ts

@@ -0,0 +1,9 @@
+import { Stream } from "effect";
+import { type SessionFailure } from "./sse.ts";
+/**
+ * A subscription as SSE text: each element as `event: element` with its
+ * encoded value as `data`, then one `end` message: `null` when the stream
+ * ended by itself, else the `ActorError` envelope or the member's declared
+ * error that ended it. Streams have no cursor, so there is no `id`.
+ */
+export declare const streamResponse: (elements: Stream.Stream<string, SessionFailure>) => Stream.Stream<Uint8Array<ArrayBufferLike>, never, never>;

package/dist/serve/sessions/stream.js

@@ -0,0 +1,9 @@
+import { Effect, Stream } from "effect";
+import { failureJson, message, valueJson, withKeepalive } from "./sse.js";
+/**
+ * A subscription as SSE text: each element as `event: element` with its
+ * encoded value as `data`, then one `end` message: `null` when the stream
+ * ended by itself, else the `ActorError` envelope or the member's declared
+ * error that ended it. Streams have no cursor, so there is no `id`.
+ */
+export const streamResponse = (elements) => elements.pipe(Stream.mapEffect((element) => valueJson(element).pipe(Effect.flatMap((json) => message({ event: "element", data: json })))), Stream.concat(Stream.fromEffect(message({ event: "end", data: null }))), Stream.catch((error) => Stream.fromEffect(failureJson(error).pipe(Effect.flatMap((body) => message({ event: "end", data: body }))))), withKeepalive);

package/dist/serve/sessions/watch.d.ts

@@ -0,0 +1,12 @@
+import { Stream } from "effect";
+import type { WatchResult } from "../../runtime/members.ts";
+import { type SessionFailure } from "./sse.ts";
+/**
+ * A watch as SSE text: each result as `event: result` with the encoded output
+ * as `data`, and as `id` the commit version its rerun waited for when there was
+ * one. A watch is state, not history, so there is no `Last-Event-ID` resume: a
+ * reconnect opens a new watch whose first result is the current state. The last
+ * message is `end`, carrying the `ActorError` envelope or the query's declared
+ * error that ended it.
+ */
+export declare const watchResponse: (results: Stream.Stream<WatchResult, SessionFailure>) => Stream.Stream<Uint8Array<ArrayBufferLike>, never, never>;

package/dist/serve/sessions/watch.js

@@ -0,0 +1,11 @@
+import { Effect, Stream } from "effect";
+import { failureJson, message, valueJson, withKeepalive } from "./sse.js";
+/**
+ * A watch as SSE text: each result as `event: result` with the encoded output
+ * as `data`, and as `id` the commit version its rerun waited for when there was
+ * one. A watch is state, not history, so there is no `Last-Event-ID` resume: a
+ * reconnect opens a new watch whose first result is the current state. The last
+ * message is `end`, carrying the `ActorError` envelope or the query's declared
+ * error that ended it.
+ */
+export const watchResponse = (results) => results.pipe(Stream.mapEffect(({ version, value }) => valueJson(value).pipe(Effect.flatMap((json) => message({ event: "result", data: json, id: version })))), Stream.catch((error) => Stream.fromEffect(failureJson(error).pipe(Effect.flatMap((body) => message({ event: "end", data: body }))))), withKeepalive);

package/dist/serve/wire.d.ts

@@ -0,0 +1,16 @@
+import { Effect, Schema } from "effect";
+import { HttpServerResponse } from "effect/http";
+import { ActorError, InvalidInput } from "../errors/actor.ts";
+/**
+ * The HTTP response an `ActorError` is served as: its status, the JSON body,
+ * `retry-after` in whole seconds when the error has a retry delay, and
+ * `www-authenticate: Bearer` for credential failures.
+ */
+export declare const actorErrorResponse: (error: ActorError) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;
+/** An `ActorError` wrapping `InvalidInput` with the given code. */
+export declare const invalidInput: (code: InvalidInput["code"]) => ActorError;
+/**
+ * A body, id, or payload that failed its schema. Issues carry a path and a
+ * fixed message, so a response never echoes the value that failed.
+ */
+export declare const undecodable: (error: Schema.SchemaError) => ActorError;

package/dist/serve/wire.js

@@ -0,0 +1,50 @@
+import { Effect, Option, Schema, SchemaIssue } from "effect";
+import { HttpServerResponse } from "effect/http";
+import { ActorError, InvalidInput, Unauthorized } from "../errors/actor.js";
+import { actorErrorBody, retryAfterSeconds, statusOf } from "../protocol/wire.js";
+/**
+ * The HTTP response an `ActorError` is served as: its status, the JSON body,
+ * `retry-after` in whole seconds when the error has a retry delay, and
+ * `www-authenticate: Bearer` for credential failures.
+ */
+export const actorErrorResponse = Effect.fnUntraced(function* (error) {
+    const retryAfter = error.retryAfter;
+    const body = yield* actorErrorBody(error);
+    const headers = {};
+    if (Option.isSome(retryAfter))
+        headers["retry-after"] = retryAfterSeconds(retryAfter.value);
+    if (Schema.is(Unauthorized)(error.reason) && error.reason.isCredential)
+        headers["www-authenticate"] = "Bearer";
+    return HttpServerResponse.jsonUnsafe(body, { status: statusOf(error.reason), headers });
+});
+const LEAF_MESSAGES = {
+    InvalidType: "Invalid type",
+    InvalidValue: "Invalid value",
+    MissingKey: "Missing key",
+    UnexpectedKey: "Unexpected key",
+    Forbidden: "Forbidden operation",
+    OneOf: "Expected exactly one member to match",
+};
+const formatIssues = SchemaIssue.makeFormatterStandardSchemaV1({
+    leafHook: (issue) => LEAF_MESSAGES[issue._tag],
+    checkHook: () => "Failed check",
+});
+/** An `ActorError` wrapping `InvalidInput` with the given code. */
+export const invalidInput = (code) => ActorError.make({ reason: InvalidInput.make({ code }) });
+/**
+ * A body, id, or payload that failed its schema. Issues carry a path and a
+ * fixed message, so a response never echoes the value that failed.
+ */
+export const undecodable = (error) => ActorError.make({
+    reason: InvalidInput.make({
+        code: "decode",
+        issues: formatIssues(error.issue).issues.map((issue) => ({
+            path: (issue.path ?? [])
+                .map((segment) => String(Schema.is(Schema.Struct({ key: Schema.PropertyKey }))(segment)
+                ? segment.key
+                : segment))
+                .join("."),
+            message: issue.message,
+        })),
+    }),
+});

package/dist/state/blob.d.ts

@@ -0,0 +1,71 @@
+import type { Cause, Effect, Option, Stream } from "effect";
+import type { InvalidContentRef } from "../errors/content.ts";
+import type { ContentEntry, ContentRef } from "../identity/content.ts";
+import type { AnyBlob, AnyContent } from "../members/blob.ts";
+import type { TableScope } from "../tables/owned.ts";
+/** Read-only access to the current actor's entries of one blob. */
+export interface BlobRead {
+    /** The entry's bytes, every appended chunk in order; none when it was never set. */
+    readonly get: (name: string) => Effect.Effect<Option.Option<Uint8Array>>;
+}
+/** Turn-bound access to the current actor's entries; writes commit or roll back with the turn. */
+export interface BlobWrite extends BlobRead {
+    /** Replaces the entry with `bytes` as its only chunk. */
+    readonly set: (name: string, bytes: Uint8Array) => Effect.Effect<void>;
+    /** Adds `bytes` as a new chunk after the existing ones, creating the entry if needed. */
+    readonly append: (name: string, bytes: Uint8Array) => Effect.Effect<void>;
+    /** Merges the entry's chunks into one without changing its bytes. */
+    readonly compact: (name: string) => Effect.Effect<void>;
+    /** Removes the entry and its bytes, so `get` returns none; removing a missing entry does nothing. */
+    readonly delete: (name: string) => Effect.Effect<void>;
+}
+/**
+ * Off-turn access to the content the current actor references. A read never
+ * returns partial bytes: content swept after its reference was resolved reads
+ * as a missing name.
+ */
+export interface ContentRead {
+    /** The referenced content's bytes; none when the actor holds no reference under `name`. */
+    readonly get: (name: string) => Effect.Effect<Option.Option<Uint8Array>>;
+    /**
+     * The referenced content's bytes in chunks from one snapshot, so a
+     * concurrent sweep never truncates them. A missing name fails before any
+     * chunk with `NoSuchElementError`.
+     */
+    readonly stream: (name: string) => Stream.Stream<Uint8Array, Cause.NoSuchElementError>;
+    /** Every reference under this blob, by name. */
+    readonly list: Effect.Effect<ReadonlyArray<ContentEntry>>;
+}
+/**
+ * Turn-bound references to shared content. Writes touch only the actor's own
+ * rows and commit or roll back with the turn; a turn never sees content bytes.
+ */
+export interface ContentWrite {
+    /**
+     * References the content `ref` names under `name`, replacing any earlier
+     * reference. Fails `InvalidContentRef` unless `ref.grant` was issued by this
+     * deployment for this tenant, hash, and size, and stays valid past the skew margin.
+     */
+    readonly attach: (name: string, ref: ContentRef) => Effect.Effect<void, InvalidContentRef>;
+    /** Drops the reference under `name`; dropping a missing one does nothing. */
+    readonly detach: (name: string) => Effect.Effect<void>;
+    /** Every reference under this blob, by name, including this turn's changes. */
+    readonly list: Effect.Effect<ReadonlyArray<ContentEntry>>;
+}
+/** What `read.blob(B)` returns for a declared blob `B`. */
+export type BlobReadOf<B extends AnyBlob> = B extends AnyContent ? ContentRead : BlobRead;
+/** What `turn.blob(B)` returns for a declared blob `B`. */
+export type BlobWriteOf<B extends AnyBlob> = B extends AnyContent ? ContentWrite : BlobWrite;
+/** Whose blob entries a capability reaches and how long it lives, as for owned tables. */
+export interface BlobScope extends Omit<TableScope, "tables"> {
+    /** The blobs the actor type declares; `blob` refuses any other. */
+    readonly blobs: ReadonlyArray<AnyBlob>;
+    /** Bytes all of the actor's entries may hold together: `policy.maxBlobBytes`. */
+    readonly maxBytes: number;
+    /** Entries and content references of all the actor's blobs together: `policy.maxBlobEntries`. */
+    readonly maxEntries: number;
+    /** `executionTimeout`: how long a content stream may hold its snapshot. */
+    readonly timeoutMs: number;
+}
+/** Turn-bound access returns the write interfaces; read access only the read ones. */
+export type BlobAccess = (blob: AnyBlob) => BlobRead | BlobWrite | ContentRead | ContentWrite;

package/dist/state/migration.d.ts

@@ -0,0 +1,53 @@
+import { Schema } from "effect";
+import type { ValueSchema } from "../members/command.ts";
+type Fields = Readonly<Record<string, ValueSchema>>;
+/**
+ * One step of a schema's history: `from` is the stored shape, `to` the next
+ * one, and `upcast` a pure conversion. A chain's last `to` is the declared
+ * shape, so a stored value upcasts through every later step in order.
+ * `downcast` converts back; an event or effect needs it only for the steps
+ * above its `writeVersion`, while a rolling deploy still writes the old shape.
+ * `upcast` and `downcast` are declared as methods so their parameters stay
+ * bivariant and any migration fits a chain.
+ */
+export interface StateMigration<From extends Fields = Fields, To extends Fields = Fields> {
+    readonly from: From;
+    readonly to: To;
+    upcast(previous: Schema.Struct<From>["Type"]): Schema.Struct<To>["Type"];
+    downcast?(next: Schema.Struct<To>["Type"]): Schema.Struct<From>["Type"];
+}
+declare const migration: <const From extends Fields, const To extends Fields>(from: From, to: To, upcast: StateMigration<From, To>["upcast"], options?: {
+    readonly downcast?: (next: Schema.Struct<To>["Type"]) => Schema.Struct<From>["Type"];
+}) => StateMigration<From, To>;
+/** Stored with the actor's state rows; version `n` means `n` migrations have been applied. */
+export declare const VERSION_KEY = "$version";
+/** A chain is valid when each `to` is the next `from` and the last `to` is the declared state. */
+declare const validateChain: (fields: Fields, chain: ReadonlyArray<StateMigration>) => void;
+/**
+ * An actor's keyed state: the current fields and the migrations that upcast
+ * older stored shapes to them. The last migration's `to` must be `fields`.
+ */
+export interface ActorState<F extends Fields = Fields> {
+    readonly fields: F;
+    readonly migrations: ReadonlyArray<StateMigration>;
+}
+declare const state: <const F extends Fields>(fields: F, options?: {
+    readonly migrations?: ReadonlyArray<StateMigration>;
+}) => ActorState<F>;
+/**
+ * `ActorStates` carries `Actor.state`, which declares an actor's keyed state
+ * fields and their migrations, `Actor.migration`, which builds one step of a
+ * chain, and `validateChain`, which `Actor.make` uses to reject a chain whose
+ * steps do not join or whose last `to` is not the declared state.
+ *
+ * @example
+ * const Counter = Actor.state({
+ *   count: Schema.Int.pipe(Schema.withDecodingDefault(Effect.succeed(0))),
+ * })
+ */
+export declare const ActorStates: {
+    make: typeof state;
+    migration: typeof migration;
+    validateChain: typeof validateChain;
+};
+export {};

package/dist/state/migration.js

@@ -0,0 +1,29 @@
+import { Schema } from "effect";
+const migration = (from, to, upcast, options) => options?.downcast === undefined
+    ? { from, to, upcast }
+    : { from, to, upcast, downcast: options.downcast };
+/** Stored with the actor's state rows; version `n` means `n` migrations have been applied. */
+export const VERSION_KEY = "$version";
+/** A chain is valid when each `to` is the next `from` and the last `to` is the declared state. */
+const validateChain = (fields, chain) => {
+    for (let index = 1; index < chain.length; index++)
+        if (chain[index - 1].to !== chain[index].from)
+            throw new Error(`State migration ${index} must start from the previous migration's result`);
+    if (chain.length > 0 && chain.at(-1).to !== fields)
+        throw new Error("The last state migration must produce the declared state");
+    if (VERSION_KEY in fields)
+        throw new Error(`State key '${VERSION_KEY}' is reserved`);
+};
+const state = (fields, options) => ({ fields, migrations: options?.migrations ?? [] });
+/**
+ * `ActorStates` carries `Actor.state`, which declares an actor's keyed state
+ * fields and their migrations, `Actor.migration`, which builds one step of a
+ * chain, and `validateChain`, which `Actor.make` uses to reject a chain whose
+ * steps do not join or whose last `to` is not the declared state.
+ *
+ * @example
+ * const Counter = Actor.state({
+ *   count: Schema.Int.pipe(Schema.withDecodingDefault(Effect.succeed(0))),
+ * })
+ */
+export const ActorStates = { make: state, migration, validateChain };