@rikalabs/akter 0.1.0-alpha.0 → 0.1.0-alpha.3

package/dist/runtime/database/schema.js

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import { dual } from "effect/Function";
+import { SqlClient } from "effect/sql";
+/**
+ * Runs an application's own schema setup on the ambient `SqlClient` while
+ * holding advisory lock `lock`, so processes starting together apply it one
+ * at a time. The lock and every statement share one transaction, so a failed
+ * setup rolls back together and releases its lock.
+ */
+export const schemaChange = dual(2, (effect, lock) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    return yield* sql.withTransaction(Effect.andThen(sql `SELECT pg_advisory_xact_lock(${lock})`, effect));
+}));

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

@@ -1,21 +1,39 @@
 import { Context, Effect } from "effect";
-import { SqlClient } from "effect/sql";
-/** One inclusive bucket range on one database shard, independent of actor compute ownership. */
+import type { SqlClient } from "effect/sql";
+/** One inclusive scheduling range, independent of actor compute ownership. */
 export interface BucketRange {
     readonly first: number;
     readonly last: number;
-    /** Neki's shard UID; absent on an ordinary single database. */
-    readonly shard?: string | undefined;
 }
-/** The data ranges this runner may scan; ordinary databases have one range and no session setting. */
+/**
+ * Bucket ranges on one database. The default covers the whole key space;
+ * tests partition it to verify range boundaries and shared claim capacity.
+ */
 export declare const ShardMap: Context.Reference<readonly BucketRange[]>;
+/** Refuses ranges that overlap or leave the bucket space. */
+export declare const checkRanges: (ranges: ReadonlyArray<BucketRange>) => boolean;
+/** The runtime's scheduling ranges, checked before any scan runs. */
+export declare const currentRanges: Effect.Effect<readonly BucketRange[], never, never>;
+/** The ranges as scans read them, in bucket order. */
+export declare const shardRanges: Effect.Effect<BucketRange[], never, never>;
+/**
+ * Captures the runtime's scheduling ranges for calls from outside fibers,
+ * such as a holder transport's, so every scan uses the same range boundaries.
+ */
+export declare const locatedHere: Effect.Effect<<A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, never>>, never, never>;
+/**
+ * Runs a scan once per scheduling range. `withinRange` keeps each statement
+ * within its inclusive buckets so no row is visited twice.
+ */
+export declare const forEachRange: <A, E, R>(effect: (range: BucketRange) => Effect.Effect<A, E, R>) => Effect.Effect<A[], E, R>;
 /**
- * Gives each targeted range its own session for the lifetime of the caller's
- * scope. A shard setting cannot leak into the shared off-turn pool, and a
- * failed setup closes the session instead of returning it to another user.
- * Untargeted ranges reuse the existing client without a setting or a lease.
+ * `AND <column> BETWEEN` the routing keys of `range`'s buckets, or nothing for
+ * the whole key space, so an unsharded database runs the statement unchanged.
+ * `WHERE` starts the predicate for a statement that has none.
  */
-export declare const shardClients: Effect.Effect<{
-    range: BucketRange;
-    sql: SqlClient.SqlClient;
-}[], import("effect/sql/SqlError").SqlError, import("effect/Scope").Scope | SqlClient.SqlClient>;
+export declare const withinRange: ({ sql, range, column, keyword, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly range: BucketRange;
+    readonly column: string;
+    readonly keyword?: "AND" | "WHERE";
+}) => import("effect/sql/Statement").Fragment;

package/dist/runtime/database/shards.js

@@ -1,37 +1,49 @@
-import { PgClient } from "@effect/sql-pg";
-import { Context, Effect, Layer } from "effect";
-import { SqlClient } from "effect/sql";
+import { Context, Effect } from "effect";
 import { BUCKETS } from "../turn/outbox.js";
