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

package/dist/runtime/layer.d.ts

@@ -5,6 +5,7 @@ import { Actors } from "../handles/actors.ts";
 import { InternalActors } from "./actors.ts";
 import type { AccessRequest } from "../policies/access.ts";
 import { pglite } from "./database/pglite.ts";
+import { type ColdStorageOptions } from "./storage/cold-tier.ts";
 import { DefectLog } from "./telemetry/defects.ts";
 import { OperatorRuntime } from "./operators/repair.ts";
 import { TelemetrySampler } from "./telemetry/sampler.ts";
@@ -15,6 +16,8 @@ import { RuntimeControl } from "./drain.ts";
 import type { AnyFleetView } from "../tables/fleet.ts";
 /** Configuration for `Actors.layer`: authorization, actor and effect layers, timing, retention, and row-level security. */
 export interface Options {
+    /** Opt-in cold state and actor blobs. Postgres only; backup retention is required. */
+    readonly coldStorage?: ColdStorageOptions;
     /**
      * The global authorization hook, asked about every external request beside
      * the actor's own `access` policy; when both exist both must allow. With
@@ -223,6 +226,10 @@ export interface Options {
  */
 export declare const layer: (options?: Options) => Layer.Layer<Actors | ContentStore | DefectLog | InternalActors | OperatorRuntime | RuntimeControl | TelemetrySampler, import("effect/sql/Migrator").MigrationError | SqlError.SqlError, Crypto.Crypto | SqlClient.SqlClient>;
 type PostgresOptions = Omit<PgClient.PgPoolConfig, "types"> & {
+    /** Opt-in transaction pooling for socket runners with table leases; session-dependent features are refused. */
+    readonly pooling?: "transaction";
+    /** Four primary sessions: one turn, two off-turn (one reserved by Cluster), and one query. Explicit pool sizes take precedence. */
+    readonly preset?: "low-connection";
     readonly offTurnConnections?: number;
     readonly queryConnections?: number;
     readonly replica?: Omit<PgClient.PgPoolConfig, "types"> | undefined;
@@ -245,11 +252,27 @@ type PostgresOptions = Omit<PgClient.PgPoolConfig, "types"> & {
  * first come, first served. Keep the sum across runners below the server's
  * `max_connections`.
  *
+ * `preset: "low-connection"` defaults these pools to 1/2/1 instead of
+ * 50/10/10. Cluster reserves one off-turn session for its entire lifetime,
+ * including with table leases, so the other must remain available for
+ * startup and ordinary work. Fleet maintenance and application reservations
+ * need additional off-turn capacity; optional pools add to the budget.
+ * Explicit pool sizes override the preset.
+ *
+ * `pooling: "transaction"` explicitly selects a transaction-pooled endpoint.
+ * It requires `Runner.socket` table leases, refuses replica, separate
+ * coordination, fleet and cold storage, disables prepared statements and
+ * warm turn speculation, and does not inject server keepalive startup
+ * parameters. Configure both proxy transport legs separately. Cluster's
+ * reservation consumes a logical client, not a backend outside transactions.
+ * Application session state, `listen` and session advisory locks remain
+ * unsupported on this endpoint.
+ *
  * `replica` is this runner's nearest streaming replica of the same primary.
  * Queries read there once it has replayed the commit version their caller
  * last saw, and read the primary when it is behind or fails. Its pool
  * (`maxConnections` default 10) opens connections only as queries need them.
- * Every pool requests server TCP keepalives at 5 seconds idle, 2 seconds
+ * Direct pools request server TCP keepalives at 5 seconds idle, 2 seconds
  * between probes, and 3 probes. `startupParameters` overrides these defaults
  * independently on the primary and replica configurations.
  *

package/dist/runtime/layer.js

@@ -15,6 +15,7 @@ import { schemaChange } from "./database/schema.js";
 import { queryPoolLayer, ReadReplica, replicaLayer } from "./database/replica.js";
 import { Coordination, coordinationLayer } from "./database/coordination.js";
 import { withKeepalives } from "./database/keepalive.js";
+import { WarmTurnFastPath } from "./turn/execute.js";
 import { checkRowLevelSecurity, TenantScope } from "./database/tenancy.js";
 import { retryDelay } from "./retry.js";
 import { withoutDatabase } from "./jobs/isolation.js";
@@ -26,6 +27,7 @@ import { ProgressSink, ProgressTap } from "./jobs/progress.js";
 import { FEED_MEMBER, isWatchMember, watchedQuery } from "./connections/protocol.js";
 import { checkIdentity, databaseTime, FrameworkClock } from "./turn/admission.js";
 import { routingKey } from "./storage/codec.js";
+import { ColdTier, coldTier } from "./storage/cold-tier.js";
 import { recordedPlacement } from "./storage/placements.js";
 import { TurnHooks } from "./turn/hooks.js";
 import { requestAttributes, SpanNames } from "./telemetry/spans.js";
@@ -220,7 +222,17 @@ export const layer = (options = {}) => {
         const frameworkClock = yield* FrameworkClock;
         const writerDeclarations = [];
         let refreshedAt;
-        const services = yield* Effect.context();
+        let services = yield* Effect.context();
+        if (options.coldStorage !== undefined &&
+            Option.isSome(yield* Effect.serviceOption(PgliteClient.PgliteClient)))
+            return yield* Effect.die(new Error("coldStorage requires Postgres, not PGlite"));
+        const tier = options.coldStorage === undefined
+            ? undefined
+            : yield* coldTier(options.coldStorage, (yield* (yield* SqlClient.SqlClient) `SELECT deployment_id FROM actor_deployment`)[0].deployment_id, relaySettings.maxBackoffMs);
+        services = Context.add(services, ColdTier, tier);
+        const coldSweep = tier?.periodic === true
+            ? yield* tier.run.pipe(Effect.provideContext(services), Effect.forkIn(scope))
+            : undefined;
         const defectLog = boundedDefectLog(defectCapacity);
         let recorder;
         const currentRecorder = () => recorder;
@@ -582,7 +594,7 @@ export const layer = (options = {}) => {
         }, () => new Map(Array.from(registrations.values(), ({ name, cron, policy }) => [
             name,
             { entries: cron, skipMs: policy.cronSkipMs },
-        ]))).pipe(Effect.provideService(ProgressSink, progressSink));
+        ]))).pipe(Effect.provideService(ProgressSink, progressSink), Effect.provideService(ColdTier, tier));
         yield* relay.run.pipe(Effect.forkIn(scope));
         let fleetSubscribe;
         if (options.fleet !== undefined && options.fleet.length > 0) {
@@ -785,7 +797,7 @@ export const layer = (options = {}) => {
             stopClaims: relay.stop,
             attemptsIdle: relay.attemptsIdle,
             interruptAttempts: relay.interruptAttempts,
-            stopBackground: sweeping === undefined ? Effect.void : Fiber.interrupt(sweeping),
+            stopBackground: Effect.forEach([sweeping, coldSweep].filter((fiber) => fiber !== undefined), Fiber.interrupt, { discard: true }),
             serving,
             scope,
         });
