@tenetkit/pg 0.28.0

package/README.md

@@ -0,0 +1,3 @@
+# @tenetkit/pg
+
+PostgreSQL runtime backend for TenetKit.

package/dist/postgres/claims.d.ts

@@ -0,0 +1,26 @@
+import { Duration, Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { StaleClaim } from "tenetkit/runtime/driver/sql/errors";
+import type { ClaimedRun } from "tenetkit/runtime/driver/sql/run-claims";
+export interface ClaimOptions {
+    readonly workerId: string;
+    readonly limit: number;
+    readonly lease: Duration.Input;
+}
+export declare const claimReadyRuns: (options: ClaimOptions) => Effect.Effect<ClaimedRun[], import("tenetkit/runtime/driver/errors").RuntimeUnavailable | import("effect/unstable/sql/SqlError").SqlError, SqlClient.SqlClient>;
+export declare const refreshLease: (input: {
+    readonly runId: string;
+    readonly workerId: string;
+    readonly attemptFence: number;
+    readonly lease: Duration.Input;
+}) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, SqlClient.SqlClient>;
+export declare const requireClaim: (input: {
+    readonly runId: string;
+    readonly workerId: string;
+    readonly attemptFence: number;
+}) => Effect.Effect<import("tenetkit/runtime/driver/sql/rows").DecodedRun, import("tenetkit/runtime/driver/errors").RuntimeUnavailable | import("effect/unstable/sql/SqlError").SqlError | StaleClaim, SqlClient.SqlClient>;
+export declare const releaseClaim: (input: {
+    readonly runId: string;
+    readonly workerId: string;
+    readonly attemptFence: number;
+}) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient.SqlClient>;

package/dist/postgres/claims.js

@@ -0,0 +1,95 @@
+import { Clock, DateTime, Duration, Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { StaleClaim } from "tenetkit/runtime/driver/sql/errors";
+import { decodeRunEffect, loadRun } from "tenetkit/runtime/driver/sql/store-helpers";
+export const claimReadyRuns = (options) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const leaseMs = Duration.toMillis(options.lease);
+    const claimed = yield* sql `
+      WITH candidates AS (
+        SELECT r.run_id
+        FROM baton_runs r
+        WHERE r.status IN ('queued', 'running', 'cancelling')
+          AND r.cancellation_requested = FALSE
+          AND (
+            (r.parent_run_id IS NULL AND EXISTS (SELECT 1 FROM baton_lanes l WHERE l.head_run_id = r.run_id))
+            OR EXISTS (
+              SELECT 1 FROM baton_run_links link
+              WHERE link.child_run_id = r.run_id AND link.readiness = 'ready'
+            )
+          )
+          AND (
+            r.owner_worker_id IS NULL
+            OR r.lease_expires_at IS NULL
+            OR r.lease_expires_at < NOW()
+          )
+        ORDER BY r.accepted_sequence ASC
+        FOR UPDATE OF r SKIP LOCKED
+        LIMIT ${options.limit}
+      )
+      UPDATE baton_runs AS r
+      SET
+        owner_worker_id = ${options.workerId},
+        lease_expires_at = NOW() + (${leaseMs}::double precision * INTERVAL '1 millisecond'),
+        attempt_fence = r.attempt_fence + 1,
+        attempt = CASE
+          WHEN r.status = 'queued' THEN r.attempt + 1
+          ELSE r.attempt
+        END,
+        status = CASE
+          WHEN r.status = 'queued' THEN 'running'
+          ELSE r.status
+        END,
+        updated_at = NOW()
+      FROM candidates c
+      WHERE r.run_id = c.run_id
+      RETURNING r.*
+    `;
+    const out = [];
+    for (const row of claimed) {
+        const run = yield* decodeRunEffect(row);
+        out.push({
+            run,
+            workerId: options.workerId,
+            attemptFence: run.attemptFence,
+            leaseExpiresAt: DateTime.toDate(DateTime.makeUnsafe(run.leaseExpiresAt ?? (yield* Clock.currentTimeMillis))),
+        });
+    }
+    return out;
+});
+export const refreshLease = (input) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const leaseMs = Duration.toMillis(input.lease);
+    const rows = yield* sql `
+      UPDATE baton_runs
+      SET
+        lease_expires_at = NOW() + (${leaseMs}::double precision * INTERVAL '1 millisecond'),
+        updated_at = NOW()
+      WHERE run_id = ${input.runId}
+        AND owner_worker_id = ${input.workerId}
+        AND attempt_fence = ${input.attemptFence}
+        AND cancellation_requested = FALSE
+        AND status NOT IN ('succeeded', 'failed', 'cancelled')
+      RETURNING run_id
+    `;
+    return rows.length > 0;
+});
+export const requireClaim = (input) => Effect.gen(function* () {
+    const run = yield* loadRun(input.runId);
+    if (run === undefined)
+        return yield* StaleClaim.make(input);
+    if (run.ownerWorkerId !== input.workerId || run.attemptFence !== input.attemptFence) {
+        return yield* StaleClaim.make(input);
+    }
+    return run;
+});
+export const releaseClaim = (input) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `
+      UPDATE baton_runs
+      SET owner_worker_id = NULL, lease_expires_at = NULL, updated_at = NOW()
+      WHERE run_id = ${input.runId}
+        AND owner_worker_id = ${input.workerId}
+        AND attempt_fence = ${input.attemptFence}
+    `;
+});

