akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/service/predefinedAdaptor/solidCache.adaptor.ts

@@ -1,6 +1,6 @@
 import type { Database } from "bun:sqlite";
 import { adapt } from "../adapt";
-import type { CacheAdaptor, CacheSetOptions } from "./cache.adaptor";
+import type { CacheAdaptor, CacheSetOptions, CacheValue } from "./cache.adaptor";
 import {
   decodeSolidValue,
   encodeSolidValue,
@@ -61,7 +61,7 @@ export class SolidCache
     this.#db?.close();
   }
 
-  async set(topic: string, key: string, value: string | number | Buffer, option: CacheSetOptions = {}) {
+  async set(topic: string, key: string, value: CacheValue, option: CacheSetOptions = {}) {
     const encoded = encodeSolidValue(value);
     const now = Date.now();
     this.#db
@@ -77,7 +77,7 @@ export class SolidCache
       .run(topic, key, encoded.value, encoded.type, toEpochMs(option.expireAt), now, now);
   }
 
-  async get<T extends string | number | Buffer>(topic: string, key: string): Promise<T | undefined> {
+  async get<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined> {
     const row = this.#db
       .query(`SELECT "value", "valueType", "expiresAt" FROM "_akan_solid_cache" WHERE "topic" = ? AND "key" = ?`)
       .get(topic, key) as CacheRow | null;
@@ -93,13 +93,88 @@ export class SolidCache
     this.#db.query(`DELETE FROM "_akan_solid_cache" WHERE "topic" = ? AND "key" = ?`).run(topic, key);
   }
 
-  async hset(
-    topic: string,
-    key: string,
-    subKey: string,
-    value: string | number | Buffer,
-    option: CacheSetOptions = {},
-  ) {
+  async getDel<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined> {
+    const row = this.#db
+      .query(
+        `DELETE FROM "_akan_solid_cache" WHERE "topic" = ? AND "key" = ? RETURNING "value", "valueType", "expiresAt"`,
+      )
+      .get(topic, key) as CacheRow | null;
+    if (!row || (row.expiresAt !== null && row.expiresAt <= Date.now())) return undefined;
+    return decodeSolidValue<T>(row.valueType, row.value);
+  }
+
+  async setIfAbsent(topic: string, key: string, value: CacheValue, option: CacheSetOptions = {}) {
+    const encoded = encodeSolidValue(value);
+    const now = Date.now();
+    const { changes } = this.#db
+      .query(
+        `INSERT INTO "_akan_solid_cache" ("topic", "key", "value", "valueType", "expiresAt", "createdAt", "updatedAt")
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?6)
+         ON CONFLICT("topic", "key") DO UPDATE SET
+          "value" = excluded."value",
+          "valueType" = excluded."valueType",
+          "expiresAt" = excluded."expiresAt",
+          "createdAt" = excluded."createdAt",
+          "updatedAt" = excluded."updatedAt"
+         WHERE "expiresAt" IS NOT NULL AND "expiresAt" <= ?6`,
+      )
+      .run(topic, key, encoded.value, encoded.type, toEpochMs(option.expireAt), now);
+    return changes > 0;
+  }
+
+  async incr(topic: string, key: string, by = 1, option: CacheSetOptions = {}) {
+    const now = Date.now();
+    const live = `"expiresAt" IS NULL OR "expiresAt" > ?5`;
+    const row = this.#db
+      .query(
+        `INSERT INTO "_akan_solid_cache" ("topic", "key", "value", "valueType", "expiresAt", "createdAt", "updatedAt")
+         VALUES (?1, ?2, CAST(?3 AS TEXT), 'number', ?4, ?5, ?5)
+         ON CONFLICT("topic", "key") DO UPDATE SET
+          "value" = CASE WHEN ${live} THEN CAST(CAST("value" AS TEXT) + ?3 AS TEXT) ELSE excluded."value" END,
+          "valueType" = 'number',
+          "expiresAt" = CASE WHEN ${live} THEN "expiresAt" ELSE excluded."expiresAt" END,
+          "updatedAt" = ?5
+         RETURNING "value"`,
+      )
+      .get(topic, key, by, toEpochMs(option.expireAt), now) as { value: string } | null;
+    return Number(row?.value);
+  }
+
+  async acquireLease(topic: string, key: string, owner: string, ttlMs: number) {
+    const now = Date.now();
+    const { changes } = this.#db
+      .query(
+        `INSERT INTO "_akan_solid_cache" ("topic", "key", "value", "valueType", "expiresAt", "createdAt", "updatedAt")
+         VALUES (?1, ?2, ?3, 'string', ?4, ?5, ?5)
+         ON CONFLICT("topic", "key") DO UPDATE SET
+          "value" = excluded."value",
+          "valueType" = 'string',
+          "expiresAt" = excluded."expiresAt",
+          "updatedAt" = excluded."updatedAt"
+         WHERE "value" = excluded."value" OR ("expiresAt" IS NOT NULL AND "expiresAt" <= ?5)`,
+      )
+      .run(topic, key, owner, now + ttlMs, now);
+    return changes > 0;
+  }
+
+  async renewLease(topic: string, key: string, owner: string, ttlMs: number) {
+    const now = Date.now();
+    const { changes } = this.#db
+      .query(
+        `UPDATE "_akan_solid_cache" SET "expiresAt" = ?1, "updatedAt" = ?2
+         WHERE "topic" = ?3 AND "key" = ?4 AND "value" = ?5 AND ("expiresAt" IS NULL OR "expiresAt" > ?2)`,
+      )
+      .run(now + ttlMs, now, topic, key, owner);
+    return changes > 0;
+  }
+
+  async releaseLease(topic: string, key: string, owner: string) {
+    this.#db
+      .query(`DELETE FROM "_akan_solid_cache" WHERE "topic" = ? AND "key" = ? AND "value" = ?`)
+      .run(topic, key, owner);
+  }
+
+  async hset(topic: string, key: string, subKey: string, value: CacheValue, option: CacheSetOptions = {}) {
     const encoded = encodeSolidValue(value);
     const now = Date.now();
     this.#db
@@ -115,7 +190,7 @@ export class SolidCache
       .run(topic, key, subKey, encoded.value, encoded.type, toEpochMs(option.expireAt), now, now);
   }
 
-  async hget<T extends string | number | Buffer>(topic: string, key: string, subKey: string): Promise<T | undefined> {
+  async hget<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined> {
     const row = this.#db
       .query(
         `SELECT "value", "valueType", "expiresAt" FROM "_akan_solid_cache_hash" WHERE "topic" = ? AND "key" = ? AND "subKey" = ?`,
@@ -143,7 +218,7 @@ export class SolidCache
     return rows.map((row) => row.subKey);
   }
 
-  async hentries<T extends string | number | Buffer>(topic: string, key: string): Promise<[string, T][]> {
+  async hentries<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<[string, T][]> {
     this.#cleanup();
     const rows = this.#db
       .query(
@@ -157,6 +232,54 @@ export class SolidCache
     this.#db.query(`DELETE FROM "_akan_solid_cache_hash" WHERE "topic" = ? AND "key" = ?`).run(topic, key);
   }
 
+  async hgetDel<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined> {
+    const row = this.#db
+      .query(
+        `DELETE FROM "_akan_solid_cache_hash" WHERE "topic" = ? AND "key" = ? AND "subKey" = ?
+         RETURNING "value", "valueType", "expiresAt"`,
+      )
+      .get(topic, key, subKey) as CacheRow | null;
+    if (!row || (row.expiresAt !== null && row.expiresAt <= Date.now())) return undefined;
+    return decodeSolidValue<T>(row.valueType, row.value);
+  }
+
+  async hsetIfAbsent(topic: string, key: string, subKey: string, value: CacheValue, option: CacheSetOptions = {}) {
+    const encoded = encodeSolidValue(value);
+    const now = Date.now();
+    const { changes } = this.#db
+      .query(
+        `INSERT INTO "_akan_solid_cache_hash" ("topic", "key", "subKey", "value", "valueType", "expiresAt", "createdAt", "updatedAt")
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?7)
+         ON CONFLICT("topic", "key", "subKey") DO UPDATE SET
+          "value" = excluded."value",
+          "valueType" = excluded."valueType",
+          "expiresAt" = excluded."expiresAt",
+          "createdAt" = excluded."createdAt",
+          "updatedAt" = excluded."updatedAt"
+         WHERE "expiresAt" IS NOT NULL AND "expiresAt" <= ?7`,
+      )
+      .run(topic, key, subKey, encoded.value, encoded.type, toEpochMs(option.expireAt), now);
+    return changes > 0;
+  }
+
+  async hincr(topic: string, key: string, subKey: string, by = 1, option: CacheSetOptions = {}) {
+    const now = Date.now();
+    const live = `"expiresAt" IS NULL OR "expiresAt" > ?6`;
+    const row = this.#db
+      .query(
+        `INSERT INTO "_akan_solid_cache_hash" ("topic", "key", "subKey", "value", "valueType", "expiresAt", "createdAt", "updatedAt")
+         VALUES (?1, ?2, ?3, CAST(?4 AS TEXT), 'number', ?5, ?6, ?6)
+         ON CONFLICT("topic", "key", "subKey") DO UPDATE SET
+          "value" = CASE WHEN ${live} THEN CAST(CAST("value" AS TEXT) + ?4 AS TEXT) ELSE excluded."value" END,
+          "valueType" = 'number',
+          "expiresAt" = CASE WHEN ${live} THEN "expiresAt" ELSE excluded."expiresAt" END,
+          "updatedAt" = ?6
+         RETURNING "value"`,
+      )
+      .get(topic, key, subKey, by, toEpochMs(option.expireAt), now) as { value: string } | null;
+    return Number(row?.value);
+  }
+
   #cleanup() {
     const now = Date.now();
     this.#db.query(`DELETE FROM "_akan_solid_cache" WHERE "expiresAt" IS NOT NULL AND "expiresAt" <= ?`).run(now);

package/service/predefinedAdaptor/solidPubsub.adaptor.ts

@@ -1,12 +1,15 @@
-import type { BaseEnv, Cls } from "akanjs/base";
+import { getEnv } from "akanjs/base";
 import { adapt } from "../adapt";
 import { sendAkanIpc } from "../ipcTypes";
-import type { WebsocketAdaptor, WsRedisEventHandler, WsSocketData } from "./websocket.adaptor";
+import type {
+  LiveChange,
+  LiveChangeHandler,
+  WebsocketAdaptor,
+  WsRedisEventHandler,
+  WsSocketData,
+} from "./websocket.adaptor";
 
-/**
- * `AppWsData` mints the id at the handshake, so this reads it; the fallback only covers a socket that
- * was upgraded outside the app router, where nothing else would have given it one.
- */
+/** `AppWsData` mints the id at the handshake; the fallback covers a socket upgraded outside the app router. */
 const getSocketId = (ws: Bun.ServerWebSocket<unknown>) => {
   const data = ws.data as WsSocketData;
   data.socketId ??= Bun.randomUUIDv7();
@@ -15,23 +18,27 @@ const getSocketId = (ws: Bun.ServerWebSocket<unknown>) => {
 
 export class SolidPubSub
   extends adapt("solidPubsub", ({ env }) => ({
-    serverId: env(
-      ({ appName, environment, operationMode }: BaseEnv) =>
-        `${appName}-${environment}-${operationMode}-${process.env.AKAN_REPLICA_IDX ?? "0"}-${process.pid}`,
-    ),
+    serverId: env(() => {
+      const { appName, environment, operationMode } = getEnv();
+      return `${appName}-${environment}-${operationMode}-${process.env.AKAN_REPLICA_IDX ?? "0"}-${process.pid}`;
+    }),
   }))
   implements WebsocketAdaptor
 {
-  readonly #endpointMap = new Map<string, { returnRef: Cls; arrDepth: number }>();
   readonly #socketRooms = new Map<string, Set<string>>();
   #eventHandler: WsRedisEventHandler | null = null;
+  #changeHandler: LiveChangeHandler | null = null;
   readonly #messageHandler = (message: unknown) => {
     if (!message || typeof message !== "object") return;
-    const data = message as { type?: string; roomId?: string; data?: unknown; origin?: string };
+    const data = message as { type?: string; roomId?: string; data?: unknown; origin?: string; change?: LiveChange };
     if (data.type === "pubsub.deliver" && data.roomId && data.origin !== this.serverId) {
       this.#eventHandler?.(data.roomId, data.data);
       return;
     }
+    if (data.type === "live.change" && data.change && data.origin !== this.serverId) {
+      this.#changeHandler?.(data.change);
+      return;
+    }
     if (data.type === "pubsub.snapshot.request") {
       sendAkanIpc({
         type: "pubsub.snapshot",
@@ -48,6 +55,7 @@ export class SolidPubSub
   override async onDestroy() {
     process.off("message", this.#messageHandler);
     this.#eventHandler = null;
+    this.#changeHandler = null;
     this.#socketRooms.clear();
   }
 
@@ -55,6 +63,14 @@ export class SolidPubSub
     sendAkanIpc({ type: "pubsub.publish", roomId, data: data as object | object[], origin: this.serverId });
   }
 
+  publishChange(change: LiveChange): void {
+    sendAkanIpc({ type: "live.change", change, origin: this.serverId });
+  }
+
+  onChange(handler: LiveChangeHandler): void {
+    this.#changeHandler = handler;
+  }
+
   setEventHandler(handler: WsRedisEventHandler): void {
     this.#eventHandler = handler;
   }
@@ -63,10 +79,6 @@ export class SolidPubSub
     this.#eventHandler = null;
   }
 
-  registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void {
-    this.#endpointMap.set(key, { returnRef, arrDepth });
-  }
-
   async joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void> {
     const socketId = getSocketId(ws);
     const rooms = this.#socketRooms.get(socketId) ?? new Set<string>();

package/service/predefinedAdaptor/solidQueue.adaptor.ts

@@ -68,6 +68,8 @@ export class SolidQueue
   #db!: Database;
   #workers = new Map<string, SolidWorker>();
   #claimStmt!: Statement;
+  #cleanupTimer: Timer | null = null;
+  #closed = false;
   readonly #messageHandler = (message: unknown) => {
     if (!message || typeof message !== "object") return;
     if ((message as { type?: string }).type === "queue.wake") this.wake((message as { name?: string }).name);
@@ -107,13 +109,23 @@ export class SolidQueue
           "status" = 'pending'
           OR ("status" = 'running' AND "lockedUntil" IS NOT NULL AND "lockedUntil" <= ?)
          )
-       ORDER BY "priority" DESC, "createdAt" ASC
+       ORDER BY "priority" ASC, "createdAt" ASC
        LIMIT 1`,
     );
     process.on("message", this.#messageHandler);
+    this.#cleanupTimer = setInterval(() => this.#startCleanup(), this.config.cleanupIntervalMs);
+    this.#startCleanup();
+  }
+
+  #startCleanup() {
+    void this.#cleanup().catch((error: unknown) => {
+      this.logger.warn(`Solid job cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
   }
 
   override async onDestroy() {
+    this.#closed = true;
+    if (this.#cleanupTimer) clearInterval(this.#cleanupTimer);
     process.off("message", this.#messageHandler);
     await Promise.all([...this.#workers.values()].map((worker) => worker.close()));
     this.#db?.run("PRAGMA wal_checkpoint(TRUNCATE)");
@@ -176,18 +188,14 @@ export class SolidQueue
   async runJob(job: AkanJob, handler: (job: AkanJob) => Promise<unknown>) {
     try {
       await handler({ ...job, data: job.data });
-      this.#db
-        .query(
-          `UPDATE "_akan_solid_jobs" SET "status" = 'completed', "lockedBy" = NULL, "lockedUntil" = NULL, "updatedAt" = ? WHERE "id" = ?`,
-        )
-        .run(Date.now(), job.id);
+      this.#settle(job, "completed", job.opts?.removeOnComplete ?? true);
     } catch (error) {
       const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
       const row = this.#db
         .query(`SELECT "attempts", "maxAttempts" FROM "_akan_solid_jobs" WHERE "id" = ?`)
         .get(job.id) as { attempts: number; maxAttempts: number } | null;
       const failed = !row || row.attempts >= row.maxAttempts;
-      const delay = this.#getBackoffDelay(job.opts?.backoff);
+      const delay = this.#getBackoffDelay(job.opts?.backoff, row?.attempts ?? 1);
       this.#db
         .query(
           `UPDATE "_akan_solid_jobs"
@@ -195,13 +203,56 @@ export class SolidQueue
            WHERE "id" = ?`,
         )
         .run(failed ? "failed" : "pending", Date.now() + delay, message, Date.now(), job.id);
-      if (failed) this.logger.error(`Solid job failed ${job.name}/${job.id}: ${message}`);
+      if (!failed) return;
+      this.logger.error(`Solid job failed ${job.name}/${job.id}: ${message}`);
+      this.#settle(job, "failed", job.opts?.removeOnFail ?? false);
+    }
+  }
+
+  #settle(job: AkanJob, status: "completed" | "failed", remove: boolean | number) {
+    if (remove === true) {
+      this.#db.query(`DELETE FROM "_akan_solid_jobs" WHERE "id" = ?`).run(job.id);
+      return;
+    }
+    if (status === "completed")
+      this.#db
+        .query(
+          `UPDATE "_akan_solid_jobs" SET "status" = 'completed', "lockedBy" = NULL, "lockedUntil" = NULL, "updatedAt" = ? WHERE "id" = ?`,
+        )
+        .run(Date.now(), job.id);
+    if (typeof remove !== "number") return;
+    this.#db
+      .query(
+        `DELETE FROM "_akan_solid_jobs" WHERE "id" IN (
+           SELECT "id" FROM "_akan_solid_jobs" WHERE "queue" = ? AND "name" = ? AND "status" = ?
+           ORDER BY "updatedAt" DESC LIMIT -1 OFFSET ?
+         )`,
+      )
+      .run(this.queueName, job.name, status, Math.max(0, Math.floor(remove)));
+  }
+
+  async #cleanup() {
+    const expiredFailedAt = Date.now() - this.config.queueFailedRetentionMs;
+    for (let batch = 0; batch < 10 && !this.#closed; batch++) {
+      const { changes } = this.#db
+        .query(
+          `DELETE FROM "_akan_solid_jobs" WHERE rowid IN (
+             SELECT rowid FROM "_akan_solid_jobs"
+             WHERE ("status" = 'completed' AND COALESCE(json_type("payload", '$.opts.removeOnComplete'), 'true') = 'true')
+                OR ("status" = 'failed' AND "updatedAt" < ? AND COALESCE(json_type("payload", '$.opts.removeOnFail'), 'null') <> 'false')
+             LIMIT 1000
+           )`,
+        )
+        .run(expiredFailedAt);
+      if (changes < 1000) return;
+      await new Promise((resolve) => setTimeout(resolve, 0));
     }
   }
 
-  #getBackoffDelay(backoff: AkanJobOptions["backoff"]) {
+  #getBackoffDelay(backoff: AkanJobOptions["backoff"], attemptsMade: number) {
     if (!backoff) return 0;
     if (typeof backoff === "number") return backoff;
-    return Number(backoff.delay ?? 0);
+    const delay = Number(backoff.delay ?? 0);
+    return backoff.type === "exponential" ? Math.round(2 ** (attemptsMade - 1) * delay) : delay;
   }
 }

package/service/predefinedAdaptor/solidSqlite.ts

@@ -1,8 +1,8 @@
 import { Database } from "bun:sqlite";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { type Dayjs, getEnv } from "akanjs/base";
-import { resolveDefaultSqliteFile } from "./sqlitePath";
+import type { Dayjs } from "akanjs/base";
+import { defaultSqliteFile } from "./sqlitePath";
 
 export interface SolidConfig {
   filePath?: string;
@@ -12,6 +12,7 @@ export interface SolidConfig {
   cleanupIntervalMs?: number;
   queuePollIntervalMs?: number;
   queueLeaseMs?: number;
+  queueFailedRetentionMs?: number;
 }
 
 export interface SolidEnv {
@@ -23,31 +24,23 @@ export type SolidValueType = "string" | "number" | "buffer" | "json";
 
 const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-const defaultSolidFile = (workspaceRoot?: string) => {
-  const { appName, environment, operationMode } = getEnv();
-  return resolveDefaultSqliteFile({
-    appName,
-    fileName: `${appName}-${environment}_solid.db`,
-    isProduction: process.env.NODE_ENV === "production",
-    operationMode,
-    workspaceRoot,
-  });
-};
-
 export const getSolidConfig = (env: SolidEnv): Required<SolidConfig> => {
   return {
-    filePath: env.solid?.filePath ?? process.env.AKAN_SOLID_DB_PATH ?? defaultSolidFile(env.workspaceRoot),
+    
+    filePath: process.env.AKAN_SOLID_DB_PATH ?? env.solid?.filePath ?? defaultSqliteFile("_solid", env.workspaceRoot),
     journalMode: env.solid?.journalMode ?? "WAL",
     busyTimeoutMs: env.solid?.busyTimeoutMs ?? 5000,
     synchronous: env.solid?.synchronous ?? "NORMAL",
     cleanupIntervalMs: env.solid?.cleanupIntervalMs ?? 60_000,
     queuePollIntervalMs: env.solid?.queuePollIntervalMs ?? 2000,
     queueLeaseMs: env.solid?.queueLeaseMs ?? 30_000,
+    queueFailedRetentionMs: env.solid?.queueFailedRetentionMs ?? 7 * 24 * 60 * 60 * 1000,
   };
 };
 
 export const openSolidDatabase = async (config: Required<SolidConfig>) => {
-  await mkdir(path.dirname(config.filePath), { recursive: true });
+  
+  await mkdir(path.dirname(path.resolve(config.filePath)), { recursive: true });
   let lastError: unknown;
   for (let attempt = 0; attempt < 8; attempt++) {
     try {
@@ -67,9 +60,10 @@ export const openSolidDatabase = async (config: Required<SolidConfig>) => {
 
 export const encodeSolidValue = (value: unknown): { type: SolidValueType; value: string | Buffer } => {
   if (Buffer.isBuffer(value)) return { type: "buffer", value };
+  if (value instanceof Uint8Array)
+    return { type: "buffer", value: Buffer.from(value.buffer, value.byteOffset, value.byteLength) };
   if (typeof value === "number") return { type: "number", value: String(value) };
   if (typeof value === "string") return { type: "string", value };
-
   return { type: "json", value: JSON.stringify(value ?? null) };
 };
 

package/service/predefinedAdaptor/sql/PendingStoreEnsures.ts

@@ -5,6 +5,7 @@ export class PendingStoreEnsures {
   track(ensure: Promise<void>): void {
     const tracked = ensure
       .catch((error: unknown) => {
+        
         if (this.#closed) return;
         throw error;
       })

package/service/predefinedAdaptor/sql/PostgresInsightSession.ts

@@ -0,0 +1,113 @@
+import type { Options, PostgresType, Sql, UnsafeQueryOptions } from "postgres";
+import type { InsightSession } from "./types";
+import { quoteIdent } from "./values";
+
+interface PostgresInsightSessionProps {
+  url: string;
+  schema: string;
+  options: Options<Record<string, PostgresType>>;
+}
+
+interface InsightRole {
+  role: string;
+  superuser: boolean;
+  memberOf: string[];
+  reads: string[];
+}
+
+/**
+ * Its own login as a role with SELECT on base columns only, so Postgres refuses `_doc` however it is reached (`*`, a
+ * whole-row value, `query_to_xml`). Not `SET ROLE`: a statement could `set_config('role', 'none', true)` its way back
+ * to the app's role. A role that can read `_doc` anywhere is refused on open.
+ */
+export class PostgresInsightSession implements InsightSession {
+  
+  static readonly #extendedProtocol = { simple: false } as unknown as UnsafeQueryOptions;
+  readonly #sql: Sql;
+  readonly #schema: string;
+
+  private constructor(sql: Sql, schema: string) {
+    this.#sql = sql;
+    this.#schema = schema;
+  }
+
+  static async open({ url, schema, options }: PostgresInsightSessionProps) {
+    const { default: postgres } = await import("postgres");
+    const sql = postgres(url, { ...options, max: 1, connection: { application_name: "akan-insight" } });
+    const session = new PostgresInsightSession(sql, schema);
+    try {
+      await session.#assertRestricted();
+      await session.#shadowDocuments();
+    } catch (error) {
+      await session.close();
+      throw error;
+    }
+    return session;
+  }
+
+  async #assertRestricted() {
+    const [role] = (await this.#sql.unsafe(
+      `SELECT r.rolname AS "role", r.rolsuper AS "superuser",
+        ARRAY(SELECT m.rolname::text FROM pg_roles m WHERE m.oid <> r.oid AND pg_has_role(r.oid, m.oid, 'MEMBER') ORDER BY 1) AS "memberOf",
+        ARRAY(SELECT c.oid::regclass::text FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid
+          WHERE a.attname = '_doc' AND a.attnum > 0 AND NOT a.attisdropped AND has_column_privilege(c.oid, a.attnum, 'SELECT') ORDER BY 1) AS "reads"
+      FROM pg_roles r WHERE r.rolname = current_user`,
+    )) as unknown as InsightRole[];
+    const refusal = !role
+      ? "cannot see its own role"
+      : role.superuser
+        ? `logs in as "${role.role}", a superuser`
+        : role.memberOf.length
+          ? `logs in as "${role.role}", a member of ${role.memberOf.join(", ")}, whose privileges it can take on`
+          : role.reads.length
+            ? `logs in as "${role.role}", which can read \`_doc\` of ${role.reads.join(", ")}`
+            : null;
+    if (refusal)
+      throw new Error(
+        `The insight connection ${refusal}. It must be a login role of its own that can read base columns and nothing else.`,
+      );
+  }
+
+  async #shadowDocuments() {
+    const tables = (await this.#sql.unsafe(
+      `SELECT c.relname AS "table", array_agg(a.attname::text ORDER BY a.attnum) AS "columns"
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+      WHERE n.nspname = $1 AND c.relkind IN ('r', 'p') AND a.attname <> '_doc'
+        AND has_column_privilege(c.oid, a.attnum, 'SELECT')
+        AND EXISTS (SELECT 1 FROM pg_attribute d WHERE d.attrelid = c.oid AND d.attname = '_doc' AND NOT d.attisdropped)
+      GROUP BY c.relname`,
+      [this.#schema],
+    )) as unknown as { table: string; columns: string[] }[];
+    if (!tables.length) return;
+    await this.#sql.unsafe(
+      tables
+        .map(
+          ({ table, columns }) =>
+            `CREATE TEMP VIEW ${quoteIdent(table)} AS SELECT ${columns.map(quoteIdent).join(", ")} FROM ${quoteIdent(this.#schema)}.${quoteIdent(table)}`,
+        )
+        .join(";\n"),
+    );
+  }
+
+  async read(statement: string, timeoutMs: number) {
+    try {
+      return await this.#sql.begin("read only", async (transaction) => {
+        await transaction.unsafe(`SET LOCAL search_path = ${quoteIdent(this.#schema)}`);
+        await transaction.unsafe(`SET LOCAL statement_timeout = ${Math.max(1, Math.floor(timeoutMs))}`);
+        const rows = await transaction.unsafe(statement, [], PostgresInsightSession.#extendedProtocol);
+        return [...rows] as Record<string, unknown>[];
+      });
+    } catch (error) {
+      if ((error as { code?: string }).code !== "42501") throw error;
+      throw new Error(
+        `An insight query reads base columns, and the role it runs as may read nothing else: ${(error as Error).message}.`,
+      );
+    }
+  }
+
+  async close() {
+    await this.#sql.end({ timeout: 1 });
+  }
+}