@rikalabs/akter 0.1.0-alpha.0

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

@@ -0,0 +1,711 @@
+import { Effect, Option, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import type * as Inspection from "../../protocol/inspection.ts";
+export type { Decoded } from "../../protocol/inspection.ts";
+/** Decodes a JSON `text` column such as a payload, caller, or outcome. */
+export declare const decodeText: (text: string | null) => Inspection.Decoded | null;
+/** Decodes a zstd-compressed JSON `bytea` column such as state, an event, or a step exit. */
+export declare const decodeBytes: (bytes: Uint8Array | null) => Inspection.Decoded | null;
+/** The widest page any list returns. */
+export declare const MAX_LIMIT = 500;
+/** Every read below is scoped to `tenant`, which comes from the authenticated principal only. */
+interface Page {
+    readonly tenant: string;
+    readonly limit: number;
+}
+/** The `(actor type, actor id)` pair that names an actor within a tenant. */
+type ActorIdentity = Pick<Inspection.ActorRow, "actorType" | "actorId">;
+/**
+ * Runs `effect` in a read-only snapshot that names `tenant`, so when
+ * row-level security owns the views they return no other tenant's rows,
+ * whatever a read's own filter says.
+ */
+export declare const readOnly: (tenant: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | import("effect/sql/SqlError").SqlError, R | SqlClient.SqlClient>;
+/** The view catalog and the tenant's row count in each view, from one snapshot. */
+export declare const overview: ({ tenant }: {
+    readonly tenant: string;
+}) => Effect.Effect<{
+    tenant: string;
+    views: readonly {
+        view: string;
+        version: number;
+    }[];
+    counts: {
+        readonly actors: number;
+        readonly receipts: number;
+        readonly events: number;
+        readonly outbox: number;
+        readonly timers: number;
+        readonly jobs: number;
+        readonly deadLetters: number;
+        readonly workflows: number;
+        readonly openWorkflows: number;
+    };
+    nextTimerDueAtMs: number | null;
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** One keyset page of actors, optionally of a single type or under an address prefix. */
+interface ActorsPage extends Page {
+    readonly actorType?: string | undefined;
+    /** Keeps only actors whose address, `type/id`, starts with it. */
+    readonly prefix?: string | undefined;
+    /** Keyset cursor: the last actor of the previous page. */
+    readonly after?: ActorIdentity | undefined;
+}
+/**
+ * The tenant's actors in `(actor_type, actor_id)` order, one page after `after`. The cursor
+ * comparison uses the same `C` collation as the ORDER BY, or a cursor could skip or repeat actors.
+ * A prefix that names a whole type, `type/` and more, matches that type's ids by their own prefix,
+ * so it reads one type rather than every actor of the tenant.
+ */
+export declare const actors: (page: ActorsPage) => Effect.Effect<{
+    actors: readonly {
+        readonly actorType: string;
+        readonly actorId: string;
+        readonly placement: string | null;
+        readonly generation: number;
+        readonly created: boolean;
+        readonly lastEventSequence: number;
+    }[];
+    next: {
+        actorType: string;
+        actorId: string;
+    } | null;
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+type ReceiptRow = Omit<Inspection.ReceiptRow, "callerKey" | "outcome" | "events"> & {
+    readonly callerKey: string;
+    readonly outcome: string;
+    readonly events: string | null;
+};
+/** The actor whose detail to read, with the row limit for each list in it. */
+interface ActorPage extends Page, ActorIdentity {
+}
+/**
+ * One actor as the inspector shows it, read through the actor's routing key:
+ * its generation, decoded state, newest receipts with the events each
+ * committed, newest events, pending outbox rows and jobs, dead letters, and
+ * workflow executions with their recorded steps. `None` when the tenant has
+ * no such actor. Every runtime index leads with `routing_key`, so each read is
+ * a key lookup, and the steps read for the same page of executions give each
+ * listed execution all its steps.
+ */
+export declare const actor: (page: ActorPage) => Effect.Effect<Option.None<{
+    actor: {
+        actorType: string;
+        actorId: string;
+        placement: string | null;
+        generation: number;
+        created: boolean;
+        lastEventSequence: number;
+    };
+    state: {
+        key: string;
+        bytes: number;
+        value: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    receipts: (Omit<ReceiptRow, "callerKey" | "events" | "outcome"> & {
+        callerKey: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        outcome: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        events: number[];
+    })[];
+    events: {
+        sequence: number;
+        event: string;
+        commandId: string | null;
+        bytes: number;
+        emittedAtMs: number;
+        value: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    outbox: {
+        actorType: string;
+        actorId: string;
+        intentId: string;
+        timerKey: string | null;
+        targetType: string;
+        targetId: string;
+        command: string;
+        attempts: number;
+        lastError: string | null;
+        dueAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    jobs: {
+        actorType: string;
+        actorId: string;
+        jobId: string;
+        job: string;
+        attempts: number;
+        lastError: string | null;
+        ambiguous: boolean;
+        dueAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    deadLetters: {
+        actorType: string;
+        actorId: string;
+        jobId: string;
+        job: string;
+        attempts: number;
+        cause: string;
+        ambiguous: boolean;
+        deadAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    workflows: {
+        actorType: string;
+        actorId: string;
+        executionId: string;
+        workflow: string;
+        workflowKey: string;
+        manifestHash: string;
+        status: string;
+        interrupt: boolean;
+        payloadBytes: number;
+        resultBytes: number | null;
+        startedAtMs: number;
+        finishedAtMs: number | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        result: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        steps: {
+            step: string;
+            attempt: number;
+            kind: string;
+            exit: {
+                readonly json: Schema.Json;
+            } | {
+                readonly undecodable: string;
+            } | null;
+            waitEvent: string | null;
+            version: number | null;
+            dueAtMs: number | null;
+            startedAtMs: number;
+            settledAtMs: number | null;
+        }[];
+    }[];
+    totals: {
+        readonly receipts: number;
+        readonly events: number;
+        readonly outbox: number;
+        readonly jobs: number;
+        readonly deadLetters: number;
+        readonly workflows: number;
+    };
+}> | Option.Some<{
+    actor: {
+        actorType: string;
+        actorId: string;
+        placement: string | null;
+        generation: number;
+        created: boolean;
+        lastEventSequence: number;
+    };
+    state: {
+        key: string;
+        bytes: number;
+        value: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    receipts: (Omit<ReceiptRow, "callerKey" | "events" | "outcome"> & {
+        callerKey: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        outcome: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        events: number[];
+    })[];
+    events: {
+        sequence: number;
+        event: string;
+        commandId: string | null;
+        bytes: number;
+        emittedAtMs: number;
+        value: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    outbox: {
+        actorType: string;
+        actorId: string;
+        intentId: string;
+        timerKey: string | null;
+        targetType: string;
+        targetId: string;
+        command: string;
+        attempts: number;
+        lastError: string | null;
+        dueAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    jobs: {
+        actorType: string;
+        actorId: string;
+        jobId: string;
+        job: string;
+        attempts: number;
+        lastError: string | null;
+        ambiguous: boolean;
+        dueAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    deadLetters: {
+        actorType: string;
+        actorId: string;
+        jobId: string;
+        job: string;
+        attempts: number;
+        cause: string;
+        ambiguous: boolean;
+        deadAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    workflows: {
+        actorType: string;
+        actorId: string;
+        executionId: string;
+        workflow: string;
+        workflowKey: string;
+        manifestHash: string;
+        status: string;
+        interrupt: boolean;
+        payloadBytes: number;
+        resultBytes: number | null;
+        startedAtMs: number;
+        finishedAtMs: number | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        result: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        steps: {
+            step: string;
+            attempt: number;
+            kind: string;
+            exit: {
+                readonly json: Schema.Json;
+            } | {
+                readonly undecodable: string;
+            } | null;
+            waitEvent: string | null;
+            version: number | null;
+            dueAtMs: number | null;
+            startedAtMs: number;
+            settledAtMs: number | null;
+        }[];
+    }[];
+    totals: {
+        readonly receipts: number;
+        readonly events: number;
+        readonly outbox: number;
+        readonly jobs: number;
+        readonly deadLetters: number;
+        readonly workflows: number;
+    };
+}>, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** The tenant's pending intents and timers, soonest first. */
+export declare const outbox: ({ tenant, limit }: Page) => Effect.Effect<{
+    outbox: {
+        actorType: string;
+        actorId: string;
+        intentId: string;
+        timerKey: string | null;
+        targetType: string;
+        targetId: string;
+        command: string;
+        attempts: number;
+        lastError: string | null;
+        dueAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** The tenant's enqueued jobs not yet settled, soonest first. */
+export declare const jobs: ({ tenant, limit }: Page) => Effect.Effect<{
+    jobs: {
+        actorType: string;
+        actorId: string;
+        jobId: string;
+        job: string;
+        attempts: number;
+        lastError: string | null;
+        ambiguous: boolean;
+        dueAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** A tenant-wide keyset page of dead letters. */
+interface DeadLettersPage extends Page {
+    /** Keyset cursor: the last dead letter of the previous page. */
+    readonly after?: {
+        readonly deadAtMs: number;
+        readonly jobId: string;
+    } | undefined;
+}
+/** The tenant's dead letters, newest first, one page after `after`. */
+export declare const deadLetters: ({ tenant, limit, after }: DeadLettersPage) => Effect.Effect<{
+    deadLetters: {
+        actorType: string;
+        actorId: string;
+        jobId: string;
+        job: string;
+        attempts: number;
+        cause: string;
+        ambiguous: boolean;
+        deadAtMs: number;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    next: {
+        deadAtMs: number;
+        jobId: string;
+    } | null;
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** A tenant-wide keyset page of workflow executions. */
+interface WorkflowsPage extends Page {
+    /**
+     * `open` is every execution not yet finished; `running`, `suspended` and
+     * `finished` name one stored status; `completed` and `failed` are finished
+     * executions whose result is, or is not, a success.
+     */
+    readonly status: "open" | "all" | "running" | "suspended" | "finished" | "completed" | "failed";
+    /** Keyset cursor: the last execution of the previous page. */
+    readonly after?: {
+        readonly startedAtMs: number;
+        readonly executionId: string;
+    } | undefined;
+}
+/**
+ * The tenant's workflow executions, newest first, one page after `after`, each
+ * with its recorded steps. The steps are read for the same page of executions,
+ * so each listed execution has all its steps. A finished execution's result
+ * is compressed, so `completed` and `failed` read finished executions
+ * `MAX_LIMIT` at a time and keep those whose result matches until the page is
+ * full; a result that does not decode matches neither.
+ */
+export declare const workflows: ({ tenant, limit, status, after }: WorkflowsPage) => Effect.Effect<{
+    workflows: {
+        actorType: string;
+        actorId: string;
+        executionId: string;
+        workflow: string;
+        workflowKey: string;
+        manifestHash: string;
+        status: string;
+        interrupt: boolean;
+        payloadBytes: number;
+        resultBytes: number | null;
+        startedAtMs: number;
+        finishedAtMs: number | null;
+        caller: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        payload: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        result: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        steps: {
+            step: string;
+            attempt: number;
+            kind: string;
+            exit: {
+                readonly json: Schema.Json;
+            } | {
+                readonly undecodable: string;
+            } | null;
+            waitEvent: string | null;
+            version: number | null;
+            dueAtMs: number | null;
+            startedAtMs: number;
+            settledAtMs: number | null;
+        }[];
+    }[];
+    next: {
+        startedAtMs: number;
+        executionId: string;
+    } | null;
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** A keyset page of names, optionally one name only or those starting with a prefix. */
+interface NamesPage extends Page {
+    /** Reads only this name. */
+    readonly name?: string | undefined;
+    /** Reads only names starting with it. */
+    readonly prefix?: string | undefined;
+    /** Keyset cursor: the last name of the previous page. */
+    readonly after?: string | undefined;
+}
+/** The tenant's actor types by name, each with how many actors it has, one page after `after`. */
+export declare const actorTypes: ({ tenant, limit, name, prefix, after }: NamesPage) => Effect.Effect<{
+    actorTypes: {
+        readonly actorType: string;
+        readonly actors: number;
+    }[];
+    next: string | null;
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * The tenant's job names, each with its pending jobs split by whether an
+ * attempt has failed, and its dead letters, one page after `after`.
+ */
+export declare const jobTypes: ({ tenant, limit, after }: NamesPage) => Effect.Effect<{
+    jobTypes: {
+        readonly job: string;
+        readonly queued: number;
+        readonly retrying: number;
+        readonly deadLetters: number;
+    }[];
+    next: string | null;
+}, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** A keyset page of receipts: one actor's, one type's or the whole tenant's. */
+interface ReceiptsPage extends Page {
+    readonly actorType?: string | undefined;
+    /** Reads one actor, of `actorType`. */
+    readonly actorId?: string | undefined;
+    readonly outcomeTag?: "Success" | "Failure" | undefined;
+    /** Keyset cursor: the last receipt of the previous page. */
+    readonly after?: (ActorIdentity & {
+        readonly expiresAtMs: number;
+        readonly commandId: string;
+    }) | undefined;
+}
+type TenantReceiptRow = ReceiptRow & ActorIdentity;
+/**
+ * Receipts, the latest expiry first, one page after `after`, each with the
+ * events it committed. A receipt's expiry is the one its command id carries,
+ * so this is the order the command ids were issued in, not the order the
+ * turns committed. `None` when the page names one actor the tenant does not
+ * have.
+ */
+export declare const receipts: (page: ReceiptsPage) => Effect.Effect<Option.None<{
+    receipts: (Omit<TenantReceiptRow, "callerKey" | "events" | "outcome"> & {
+        callerKey: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        outcome: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        events: number[];
+    })[];
+    next: {
+        actorType: string;
+        actorId: string;
+        expiresAtMs: number;
+        commandId: string;
+    } | null;
+}> | Option.Some<{
+    receipts: (Omit<TenantReceiptRow, "callerKey" | "events" | "outcome"> & {
+        callerKey: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        outcome: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+        events: number[];
+    })[];
+    next: {
+        actorType: string;
+        actorId: string;
+        expiresAtMs: number;
+        commandId: string;
+    } | null;
+}>, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** A keyset page of one actor's event names. */
+interface LatestEventsPage extends ActorPage {
+    /** Keyset cursor: the last event name of the previous page. */
+    readonly after?: string | undefined;
+}
+/**
+ * The newest retained event of each name one actor emitted, by name, one page
+ * after `after`. `None` when the tenant has no such actor.
+ */
+export declare const latestEvents: (page: LatestEventsPage) => Effect.Effect<Option.None<{
+    events: {
+        readonly event: string;
+        readonly sequence: number;
+        readonly emittedAtMs: number;
+    }[];
+    next: string | null;
+}> | Option.Some<{
+    events: {
+        readonly event: string;
+        readonly sequence: number;
+        readonly emittedAtMs: number;
+    }[];
+    next: string | null;
+}>, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** A keyset page of one actor's timeline. */
+interface TimelinePage extends ActorPage {
+    /** Keyset cursor: the last entry of the previous page. */
+    readonly before?: {
+        readonly sequence: number;
+        readonly kind: "command" | "event";
+    } | undefined;
+}
+/**
+ * One actor's timeline, newest first, one page after `before`: every retained
+ * event at its emission time, and every retained receipt whose turn emitted
+ * events, at that turn's emission time and placed after its own events. A
+ * receipt whose turn emitted nothing has no recorded time, so it is not on the
+ * timeline. Event sequences only grow, so they order the timeline exactly.
+ * `None` when the tenant has no such actor.
+ */
+export declare const timeline: (page: TimelinePage) => Effect.Effect<Option.None<{
+    entries: {
+        kind: "command" | "event";
+        sequence: number;
+        name: string;
+        commandId: string;
+        atMs: number;
+        callerKey: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    next: {
+        sequence: number;
+        kind: "command" | "event";
+    } | null;
+}> | Option.Some<{
+    entries: {
+        kind: "command" | "event";
+        sequence: number;
+        name: string;
+        commandId: string;
+        atMs: number;
+        callerKey: {
+            readonly json: Schema.Json;
+        } | {
+            readonly undecodable: string;
+        } | null;
+    }[];
+    next: {
+        sequence: number;
+        kind: "command" | "event";
+    } | null;
+}>, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;