@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/connections/reads.js

@@ -0,0 +1,19 @@
+import { dual } from "effect/Function";
+/** A read set that has recorded nothing. */
+export const emptyReadSet = () => ({
+    state: false,
+    events: new Set(),
+    tables: new Set(),
+    blobs: new Set(),
+    group: false,
+    caller: false,
+});
+/** Whether a commit that wrote `writes` may have changed the result of a query that read `reads`. */
+export const invalidates = dual(2, (writes, reads) => (writes.state && reads.state) ||
+    writes.events.some((tag) => reads.events.has(tag)) ||
+    writes.tables.some((table) => reads.tables.has(table)) ||
+    writes.blobs.some((blob) => reads.blobs.has(blob)));
+/** The read that makes a query unwatchable, named for the refusal; undefined when every read is supported. */
+export const unsupportedRead = (reads) => reads.group
+    ? "The query reads its placement group, which has no commit signal per actor"
+    : undefined;

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

@@ -0,0 +1,62 @@
+import { Effect, Stream } from "effect";
+import type { SqlClient } from "effect/sql";
+import { ActorError } from "../../errors/actor.ts";
+import type { ActorRef, Caller } from "../../identity/caller.ts";
+import type { Registration, StreamInput } from "../members.ts";
+import type { Activation } from "./owner.ts";
+import type { Transport } from "./transport.ts";
+/** One live subscription, owned until its subscriber or activation ends. */
+export interface Subscription {
+    readonly member: string;
+    readonly caller: Caller;
+    /** When authorization last succeeded, on the framework clock. */
+    lastAuthorized: number;
+    checking: boolean;
+    /** Since when the handler has waited on a full window. */
+    stalledSince: number | undefined;
+    readonly end: (error: ActorError, discard: boolean) => Effect.Effect<void>;
+}
+/** Decides whether a caller may open a stream or renew its access; `false` refuses. */
+export type Authorize = (request: {
+    readonly caller: Caller;
+    readonly ref: ActorRef;
+    readonly command: string;
+    readonly kind: "stream" | "reauthorize";
+    /** A stream tag must not be interpreted as a feed event tag. */
+    readonly of?: "stream";
+}) => Effect.Effect<boolean>;
+/**
+ * Owns stream admission, producer lifetime, bounded delivery and revocation.
+ * The connection owner supplies the committed read context only after access
+ * and capacity are checked; it retains generation acquisition and the ordered
+ * broadcast channel. Streams have no durable session rows or replay promise.
+ */
+export declare const streamSubscriptions: ({ registration, activations, transport, authorize, now, prepare, }: {
+    readonly registration: Registration;
+    readonly activations: ReadonlyMap<string, Activation>;
+    readonly transport: Pick<Transport, "holder" | "epoch">;
+    readonly authorize: Authorize;
+    readonly now: Effect.Effect<number>;
+    readonly prepare: (activation: Activation) => Effect.Effect<Omit<StreamInput, "caller">, ActorError, SqlClient.SqlClient>;
+}) => {
+    subscribe: (activation: Activation, request: {
+        readonly member: string;
+        readonly caller: Caller;
+        readonly input: string;
+        readonly authorizedUntil: number;
+    }) => Stream.Stream<{
+        readonly _tag: "Done";
+    } | {
+        readonly _tag: "Element";
+        readonly value: string;
+    } | {
+        readonly _tag: "Started";
+        readonly owner: string;
+        readonly ownerEpoch: string;
+    }, ActorError | {
+        readonly _tag: "StreamFailed";
+        readonly value: string;
+    }, SqlClient.SqlClient>;
+    end: (activation: Activation) => Effect.Effect<void, never, never>;
+    watch: Effect.Effect<void, never, never>;
+};

package/dist/runtime/connections/streams.js