package/dist/postgres/event-stream.d.ts

@@ -0,0 +1,20 @@
+import { Effect, Stream } from "effect";
+import type { PgClient } from "@effect/sql-pg";
+import type { Cursor } from "tenetkit/runtime/driver/cursor";
+import type { CursorExpired, RunNotFound, RuntimeUnavailable, SubscriberLagged } from "tenetkit/runtime/driver/errors";
+import type { RunEvent } from "tenetkit/runtime/driver/run-event";
+import type { EventHub } from "tenetkit/runtime/driver/sql/subscribers";
+type EventsError = CursorExpired | RunNotFound | RuntimeUnavailable | SubscriberLagged;
+export declare const makeEventStream: (input: {
+    readonly hub: EventHub;
+    readonly pg: PgClient.PgClient;
+    readonly runId: string;
+    readonly cursor: Cursor;
+    readonly capacity: number;
+    readonly loadReplay: Effect.Effect<{
+        readonly replay: ReadonlyArray<RunEvent>;
+        readonly lastSequence: number;
+    }, RunNotFound | RuntimeUnavailable>;
+    readonly loadAfter: (cursor: Cursor) => Effect.Effect<ReadonlyArray<RunEvent>, RunNotFound | RuntimeUnavailable>;
+}) => Stream.Stream<RunEvent, EventsError>;
+export {};

package/dist/postgres/event-stream.js

@@ -0,0 +1,16 @@
+import { Effect, Schedule, Stream, SynchronizedRef } from "effect";
+import { NOTIFY_CHANNEL } from "./schema.js";
+export const makeEventStream = (input) => Stream.unwrap(Effect.gen(function* () {
+    const cursor = yield* SynchronizedRef.make(input.cursor);
+    const catchUp = SynchronizedRef.modifyEffect(cursor, (current) => input.loadAfter(current).pipe(Effect.flatMap((events) => Effect.forEach(events, (event) => input.hub.publish(input.runId, event)).pipe(Effect.as(events.at(-1)?.sequence ?? current))), Effect.map((last) => [last, last]))).pipe(Effect.ignore);
+    return input.hub.subscribe({
+        runId: input.runId,
+        cursor: input.cursor,
+        loadReplay: input.loadReplay.pipe(Effect.tap(({ lastSequence }) => SynchronizedRef.set(cursor, lastSequence))),
+        capacity: input.capacity,
+        onSubscribed: Effect.gen(function* () {
+            yield* Effect.forkScoped(catchUp.pipe(Effect.repeat(Schedule.spaced("1 second")), Effect.ignore));
+            yield* input.pg.listen(NOTIFY_CHANNEL).pipe(Stream.runForEach((payload) => (payload !== input.runId ? Effect.void : catchUp)), Effect.ignore);
+        }),
+    });
+}));

package/dist/postgres/index.d.ts

@@ -0,0 +1,3 @@
+export { layerPostgres, type PostgresStoreOptions, type PostgresStoreError } from "./runtime-layer.js";
+export * as RunSchema from "./run-schema.js";
+export * from "tenetkit/runtime";

package/dist/postgres/index.js

@@ -0,0 +1,3 @@
+export { layerPostgres } from "./runtime-layer.js";
+export * as RunSchema from "./run-schema.js";
+export * from "tenetkit/runtime";