-/** The data ranges this runner may scan; ordinary databases have one range and no session setting. */
+/**
+ * Bucket ranges on one database. The default covers the whole key space;
+ * tests partition it to verify range boundaries and shared claim capacity.
+ */
 export const ShardMap = Context.Reference("akter/ShardMap", {
     defaultValue: () => [BUCKETS],
 });
-/**
- * Gives each targeted range its own session for the lifetime of the caller's
- * scope. A shard setting cannot leak into the shared off-turn pool, and a
- * failed setup closes the session instead of returning it to another user.
- * Untargeted ranges reuse the existing client without a setting or a lease.
- */
-export const shardClients = Effect.gen(function* () {
-    const sql = yield* SqlClient.SqlClient;
-    const ranges = yield* ShardMap;
+/** Refuses ranges that overlap or leave the bucket space. */
+export const checkRanges = (ranges) => {
     const sorted = [...ranges].sort((a, b) => a.first - b.first);
-    for (const [index, range] of sorted.entries()) {
+    for (const [index, range] of sorted.entries())
         if (!Number.isInteger(range.first) ||
             !Number.isInteger(range.last) ||
             range.first < BUCKETS.first ||
             range.last > BUCKETS.last ||
             range.first > range.last ||
-            (index > 0 && sorted[index - 1].last >= range.first) ||
-            range.shard === "")
-            return yield* Effect.die(new Error("Invalid or overlapping shard bucket ranges"));
-    }
-    return yield* Effect.forEach(ranges, (range) => Effect.gen(function* () {
-        if (range.shard === undefined)
-            return { range, sql };
-        const postgres = yield* PgClient.PgClient;
-        const client = Context.get(yield* Layer.build(PgClient.layerFrom(PgClient.makeClient(postgres.config))), SqlClient.SqlClient);
-        yield* client `SET __neki.shard = ${client.literal(`'${range.shard.replaceAll("'", "''")}'`)}`;
-        return { range, sql: client };
-    }));
+            (index > 0 && sorted[index - 1].last >= range.first))
+            return false;
+    return true;
+};
+/** The runtime's scheduling ranges, checked before any scan runs. */
+export const currentRanges = Effect.gen(function* () {
+    const ranges = yield* ShardMap;
+    if (!checkRanges(ranges))
+        return yield* Effect.die(new Error("Invalid or overlapping shard bucket ranges"));
+    return ranges;
 });
+/** The ranges as scans read them, in bucket order. */
+export const shardRanges = Effect.map(currentRanges, (ranges) => [...ranges].sort((a, b) => a.first - b.first));
+/**
+ * Captures the runtime's scheduling ranges for calls from outside fibers,
+ * such as a holder transport's, so every scan uses the same range boundaries.
+ */
+export const locatedHere = Effect.map(ShardMap, (map) => (effect) => Effect.provideService(effect, ShardMap, map));
+/**
+ * Runs a scan once per scheduling range. `withinRange` keeps each statement
+ * within its inclusive buckets so no row is visited twice.
+ */
+export const forEachRange = (effect) => Effect.flatMap(shardRanges, (ranges) => Effect.forEach(ranges, effect));
+/**
+ * `AND <column> BETWEEN` the routing keys of `range`'s buckets, or nothing for
+ * the whole key space, so an unsharded database runs the statement unchanged.
+ * `WHERE` starts the predicate for a statement that has none.
+ */
+export const withinRange = ({ sql, range, column, keyword = "AND", }) => range.first === BUCKETS.first && range.last === BUCKETS.last
+    ? sql.literal("")
+    : sql `${sql.literal(keyword)} ${sql.literal(column)} BETWEEN ${BigInt(range.first) << 56n} AND ${(BigInt(range.last + 1) << 56n) - 1n}`;

package/dist/runtime/entity/register.d.ts

@@ -9,6 +9,7 @@ import { ActorRef } from "../../identity/caller.ts";
 import type { Authorize } from "../connections/streams.ts";
 import type { Transport } from "../connections/transport.ts";
 import { DefectLog } from "../telemetry/defects.ts";
+import type { LiveRecorder } from "../telemetry/live.ts";
 /**
  * The commands an activation holds, waiting and in its current batch, when its
  * policy declares no `mailboxCapacity`. Cluster refuses the next, which
@@ -297,7 +298,7 @@ export declare const registerActor: (registration: Registration, transport: Tran
     readonly open: boolean;
     close: Effect.Effect<void, never, never>;
     expire: Effect.Effect<number, never, never>;
-}, writable: Effect.Effect<void, ActorError, never>) => Effect.Effect<{
+}, writable: Effect.Effect<void, ActorError, never>, recorder: () => LiveRecorder | undefined) => Effect.Effect<{
     isResident: (entityId: string) => boolean;
     owner: {
         activations: Map<string, import("../connections/owner.ts").Activation>;
@@ -419,6 +420,12 @@ export declare const registerActor: (registration: Registration, transport: Tran
     };
     /** This type's view of one activation, for a delivery that timed out. */
     diagnose: (entityId: string) => ActivationDiagnosis;
+    /** The activations of this type resident now, with the commands waiting in each mailbox. */
+    resident: () => {
+        tenant: string;
+        id: string;
+        mailbox: number;
+    }[];
     /** Activations of this type being rebuilt or restarted in place now. */
     restarting: () => string[];
 }, never, Crypto.Crypto | DefectLog | Scope.Scope | Sharding.Sharding | SqlClient.SqlClient>;