@@ -0,0 +1,128 @@
+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";
+/** Open stream subscriptions one actor may have. */
+const MAX_ACTOR_STREAMS = 256;
+/** Stream elements held for one subscriber before its handler waits. */
+const STREAM_WINDOW = 256;
+/** How long a stream's window may stay full before the subscription ends. */
+const STREAM_STALL_MS = 30_000;
+/** How often the owner checks subscriptions' authorization and windows. */
+const STREAM_TICK = "100 millis";
+const unauthorized = (code) => ActorError.make({ reason: Unauthorized.make({ code }) });
+const ended = (cause, resync) => ActorError.make({ reason: SessionEnded.make({ cause, resync }) });
+/**
+ * Owns stream admission, producer lifetime, bounded delivery and revocation.
+ * The connection owner supplies the committed read context only after access
+ * and capacity are checked; it retains generation acquisition and the ordered
+ * broadcast channel. Streams have no durable session rows or replay promise.
+ */
+export const streamSubscriptions = ({ registration, activations, transport, authorize, now, prepare, }) => {
+    /** Natural completion follows all elements; every other end is an explicit error. */
+    const subscribe = (activation, request) => Stream.unwrap(Effect.gen(function* () {
+        const stream = registration.streams.get(request.member);
+        if (stream === undefined)
+            return yield* Effect.die(new Error(`Unregistered stream ${request.member}`));
+        if ((yield* now) >= request.authorizedUntil)
+            return yield* unauthorized("reauthorization_unavailable");
+        const allowed = yield* authorize({
+            caller: request.caller,
+            ref: activation.ref,
+            command: request.member,
+            kind: "stream",
+        });
+        if (!allowed)
+            return yield* unauthorized("access_denied");
+        const queue = yield* Queue.bounded(STREAM_WINDOW);
+        let producer;
+        let closed = false;
+        const subscription = {
+            member: request.member,
+            caller: request.caller,
+            lastAuthorized: yield* now,
+            checking: false,
+            stalledSince: undefined,
+            end: (error, discard) => Effect.gen(function* () {
+                if (closed)
+                    return;
+                closed = true;
+                activation.streams.delete(subscription);
+                if (producer !== undefined)
+                    yield* Fiber.interrupt(producer);
+                if (discard)
+                    yield* Queue.clear(queue).pipe(Effect.ignore);
+                yield* Queue.fail(queue, error);
+            }),
+        };
+        const admitted = yield* Effect.sync(() => {
+            if (activation.streams.size >= MAX_ACTOR_STREAMS)
+                return false;
+            activation.streams.add(subscription);
+            return true;
+        });
+        if (!admitted)
+            return yield* ActorError.make({ reason: RunnerAtCapacity.make({}) });
+        yield* Effect.addFinalizer(() => Effect.gen(function* () {
+            closed = true;
+            activation.streams.delete(subscription);
+            if (producer !== undefined)
+                yield* Fiber.interrupt(producer);
+        }));
+        const input = yield* prepare(activation);
+        const offer = (item) => Effect.gen(function* () {
+            if (Queue.offerUnsafe(queue, item))
+                return;
+            subscription.stalledSince = yield* now;
+            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(() => {
+            closed = true;
+            activation.streams.delete(subscription);
+        })), Effect.forkDetach);
+        return Stream.succeed(StreamItem.cases.Started.make({ owner: transport.holder, ownerEpoch: transport.epoch })).pipe(Stream.concat(Stream.fromQueue(queue)));
+    }));
+    const end = (activation) => Effect.forEach([...activation.streams], (subscription) => subscription.end(ended("ActivationEnded", false), false), { discard: true });
+    const reauthorize = (activation, subscription, at) => Effect.gen(function* () {
+        subscription.checking = true;
+        const every = registration.policy.reauthorizeMs;
+        const allowed = yield* authorize({
+            caller: subscription.caller,
+            ref: activation.ref,
+            command: subscription.member,
+            kind: "reauthorize",
+            of: "stream",
+        }).pipe(Effect.timeout(Math.min(10_000, every / 2)), Effect.exit);
+        subscription.checking = false;
+        const bound = subscription.lastAuthorized + every;
+        if (Exit.isSuccess(allowed) && allowed.value && (yield* now) >= bound)
+            yield* subscription.end(unauthorized("reauthorization_unavailable"), true);
+        else if (Exit.isSuccess(allowed) && allowed.value)
+            subscription.lastAuthorized = at;
+        else if (Exit.isSuccess(allowed))
+            yield* subscription.end(unauthorized("access_denied"), true);
+    });
+    /** Revocation discards undelivered elements, including while a check is in flight. */
+    const watch = Effect.gen(function* () {
+        const at = yield* now;
+        const every = registration.policy.reauthorizeMs;
+        for (const activation of activations.values())
+            for (const subscription of activation.streams) {
+                if (at >= subscription.lastAuthorized + every) {
+                    yield* subscription
+                        .end(unauthorized("reauthorization_unavailable"), true)
+                        .pipe(Effect.forkDetach);
+                    continue;
+                }
+                if (subscription.stalledSince !== undefined &&
+                    at - subscription.stalledSince >= STREAM_STALL_MS) {
+                    yield* subscription.end(ended("SlowConsumer", true), true).pipe(Effect.forkDetach);
+                    continue;
+                }
+                if (!subscription.checking &&
+                    at >= subscription.lastAuthorized + every - Math.min(10_000, every / 2))
+                    yield* reauthorize(activation, subscription, at).pipe(Effect.forkDetach);
+            }
+    }).pipe(Effect.repeat(Schedule.spaced(STREAM_TICK)), Effect.asVoid);
+    return { subscribe, end, watch };
+};

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