@@ -839,12 +851,19 @@ export const layer = (options = {}) => {
                 }));
             }),
         });
-        return Context.make(Actors, publicActors).pipe(Context.add(ContentStore, contentStore), Context.add(InternalActors, internalActors), Context.add(RuntimeControl, control), Context.add(DefectLog, defectLog), Context.add(TelemetrySampler, TelemetrySampler.of({ sample })), Context.add(OperatorRuntime, operators));
+        return Context.make(Actors, publicActors).pipe(Context.add(ColdTier, tier), Context.add(ContentStore, contentStore), Context.add(InternalActors, internalActors), Context.add(RuntimeControl, control), Context.add(DefectLog, defectLog), Context.add(TelemetrySampler, TelemetrySampler.of({ sample })), Context.add(OperatorRuntime, operators));
     }));
     return Layer.unwrap(Effect.gen(function* () {
         const sql = yield* SqlClient.SqlClient;
         const coordination = (yield* Coordination) ?? sql;
         const wiring = Option.getOrUndefined(yield* Effect.serviceOption(RunnerWiring));
+        const transactionPooling = yield* TransactionPooling;
+        if (transactionPooling &&
+            (wiring?.production !== true ||
+                wiring.config?.shardLockDisableAdvisory !== true ||
+                options.coldStorage !== undefined ||
+                (options.fleet?.length ?? 0) > 0))
+            return yield* Effect.die(new Error("Transaction pooling requires Runner.socket table leases and does not support coldStorage or fleet"));
         yield* migrate;
         if (options.rowLevelSecurity !== undefined &&
             options.adoption !== undefined &&
@@ -889,7 +908,7 @@ export const layer = (options = {}) => {
                 expiration: Duration.fromInputUnsafe(config.shardLockExpiration ?? ShardingConfig.defaults.shardLockExpiration),
             }))
             : Layer.empty;
-        return runtime.pipe(Layer.provide(sharding), Layer.provide(lease), Layer.provide(Layer.succeed(TenantScope, {
+        return runtime.pipe(Layer.provide(transactionPooling ? Layer.succeed(WarmTurnFastPath, false) : Layer.empty), Layer.provide(sharding), Layer.provide(lease), Layer.provide(Layer.succeed(TenantScope, {
             role: options.rowLevelSecurity?.role,
             adoption: options.adoption === undefined
                 ? undefined
@@ -897,6 +916,10 @@ export const layer = (options = {}) => {
         })));
     }));
 };
+/** Explicit pooling mode, independent of endpoint names or URL parameters. */
+const TransactionPooling = Context.Reference("akter/TransactionPooling", {
+    defaultValue: () => false,
+});
 /**
  * A runner holds three primary pools, plus optional replica and coordination
  * pools. Turns lease sessions from the turn pool, `maxConnections` (default
@@ -913,11 +936,27 @@ export const layer = (options = {}) => {
  * first come, first served. Keep the sum across runners below the server's
  * `max_connections`.
  *
+ * `preset: "low-connection"` defaults these pools to 1/2/1 instead of
+ * 50/10/10. Cluster reserves one off-turn session for its entire lifetime,
+ * including with table leases, so the other must remain available for
+ * startup and ordinary work. Fleet maintenance and application reservations
+ * need additional off-turn capacity; optional pools add to the budget.
+ * Explicit pool sizes override the preset.
+ *
+ * `pooling: "transaction"` explicitly selects a transaction-pooled endpoint.
+ * It requires `Runner.socket` table leases, refuses replica, separate
+ * coordination, fleet and cold storage, disables prepared statements and
+ * warm turn speculation, and does not inject server keepalive startup
+ * parameters. Configure both proxy transport legs separately. Cluster's
+ * reservation consumes a logical client, not a backend outside transactions.
+ * Application session state, `listen` and session advisory locks remain
+ * unsupported on this endpoint.
+ *
  * `replica` is this runner's nearest streaming replica of the same primary.
  * Queries read there once it has replayed the commit version their caller
  * last saw, and read the primary when it is behind or fails. Its pool
  * (`maxConnections` default 10) opens connections only as queries need them.
- * Every pool requests server TCP keepalives at 5 seconds idle, 2 seconds
+ * Direct pools request server TCP keepalives at 5 seconds idle, 2 seconds
  * between probes, and 3 probes. `startupParameters` overrides these defaults
  * independently on the primary and replica configurations.
  *
@@ -925,6 +964,9 @@ export const layer = (options = {}) => {
  * migrator needs it on restart; remove once Effect #8309 lands.
  */
 function postgres(options) {
+    if (options.pooling === "transaction" &&
+        (options.replica !== undefined || options.coordination !== undefined))
+        throw new Error("Transaction pooling does not support replica or separate coordination");
     const types = PgTypes.makeRegistry();
     types.register(2205, {
         encode: (value) => PgTypes.encode(value, PgTypes.OID.oid),
@@ -932,9 +974,22 @@ function postgres(options) {
             ? Result.succeed(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0))
             : Result.fail(new PgTypes.CodecError({ message: "Invalid regclass value" })),
     });
-    const { offTurnConnections, queryConnections, replica, coordination, ...configured } = options;
-    const pool = withKeepalives(configured);
-    return Layer.mergeAll(boundedLayer({ ...pool, maxConnections: offTurnConnections ?? 10, types }), turnGroups.pipe(Layer.provideMerge(turnConnections({ ...pool, maxConnections: pool.maxConnections ?? 50, types }))), queryPoolLayer({ ...pool, maxConnections: queryConnections ?? 10, types }), replicaLayer(replica === undefined ? undefined : { ...withKeepalives(replica), types }), coordinationLayer(coordination === undefined ? undefined : { ...withKeepalives(coordination), types }));
+    const { pooling, preset, offTurnConnections, queryConnections, replica, coordination, ...configured } = options;
+    const pool = pooling === "transaction" ? { ...configured, prepare: false } : withKeepalives(configured);
+    const lowConnection = preset === "low-connection";
+    return Layer.mergeAll(Layer.succeed(TransactionPooling, pooling === "transaction"), boundedLayer({
+        ...pool,
+        maxConnections: offTurnConnections ?? (lowConnection ? 2 : 10),
+        types,
+    }), turnGroups.pipe(Layer.provideMerge(turnConnections({
+        ...pool,
+        maxConnections: pool.maxConnections ?? (lowConnection ? 1 : 50),
+        types,
+    }))), queryPoolLayer({
+        ...pool,
+        maxConnections: queryConnections ?? (lowConnection ? 1 : 10),
+        types,
+    }), replicaLayer(replica === undefined ? undefined : { ...withKeepalives(replica), types }), coordinationLayer(coordination === undefined ? undefined : { ...withKeepalives(coordination), types }));
 }
 /** Database layers for `Actors.layer`: `postgres` for real deployments, `pglite` for embedded and test use. */
 export const Database = {

package/dist/runtime/members.d.ts

@@ -279,6 +279,7 @@ export interface RegisteredQuery {
 /** What an actor type's query layer registers with the runtime. */
 export interface QueryRegistration {
     readonly name: string;
+    readonly stateVersion: number;
     readonly placement: Placement;
     /** `commandTimeout`: a query's reads are cancelled on the server past it. */
     readonly timeoutMs: number;
@@ -293,6 +294,7 @@ export interface QueryRegistration {
 /** What an actor type's command layer registers with the runtime. */
 export interface Registration {
     readonly name: string;
+    readonly stateVersion: number;
     readonly singleton: boolean;
     /** Unkeyed with `policy.createdBy`: its UUIDv8 ids come only from `turn.mint`. */
     readonly mintable: boolean;

package/dist/runtime/operators/export.d.ts

@@ -21,7 +21,9 @@ export declare class ExportRefused extends ExportRefused_base {
  * them in `omitted`. Subscription cursors and connections are neither carried
  * nor counted. A job whose attempt has been cancelled or has finally failed
  * is not pending and is left out. It reads the runtime tables, not the
- * inspection views, because the views do not show a cancelled job. `None`
+ * inspection views, because the views do not show a cancelled job. A cold
+ * pointer is captured in that snapshot; its immutable material is fetched
+ * only after the transaction ends, without activation or write-back. `None`
  * when the tenant has no such actor.
  */
 export declare const exportActor: (page: {

package/dist/runtime/operators/export.js

@@ -5,6 +5,7 @@ import { JOB_KEY_PREFIX } from "../../handles/intents.js";
 import { decodeBytes, decodeText } from "../inspector/queries.js";
 import { inReadOnlySnapshot } from "../database/snapshot.js";
 import { TenantScope, tenantSettings } from "../database/tenancy.js";
+import { ColdTier } from "../storage/cold-tier.js";
 import { databaseTime } from "../turn/admission.js";
 import { SEED_FORMAT } from "./seed.js";
 /** The most pending intents, and the most pending jobs, one export carries. */
@@ -41,18 +42,21 @@ const tenantSnapshot = (tenant) => (effect) => Effect.gen(function* () {
  * them in `omitted`. Subscription cursors and connections are neither carried
  * nor counted. A job whose attempt has been cancelled or has finally failed
  * is not pending and is left out. It reads the runtime tables, not the
- * inspection views, because the views do not show a cancelled job. `None`
+ * inspection views, because the views do not show a cancelled job. A cold
+ * pointer is captured in that snapshot; its immutable material is fetched
+ * only after the transaction ends, without activation or write-back. `None`
  * when the tenant has no such actor.
  */
 export const exportActor = (page) => tenantSnapshot(page.tenant)(Effect.gen(function* () {
     const sql = yield* SqlClient.SqlClient;
     const [found] = yield* sql `
-        SELECT routing_key::text AS "routingKey", created FROM actor_generations
+        SELECT routing_key::text AS "routingKey", created, cold_ref, cold_digest, cold_state_version
+        FROM actor_generations
         WHERE tenant_id = ${page.tenant} AND actor_type = ${page.actorType}
           AND actor_id = ${page.actorId}`;
     if (found === undefined)
-        return Option.none();
-    const { routingKey, created } = found;
+        return undefined;
+    const { routingKey } = found;
     const owned = sql `routing_key = ${routingKey}::int8 AND tenant_id = ${page.tenant}
         AND actor_type = ${page.actorType} AND actor_id = ${page.actorId}`;
     const exportedAtMs = yield* databaseTime;
@@ -93,14 +97,36 @@ export const exportActor = (page) => tenantSnapshot(page.tenant)(Effect.gen(func
             AND actor_id = ${page.actorId}`;
         tableRows += rows.count;
     }
+    return { found, stored, intents, jobs, counted: counted, tableRows, exportedAtMs };
+})).pipe(Effect.flatMap((snapshot) => Effect.gen(function* () {
+    if (snapshot === undefined)
+        return Option.none();
+    const { found, stored, intents, jobs, counted, tableRows, exportedAtMs } = snapshot;
+    const { routingKey, created } = found;
+    const material = found.cold_ref === null
+        ? undefined
+        : yield* Effect.flatMap(ColdTier, (tier) => tier === undefined
+            ? Effect.die(new Error("Cold export needs coldStorage"))
+            : tier
+                .fetch({
+                key: BigInt(routingKey),
+                ref: { tenant: page.tenant, actor: page.actorType, id: page.actorId },
+            }, {
+                ref: found.cold_ref,
+                digest: found.cold_digest,
+                version: found.cold_state_version,
+            })
+                .pipe(Effect.orDie));
+    const entries = material === undefined
+        ? stored.map(({ key, value }) => [key, decodeBytes(value)])
+        : material.envelope.state.map(([key, value]) => [key, decodeText(value)]);
     const state = {};
     let stateVersion = 0;
-    for (const row of stored) {
-        const decoded = decodeBytes(row.value);
+    for (const [key, decoded] of entries) {
         if (decoded === null || "undecodable" in decoded)
-            return yield* ExportRefused.make({ reason: "undecodable", detail: `state ${row.key}` });
-        if (row.key !== VERSION_KEY)
-            state[row.key] = decoded.json;
+            return yield* ExportRefused.make({ reason: "undecodable", detail: `state ${key}` });
+        if (key !== VERSION_KEY)
+            state[key] = decoded.json;
         else
             stateVersion = Option.getOrElse(decodeVersion(decoded.json), () => 0);
     }
@@ -131,7 +157,12 @@ export const exportActor = (page) => tenantSnapshot(page.tenant)(Effect.gen(func
             key: row.timerKey?.replace(JOB_KEY_PREFIX, "") ?? undefined,
             dueInMs: dueIn(row.dueAtMs),
         }))),
-        omitted: { ...counted, tableRows },
+        omitted: {
+            ...counted,
+            tableRows,
+            blobs: counted.blobs +
+                (material?.envelope.blobs.filter(({ chunk }) => chunk === 0).length ?? 0),
+        },
     };
     return Option.some(seed);
-}));
+})));

package/dist/runtime/queries.d.ts

@@ -4,7 +4,7 @@ import { SqlClient } from "effect/sql";
 import { ActorError } from "../errors/actor.ts";
 import { type InternalActors } from "./actors.ts";
 import { type Request } from "./request.ts";
-import { type QueryRegistration, type Registration } from "./members.ts";
+import type { QueryRegistration, Registration } from "./members.ts";
 import type { Holder } from "./connections/holder.ts";
 export declare const committedReads: ({ registrations, queryRegistrations, services, allow, primary, replica, holder, }: {
     readonly registrations: ReadonlyMap<string, Registration>;

package/dist/runtime/queries.js

@@ -4,12 +4,13 @@ import { SqlClient, SqlError } from "effect/sql";
 import { ActorError, ActorUnavailable, InvalidInput, NotCreated, Timeout } from "../errors/actor.js";
 import {} from "./actors.js";
 import { Outcome } from "./request.js";
-import {} from "./members.js";
 import { watchStream } from "./connections/watch.js";
 import { caughtUp, QueryPool } from "./database/replica.js";
 import { withTenant } from "./database/tenancy.js";
 import { replayEvents } from "./events/replay.js";
 import { decompress, routingKey } from "./storage/codec.js";
+import { ColdTier } from "./storage/cold-tier.js";
+import { ColdRead } from "./turn/blobs.js";
 import { accountsUsage, UsageAccounting } from "./telemetry/usage.js";
 import { decodeResult } from "./workflows/engine.js";
 /**
@@ -57,15 +58,16 @@ export const committedReads = ({ registrations, queryRegistrations, services, al
         const key = routingKey({ ref: request.ref, placement: registration.placement });
         const read = (client) => Effect.gen(function* () {
             const rows = yield* client `
-              SELECT event_sequence::text AS head, NULL AS key, NULL::bytea AS value
+              SELECT event_sequence::text AS head, NULL AS key, NULL::bytea AS value,
+                cold_ref, cold_digest, cold_state_version
               FROM actor_generations
               WHERE routing_key = ${key} AND tenant_id = ${request.ref.tenant}
                 AND actor_type = ${request.ref.actor} AND actor_id = ${request.ref.id}
               UNION ALL
-              SELECT NULL, key, value
+              SELECT NULL, key, value, NULL, NULL, NULL
               FROM actor_state
               WHERE routing_key = ${key} AND tenant_id = ${request.ref.tenant}
-                AND actor_type = ${request.ref.actor} AND actor_id = ${request.ref.id}`;
+                AND actor_type = ${request.ref.actor} AND actor_id = ${request.ref.id}`.pipe(withTenant(request.ref.tenant));
             let head;
             const state = [];
             for (const row of rows)
@@ -76,11 +78,26 @@ export const committedReads = ({ registrations, queryRegistrations, services, al
             if (head === undefined)
                 state.length = 0;
             const cursor = head ?? "0";
-            const outcome = yield* query.run(request, state, cursor, (tag, after, limit) => replayEvents(request.ref, key, [tag], after, BigInt(cursor), limit).pipe(Effect.catchIf(SqlError.isSqlError, Effect.die), Effect.provideService(SqlClient.SqlClient, client), Effect.provideContext(services)), reads);
+            const pointer = rows.find((row) => row.head !== null);
+            const tier = Context.get(services, ColdTier);
+            const material = pointer?.cold_ref == null
+                ? undefined
+                : yield* Effect.suspend(() => tier === undefined
+                    ? Effect.die(new Error("Cold query needs coldStorage"))
+                    : tier
+                        .fetch({ key, ref: request.ref }, {
+                        ref: pointer.cold_ref,
+                        digest: pointer.cold_digest,
+                        version: pointer.cold_state_version,
+                    })
+                        .pipe(Effect.mapError((cause) => ActorError.make({ reason: ActorUnavailable.make({ cause }) }))));
+            const outcome = yield* query
+                .run(request, material?.envelope.state ?? state, cursor, (tag, after, limit) => replayEvents(request.ref, key, [tag], after, BigInt(cursor), limit).pipe(Effect.catchIf(SqlError.isSqlError, Effect.die), Effect.provideService(SqlClient.SqlClient, client), Effect.provideContext(services)), reads)
+                .pipe(Effect.provideService(ColdRead, material), withTenant(request.ref.tenant));
             if (Outcome.guards.Defect(outcome) && SqlError.isSqlError(outcome.cause))
                 return yield* outcome.cause;
             return outcome;
-        }).pipe(withTenant(request.ref.tenant), Effect.provideService(SqlClient.SqlClient, client));
+        }).pipe(Effect.provideService(SqlClient.SqlClient, client));
         const owned = registration.tables.length > 0 || registration.blobs.length > 0;
         const local = owned ? primary : (queryPool ?? primary);
         const outcome = yield* Effect.gen(function* () {

package/dist/runtime/registration.js

@@ -1,4 +1,5 @@
-import { Context, Crypto, Effect } from "effect";
+import { PgliteClient } from "@effect/sql-pglite";
+import { Context, Crypto, Effect, Option } from "effect";
 import { Sharding } from "effect/cluster";
 import { SqlClient, SqlError } from "effect/sql";
 import { isContent } from "../members/blob.js";
@@ -25,6 +26,29 @@ const ROUTED_SUBSCRIBER_WAIT_MS = 5000;
 export const actorRegistration = ({ registrations, queryRegistrations, jobRegistrations, residency, diagnostics, owners, heldTypes, heldType, sweepsWorkflows, checked, services, frameworkClock, content, retryWindowMs, tableRole, adoptionRole, enforcedTypes, writerDeclarations, refreshPayloadWriters, subscriptions, transport, authorize, gate, writable, defectLog, outbox, recorder, }) => {
     /** Concurrent layers can exceed checkout capacity; only a refused checkout is safe to retry here. */
     const startupSql = (effect) => retryPoolRefusal(effect).pipe(Effect.orDie);
+    /**
+     * A shortened migration history cannot reinterpret older cold objects.
+     * PGlite cannot offload, so it needs no transaction that would eagerly start
+     * its singleton actors during registration.
+     */
+    const checkColdState = Effect.fnUntraced(function* (registration) {
+        if (Option.isSome(yield* Effect.serviceOption(PgliteClient.PgliteClient)))
+            return;
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql.withTransaction(Effect.gen(function* () {
+            const [record] = yield* sql `SELECT state_version FROM actor_placements
+        WHERE actor_type = ${registration.name} FOR UPDATE`;
+            const previous = record.state_version;
+            const unreadable = yield* sql `SELECT 1 FROM actor_generations
+        WHERE actor_type = ${registration.name} AND cold_ref IS NOT NULL
+          AND (cold_state_version > ${registration.stateVersion}
+            OR (${registration.stateVersion} < ${previous} AND cold_state_version < ${previous})) LIMIT 1`;
+            if (unreadable.length > 0)
+                return yield* Effect.die(new Error(`Actor ${registration.name} state chain is shortened while cold actors need it; deploy refused`));
+            yield* sql `UPDATE actor_placements SET state_version = ${registration.stateVersion}
+        WHERE actor_type = ${registration.name}`;
+        }));
+    });
     /**
      * Refuses a layer that can't read every payload version the database
      * may hold, as a placement or workflow mismatch is refused. `writes`
@@ -91,6 +115,7 @@ export const actorRegistration = ({ registrations, queryRegistrations, jobRegist
             if (registrations.has(registration.name))
                 return yield* Effect.die(new Error(`Duplicate actor: ${registration.name}`));
             yield* checkPlacement(registration).pipe(Effect.provideContext(services), startupSql);
+            yield* checkColdState(registration).pipe(Effect.provideContext(services), startupSql);
             if (declaresContent(registration)) {
                 yield* requireContent(registration.name);
                 yield* recordContentTurn(registration).pipe(Effect.provideContext(services), startupSql);
@@ -159,6 +184,7 @@ export const actorRegistration = ({ registrations, queryRegistrations, jobRegist
             if (queryRegistrations.has(registration.name))
                 return yield* Effect.die(new Error(`Duplicate query layer: ${registration.name}`));
             yield* checkPlacement(registration).pipe(Effect.provideContext(services), startupSql);
+            yield* checkColdState(registration).pipe(Effect.provideContext(services), startupSql);
             if (declaresContent(registration))
                 yield* requireContent(registration.name);
             yield* checkTables(registration.name, registration.tables, tableRole, {

package/dist/runtime/request.d.ts

@@ -86,7 +86,7 @@ export declare const Request: Schema.Struct<{
     readonly 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/runner.d.ts

@@ -71,9 +71,24 @@ export interface SocketRunnerOptions<E> {
     readonly shardLockRefreshInterval?: Duration.Input;
     /** Default 1 second. */
     readonly refreshAssignmentsInterval?: Duration.Input;
-    /** Default 15 seconds, bounding activation shutdown during a shard handoff. */
+    /**
+     * Default 15 seconds, bounding activation shutdown during a shard handoff.
+     * Must not exceed shardLockExpiration minus the smaller of
+     * shardLockRefreshInterval and one third of shardLockExpiration.
+     */
     readonly entityTerminationTimeout?: Duration.Input;
 }
+declare const RunnerConfigurationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RunnerConfigurationError";
+} & Readonly<A>;
+/** Synchronous configuration refusal before runner startup when shutdown can outlast its shard lock. */
+export declare class RunnerConfigurationError extends RunnerConfigurationError_base<{
+    readonly entityTerminationTimeoutMs: number;
+    readonly shardLockExpirationMs: number;
+    readonly effectiveRefreshIntervalMs: number;
+}> {
+    get message(): string;
+}
 /**
  * Joins separate processes over TCP sockets. Provide this layer to
  * `Actors.layer`; the framework keeps direct commands, SQL ownership, receipts,
@@ -82,6 +97,8 @@ export interface SocketRunnerOptions<E> {
  * transport unless the network is isolated to this deployment's runners. The
  * transport's own services stay in the runtime, so readiness sees whether a
  * mutual TLS transport can still peer.
+ * Throws RunnerConfigurationError synchronously if activation shutdown can
+ * outlast the shard lock's remaining lifetime after its effective refresh.
  */
 export declare const socket: <E>(options: SocketRunnerOptions<E>) => Layer.Layer<RunnerWiring, never, never>;
 /**

package/dist/runtime/runner.js

@@ -1,4 +1,4 @@
-import { Context, Duration, Effect, HashRing, Layer, Option, PrimaryKey } from "effect";
+import { Context, Data, Duration, Effect, HashRing, Layer, Option, PrimaryKey } from "effect";
 import { MessageStorage, RunnerAddress, RunnerHealth, Runners, RunnerServer, RunnerStorage, Sharding, ShardingConfig, ShardId, } from "effect/cluster";
 import { RpcSerialization, RpcServer } from "effect/rpc";
 import { SocketServer } from "effect/socket";
@@ -60,6 +60,12 @@ export const acquiredShards = Effect.gen(function* () {
         }).pipe(Effect.timeoutOption("2 seconds"), Effect.map(Option.getOrElse(() => false)), Effect.orElseSucceed(() => false)),
     });
 });
+/** Synchronous configuration refusal before runner startup when shutdown can outlast its shard lock. */
+export class RunnerConfigurationError extends Data.TaggedError("RunnerConfigurationError") {
+    get message() {
+        return `entityTerminationTimeout (${this.entityTerminationTimeoutMs} ms) must not exceed shardLockExpiration minus the effective shardLockRefreshInterval (${this.shardLockExpirationMs - this.effectiveRefreshIntervalMs} ms)`;
+    }
+}
 const address = (value, advertise) => {
     if (value.host.trim().length === 0 ||
         (advertise && ["0.0.0.0", "::", "*"].includes(value.host)) ||
@@ -83,21 +89,35 @@ const duration = (value, name, minimum = 1) => {
  * transport unless the network is isolated to this deployment's runners. The
  * transport's own services stay in the runtime, so readiness sees whether a
  * mutual TLS transport can still peer.
+ * Throws RunnerConfigurationError synchronously if activation shutdown can
+ * outlast the shard lock's remaining lifetime after its effective refresh.
  */
 export const socket = (options) => {
     const shardsPerGroup = options.shardsPerGroup ?? 256;
     if (!Number.isSafeInteger(shardsPerGroup) || shardsPerGroup < 1 || shardsPerGroup > 65536)
         throw new Error("shardsPerGroup must be an integer between 1 and 65536");
+    const shardLockExpiration = duration(options.shardLockExpiration ?? "35 seconds", "shardLockExpiration", 3000);
+    const shardLockRefreshInterval = duration(options.shardLockRefreshInterval ?? "10 seconds", "shardLockRefreshInterval");
+    const entityTerminationTimeout = duration(options.entityTerminationTimeout ?? "15 seconds", "entityTerminationTimeout");
+    const shardLockExpirationMs = Duration.toMillis(shardLockExpiration);
+    const effectiveRefreshIntervalMs = Math.min(Duration.toMillis(shardLockRefreshInterval), shardLockExpirationMs / 3);
+    const entityTerminationTimeoutMs = Duration.toMillis(entityTerminationTimeout);
+    if (entityTerminationTimeoutMs > shardLockExpirationMs - effectiveRefreshIntervalMs)
+        throw new RunnerConfigurationError({
+            entityTerminationTimeoutMs,
+            shardLockExpirationMs,
+            effectiveRefreshIntervalMs,
+        });
     const config = {
         runnerAddress: Option.some(address(options.address, true)),
         runnerListenAddress: Option.some(address(options.listenAddress ?? options.address, false)),
         shardsPerGroup,
         shardLockDisableAdvisory: true,
-        shardLockExpiration: duration(options.shardLockExpiration ?? "35 seconds", "shardLockExpiration", 3000),
-        shardLockRefreshInterval: duration(options.shardLockRefreshInterval ?? "10 seconds", "shardLockRefreshInterval"),
+        shardLockExpiration,
+        shardLockRefreshInterval,
         refreshAssignmentsInterval: duration(options.refreshAssignmentsInterval ?? "1 second", "refreshAssignmentsInterval"),
         entityMessagePollInterval: "1 second",
-        entityTerminationTimeout: duration(options.entityTerminationTimeout ?? "15 seconds", "entityTerminationTimeout"),
+        entityTerminationTimeout,
     };
     const sharding = RunnerServer.layer.pipe(Layer.provideMerge(admissionSharding), Layer.provideMerge(Runners.layerRpc), Layer.provide(RpcServer.layerProtocolSocketServer), Layer.provideMerge(options.transport), Layer.provide(RpcSerialization.layerNdjson), Layer.orDie);
     return Layer.succeed(RunnerWiring, {

package/dist/runtime/storage/cold-storage.d.ts

@@ -0,0 +1,56 @@
+import { type S3ClientConfig } from "@aws-sdk/client-s3";
+import { Effect, FileSystem, Path, Stream } from "effect";
+declare const ColdStorageError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ColdStorageError";
+} & Readonly<A>;
+/** A failed object operation, including an unknown upload or deletion outcome. */
+export declare class ColdStorageError extends ColdStorageError_base<{
+    readonly cause: unknown;
+}> {
+}
+/** An immutable object's key and creation time, used only as an orphan retention bound. */
+export interface ColdObject {
+    readonly key: string;
+    readonly createdAtMs: number;
+}
+/**
+ * Private deployment object storage. `put` creates a key once and returns
+ * false if it already exists; a retry must verify the existing bytes.
+ * `delete` succeeds only when absence is confirmed. Listing is paginated,
+ * and failures never mean an empty object or a successful deletion.
+ */
+export interface ColdStorage {
+    readonly get: (key: string) => Effect.Effect<Uint8Array, ColdStorageError>;
+    readonly put: (key: string, bytes: Uint8Array) => Effect.Effect<boolean, ColdStorageError>;
+    readonly delete: (key: string) => Effect.Effect<void, ColdStorageError>;
+    readonly list: (prefix: string) => Stream.Stream<ColdObject, ColdStorageError>;
+}
+/** A deterministic create-only store for local tests; copies bytes at both boundaries. */
+declare const memory: () => ColdStorage;
+/** S3-compatible credentials, endpoint, bucket, and deployment encryption settings. */
+export interface S3ColdStorageOptions extends S3ClientConfig {
+    readonly bucket: string;
+    /** Omitted, use the bucket's configured encryption. */
+    readonly encryption?: "AES256" | "aws:kms";
+    readonly encryptionKey?: string;
+}
+/** Object-storage adapters for runtime-only cold state, never tenant content. */
+export declare const ColdStorage: {
+    memory: typeof memory;
+    filesystem: (directory: string) => Effect.Effect<{
+        get: (key: string) => Effect.Effect<Uint8Array<ArrayBufferLike>, ColdStorageError, never>;
+        put: (key: string, bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<boolean, ColdStorageError, never>;
+        delete: (key: string) => Effect.Effect<void, ColdStorageError, never>;
+        list: (prefix: string) => Stream.Stream<ColdObject, ColdStorageError, never>;
+    }, never, FileSystem.FileSystem | Path.Path>;
+    s3: (args_0: S3ColdStorageOptions) => Effect.Effect<{
+        get: (key: string) => Effect.Effect<Uint8Array<ArrayBufferLike>, ColdStorageError, never>;
+        put: (key: string, bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<boolean, ColdStorageError, never>;
+        delete: (key: string) => Effect.Effect<void, ColdStorageError, never>;
+        list: (prefix: string) => Stream.Stream<{
+            key: string;
+            createdAtMs: number;
+        }, ColdStorageError, never>;
+    }, never, import("effect/Scope").Scope>;
+};
+export {};