package/dist/runtime/entity/register.js

@@ -5,7 +5,7 @@ import { SqlClient, SqlError } from "effect/sql";
 import { ActorError, ActorUnavailable } from "../../errors/actor.js";
 import { DeliveryFailed, Executed, Outcome, Request } from "../request.js";
 import {} from "../members.js";
-import { ActorRef } from "../../identity/caller.js";
+import { ActorRef, callerKey } from "../../identity/caller.js";
 import { bootstrapTicks } from "../cron/schedule.js";
 import { parentPlacement, routingKey } from "../storage/codec.js";
 import { ShardLease } from "../topology/locks.js";
@@ -158,7 +158,8 @@ const keepSingletonAwake = Effect.fnUntraced(function* (registration, entity, se
         actor: registration.name,
         id: "singleton",
     });
-    yield* bootstrapTicks(routingKey({ ref, placement: registration.placement }), ref, registration.cron).pipe(Effect.provideContext(services), Effect.orDie);
+    const key = routingKey({ ref, placement: registration.placement });
+    yield* bootstrapTicks(key, ref, registration.cron).pipe(Effect.provideContext(services), Effect.orDie);
     const address = yield* encodeEntityId([registration.tenant, "singleton"]).pipe(Effect.orDie);
     const client = (yield* sharding.makeClient(entity))(address);
     const wakeInterval = Duration.min(SINGLETON_WAKE_INTERVAL, Duration.millis(registration.policy.idleMs / 2));