@@ -0,0 +1,40 @@
+import { Crypto, Effect, Schema } from "effect";
+import { Sharding, ShardingConfig } from "effect/cluster";
+import { type Deliver, type Delivered } from "./protocol.ts";
+declare const HolderUnreachable_base: Schema.Class<HolderUnreachable, Schema.TaggedStruct<"HolderUnreachable", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A holder could not be reached: the owner treats its connections as lost. */
+export declare class HolderUnreachable extends HolderUnreachable_base {
+}
+/**
+ * This runner's transport identity and the channel to every other runner's
+ * holder. A runner with a Cluster address hosts a holder entity in a shard
+ * group named after that address; an unclustered runtime reaches only itself.
+ */
+export interface Transport {
+    readonly holder: string;
+    readonly epoch: string;
+    readonly deliver: (holder: string, epoch: string, message: Deliver) => Effect.Effect<Delivered, HolderUnreachable>;
+    /** Whether the runner `holder` is still running the process that took `epoch`. */
+    readonly ping: (holder: string, epoch: string) => Effect.Effect<boolean>;
+}
+/**
+ * A runner that hosts no actors still hosts its own holder, so its group is
+ * assigned regardless of the configured ones.
+ */
+export declare const holderShardGroups: (config: Partial<ShardingConfig.ShardingConfig["Service"]>) => {} | {
+    availableShardGroups: string[];
+    assignedShardGroups: string[];
+};
+/**
+ * Shard placement for the holder's own group can lag a moment behind registration,
+ * so an unassigned entity is retried.
+ */
+export declare const holderTransport: (local: (message: Deliver) => Effect.Effect<Delivered>) => Effect.Effect<{
+    holder: string;
+    epoch: string;
+    deliver: (holder: string, epoch: string, message: Deliver) => Effect.Effect<Delivered, HolderUnreachable>;
+    ping: (holder: string, epoch: string) => Effect.Effect<boolean>;
+}, never, Crypto.Crypto | import("effect/Scope").Scope | Sharding.Sharding | ShardingConfig.ShardingConfig>;
+export {};

package/dist/runtime/connections/transport.js