package/dist/postgres/locks.d.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { RunNotFound, RunTerminal } from "tenetkit/runtime/driver/errors";
+/**
+ * One Run-level lock serializing admission, steering, response, resume, timeout,
+ * cancellation, and terminal settlement. Always taken advisory-first, then row,
+ * so every writer acquires them in the same order.
+ */
+export declare const lockRun: (runId: string) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient.SqlClient>;
+export declare const lockRunHierarchy: (runId: string) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * One mailbox-level lock serializing admission into one target session's inbox.
+ *
+ * A mailbox entry takes the next sequence for its target, so concurrent senders must be serialized
+ * on the target rather than on any one sender's Run.
+ */
+export declare const lockMailbox: (targetSessionId: string) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, SqlClient.SqlClient>;
+export declare const lockSpawnParent: (runId: string) => Effect.Effect<import("tenetkit/runtime/driver/sql/rows").DecodedRun, RunNotFound | RunTerminal | import("tenetkit/runtime/driver/errors").RuntimeUnavailable | import("effect/unstable/sql/SqlError").SqlError, SqlClient.SqlClient>;

package/dist/postgres/locks.js

@@ -0,0 +1,51 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { RunNotFound, RunTerminal } from "tenetkit/runtime/driver/errors";
+import { isTerminal } from "tenetkit/runtime/driver/run";
+import { loadRun } from "./pg-helpers.js";
+/**
+ * One Run-level lock serializing admission, steering, response, resume, timeout,
+ * cancellation, and terminal settlement. Always taken advisory-first, then row,
+ * so every writer acquires them in the same order.
+ */
+export const lockRun = (runId) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `SELECT pg_advisory_xact_lock(hashtext(${`run:${runId}`}))`;
+    yield* sql `SELECT run_id FROM baton_runs WHERE run_id = ${runId} FOR UPDATE`;
+});
+export const lockRunHierarchy = (runId) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const hierarchy = [runId];
+    let current = runId;
+    while (true) {
+        const row = (yield* sql `
+        SELECT parent_run_id FROM baton_runs WHERE run_id = ${current}
+      `)[0];
+        if (row?.parent_run_id === null || row?.parent_run_id === undefined)
+            break;
+        hierarchy.push(row.parent_run_id);
+        current = row.parent_run_id;
+    }
+    for (const id of hierarchy.reverse())
+        yield* lockRun(id);
+});
+/**
+ * One mailbox-level lock serializing admission into one target session's inbox.
+ *
+ * A mailbox entry takes the next sequence for its target, so concurrent senders must be serialized
+ * on the target rather than on any one sender's Run.
+ */
+export const lockMailbox = (targetSessionId) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `SELECT pg_advisory_xact_lock(hashtext(${`mailbox:${targetSessionId}`}))`;
+}).pipe(Effect.asVoid);
+export const lockSpawnParent = (runId) => Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql `SELECT run_id FROM baton_runs WHERE run_id = ${runId} FOR UPDATE`;
+    const parent = yield* loadRun(runId);
+    if (parent === undefined)
+        return yield* RunNotFound.make({ runId });
+    if (isTerminal(parent.status))
+        return yield* RunTerminal.make({ runId, status: parent.status });
+    return parent;
+});

package/dist/postgres/pg-helpers.d.ts

