@rikalabs/akter 0.1.0-alpha.5 → 0.1.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.0-alpha.6 (2026-10-11)
+
+The framework and CLI release together on the `alpha` and `latest` npm dist-tags. This release adds SQL migrations `0034_cold_tier` and `0035_hot_table_foreign_keys` and an opt-in cold-object format. Rolling-upgrade safety from alpha.5 is **not established**; back up and rehearse a stopped-runner upgrade using the [alpha upgrade notes](https://docs.akter.dev/operations/alpha-upgrades) and [migration procedure](https://docs.akter.dev/operations/02-migrations).
+
+- `0034_cold_tier` adds the `cold_ref`, `cold_digest` and `cold_state_version` generation tuple, a cold-version index, `actor_placements.state_version`, constrained `cold` outbox work, the tenant-RLS-protected `actor_cold_garbage` table and its due index, and `durable.actors.cold`. When enabled, state and actor-blob chunks move together into immutable zstd-compressed JSON envelopes with `format: 1` and `codec: 1`, actor identity, routing key, generation, state version, stored key/value pairs and base64 blob chunks; SQL pointers record the compressed bytes' SHA-256. Existing routing-key, warm-state, receipt, event and job payload encodings are unchanged.
+- Adds opt-in Postgres cold storage through `Actors.layer({ coldStorage })`, `policy.coldAfter` and the runtime `ColdStorage` memory, filesystem and S3-compatible adapters. Nothing offloads without a store; PGlite refuses the option. Queries and operator exports read through without restoring; successful commands atomically restore all state and blobs, while declared failures retain the pointer. Command/query object outages are retryable `ActorUnavailable`; failed operator exports return 500, never an empty seed. Retained receipt replay needs no object read. All serving runners need the same store and namespace. Preserve state migration chains needed by cold objects: startup refuses a shortened chain that cannot read them. See [cold-tier verification](https://docs.akter.dev/verification/cold-tier).
+- Enabling cold storage extends the backup boundary to the private object namespace. Configure `backupRetention` plus grace, preserve the deployment id and namespace on restore, stop every runner and maintenance pool, and verify every restored pointer's object, digest and identity before restart. Collectors retain live references and pending cold work through the backup horizon. Filesystem and MinIO evidence does not establish hosted cold-wake latency, provider replication or online PITR; see [backup and restore](https://docs.akter.dev/operations/04-backup-restore).
+- `0035_hot_table_foreign_keys` drops only the `actor_state` and `actor_receipts` foreign keys to `actor_generations`, resolving exact catalog names and refusing unexpected or ambiguous definitions. Both drops use one bounded-lock savepoint/retry boundary; no actor rows are scanned, rewritten or backfilled. Primary/unique keys, tenant RLS, other references and the transactional generation fence remain. Startup applies both migrations before registration; there are no down migrations. See [storage layout](https://docs.akter.dev/architecture/03-storage-layout).
+- **Breaking:** command and reducer tags beginning with `$` are now rejected when compiling an actor because that prefix is reserved for framework maintenance. Rename such declarations before upgrading. `System.source` also gains `cold` for internal cold-state maintenance.
+- **Breaking:** `Runner.socket` now throws the exported `RunnerConfigurationError` synchronously when `entityTerminationTimeout` exceeds `shardLockExpiration - min(shardLockRefreshInterval, shardLockExpiration / 3)`. Previously accepted unsafe configurations are refused, including a 3-second expiration with the omitted 15-second default termination timeout. Set an explicit timeout within the bound, or raise expiration to satisfy it; the ordinary defaults remain valid. See the [alpha upgrade notes](https://docs.akter.dev/operations/alpha-upgrades).
+- Eligible single warm, state-only commands use one guarded Postgres commit flight instead of two. The database still fences generation, event head, creation, cold pointer, receipt identity and expiry; a guard miss discards speculation and uses ordinary admission. Handlers can be evaluated again, and SQL-capable, batched, cold, recovery and new-job/intent/subscription turns retain ordinary admission. Queries always read a database snapshot with the existing replica catch-up/primary fallback rules, never activation memory; `read.version` is undefined. The intermediate cached-query path from [#719](https://github.com/Rika-Labs/akter/pull/719) was removed by [#745](https://github.com/Rika-Labs/akter/pull/745). Protocol-flight evidence is not a production latency or throughput guarantee.
+- Shares activation-worker wiring per actor type and mailbox methods on a prototype, while queues, wake-ups, retry isolation, scoped ownership and actor state remain per activation. The [local retained-heap measurements](https://github.com/Rika-Labs/akter/blob/main/BENCHMARKS.md#resident-heap-follow-up-on-the-mac) do not establish a stable RSS saving or throughput improvement.
+- Fixes `ActorTest.advance` missing an attempt claimed while its lease extension waits for the relay pass lock. The running-attempt snapshot now happens under that lock, preventing a synthetic clock jump from manufacturing lease loss and duplicate same-ID attempts. Production claim, renewal, retry and fencing semantics are unchanged; see [verification](https://docs.akter.dev/verification/relay-clock-jumps). Cold fixtures now wait through actual durable offload retries instead of assuming the first upload succeeded.
+- Adds narrow, opt-in `Database.postgres({ pooling: "transaction", preset: "low-connection" })` for public `Runner.socket` table-lease runners on one primary. It forces `prepare: false`, omits direct-server keepalive startup defaults, disables warm speculation and refuses fleet, cold storage, replicas and separate coordination. Application `LISTEN`, session advisory locks and temporary/session state are outside the mode. Startup migration coordination now uses a transaction-scoped advisory lock including history creation, without a new migration id. Real PgBouncer 1.25.2/Postgres 18.6/Bun 1.4.2 evidence covers bounded startup, rollback, tenant isolation, cancellation, serving and process recovery; Node pooled transport, provider/proxy TLS and general pooler support remain unverified. The four logical clients and proxy backend budget are separate; see [transaction-pooling verification](https://docs.akter.dev/verification/low-connection-postgres#transaction-pooling).
+- The matching CLI adds environment API key schemas and `akter keys create`, `list` and `revoke`; see its [changelog](https://github.com/Rika-Labs/akter/blob/main/apps/cli/CHANGELOG.md). Cloud docs clarify native RDS/Aurora TLS trust, four-session runner and rollout-overlap budgeting, subscription renewal versus Free usage periods, and system-theme/font behavior. These docs do not expand framework provider certification. CI reduces duplicate pipeline setup while continuing to execute tests rather than replay cached results; logs-follow interruption and event-order fixtures synchronize with actual outstanding work.
+
 ## 0.1.0-alpha.5 (2026-10-09)
 
 The framework and CLI release together on the `alpha` and `latest` npm dist-tags. Stored formats and the default Postgres pool sizes are unchanged from alpha.4.

package/dist/actor/descriptor.js

@@ -166,6 +166,9 @@ export const compile = ({ name, declared, }) => {
     const members = [...Object.values(api), ...Object.values(internal)];
     const commands = members.filter((member) => member.kind === "command");
     const queries = members.filter((member) => member.kind === "query");
+    for (const member of members)
+        if ((member.kind === "command" || member.kind === "reducer") && member.tag.startsWith("$"))
+            throw new Error(`Command tag ${member.tag} uses the reserved $ prefix`);
     const connections = members.filter((member) => member.kind === "connection");
     const streams = members.filter((member) => member.kind === "stream");
     const reducers = members.filter((member) => member.kind === "reducer");

package/dist/actor/handles.d.ts

@@ -20,7 +20,7 @@ export declare const handleOf: (descriptor: Descriptor, id: string, includeInter
     readonly _tag: "Anonymous";
 } | {
     readonly _tag: "System";
-    readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+    readonly source: "actor" | "cold" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
     readonly ref?: {
         readonly tenant: string;
         readonly actor: string;

package/dist/actor/layers.js

@@ -13,6 +13,7 @@ const built = (build) => (Effect.isEffect(build) ? build : Effect.succeed(build)
 const erased = (entries) => entries;
 const registrationOf = (descriptor, tenant) => ({
     name: descriptor.name,
+    stateVersion: descriptor.state.version,
     singleton: descriptor.singleton,
     mintable: descriptor.mintable,
     watches: descriptor.watches,
@@ -153,6 +154,7 @@ export const queryLayer = ({ descriptor, phases, build, services: capture, }) =>
     const services = (yield* capture);
     yield* actors.registerQueries({
         name: descriptor.name,
+        stateVersion: descriptor.state.version,
         access: descriptor.access,
         placement: descriptor.placement,
         timeoutMs: descriptor.policy.executionMs,

package/dist/actor/reads.js

@@ -110,6 +110,7 @@ export const queriesOf = ({ descriptor, Read, handlers, services, actors, }) =>
                     maxEntries: descriptor.policy.blobMaxEntries,
                     timeoutMs: descriptor.policy.executionMs,
                 }, false);
+                const events = eventsWith({ descriptor, readEvents });
                 const context = {
                     id: request.ref.id,
                     ref: request.ref,
@@ -117,7 +118,7 @@ export const queriesOf = ({ descriptor, Read, handlers, services, actors, }) =>
                     principal: principal(request.caller),
                     state: Object.freeze(state),
                     cursor,
-                    events: eventsWith({ descriptor, readEvents }),
+                    events,
                     rows: access.rows,
                     group: access.group,
                     blob: blob,

package/dist/contexts/command.d.ts

@@ -79,6 +79,8 @@ export interface QueryContext<State, Event extends EventClass = never, Tables ex
     readonly principal: Option.Option<Principal>;
     /** The last committed state; never uncommitted writes of a running turn. */
     readonly state: Readonly<State>;
+    /** Always undefined: a query reads the database, not a resident snapshot. */
+    readonly version?: string | undefined;
     /**
      * The last event committed when `state` was read: resume `events` after it
      * to follow on from this state without missing or repeating an event.

package/dist/identity/caller.d.ts

@@ -30,13 +30,13 @@ export type MintProof = typeof MintProof.Type;
  * A caller the framework creates for its own deliveries, and the caller of
  * code that runs in the application's own process. `source` names the
  * mechanism (the process itself, an actor's intent, a timer, cron, a workflow,
- * a job route, or a subscription), `ref` the actor that sent it, and
+ * a job route, a subscription, or cold-state maintenance), `ref` the actor that sent it, and
  * `onBehalfOf` the principal of the turn that caused it. `mint` is set only on
  * a minted child's creating intent, and proves the child's id was derived by
  * its parent.
  */
 export declare const System: Schema.TaggedStruct<"System", {
-    readonly source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription"]>;
+    readonly source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription", "cold"]>;
     readonly ref: Schema.optional<Schema.Struct<{
         readonly tenant: Schema.NonEmptyString;
         readonly actor: Schema.NonEmptyString;
@@ -54,7 +54,7 @@ export declare const System: Schema.TaggedStruct<"System", {
 export declare const 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 source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription", "cold"]>;
     readonly ref: Schema.optional<Schema.Struct<{
         readonly tenant: Schema.NonEmptyString;
         readonly actor: Schema.NonEmptyString;
@@ -80,7 +80,7 @@ export declare const CurrentCaller: Context.Reference<{
     readonly _tag: "Anonymous";
 } | {
     readonly _tag: "System";
-    readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+    readonly source: "actor" | "cold" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
     readonly ref?: {
         readonly tenant: string;
         readonly actor: string;

package/dist/identity/caller.js

@@ -20,13 +20,22 @@ export const MintProof = Schema.Struct({
  * A caller the framework creates for its own deliveries, and the caller of
  * code that runs in the application's own process. `source` names the
  * mechanism (the process itself, an actor's intent, a timer, cron, a workflow,
- * a job route, or a subscription), `ref` the actor that sent it, and
+ * a job route, a subscription, or cold-state maintenance), `ref` the actor that sent it, and
  * `onBehalfOf` the principal of the turn that caused it. `mint` is set only on
  * a minted child's creating intent, and proves the child's id was derived by
  * its parent.
  */
 export const System = Schema.TaggedStruct("System", {
-    source: Schema.Literals(["process", "actor", "timer", "cron", "workflow", "job", "subscription"]),
+    source: Schema.Literals([
+        "process",
+        "actor",
+        "timer",
+        "cron",
+        "workflow",
+        "job",
+        "subscription",
+        "cold",
+    ]),
     ref: Schema.optional(ActorRef),
     onBehalfOf: Schema.optional(Principal),
     mint: Schema.optional(MintProof),

package/dist/identity/mint.d.ts

@@ -28,7 +28,7 @@ export declare const provesMint: (caller: {
     readonly _tag: "Anonymous";
 } | {
     readonly _tag: "System";
-    readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+    readonly source: "actor" | "cold" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
     readonly ref?: {
         readonly tenant: string;
         readonly actor: string;

package/dist/policies/command.d.ts

@@ -8,6 +8,8 @@ import type { AnyCommand } from "../members/command.ts";
 export interface Policy {
     /** Idle time before the activation sleeps. Default 60 seconds. */
     readonly hibernateAfter?: Duration.Input;
+    /** Continuous sleep before state and actor blobs may be offloaded. Default 30 days; never opts out. */
+    readonly coldAfter?: Duration.Input | "never";
     /**
      * Deadline for one command turn's transaction and one query's execution.
      * It does not bound a workflow or a live session. Default 30 seconds.
@@ -95,6 +97,7 @@ export interface TurnPolicy {
     readonly deliveryMs: number;
     readonly stateMaxBytes: number;
     readonly idleMs: number;
+    readonly coldMs: number | undefined;
     readonly mailboxCapacity: number | "unbounded";
     readonly createdBy: string | undefined;
     readonly keepReceiptsMs: number;

package/dist/policies/command.js

@@ -20,6 +20,7 @@ export const resolvePolicy = (policy) => {
         deliveryMs: milliseconds(declared?.deliveryTimeout ?? "30 seconds"),
         stateMaxBytes: Positive.make(declared?.maxStateBytes ?? 65_536),
         idleMs: milliseconds(declared?.hibernateAfter ?? "60 seconds"),
+        coldMs: declared?.coldAfter === "never" ? undefined : horizon(declared?.coldAfter ?? "30 days"),
         mailboxCapacity: declared?.mailboxCapacity === undefined
             ? "unbounded"
             : Positive.make(declared.mailboxCapacity),

package/dist/runtime/connections/owner.js

@@ -7,6 +7,8 @@ import { ConnectionPhase, } from "../members.js";
 import { Caller, principal } from "../../identity/caller.js";
 import { replayEvents } from "../events/replay.js";
 import { compress, decompress } from "../storage/codec.js";
+import { ColdTier } from "../storage/cold-tier.js";
+import { ColdRead } from "../turn/blobs.js";
 import { FrameworkClock } from "../turn/admission.js";
 import { actorRow, emptyActivationCache, forget as forgetGeneration, heldGeneration, } from "../storage/generation.js";
 import { Committed, FEED_MEMBER, FeedFrame, HolderItem, isWatchMember, watchedQuery, watchMember, } from "./protocol.js";
@@ -191,7 +193,18 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
             return;
         activations.delete(entityId);
         yield* seal(activation);
+        yield* scheduleCold(activation);
     }));
+    const scheduleCold = (activation) => Effect.gen(function* () {
+        const tier = yield* ColdTier;
+        const generation = activation.cache.generation;
+        const delay = registration.policy.coldMs;
+        if (tier === undefined || generation === undefined || delay === undefined)
+            return;
+        yield* tier
+            .hibernate(activation, generation, delay)
+            .pipe(Effect.catchCause((cause) => Effect.logWarning("Cold timer could not be scheduled", cause)));
+    });
     const channelOf = (activation, holder, epoch) => {
         const name = `${holder}|${epoch}`;
         const found = activation.channels.get(name);
@@ -255,11 +268,13 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
         activation.channels.clear();
     };
     /** Fences this activation's generation and loads committed state, as a command turn would. */
-    const acquire = (activation) => activation.cache.generation !== undefined && activation.cache.state !== undefined
+    const acquire = (activation, fetch = true) => activation.cache.generation !== undefined &&
+        (activation.cache.state !== undefined || activation.cache.cold !== undefined)
         ? Effect.void
-        : activation.acquiring.withPermit(acquireOnce(activation));
-    const acquireOnce = (activation) => Effect.gen(function* () {
-        if (activation.cache.generation !== undefined && activation.cache.state !== undefined)
+        : activation.acquiring.withPermit(acquireOnce(activation, fetch));
+    const acquireOnce = (activation, fetch) => Effect.gen(function* () {
+        if (activation.cache.generation !== undefined &&
+            (activation.cache.state !== undefined || activation.cache.cold !== undefined))
             return;
         const sql = yield* SqlClient.SqlClient;
         const actor = actorRow({ sql, actor: activation });
@@ -270,10 +285,10 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
             const [row] = activation.cache.generation === undefined
                 ? yield* sql `
                   UPDATE actor_generations SET generation = generation + 1 WHERE ${actor}
-                  RETURNING generation::text AS generation, event_sequence::text AS head`
+                  RETURNING generation::text AS generation, event_sequence::text AS head, cold_ref, cold_digest, cold_state_version`
                 : yield* sql `
-                  SELECT generation::text AS generation, event_sequence::text AS head
-                  FROM actor_generations WHERE ${actor}`;
+                  SELECT generation::text AS generation, event_sequence::text AS head, cold_ref, cold_digest, cold_state_version
+                  FROM actor_generations WHERE ${actor} FOR UPDATE`;
             if (activation.cache.generation !== undefined &&
                 activation.cache.generation !== row.generation) {
                 forget(activation);
@@ -281,10 +296,35 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
             }
             const state = yield* sql `
             SELECT key, value FROM actor_state WHERE ${actor}`;
+            yield* sql `DELETE FROM actor_outbox WHERE ${actor} AND timer_key = '$cold'`;
             return { row: row, state };
         }));
         activation.cache.generation = acquired.row.generation;
-        activation.cache.state = new Map(acquired.state.map(({ key, value }) => [key, decompress(value)]));
+        if (acquired.row.cold_ref === null) {
+            activation.cache.state = new Map(acquired.state.map(({ key, value }) => [key, decompress(value)]));
+            activation.cache.cold = undefined;
+        }
+        else if (fetch) {
+            const tier = yield* ColdTier;
+            if (tier === undefined)
+                return yield* unavailable("Cold actor needs coldStorage");
+            const material = yield* tier
+                .fetch(activation, {
+                ref: acquired.row.cold_ref,
+                digest: acquired.row.cold_digest,
+                version: acquired.row.cold_state_version,
+            })
+                .pipe(Effect.catch(() => unavailable("Cold object unavailable")));
+            const matching = yield* sql `SELECT 1 FROM actor_generations WHERE ${actor}
+          AND generation = ${acquired.row.generation} AND cold_ref = ${material.ref}
+          AND cold_digest = ${material.digest} AND cold_state_version = ${material.version}`;
+            if (matching.length === 0) {
+                forget(activation);
+                return yield* unavailable("Cold read lost its generation");
+            }
+            activation.cache.cold = material;
+            activation.cache.state = undefined;
+        }
         advance(activation, acquired.row.head);
         activation.through = acquired.row.head;
     });
@@ -321,7 +361,7 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
     }).pipe(Effect.catchIf(SqlError.isSqlError, Effect.die));
     /** Readies an activation that is about to run a turn: fenced, with its connection rows. */
     const prepare = (activation) => hasConnections
-        ? Effect.andThen(acquire(activation), load(activation)).pipe(Effect.orDie)
+        ? Effect.andThen(acquire(activation, false), load(activation)).pipe(Effect.orDie)
         : Effect.void;
     const list = (activation) => (member) => Effect.sync(() => [...(activation.rows?.values() ?? [])]
         .filter((row) => row.member === member && row.buffered === undefined)
@@ -413,19 +453,23 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
     const run = (activation, row, phase, commands) => Effect.gen(function* () {
         const connection = registration.connections.get(row.member);
         const sql = yield* SqlClient.SqlClient;
-        return yield* connection.run({
+        return yield* connection
+            .run({
             ref: activation.ref,
             connectionId: row.connectionId,
             member: row.member,
             caller: row.caller,
             resumed: !ConnectionPhase.guards.Open(phase) && !activation.opened.has(row.connectionId),
             cursor: activation.through,
-            state: [...(activation.cache.state ?? new Map())],
+            state: activation.cache.cold?.envelope.state ?? [
+                ...(activation.cache.state ?? new Map()),
+            ],
             session: row.session,
             connections: list(activation),
             events: events(activation, sql),
             commands,
-        }, phase);
+        }, phase)
+            .pipe(Effect.provideService(ColdRead, activation.cache.cold));
     });
     const checkSession = (result) => result.session !== undefined &&
         utf8.encode(result.session).byteLength - SESSION_ENVELOPE_BYTES > MAX_SESSION_BYTES
@@ -675,7 +719,9 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
             return {
                 ref: activation.ref,
                 cursor: activation.head,
-                state: [...(activation.cache.state ?? new Map())],
+                state: activation.cache.cold?.envelope.state ?? [
+                    ...(activation.cache.state ?? new Map()),
+                ],
                 events: events(activation, sql),
                 follow: follow(activation, sql),
                 progress: (tag, jobId) => progressFeed(activation, tag, jobId),
@@ -863,6 +909,7 @@ export const activationOwner = ({ registration, transport, authorize, clock, rol
             return;
         yield* streams.end(activation);
         yield* seal(activation);
+        yield* scheduleCold(activation);
         forget(activation);
         activation.opened.clear();
         activation.progress.clear();

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

@@ -334,7 +334,7 @@ export declare const connectionsEntity: (name: string) => Entity.Entity<`${strin
     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 source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription", "cold"]>;
         readonly ref: Schema.optional<Schema.Struct<{
             readonly tenant: Schema.NonEmptyString;
             readonly actor: Schema.NonEmptyString;
@@ -411,7 +411,7 @@ export declare const connectionsEntity: (name: string) => Entity.Entity<`${strin
     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 source: Schema.Literals<readonly ["process", "actor", "timer", "cron", "workflow", "job", "subscription", "cold"]>;
         readonly ref: Schema.optional<Schema.Struct<{
             readonly tenant: Schema.NonEmptyString;
             readonly actor: Schema.NonEmptyString;

package/dist/runtime/connections/streams.js

@@ -1,6 +1,7 @@
 import { Cause, Effect, Exit, Fiber, Queue, Schedule, Stream } from "effect";
 import { ActorError, RunnerAtCapacity, SessionEnded, Unauthorized } from "../../errors/actor.js";
 import { StreamFailed, StreamItem } from "./protocol.js";
+import { ColdRead } from "../turn/blobs.js";
 /** Open stream subscriptions one actor may have. */
 const MAX_ACTOR_STREAMS = 256;
 /** Stream elements held for one subscriber before its handler waits. */
@@ -76,7 +77,7 @@ export const streamSubscriptions = ({ registration, activations, transport, auth
             yield* Queue.offer(queue, item);
             subscription.stalledSince = undefined;
         });
-        producer = yield* stream.run(request.input, { ...input, caller: request.caller }).pipe(Stream.runForEach((value) => offer(StreamItem.cases.Element.make({ value }))), Effect.andThen(offer(StreamItem.cases.Done.make({}))), Effect.andThen(Queue.end(queue)), Effect.catch(({ failure }) => Queue.fail(queue, StreamFailed.make({ value: failure }))), Effect.catchDefect((cause) => Effect.andThen(Effect.logError("Stream handler defect", Cause.die(cause)), Queue.fail(queue, ended("Defect", false)))), Effect.asVoid, Effect.ensuring(Effect.sync(() => {
+        producer = yield* stream.run(request.input, { ...input, caller: request.caller }).pipe(Stream.provideService(ColdRead, activation.cache.cold), Stream.runForEach((value) => offer(StreamItem.cases.Element.make({ value }))), Effect.andThen(offer(StreamItem.cases.Done.make({}))), Effect.andThen(Queue.end(queue)), Effect.catch(({ failure }) => Queue.fail(queue, StreamFailed.make({ value: failure }))), Effect.catchDefect((cause) => Effect.andThen(Effect.logError("Stream handler defect", Cause.die(cause)), Queue.fail(queue, ended("Defect", false)))), Effect.asVoid, Effect.ensuring(Effect.sync(() => {
             closed = true;
             activation.streams.delete(subscription);
         })), Effect.forkDetach);

package/dist/runtime/database/bounded.js

@@ -1,5 +1,5 @@
 import { PgClient, PgPool } from "@effect/sql-pg";
-import { Duration, Effect, Schedule, Schema, Scope } from "effect";
+import { Duration, Effect, Schedule, Schema, Scope, Semaphore, Stream } from "effect";
 import { SqlClient, SqlError, Statement } from "effect/sql";
 import { admissionLimit, isOverloaded } from "../admission.js";
 import { ActorError } from "../../errors/actor.js";
@@ -49,9 +49,24 @@ const boundedSessions = Effect.fnUntraced(function* (options) {
     const fair = fairGate(slots);
     const enter = Effect.andThen(admission.take.pipe(Effect.mapError(poolRefusal)), fair.take);
     const connection = (session) => asSqlConnection({ connection: session, send: direct });
+    /** A reservation cannot return to the pool while an interrupted statement is still draining its wire response. */
+    const reserve = Effect.gen(function* () {
+        yield* enter;
+        const session = yield* pool.reserve;
+        const statements = Semaphore.makeUnsafe(1);
+        let closing = false;
+        yield* Effect.addFinalizer(() => Effect.sync(() => {
+            closing = true;
+        }).pipe(Effect.andThen(statements.withPermit(Effect.void))));
+        return asSqlConnection({
+            connection: session,
+            send: (statement) => statements.withPermit(Effect.suspend(() => (closing ? Effect.interrupt : statement))),
+            sendStream: (stream) => Stream.unwrap(Effect.acquireRelease(statements.take(1), () => statements.release(1)).pipe(Effect.andThen(Effect.suspend(() => (closing ? Effect.interrupt : Effect.succeed(stream)))))),
+        });
+    });
     return {
         acquire: Effect.andThen(enter, Effect.map(pool.get, connection)),
-        reserve: Effect.andThen(enter, Effect.map(pool.reserve, connection)),
+        reserve,
         borrow: (use) => admission
             .admit(fair.use(pool.use((session) => use(connection(session)))))
             .pipe(Effect.mapError((error) => (Schema.is(ActorError)(error) ? poolRefusal(error) : error))),

package/dist/runtime/database/connection.d.ts

@@ -1,8 +1,9 @@
 import type { PgConnection } from "@effect/sql-pg";
-import { Effect } from "effect";
+import { Effect, Stream } from "effect";
 import type { SqlConnection, SqlError } from "effect/sql";
 /** A leased session as a `SqlClient` connection, so the runtime's statements reach it. */
-export declare const asSqlConnection: ({ connection, send, }: {
+export declare const asSqlConnection: ({ connection, send, sendStream, }: {
     readonly connection: PgConnection.PgConnection;
     readonly send: <A>(statement: Effect.Effect<A, SqlError.SqlError>) => Effect.Effect<A, SqlError.SqlError>;
+    readonly sendStream?: <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<A, E, R>;
 }) => SqlConnection.Connection;

package/dist/runtime/database/connection.js

@@ -1,6 +1,6 @@
 import { Effect, Stream } from "effect";
 /** A leased session as a `SqlClient` connection, so the runtime's statements reach it. */
-export const asSqlConnection = ({ connection, send, }) => {
+export const asSqlConnection = ({ connection, send, sendStream, }) => {
     const rows = (prepare) => (sql, params, transformRows) => {
         const found = send(Effect.map(connection.query(sql, params, prepare), (result) => result.rows));
         return transformRows === undefined ? found : Effect.map(found, transformRows);
@@ -8,9 +8,14 @@ export const asSqlConnection = ({ connection, send, }) => {
     return {
         execute: rows(true),
         executeRaw: (sql, params) => send(connection.query(sql, params)),
-        executeStream: (sql, params, transformRows) => Stream.unwrap(Effect.as(send(Effect.void), transformRows === undefined
-            ? connection.stream(sql, params)
-            : Stream.map(connection.stream(sql, params), (row) => transformRows([row])[0]))),
+        executeStream: (sql, params, transformRows) => {
+            const stream = transformRows === undefined
+                ? connection.stream(sql, params)
+                : Stream.map(connection.stream(sql, params), (row) => transformRows([row])[0]);
+            return sendStream === undefined
+                ? Stream.unwrap(Effect.as(send(Effect.void), stream))
+                : sendStream(stream);
+        },
         executeValues: (sql, params) => send(connection.queryValues(sql, params)),
         executeValuesUnprepared: (sql, params) => send(connection.queryValues(sql, params, false)),
         executeUnprepared: rows(false),

package/dist/runtime/database/coordination.d.ts

@@ -1,4 +1,4 @@
-import { PgClient } from "@effect/sql-pg";
+import type { PgClient } from "@effect/sql-pg";
 import { Context, Effect, Layer, type Scope } from "effect";
 import { SqlClient } from "effect/sql";
 /** The deployment's coordination database, shared by every runner. */
@@ -7,8 +7,11 @@ export declare const Coordination: Context.Reference<SqlClient.SqlClient | undef
 export declare const registry: Context.Service<SqlClient.SqlClient, SqlClient.SqlClient>;
 /** The client deployment-wide locks are taken on: the designated coordination pool, else `registry`. */
 export declare const authority: Effect.Effect<SqlClient.SqlClient, never, SqlClient.SqlClient>;
-/** Holds startup coordination before even the history table is created, on one leased session. */
-export declare const withMigrationCoordination: <A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient | Scope.Scope>) => Effect.Effect<A, E | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** Holds startup coordination, history creation and migrations in one bounded transaction. */
+export declare const withMigrationCoordination: <A, E>({ effect, history, }: {
+    readonly effect: Effect.Effect<A, E, SqlClient.SqlClient | Scope.Scope>;
+    readonly history?: "actor_migrations" | "actor_coordination_migrations";
+}) => Effect.Effect<A, E | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
 /** Supplies an independent client so coordination transactions never borrow a data transaction's connection. */
 export declare const coordinationLayer: (options: PgClient.PgPoolConfig | undefined) => Layer.Layer<never, import("effect/sql/SqlError").SqlError, never>;
 /**

package/dist/runtime/database/coordination.js

@@ -1,4 +1,3 @@
-import { PgClient } from "@effect/sql-pg";
 import { Context, Effect, Layer } from "effect";
 import { Reactivity } from "effect/reactivity";
 import { Migrator, SqlClient } from "effect/sql";
@@ -16,30 +15,32 @@ const prepareCoordination = Effect.gen(function* () {
     resource text PRIMARY KEY
   )`;
 });
-/** Holds startup coordination before even the history table is created, on one leased session. */
-export const withMigrationCoordination = (effect) => Effect.scoped(Effect.gen(function* () {
+/** Holds startup coordination, history creation and migrations in one bounded transaction. */
+export const withMigrationCoordination = ({ effect, history, }) => Effect.scoped(Effect.gen(function* () {
     const source = yield* SqlClient.SqlClient;
-    const connection = yield* source.reserve;
-    yield* Effect.acquireRelease(connection.execute("SELECT pg_advisory_lock(1935764837, 487)", [], undefined), () => connection
-        .execute("SELECT pg_advisory_unlock(1935764837, 487)", [], undefined)
-        .pipe(Effect.orDie));
-    const reactivity = yield* Reactivity.make;
-    const client = yield* SqlClient.make({
-        acquirer: Effect.succeed(connection),
-        compiler: PgClient.makeCompiler(),
-        spanAttributes: [],
-    }).pipe(Effect.provideService(Reactivity.Reactivity, reactivity));
-    return yield* Effect.provideService(effect, SqlClient.SqlClient, client);
+    return yield* source.withTransaction(Effect.gen(function* () {
+        yield* source `SELECT pg_advisory_xact_lock(1935764837, 487)`;
+        if (history !== undefined)
+            yield* source `CREATE TABLE IF NOT EXISTS ${source(history)} (
+              migration_id integer primary key,
+              created_at timestamp with time zone not null default now(),
+              name text not null
+            )`;
+        return yield* effect;
+    }));
 }));
 /** Supplies an independent client so coordination transactions never borrow a data transaction's connection. */
 export const coordinationLayer = (options) => Layer.effect(Coordination, Effect.gen(function* () {
     if (options === undefined)
         return undefined;
     const sql = yield* boundedPool(options);
-    yield* withMigrationCoordination(Migrator.make({})({
-        table: "actor_coordination_migrations",
-        loader: Migrator.fromRecord({ "0001_coordination": prepareCoordination }),
-    })).pipe(Effect.provideService(SqlClient.SqlClient, sql), Effect.orDie);
+    yield* withMigrationCoordination({
+        effect: Migrator.make({})({
+            table: "actor_coordination_migrations",
+            loader: Migrator.fromRecord({ "0001_coordination": prepareCoordination }),
+        }),
+        history: "actor_coordination_migrations",
+    }).pipe(Effect.provideService(SqlClient.SqlClient, sql), Effect.orDie);
     return sql;
 })).pipe(Layer.provide(Reactivity.layer));
 /**

package/dist/runtime/database/migrations.d.ts

@@ -196,6 +196,10 @@ export declare const migrations: {
     "0032_authority_placement": Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
     /** Retires the single-table inspection variants without rewriting the applied migration that created them. */
     "0033_joined_inspection": Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
+    /** Cold pointers replace state and blob rows atomically; garbage rows never authorize deletion by themselves. */
+    "0034_cold_tier": Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
+    /** The transaction's generation lock, not a referential trigger, authorizes state and receipt writes. */
+    "0035_hot_table_foreign_keys": Effect.Effect<void, Migrator.MigrationError | SqlError.SqlError, SqlClient.SqlClient>;
 };
 /**
  * Runs `record` like `Migrator`, but first refuses a database where a