@@ -0,0 +1,68 @@
+import { Crypto, Effect, Option, Schedule, Schema } from "effect";
+import { ClusterError, EntityId, Sharding, ShardingConfig } from "effect/cluster";
+import { HolderEntity, holderEntityId, holderGroup, } from "./protocol.js";
+const LOCAL = "local";
+/** How long an owner waits for a holder to acknowledge one message, before one retry. */
+const ACK_TIMEOUT = "1 second";
+/** A holder could not be reached: the owner treats its connections as lost. */
+export class HolderUnreachable extends Schema.TaggedError()("HolderUnreachable", { message: Schema.String }) {
+}
+/**
+ * A runner that hosts no actors still hosts its own holder, so its group is
+ * assigned regardless of the configured ones.
+ */
+export const holderShardGroups = (config) => Option.match(config.runnerAddress ?? Option.none(), {
+    onNone: () => ({}),
+    onSome: (address) => ({
+        availableShardGroups: ["default", holderGroup(address)],
+        assignedShardGroups: [...(config.assignedShardGroups ?? ["default"]), holderGroup(address)],
+    }),
+});
+/**
+ * Shard placement for the holder's own group can lag a moment behind registration,
+ * so an unassigned entity is retried.
+ */
+export const holderTransport = Effect.fnUntraced(function* (local) {
+    const config = yield* ShardingConfig.ShardingConfig;
+    const sharding = yield* Sharding.Sharding;
+    const crypto = yield* Crypto.Crypto;
+    const epoch = yield* crypto.randomUUIDv7.pipe(Effect.orDie);
+    const holder = Option.match(config.runnerAddress, {
+        onNone: () => LOCAL,
+        onSome: holderGroup,
+    });
+    const clustered = holder !== LOCAL && config.assignedShardGroups.includes(holder);
+    if (clustered)
+        yield* sharding.registerEntity(HolderEntity, Effect.succeed(HolderEntity.of({
+            Deliver: ({ payload }) => payload.epoch === epoch
+                ? local(payload)
+                : Effect.succeed({ wrongEpoch: true, unknown: [] }),
+            Ping: ({ payload }) => Effect.succeed(payload.epoch === epoch),
+        })), { concurrency: "unbounded" });
+    const client = clustered ? yield* sharding.makeClient(HolderEntity) : undefined;
+    const deliver = (target, targetEpoch, message) => {
+        if (target === holder)
+            return targetEpoch === epoch
+                ? local(message)
+                : Effect.succeed({ wrongEpoch: true, unknown: [] });
+        if (client === undefined || target === LOCAL)
+            return Effect.fail(HolderUnreachable.make({ message: `Holder ${target} is not reachable` }));
+        return client(EntityId.make(holderEntityId({ holder: target, epoch: targetEpoch })))
+            .Deliver(message)
+            .pipe(Effect.retry({
+            while: (error) => ClusterError.EntityNotAssignedToRunner.is(error) ||
+                ClusterError.RunnerUnavailable.is(error),
+            schedule: Schedule.spaced("50 millis"),
+        }), Effect.timeout(ACK_TIMEOUT), Effect.retry({ times: 1 }), Effect.mapError(() => HolderUnreachable.make({ message: `Holder ${target} did not acknowledge` })));
+    };
+    const ping = (target, targetEpoch) => {
+        if (target === holder)
+            return Effect.succeed(targetEpoch === epoch);
+        if (client === undefined || target === LOCAL)
+            return Effect.succeed(false);
+        return client(EntityId.make(holderEntityId({ holder: target, epoch: targetEpoch })))
+            .Ping({ epoch: targetEpoch })
+            .pipe(Effect.timeout(ACK_TIMEOUT), Effect.retry({ times: 1 }), Effect.orElseSucceed(() => false));
+    };
+    return { holder, epoch, deliver, ping };
+});

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

@@ -0,0 +1,52 @@
+import { Context, Effect, Stream } from "effect";
+import { ActorError } from "../../errors/actor.ts";
+import { Outcome, type Request } from "../request.ts";
+import { type WatchResult } from "../members.ts";
+import type { Holder } from "./holder.ts";
+import { type ReadSet } from "./reads.ts";
+/**
+ * Asked before an owner broadcasts a commit's `Committed` frame; `true` drops
+ * it, as a lost best-effort broadcast would. Tests drop frames here to show
+ * the reconcile rerun recovers them.
+ */
+export declare const WatchTap: Context.Reference<{
+    readonly dropsCommitted: () => boolean;
+}>;
+/** What a watch needs from its runner: the holder its connection parks at, and one rerun of the query. */
+export interface WatchOptions {
+    readonly holder: Holder;
+    /** The request to watch: `command` is the query and `payload` its encoded input. */
+    readonly request: Request;
+    readonly minIntervalMs: number;
+    readonly reconcileMs: number;
+    /** A commit version the first result must reflect at least. */
+    readonly minVersion: string | undefined;
+    /** The credential's own expiry in epoch milliseconds, if it has one. */
+    readonly expiresAt: number | undefined;
+    /**
+     * Reruns the query for this watch and records what it read. `version` is
+     * called once the rerun holds its place among the runner's reruns, so a rerun
+     * that waited for one starts from the newest version seen meanwhile.
+     */
+    readonly rerun: (version: () => string | undefined, reads: ReadSet) => Effect.Effect<Outcome, ActorError>;
+}
+/**
+ * A watch on one query: its current result first, then the newest result after
+ * each commit whose writes intersect what the last run read. The watch is a
+ * parked framework connection, so the owner sends it one `Committed` frame per
+ * commit and nothing keeps the actor resident.
+ *
+ * Reruns are coalesced: at most one runs and one waits, frames that arrive
+ * meanwhile only raise the version the next rerun waits for, and reruns of one
+ * watch start at least `minIntervalMs` apart. A result equal to the last one
+ * sent is not sent, and the newest result replaces one nobody has read yet, so
+ * a slow reader never ends the watch. The broadcast is best-effort, so the
+ * watch also reruns every `reconcileMs`, after a holder resync, and after a
+ * reopen, which is how a lost frame or a change no commit reports is shown.
+ * A rerun that reads what a commit signal cannot cover ends the watch with
+ * `not_watchable`, and one that fails transiently is retried. A result read
+ * for a session past its authorization bound is dropped.
+ */
+export declare const watchStream: (options: WatchOptions) => Effect.Effect<Stream.Stream<WatchResult, ActorError | {
+    readonly failure: string;
+}, never>, ActorError, never>;