@@ -0,0 +1,91 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { PgClient } from "@effect/sql-pg";
+import { type RunEvent } from "tenetkit/runtime/driver/run-event";
+import type { ExecutableManifest, ExecutableRef } from "tenetkit/runtime/driver/executable-manifest";
+import type { Message } from "tenetkit/runtime/driver/message";
+import { type RunStatus } from "tenetkit/runtime/driver/run";
+import { decodeMessage, decodeQueue, encodeQueue } from "tenetkit/runtime/driver/sql/codecs";
+import type { EventHub } from "tenetkit/runtime/driver/sql/subscribers";
+import type { DecodedRun } from "tenetkit/runtime/driver/sql/rows";
+import type { EmittableAgentLoopEvent } from "tenetkit/runtime/driver/agent-event";
+import { type ExecutionClaim } from "tenetkit/runtime/driver/run-store";
+import type { ExecutionResult } from "tenetkit/runtime/driver/execution-state";
+import { RunNotFound, RunTerminal, RuntimeUnavailable } from "tenetkit/runtime/driver/errors";
+import { StaleClaim } from "tenetkit/runtime/driver/sql/errors";
+type StoreError = RuntimeUnavailable | SqlError;
+type StoreEffect<A> = Effect.Effect<A, StoreError, SqlClient.SqlClient>;
+type SqlOnlyEffect<A> = Effect.Effect<A, SqlError, SqlClient.SqlClient>;
+type RunEventEffect = Effect.Effect<RunEvent, RuntimeUnavailable | SqlError, SqlClient.SqlClient>;
+type LaneEffect = Effect.Effect<{
+    acceptedSequence: number;
+    isHead: boolean;
+}, SqlError, SqlClient.SqlClient>;
+type AgentEventError = RunNotFound | RunTerminal | StoreError | StaleClaim;
+type AgentEventEffect = Effect.Effect<undefined, AgentEventError, SqlClient.SqlClient>;
+type CompleteRunEffect = Effect.Effect<undefined, RunTerminal | StoreError, SqlClient.SqlClient>;
+type SettleParentEffect = Effect.Effect<void, StoreError, SqlClient.SqlClient | PgClient.PgClient>;
+export type EventPartial = {
+    readonly _tag: string;
+} & Record<string, unknown>;
+export declare const loadRun: (runId: string) => Effect.Effect<DecodedRun | undefined, RuntimeUnavailable | SqlError, SqlClient.SqlClient>;
+export declare const requireRun: (runId: string) => Effect.Effect<DecodedRun, RunNotFound | RuntimeUnavailable | SqlError, SqlClient.SqlClient>;
+export declare const emitAgentEvent: {
+    (input: ExecutionClaim & {
+        readonly event: EmittableAgentLoopEvent;
+    }): (hub: EventHub) => AgentEventEffect;
+    (hub: EventHub, input: ExecutionClaim & {
+        readonly event: EmittableAgentLoopEvent;
+    }): AgentEventEffect;
+};
+export declare const loadEventsAfter: {
+    (cursor: number): (runId: string) => StoreEffect<RunEvent[]>;
+    (runId: string, cursor: number): StoreEffect<RunEvent[]>;
+};
+export declare const allocateSequence: (runId: string) => Effect.Effect<number, SqlError, SqlClient.SqlClient>;
+export declare const appendEvent: {
+    (run: DecodedRun, partial: EventPartial, nextStatus?: RunStatus): (hub: EventHub) => RunEventEffect;
+    (hub: EventHub, run: DecodedRun, partial: EventPartial, nextStatus?: RunStatus): RunEventEffect;
+};
+export declare const promoteHead: {
+    (address: string, sessionId: string): (hub: EventHub) => StoreEffect<void>;
+    (hub: EventHub, address: string, sessionId: string): StoreEffect<void>;
+};
+export declare const removeFromLane: {
+    (sessionId: string, runId: string): (address: string) => SqlOnlyEffect<void>;
+    (address: string, sessionId: string, runId: string): SqlOnlyEffect<void>;
+};
+export declare const afterTerminal: {
+    (run: DecodedRun): (hub: EventHub) => StoreEffect<void>;
+    (hub: EventHub, run: DecodedRun): StoreEffect<void>;
+};
+export declare const completeRun: {
+    (run: DecodedRun, result: ExecutionResult): (hub: EventHub) => CompleteRunEffect;
+    (hub: EventHub, run: DecodedRun, result: ExecutionResult): CompleteRunEffect;
+};
+export declare const settleParent: {
+    (child: DecodedRun, terminalEventId: string): (hub: EventHub) => SettleParentEffect;
+    (hub: EventHub, child: DecodedRun, terminalEventId: string): SettleParentEffect;
+};
+export declare const insertRun: (input: {
+    readonly runId: string;
+    readonly status: RunStatus;
+    readonly message: Message;
+    readonly digest: string;
+    readonly executableRef: ExecutableRef;
+    readonly executableManifest: ExecutableManifest;
+    readonly rootRunId: string;
+    readonly depth: number;
+    readonly treePolicy: import("tenetkit/runtime/driver/tree-policy").TreePolicy;
+    readonly parentRunId?: string;
+    readonly invocationId?: string;
+    readonly acceptedSequence: number;
+    readonly attempt?: number;
+}) => Effect.Effect<void, SqlError, SqlClient.SqlClient>;
+export declare const enqueueLane: {
+    (sessionId: string, runId: string): (address: string) => LaneEffect;
+    (address: string, sessionId: string, runId: string): LaneEffect;
+};
+export { toOperationRecord } from "tenetkit/runtime/driver/sql/operations";
+export { decodeMessage, encodeQueue, decodeQueue };