@@ -207,7 +208,9 @@ const keepSingletonAwake = Effect.fnUntraced(function* (registration, entity, se
  */
 export const registerActor = Effect.fnUntraced(function* (registration, transport, authorize, gate, 
 /** Fails while this runtime may not start turns, e.g. its payload writer rows are stale. */
-writable) {
+writable, 
+/** The live recorder, once the inspector enabled one. */
+recorder) {
     const sharding = yield* Sharding.Sharding;
     const defects = yield* DefectLog;
     const typeAttributes = { actor_type: registration.name };
@@ -221,7 +224,8 @@ writable) {
     });
     const ownedOf = (entityId) => Effect.flatMap(Effect.orDie(decodeEntityId(entityId)), ([tenant, id]) => {
         const ref = { actor: registration.name, tenant, id };
-        return owner.enter(entityId, ref, routingKey({ ref, placement: registration.placement }));
+        const key = routingKey({ ref, placement: registration.placement });
+        return owner.enter(entityId, ref, key);
     });
     const services = yield* Effect.context();
     const usage = Context.getUnsafe(services, UsageAccounting);
@@ -231,6 +235,7 @@ writable) {
     const workflowRoutes = workflowCommands({ registration, routingKeyOf, services });
     const waited = new Set([...registration.workflows.values()].flatMap((workflow) => [...workflow.member.registry.steps.values()].flatMap((step) => step.event === undefined ? [] : [step.event])));
     const resident = new Map();
+    const residentRefs = new Map();
     const building = new Set();
     const workers = new Map();
     const lease = registration.singleton
@@ -240,10 +245,15 @@ writable) {
      * Counts a handler of `entityId` as resident until its scope closes; a
      * rebuilt handler can overlap its predecessor, hence the count.
      */
-    const residentWhile = (entityId) => Effect.acquireRelease(Effect.sync(() => resident.set(entityId, (resident.get(entityId) ?? 0) + 1)).pipe(Effect.andThen(count(Metrics.activationsStarted, typeAttributes, 1)), Effect.andThen(Metric.modify(activations, 1))), () => Effect.sync(() => {
+    const residentWhile = (entityId, tenant, id) => Effect.acquireRelease(Effect.sync(() => {
+        resident.set(entityId, (resident.get(entityId) ?? 0) + 1);
+        residentRefs.set(entityId, { tenant, id });
+    }).pipe(Effect.andThen(count(Metrics.activationsStarted, typeAttributes, 1)), Effect.andThen(Metric.modify(activations, 1))), () => Effect.sync(() => {
         const left = resident.get(entityId) - 1;
-        if (left === 0)
+        if (left === 0) {
             resident.delete(entityId);
+            residentRefs.delete(entityId);
+        }
         else
             resident.set(entityId, left);
     }).pipe(Effect.andThen(Metric.modify(activations, -1))));
@@ -268,6 +278,38 @@ writable) {
         yield* count(Metrics.outboxStaged, { kind: "intent" }, done.written.intents);
         yield* count(Metrics.outboxStaged, { kind: "job" }, done.written.jobs);
     });
+    /**
+     * Hands each command of a committed batch that wrote a receipt to the live
+     * recorder and the tenant's command streams. A replay, a refusal and an
+     * acknowledged delivery wrote none. The turn's time is its transaction's on
+     * the database clock, from the fenced read to the clock read after `COMMIT`.
+     */
+    const recordLive = (live, batch, done, nowMs) => {
+        const durationMs = Math.max(0, done.endedAtMs - done.startedAtMs);
+        for (const [index, settled] of done.settled.entries()) {
+            if (Result.isFailure(settled) || done.replays.has(index))
+                continue;
+            const outcome = settled.success;
+            const failure = Outcome.guards.Failure(outcome) ? outcome.value : undefined;
+            if (!Outcome.guards.Success(outcome) && failure === undefined)
+                continue;
+            const { request } = batch[index];
+            const failed = failure !== undefined;
+            live.record(request.ref.tenant, registration.name, request.command, durationMs, nowMs);
+            live.publish(request.ref.tenant, nowMs, () => ({
+                commandId: request.commandId,
+                atMs: done.endedAtMs,
+                durationMs,
+                actorType: registration.name,
+                actorId: request.ref.id,
+                command: request.command,
+                callerKey: callerKey(request.caller),
+                failed,
+                payload: request.payload,
+                failure,
+            }));
+        }
+    };
     /**
      * Records a deterministic defect in the defect log under its turn span's
      * name and trace, and marks the span's outcome.
@@ -333,7 +375,7 @@ writable) {
         let refused;
         const handler = yield* Scope.fork(activation);
         memory.handler = handler;
-        yield* residentWhile(entityId).pipe(Scope.provide(handler));
+        yield* residentWhile(entityId, tenant, id).pipe(Scope.provide(handler));
         const start = Effect.gen(function* () {
             const scope = yield* Scope.fork(handler);
             if (lease !== undefined)
@@ -437,6 +479,9 @@ writable) {
                     "turn.outcome": labels[0],
                 });
             yield* countWritten(done);
+            const live = recorder();
+            if (live !== undefined && done.written.receipts > 0)
+                recordLive(live, batch, done, yield* Clock.currentTimeMillis);
             if (owner.hasProgress) {
                 for (const [index, settled] of done.settled.entries())
                     if (Result.isSuccess(settled) && !Outcome.guards.Defect(settled.success))
@@ -658,6 +703,12 @@ writable) {
             building: building.has(entityId),
             ...(workers.get(entityId)?.() ?? { worker: "none", mailbox: 0, batch: 0 }),
         }),
+        /** The activations of this type resident now, with the commands waiting in each mailbox. */
+        resident: () => [...residentRefs].map(([entityId, { tenant, id }]) => ({
+            tenant,
+            id,
+            mailbox: workers.get(entityId)?.().mailbox ?? 0,
+        })),
         /** Activations of this type being rebuilt or restarted in place now. */
         restarting: () => [
             ...new Set([

package/dist/runtime/fleet/checks.js

@@ -54,9 +54,9 @@ export const checkFleet = Effect.fnUntraced(function* (views, tenantRole) {
         if (table === undefined)
             return yield* refuse(`${view.name} reads ${source}, which does not exist; apply its drizzle-kit migration`);
         if (!table.published)
-            return yield* refuse(`${source} is not in publication ${FLEET_PUBLICATION}; run durable fleet setup`);
+            return yield* refuse(`${source} is not in publication ${FLEET_PUBLICATION}; run akter fleet setup`);
         if (table.identity !== "f")
-            return yield* refuse(`${source} does not have full replica identity; run durable fleet setup (ALTER TABLE ${source} REPLICA IDENTITY FULL)`);
+            return yield* refuse(`${source} does not have full replica identity; run akter fleet setup (ALTER TABLE ${source} REPLICA IDENTITY FULL)`);
         const leading = [view.routingColumn, view.tenantColumn, ...view.groupColumns];
         const indexes = yield* sql `
       SELECT array(
@@ -88,9 +88,9 @@ export const checkFleet = Effect.fnUntraced(function* (views, tenantRole) {
     SELECT wal_status FROM pg_replication_slots
     WHERE slot_name = ${FLEET_SLOT} AND database = current_database() AND slot_type = 'logical'`;
     if (slot === undefined)
-        return yield* refuse(`replication slot ${FLEET_SLOT} does not exist; run durable fleet setup`);
+        return yield* refuse(`replication slot ${FLEET_SLOT} does not exist; run akter fleet setup`);
     if (slot.wal_status === "lost")
-        return yield* refuse(`replication slot ${FLEET_SLOT} is lost; run durable fleet setup to recreate it, and every view rebuilds`);
+        return yield* refuse(`replication slot ${FLEET_SLOT} is lost; run akter fleet setup to recreate it, and every view rebuilds`);
     const at = yield* Clock.currentTimeMillis;
     for (const { view, sourceSchema } of resolved) {
         yield* sql `INSERT INTO actor_fleet_views (view_name, source_schema, source_table, definition_hash,

package/dist/runtime/fleet/maintainer.d.ts

@@ -31,7 +31,7 @@ export interface ResolvedView {
  * the two replays a batch whose recompute is idempotent. When no change is
  * waiting it rebuilds `building` and `stale` views a few tenants at a time.
  * A view whose recompute fails is marked stale with its error and skipped
- * until `durable fleet rebuild`, so it never stops the others. A slot that
+ * until `akter fleet rebuild`, so it never stops the others. A slot that
  * is missing, lost, or moved by anyone else marks every view stale. The
  * runner that cannot take the lock retries every `LOCK_RETRY`.
  */

package/dist/runtime/fleet/maintainer.js

@@ -101,7 +101,7 @@ const innermost = (error) => {
  * the two replays a batch whose recompute is idempotent. When no change is
  * waiting it rebuilds `building` and `stale` views a few tenants at a time.
  * A view whose recompute fails is marked stale with its error and skipped
- * until `durable fleet rebuild`, so it never stops the others. A slot that
+ * until `akter fleet rebuild`, so it never stops the others. A slot that
  * is missing, lost, or moved by anyone else marks every view stale. The
  * runner that cannot take the lock retries every `LOCK_RETRY`.
  */

package/dist/runtime/index.d.ts

@@ -21,6 +21,8 @@ export { ASSERTION_SKEW_MS, AssertionClaims, AssertionKey, AssertionKeySet, KeyR
 export type { AssertionOptions } from "../serve/assertion/verify.ts";
 export { actorErrorBody, closeCodeOf, statusOf } from "../protocol/wire.ts";
 export { Database } from "./layer.ts";
+export { App, AppLayerFailed } from "./app.ts";
+export type { AppActor, AppServices } from "./app.ts";
 export { Runner } from "./runner.ts";
 export type { SocketRunnerOptions } from "./runner.ts";
 export type { MutualTlsOptions } from "./peering/transport.ts";

package/dist/runtime/index.js

@@ -10,6 +10,7 @@ export const Auth = { none, make, jwt, assertion };
 export { ASSERTION_SKEW_MS, AssertionClaims, AssertionKey, AssertionKeySet, KeyRefreshClaims, MAX_ASSERTION_SECONDS, } from "../serve/assertion/verify.js";
 export { actorErrorBody, closeCodeOf, statusOf } from "../protocol/wire.js";
 export { Database } from "./layer.js";
+export { App, AppLayerFailed } from "./app.js";
 export { Runner } from "./runner.js";
 export { RunnerAuthority } from "./peering/authority.js";
 export { DataDirLocked, DataDirVersion } from "../errors/database.js";

package/dist/runtime/inspector/layer.d.ts

@@ -11,6 +11,10 @@ export interface InspectorOptions<R> {
     readonly auth: AuthProvider<R>;
     /** Prefix for every route. Default `"/inspector"`. */
     readonly basePath?: `/${string}`;
+    /** The name live reads give this runner, such as its host or task; null in them when unset. */
+    readonly runner?: string | undefined;
+    /** The region live reads say this runner serves; null in them when unset. */
+    readonly region?: string | undefined;
 }
 /**
  * Serves read-only JSON over the `durable` inspection views as routes on the
@@ -37,6 +41,22 @@ export interface InspectorOptions<R> {
  * - `GET /outbox`, `/jobs`, `/dead-letters?afterDeadAtMs&afterJobId`,
  *   `/workflows?status=open|all|running|suspended|finished|completed|failed&afterStartedAtMs&afterExecutionId`:
  *   tenant-wide lists; the paged ones answer the `next` cursor to pass back.
+ *
+ * Inside a runtime it also serves the schedules and this runner's own memory,
+ * each live answer naming the runner, its region, when it began recording and
+ * how many other runners the cluster lists:
+ *
+ * - `GET /schedules`: each declared cron entry with its pending ticks and last committed tick.
+ * - `GET /live/overview`: recent rates, resident activations and the deepest mailbox, by type.
+ * - `GET /live/activity?type&window`, `/live/latency?type&window`: one type's, or every type's,
+ *   committed turns over `1h`, `24h` (default) or `7d`.
+ * - `GET /live/actors?type&ids`: whether each named actor is resident, its
+ *   mailbox, sockets and feeds; `ids` is a JSON array of at most 100.
+ * - `GET /live/connections`: open sockets and SSE responses, by type.
+ * - `GET /commands/stream?type&outcome&after`: SSE of each command this runner
+ *   commits for the tenant, `id` its position, resuming after `after` while the
+ *   runner still holds it and sending `gap` when it does not, until the
+ *   credential expires.
  */
 declare const serve: <R = never>(options: InspectorOptions<R>) => import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter | SqlClient.SqlClient | Exclude<R, import("effect/Scope").Scope>>;
 /** The read-only inspector: `serve` mounts its routes. */