package/dist/runtime/connections/watch.js

@@ -0,0 +1,159 @@
+import { Clock, Context, Deferred, Effect, Match, Option, Predicate, Queue, Result, Schema, Stream, } from "effect";
+import { ActorError, InvalidInput, SessionEnded } from "../../errors/actor.js";
+import { Outcome } from "../request.js";
+import {} from "../members.js";
+import { Committed, watchMember } from "./protocol.js";
+import { emptyReadSet, invalidates, unsupportedRead } from "./reads.js";
+/**
+ * Asked before an owner broadcasts a commit's `Committed` frame; `true` drops
+ * it, as a lost best-effort broadcast would. Tests drop frames here to show
+ * the reconcile rerun recovers them.
+ */
+export const WatchTap = Context.Reference("@rikalabs/akter/runtime/connections/watch/WatchTap", { defaultValue: () => ({ dropsCommitted: () => false }) });
+/** How long a watch waits before it reruns after a rerun failed for a reason a later attempt may not share. */
+const RERUN_RETRY_MS = 1_000;
+const decodeCommitted = Schema.decodeEffect(Schema.fromJsonString(Committed));
+/** Ends that a watch survives by reopening at its holder and rerunning, as a feed does. */
+const recoverable = (error) => Predicate.isTagged(error.reason, "SessionEnded") &&
+    ["SlowConsumer", "OwnerLost", "ActorUnavailable"].includes(error.reason.cause);
+/** Failures of a rerun that the next attempt may not repeat. */
+const transient = (error) => Predicate.isTagged(error.reason, "ActorUnavailable") ||
+    Predicate.isTagged(error.reason, "Timeout") ||
+    Predicate.isTagged(error.reason, "RunnerAtCapacity");
+/**
+ * A watch on one query: its current result first, then the newest result after
+ * each commit whose writes intersect what the last run read. The watch is a
+ * parked framework connection, so the owner sends it one `Committed` frame per
+ * commit and nothing keeps the actor resident.
+ *
+ * Reruns are coalesced: at most one runs and one waits, frames that arrive
+ * meanwhile only raise the version the next rerun waits for, and reruns of one
+ * watch start at least `minIntervalMs` apart. A result equal to the last one
+ * sent is not sent, and the newest result replaces one nobody has read yet, so
+ * a slow reader never ends the watch. The broadcast is best-effort, so the
+ * watch also reruns every `reconcileMs`, after a holder resync, and after a
+ * reopen, which is how a lost frame or a change no commit reports is shown.
+ * A rerun that reads what a commit signal cannot cover ends the watch with
+ * `not_watchable`, and one that fails transiently is retried. A result read
+ * for a session past its authorization bound is dropped.
+ */
+export const watchStream = Effect.fnUntraced(function* (options) {
+    const { holder, request } = options;
+    const open = holder
+        .open({
+        ref: request.ref,
+        member: watchMember(request.command),
+        caller: request.caller,
+        params: "",
+        expiresAt: options.expiresAt,
+    })
+        .pipe(Effect.catchTag("OpenRejected", () => Effect.die(new Error("A watch has no open handler"))));
+    const first = yield* open;
+    return Stream.callback((out) => Effect.gen(function* () {
+        let held = first;
+        let pending = options.minVersion === undefined ? undefined : BigInt(options.minVersion);
+        let reads;
+        let dirty = true;
+        let sent;
+        let settling = [];
+        const signal = yield* Queue.sliding(1);
+        yield* Effect.addFinalizer(() => held.close);
+        const raise = () => {
+            dirty = true;
+            Queue.offerUnsafe(signal, undefined);
+        };
+        const note = (committed) => {
+            const version = BigInt(committed.version);
+            if (pending === undefined || version > pending)
+                pending = version;
+            if (reads === undefined || invalidates(committed.writes, reads))
+                raise();
+        };
+        const listen = (connection) => connection.messages.pipe(Stream.runForEach((item) => Match.value(item).pipe(Match.tagsExhaustive({
+            Frame: (frame) => decodeCommitted(frame.frame).pipe(Effect.orDie, Effect.map(note)),
+            Resync: () => Effect.void,
+            ResyncReplayed: () => Effect.gen(function* () {
+                const done = yield* Deferred.make();
+                settling.push(done);
+                raise();
+                yield* Deferred.await(done);
+                yield* connection.resyncDone;
+            }),
+            Progress: () => Effect.void,
+        }))));
+        const follow = Effect.gen(function* () {
+            while (true) {
+                const ended = yield* listen(held).pipe(Effect.flip, Effect.option);
+                if (Option.isNone(ended))
+                    return;
+                if (!recoverable(ended.value))
+                    return yield* ended.value;
+                held = yield* open;
+                raise();
+            }
+        });
+        const refuse = (reason) => ActorError.make({
+            reason: InvalidInput.make({
+                code: "not_watchable",
+                issues: [{ path: request.command, message: reason }],
+            }),
+        });
+        const rerun = Effect.gen(function* () {
+            const read = emptyReadSet();
+            let version;
+            const outcome = yield* options
+                .rerun(() => (version = pending?.toString()), read)
+                .pipe(Effect.result);
+            if (Result.isFailure(outcome)) {
+                if (!transient(outcome.failure))
+                    return yield* outcome.failure;
+                raise();
+                yield* Effect.sleep(RERUN_RETRY_MS);
+                return;
+            }
+            const result = outcome.success;
+            if (Outcome.guards.Failure(result))
+                return yield* Effect.fail({ failure: result.value });
+            if (Outcome.guards.Defect(result)) {
+                yield* Effect.logError("Watch handler defect", result.cause);
+                return yield* ActorError.make({
+                    reason: SessionEnded.make({ cause: "Defect", resync: false }),
+                });
+            }
+            if (!Outcome.guards.Success(result))
+                return yield* Effect.die(new Error("A query cannot acknowledge"));
+            const unsupported = unsupportedRead(read);
+            if (unsupported !== undefined)
+                return yield* refuse(unsupported);
+            reads = read;
+            if (result.value === sent || !(yield* held.authorized))
+                return;
+            sent = result.value;
+            yield* Queue.offer(out, { version, value: result.value });
+        });
+        const reruns = Effect.gen(function* () {
+            let startedAt = Number.NEGATIVE_INFINITY;
+            while (true) {
+                while (!dirty) {
+                    const woke = yield* Queue.take(signal).pipe(Effect.timeoutOption(options.reconcileMs));
+                    if (Option.isNone(woke))
+                        dirty = true;
+                }
+                const wait = startedAt + options.minIntervalMs - (yield* Clock.currentTimeMillis);
+                if (wait > 0)
+                    yield* Effect.sleep(wait);
+                startedAt = yield* Clock.currentTimeMillis;
+                dirty = false;
+                const covered = settling;
+                settling = [];
+                yield* rerun;
+                yield* Effect.forEach(covered, (done) => Deferred.succeed(done, undefined), {
+                    discard: true,
+                });
+            }
+        });
+        yield* Effect.all([follow, reruns], { concurrency: "unbounded", discard: true }).pipe(Effect.catch((error) => Schema.is(ActorError)(error) && Predicate.isTagged(error.reason, "Unauthorized")
+            ? Effect.andThen(Effect.ignore(Queue.clear(out)), Queue.fail(out, error))
+            : Queue.fail(out, error)), Effect.catchCause((cause) => Queue.failCause(out, cause)), Effect.forkScoped);
+    }), { bufferSize: 1, strategy: "sliding" });
+});

package/dist/runtime/content/grant.d.ts

@@ -0,0 +1,34 @@
+import { Effect, Redacted, Result } from "effect";
+import type { InvalidContentRef } from "../../errors/content.ts";
+/** How long a grant lasts from when it is issued. */
+export declare const GRANT_LIFETIME_MS = 3600000;
+/** One deployment secret grants are signed or verified with. */
+export interface GrantKey {
+    /** Named in every grant it signs, so a rotated-out key still verifies its grants. */
+    readonly id: string;
+    /** At least 32 bytes of UTF-8. */
+    readonly secret: Redacted.Redacted<string>;
+}
+/** What a grant binds. The deployment id keeps grants of one database out of another. */
+export interface Granted {
+    readonly tenant: string;
+    readonly hash: string;
+    readonly size: number;
+    readonly expiresAt: number;
+}
+/** Signs and verifies content grants. Verification compares MACs in constant time (WebCrypto). */
+export interface Grants {
+    /** Signs with the first key. */
+    readonly sign: (granted: Granted) => Effect.Effect<string>;
+    /**
+     * Checks a grant's MAC under any configured key; returns its expiry. The
+     * caller checks the expiry against the database clock.
+     */
+    readonly verify: (grant: string, bound: Omit<Granted, "expiresAt">) => Effect.Effect<Result.Result<number, InvalidContentRef["reason"]>>;
+}
+/**
+ * Validates `keys` and imports them once. The first key signs; every key
+ * verifies, so an operator adds the new key first, keeps the old one listed
+ * for one grant lifetime, and then removes it.
+ */
+export declare const grantKeys: (keys: readonly GrantKey[], deployment: string) => Effect.Effect<Grants, never, never>;

package/dist/runtime/content/grant.js

@@ -0,0 +1,58 @@
+import { Effect, Redacted, Result } from "effect";
+import { Base64Url } from "effect/encoding";
+/** How long a grant lasts from when it is issued. */
+export const GRANT_LIFETIME_MS = 3_600_000;
+const KEY_ID = /^[A-Za-z0-9_-]{1,32}$/;
+/** A grant is `g1.<key id>.<expires ms>.<mac>`, the MAC as unpadded base64url of 32 bytes. */
+const GRANT = /^g1\.([A-Za-z0-9_-]{1,32})\.([1-9][0-9]{0,15})\.([A-Za-z0-9_-]{43})$/;
+const utf8 = new TextEncoder();
+/** The signed message: length-prefixed parts, so no two bindings encode to the same message. */
+const message = (deployment, granted) => utf8.encode([
+    "durable-content/v1",
+    deployment,
+    granted.tenant,
+    granted.hash,
+    String(granted.size),
+    String(granted.expiresAt),
+]
+    .map((part) => `${part.length}:${part}`)
+    .join(""));
+/**
+ * Validates `keys` and imports them once. The first key signs; every key
+ * verifies, so an operator adds the new key first, keeps the old one listed
+ * for one grant lifetime, and then removes it.
+ */
+export const grantKeys = Effect.fnUntraced(function* (keys, deployment) {
+    if (keys.length === 0)
+        return yield* Effect.die(new Error("content.keys needs at least one key"));
+    const imported = new Map();
+    for (const key of keys) {
+        if (!KEY_ID.test(key.id))
+            return yield* Effect.die(new Error("content.keys ids are 1-32 letters, digits, - or _"));
+        if (imported.has(key.id))
+            return yield* Effect.die(new Error(`content.keys lists ${key.id} twice`));
+        const secret = utf8.encode(Redacted.value(key.secret));
+        if (secret.byteLength < 32)
+            return yield* Effect.die(new Error(`content.keys ${key.id} needs a secret of at least 32 bytes`));
+        imported.set(key.id, yield* Effect.promise(() => globalThis.crypto.subtle.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"])));
+    }
+    const signer = keys[0].id;
+    const grants = {
+        sign: (granted) => Effect.promise(() => globalThis.crypto.subtle.sign("HMAC", imported.get(signer), message(deployment, granted))).pipe(Effect.map((mac) => `g1.${signer}.${granted.expiresAt}.${Base64Url.encode(new Uint8Array(mac))}`)),
+        verify: (grant, bound) => Effect.gen(function* () {
+            const parts = GRANT.exec(grant);
+            if (parts === null)
+                return Result.fail("malformed");
+            const expiresAt = Number(parts[2]);
+            const key = imported.get(parts[1]);
+            const mac = Base64Url.decode(parts[3]);
+            if (!Number.isSafeInteger(expiresAt) || Result.isFailure(mac))
+                return Result.fail("malformed");
+            if (key === undefined)
+                return Result.fail("invalid");
+            const valid = yield* Effect.promise(() => globalThis.crypto.subtle.verify("HMAC", key, new Uint8Array(mac.success), message(deployment, { ...bound, expiresAt })));
+            return valid ? Result.succeed(expiresAt) : Result.fail("invalid");
+        }),
+    };
+    return grants;
+});