@coffre/db 0.14.4 → 0.15.0

package/dist/schema.js

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
-import { n as relationsOf, t as ACTIVE_SUBJECT } from "./relations-BfR3JjT1.js";
+import { n as recorded, r as ACTIVE_SUBJECT } from "./change-records-_fKvahvs.js";
 import { sql } from "drizzle-orm";
-import { bigint, boolean, check, customType, foreignKey, index, integer, pgTable, primaryKey, text, timestamp, unique, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { bigint, boolean, check, customType, foreignKey, index, integer, pgTable, primaryKey, smallint, text, timestamp, unique, uniqueIndex, uuid } from "drizzle-orm/pg-core";
 //#region src/schema.ts
 var schema_exports = /* @__PURE__ */ __exportAll({
 	auditChainHead: () => auditChainHead,
@@ -13,8 +13,17 @@ var schema_exports = /* @__PURE__ */ __exportAll({
 	dismissedKeys: () => dismissedKeys,
 	enrollments: () => enrollments,
 	environments: () => environments,
-	environmentsRelations: () => environmentsRelations,
 	identities: () => identities,
+	logBulk: () => logBulk,
+	logChanges: () => logChanges,
+	logCheckpoints: () => logCheckpoints,
+	logConfig: () => logConfig,
+	logFence: () => logFence,
+	logReadDays: () => logReadDays,
+	logReads: () => logReads,
+	logReadsCursor: () => logReadsCursor,
+	logTiles: () => logTiles,
+	logUses: () => logUses,
 	mcpApprovals: () => mcpApprovals,
 	mcpConnections: () => mcpConnections,
 	oauthClients: () => oauthClients,
@@ -22,7 +31,6 @@ var schema_exports = /* @__PURE__ */ __exportAll({
 	secretReferences: () => secretReferences,
 	secretVersions: () => secretVersions,
 	secrets: () => secrets,
-	secretsRelations: () => secretsRelations,
 	serviceBindings: () => serviceBindings,
 	vaultGrants: () => vaultGrants,
 	vaultMembers: () => vaultMembers,
@@ -63,8 +71,11 @@ const environments = pgTable("environments", {
 	createdAt: createdAt(),
 	archivedAt: timestamp("archived_at", { withTimezone: true }),
 	parentId: uuid("parent_id"),
-	owner: text()
+	owner: text(),
+	protected: boolean(),
+	seal: bytea()
 }, (table) => [
+	check("environments_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`),
 	unique("environments_project_id_slug_key").on(table.projectId, table.slug),
 	unique("environments_project_scoped").on(table.id, table.projectId),
 	check("environments_slug_check", sql`${table.slug} ~ ${PLACE_SLUG}`),
@@ -93,8 +104,10 @@ const secrets = pgTable("secrets", {
 	currentVersionId: uuid("current_version_id").references(() => secretVersions.id, { onDelete: "no action" }),
 	currentVersion: integer("current_version").notNull().default(0),
 	archivedAt: timestamp("archived_at", { withTimezone: true }),
-	folder: text()
+	folder: text(),
+	seal: bytea()
 }, (table) => [
+	check("secrets_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`),
 	unique("secrets_project_id_environment_id_key_key").on(table.projectId, table.environmentId, table.key),
 	check("secrets_key_check", sql`${table.key} ~ '^[A-Za-z_][A-Za-z0-9_]{0,127}$'`),
 	folderCheck("secrets_folder_check", table.folder),
@@ -113,7 +126,8 @@ const secrets = pgTable("secrets", {
 		columns: [table.environmentId, table.projectId],
 		foreignColumns: [environments.id, environments.projectId]
 	}),
-	index("secrets_lookup_idx").on(table.projectId, table.environmentId, table.key)
+	index("secrets_lookup_idx").on(table.projectId, table.environmentId, table.key),
+	index("secrets_live_idx").on(table.environmentId).where(sql`${table.archivedAt} IS NULL`)
 ]);
 const secretVersions = pgTable("secret_versions", {
 	id: uuid().primaryKey().defaultRandom(),
@@ -192,8 +206,10 @@ const vaultMembers = pgTable("vault_members", {
 	statusChangedAt: bigint("status_changed_at", { mode: "number" }).notNull(),
 	statusChangedBy: text("status_changed_by").notNull(),
 	accessSeq: bigint("access_seq", { mode: "bigint" }).notNull(),
-	mac: bytea().notNull()
+	mac: bytea().notNull(),
+	seal: bytea()
 }, (table) => [
+	check("vault_members_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`),
 	check("vault_members_mac_check", sql`octet_length(${table.mac}) = 32`),
 	check("vault_members_principal_check", sql`${table.principal} ~ '^(user|token):[^[:space:]:][^[:space:]]*$'`),
 	check("vault_members_user_lowercase", sql`${table.principal} NOT LIKE 'user:%' OR ${table.principal} = lower(${table.principal})`),
@@ -250,8 +266,9 @@ const vaultGrants = pgTable("vault_grants", {
 * read them from the entries before (an entry that names none, which only
 * a forged one is, counts as a key of its own, `entry:<seq>`). No login
 * writes it: the vault and the backup read it. A row a window old counts
-* for nothing, so nothing prunes them: there are at most as many as
-* principals times keys, and a count reads one principal's.
+* for nothing: the vault's checkpoint forgets those a day and an hour old,
+* longer than any window (`prune_vault_releases`), so a count reads about a
+* day of keys.
 */
 const vaultReleases = pgTable("vault_releases", {
 	principal: text().notNull(),
@@ -282,7 +299,8 @@ const auditLog = pgTable("audit_log", {
 	metadata: text().notNull().default("{}"),
 	prevHash: bytea("prev_hash").notNull(),
 	mac: bytea().notNull(),
-	hash: bytea().notNull()
+	hash: bytea().notNull(),
+	log015: boolean("log015")
 }, (table) => [
 	check("audit_log_author_check", sql`${table.author} IN ('app', 'vault')`),
 	check("audit_log_actor_check", sql`${table.actor} ~ '^(user|token|system):.+$'`),
@@ -352,7 +370,8 @@ const secretReferences = pgTable("secret_references", {
 	sourceSecretId: uuid("source_secret_id").notNull(),
 	createdSeq: bigint("created_seq", { mode: "bigint" }).notNull(),
 	createdAt: createdAt(),
-	createdBy: text("created_by").notNull()
+	createdBy: text("created_by").notNull(),
+	endedAt: timestamp("ended_at", { withTimezone: true })
 }, (table) => [
 	unique("secret_references_created_seq_key").on(table.createdSeq),
 	foreignKey({
@@ -440,13 +459,16 @@ const serviceBindings = pgTable("service_bindings", {
 	claims: text().notNull(),
 	scope: text(),
 	policy: text(),
+	origin: text(),
 	label: text(),
 	createdAt: createdAt(),
 	createdBy: text("created_by").notNull(),
 	lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
 	revokedAt: timestamp("revoked_at", { withTimezone: true }),
-	revokedBy: text("revoked_by")
+	revokedBy: text("revoked_by"),
+	seal: bytea()
 }, (table) => [
+	check("service_bindings_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`),
 	check("service_bindings_principal_check", sql`${table.principal} LIKE 'token:%'`),
 	check("service_bindings_auth_mac_check", sql`octet_length(${table.authMac}) = 32`),
 	check("service_bindings_claims_check", sql`${table.claims}::jsonb IS NOT NULL`),
@@ -526,8 +548,10 @@ const mcpConnections = pgTable("mcp_connections", {
 	lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
 	lastUsedIp: text("last_used_ip"),
 	revokedAt: timestamp("revoked_at", { withTimezone: true }),
-	revokedBy: text("revoked_by")
+	revokedBy: text("revoked_by"),
+	seal: bytea()
 }, (table) => [
+	check("mcp_connections_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`),
 	check("mcp_connections_principal_check", sql`${table.principal} LIKE 'user:%'`),
 	check("mcp_connections_registration_check", sql`${table.registration} IN ('cimd', 'dcr')`),
 	check("mcp_connections_auth_mac_check", sql`octet_length(${table.authMac}) = 32`),
@@ -638,8 +662,10 @@ const credentials = pgTable("credentials", {
 	constraints: text(),
 	enrollmentId: uuid("enrollment_id"),
 	approvedAt: timestamp("approved_at", { withTimezone: true }),
-	approvedBy: text("approved_by")
+	approvedBy: text("approved_by"),
+	seal: bytea()
 }, (table) => [
+	check("credentials_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`),
 	unique("credentials_token_hash_key").on(table.tokenHash),
 	check("credentials_kind_check", sql`${table.kind} IN ('browser', 'cli', 'service', 'personal', 'handle', 'workload')`),
 	check("credentials_principal_check", sql`${table.principal} LIKE 'user:%' OR ${table.principal} LIKE 'token:%'`),
@@ -712,11 +738,192 @@ const deviceAuthorizations = pgTable("device_authorizations", {
 		foreignColumns: [vaultMembers.principal]
 	}).onDelete("restrict")
 ]);
-const { environmentsRelations, secretsRelations } = relationsOf({
-	projects,
-	environments,
-	secrets,
-	secretVersions
-});
+/**
+* 0.15's configuration objects (0022_log_015): decision inputs no other row
+* holds, one row each, sealed as every input is. `policy` holds the bulk
+* cap's count and window, which a use reads in its own statement; `roles`
+* the role tables. JSON, as the vault writes it. Written only through
+* `change_input`.
+*/
+const logConfig = pgTable("log_config", {
+	name: text().primaryKey(),
+	value: text().notNull(),
+	seal: bytea()
+}, (table) => [
+	check("log_config_name_check", sql`${table.name} IN ('policy', 'roles')`),
+	check("log_config_value_check", sql`${table.value}::jsonb IS NOT NULL`),
+	check("log_config_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`)
+]);
+/**
+* 0.15's log (0022_log_015, docs/design/hot-path-one.md): two tables numbered
+* from one sequence, `log_number`, each number taken under the fence's lock
+* (a credential's issue: under the issue lock, which the barrier waits for;
+* 0026), so that the number alone orders uses against changes. Nothing reads or
+* writes them before 0.15's vault; the vault login reads them and writes
+* them only through the migration's functions.
+*
+* A change: any write to a decision input, or to configuration, kept for
+* good. `object` is the input it changes (`log_object(kind, id)`), `seal`
+* that object's seal after it, `payload` what it does. The MAC is the
+* vault's, 16 bytes, its key's tag then HMAC-SHA256 cut to 12 (D162), over everything but the number,
+* which the vault does not know when it asks. The vault login reads them,
+* and the app's reads the changes too, for the audit pages: a sign-in
+* through a trust binding, and the vault's token issues, revokes and
+* sign-outs, are recorded there alone (D147, T156, T164).
+*/
+const logChanges = pgTable("log_changes", {
+	number: bigint({ mode: "bigint" }).primaryKey(),
+	at: bigint({ mode: "number" }).notNull(),
+	requestId: text("request_id").notNull(),
+	object: uuid().notNull(),
+	actor: text().notNull(),
+	payload: text().notNull(),
+	seal: bytea(),
+	mac: bytea().notNull()
+}, (table) => [
+	unique("log_changes_request_id_key").on(table.requestId),
+	check("log_changes_seal_check", sql`${table.seal} IS NULL OR octet_length(${table.seal}) = 16`),
+	check("log_changes_mac_check", sql`octet_length(${table.mac}) = 16`),
+	index("log_changes_object_idx").on(table.object, table.number),
+	index("log_changes_sign_in_idx").on(table.at, table.number).where(recorded("postgres", table.payload, "signIn")),
+	index("log_changes_sign_in_actor_idx").on(table.actor, table.at, table.number).where(recorded("postgres", table.payload, "signIn")),
+	index("log_changes_issue_revoke_idx").on(table.at, table.number).where(recorded("postgres", table.payload, "issue", "revoke", "signOut")),
+	index("log_changes_issue_revoke_actor_idx").on(table.actor, table.at, table.number).where(recorded("postgres", table.payload, "issue", "revoke", "signOut"))
+]);
+/**
+* A use, the slim row (R53): no principal (the credential's), no
+* environment (the secret's, or `place`), no kind (the table says it).
+* Partitioned by the day of `at` (`make_day`), which retention drops whole;
+* fixed-width columns first, and eight of them, so the row pads to nothing. One index, the
+* replay's: a retried call repeats its `at` and request id, both under its
+* MAC, and lands in the same day.
+*/
+const logUses = pgTable("log_uses", {
+	number: bigint({ mode: "bigint" }).notNull(),
+	at: bigint({ mode: "number" }).notNull(),
+	requestId: bigint("request_id", { mode: "bigint" }).notNull(),
+	credential: uuid().notNull(),
+	secret: uuid().notNull(),
+	purpose: smallint().notNull(),
+	mac: bytea().notNull(),
+	place: uuid()
+}, (table) => [check("log_uses_mac_check", sql`octet_length(${table.mac}) = 16`), uniqueIndex("log_uses_request_idx").on(table.at, table.requestId)]);
+/**
+* 0.15's reads as the audit pages list them (T166; formal/Reads.tla): a
+* projection of each use a signed pair seals, written by the vault's
+* projector apart from the checkpointer, from the sealed objects at the
+* use's number: its account, its key's place, the fork it was read in,
+* through a reference the source and its place, the version read; under the
+* vault's MAC over all of it, the number included. Partitioned by the day of
+* `at`, as the uses are (`make_reads_day`), and dropped with them.
+*/
+const logReads = pgTable("log_reads", {
+	number: bigint({ mode: "bigint" }).notNull(),
+	at: bigint({ mode: "number" }).notNull(),
+	credential: uuid().notNull(),
+	purpose: smallint().notNull(),
+	principal: text().notNull(),
+	secret: uuid().notNull(),
+	environment: uuid().notNull(),
+	project: uuid().notNull(),
+	place: uuid(),
+	source: uuid(),
+	sourceEnvironment: uuid("source_environment"),
+	sourceProject: uuid("source_project"),
+	version: uuid(),
+	mac: bytea().notNull()
+}, (table) => [
+	check("log_reads_mac_check", sql`octet_length(${table.mac}) = 16`),
+	uniqueIndex("log_reads_number_idx").on(table.at, table.number),
+	index("log_reads_principal_idx").on(table.principal, table.at, table.number)
+]);
+/** The days each member's reads are in (`log_reads`), so that a page of theirs reads those days alone: the projector writes them with the reads. */
+const logReadDays = pgTable("log_read_days", {
+	principal: text().notNull(),
+	day: integer().notNull()
+}, (table) => [primaryKey({
+	name: "log_read_days_pkey",
+	columns: [table.principal, table.day]
+})]);
+/** How far the projector has gone: the number every use at or below it is projected, and when. */
+const logReadsCursor = pgTable("log_reads_cursor", {
+	onlyRow: boolean("only_row").primaryKey().default(true),
+	through: bigint({ mode: "bigint" }).notNull(),
+	pair: bigint({ mode: "bigint" }).notNull(),
+	at: bigint({ mode: "number" }).notNull(),
+	mac: bytea()
+}, (table) => [check("log_reads_cursor_only_row_check", sql`${table.onlyRow}`), check("log_reads_cursor_mac_check", sql`${table.mac} IS NULL OR octet_length(${table.mac}) = 16`)]);
+/**
+* The bulk cap (R28, R52): each principal's last logged use of each key, as
+* the start of that use's refresh period, written only by a use that holds
+* the principal's lock (exclusive to enter a key, shared to move it on:
+* 0028), at most once per refresh per key. A row older than the window, a
+* refresh, the deadline and a minute counts for nothing; `prune_bulk`
+* forgets it an hour after that.
+*/
+const logBulk = pgTable("log_bulk", {
+	principal: text().notNull(),
+	secret: uuid().notNull(),
+	last: bigint({ mode: "number" }).notNull()
+}, (table) => [primaryKey({
+	name: "log_bulk_pkey",
+	columns: [table.principal, table.secret]
+})]);
+/**
+* The fence's one row: the lowest `at` a use may still be written with,
+* raised by each checkpoint's barrier (`close_one`), never lowered. Made
+* by the migration; without it every use is refused.
+*/
+const logFence = pgTable("log_fence", {
+	onlyRow: boolean("only_row").primaryKey().default(true),
+	atFloor: bigint("at_floor", { mode: "number" }).notNull()
+}, (table) => [check("log_fence_only_row_check", sql`${table.onlyRow}`)]);
+/**
+* A signed checkpoint: the pair of tree heads (W212), changes and uses, at
+* one `upto`, every number at or below which is final. One row, so that no
+* state holds one head without the other. `at_floor` is the floor its
+* barrier set: the next window's uses have an `at` at or above it.
+*/
+const logCheckpoints = pgTable("log_checkpoints", {
+	upto: bigint({ mode: "bigint" }).primaryKey(),
+	at: bigint({ mode: "number" }).notNull(),
+	atFloor: bigint("at_floor", { mode: "number" }).notNull(),
+	changesSize: bigint("changes_size", { mode: "bigint" }).notNull(),
+	changesRoot: bytea("changes_root").notNull(),
+	changesNote: text("changes_note").notNull(),
+	usesSize: bigint("uses_size", { mode: "bigint" }).notNull(),
+	usesRoot: bytea("uses_root").notNull(),
+	usesNote: text("uses_note").notNull()
+}, (table) => [
+	check("log_checkpoints_changes_root_check", sql`octet_length(${table.changesRoot}) = 32`),
+	check("log_checkpoints_uses_root_check", sql`octet_length(${table.usesRoot}) = 32`),
+	index("log_checkpoints_floor_idx").on(table.atFloor, table.upto)
+]);
+/**
+* The two trees' tiles (C2SP tlog-tiles: height 8, up to 256 hashes of one
+* level). Partitioned by tree; the uses tree's leaf tiles (level 0) by
+* `leaf`, the first leaf a tile covers (`make_tiles`), so that retention
+* drops a table rather than deleting a day's rows (W212); its levels above,
+* which span far past their first leaf, in one table (W217).
+*/
+const logTiles = pgTable("log_tiles", {
+	tree: text().notNull(),
+	level: smallint().notNull(),
+	leaf: bigint({ mode: "bigint" }).notNull(),
+	hashes: bytea().notNull()
+}, (table) => [
+	primaryKey({
+		name: "log_tiles_pkey",
+		columns: [
+			table.tree,
+			table.level,
+			table.leaf
+		]
+	}),
+	check("log_tiles_tree_check", sql`${table.tree} IN ('changes', 'uses')`),
+	check("log_tiles_level_check", sql`${table.level} BETWEEN 0 AND 7`),
+	check("log_tiles_leaf_check", sql`${table.leaf} >= 0 AND ${table.leaf} % (256::numeric ^ (${table.level} + 1)) = 0`),
+	check("log_tiles_hashes_check", sql`octet_length(${table.hashes}) BETWEEN 32 AND 8192 AND octet_length(${table.hashes}) % 32 = 0`)
+]);
 //#endregion
-export { auditChainHead, auditLog, cappedAlerts, consumedTokens, credentials, deviceAuthorizations, dismissedKeys, enrollments, environments, environmentsRelations, identities, mcpApprovals, mcpConnections, oauthClients, projects, secretReferences, secretVersions, secrets, secretsRelations, serviceBindings, schema_exports as t, vaultGrants, vaultMembers, vaultReleases };
+export { auditChainHead, auditLog, cappedAlerts, consumedTokens, credentials, deviceAuthorizations, dismissedKeys, enrollments, environments, identities, logBulk, logChanges, logCheckpoints, logConfig, logFence, logReadDays, logReads, logReadsCursor, logTiles, logUses, mcpApprovals, mcpConnections, oauthClients, projects, secretReferences, secretVersions, secrets, serviceBindings, schema_exports as t, vaultGrants, vaultMembers, vaultReleases };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -74,16 +74,24 @@
     },
     "./package.json": "./package.json"
   },
+  "imports": {
+    "#postgres/platform": {
+      "coffre:source": {
+        "workerd": "./src/postgres-js/platform.workerd.ts",
+        "default": "./src/postgres-js/platform.node.ts"
+      },
+      "types": "./dist/postgres-platform-node.d.ts",
+      "workerd": "./dist/postgres-platform-workerd.js",
+      "default": "./dist/postgres-platform-node.js"
+    }
+  },
   "dependencies": {
     "@libsql/client": "0.18.0",
     "drizzle-orm": "0.45.2",
-    "pg": "8.16.3",
-    "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.14.4"
+    "@coffre/core": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "26.1.1",
-    "@types/pg": "8.20.0",
     "drizzle-kit": "0.31.10",
     "tsdown": "0.23.0",
     "typescript": "5.9.3"

package/src/active-subject.ts

@@ -0,0 +1,9 @@
+import { sql } from 'drizzle-orm';
+
+/**
+ * `identities.active_subject`: the subject while the account is bound, null
+ * once revoked. A unique index on (provider, issuer_hash, active_subject)
+ * binds an account to one person at a time. Plain column names, so the
+ * expression reads the same on both databases.
+ */
+export const ACTIVE_SUBJECT = sql`CASE WHEN revoked_at IS NULL THEN subject END`;

package/src/change-records.ts

@@ -0,0 +1,38 @@
+import { sql, type SQL, type SQLWrapper } from 'drizzle-orm';
+
+/**
+ * What a change of 0.15's log records besides its op, which the audit pages
+ * list where 0.14's entry stood (D147): a sign-in through a trust binding
+ * (`signIn`, T156); a token the vault issued (`issue`); a credential it
+ * revoked by request, or that signed itself out (a revoke's `reason`,
+ * T164). Each is known by text its payload holds (`holds`), and by how the
+ * payload starts (`starts`): the vault writes it canonical, its keys in
+ * order, so an issue's is `{"caller":…` and a revoke's
+ * `{"op":"credential.revoke",…`. A string the payload holds has its quotes
+ * escaped, but an object's keys need not be the vault's own (a role's
+ * name, in the roles' change: review r1), so where the text alone could be
+ * one, the start says whose payload it is. The partial indexes of
+ * `log_changes` hold each set, and a read that is to use one repeats its
+ * condition (`recorded`), word for word and with no parameter.
+ */
+export const RECORDS = {
+  signIn: { holds: '"signIn":{' },
+  issue: { starts: '{"caller":"', holds: '"issue":{"by":"' },
+  revoke: { starts: '{"op":"credential.revoke",', holds: '"reason":"revoke"' },
+  signOut: { starts: '{"op":"credential.revoke",', holds: '"reason":"sign_out"' },
+} as const satisfies Record<string, { starts?: string; holds: string }>;
+
+export type ChangeRecord = keyof typeof RECORDS;
+
+/** Whether `payload` holds one of `records`, on Postgres or SQLite: an index's condition, and the reads' that use it. */
+export function recorded(engine: 'postgres' | 'sqlite', payload: SQLWrapper, ...records: ChangeRecord[]): SQL {
+  const at = (text: string) => {
+    const marker = sql.raw(`'${text}'`);
+    return engine === 'postgres' ? sql`strpos(${payload}, ${marker})` : sql`instr(${payload}, ${marker})`;
+  };
+  const each = records.map((record) => {
+    const { starts, holds }: { starts?: string; holds: string } = RECORDS[record];
+    return starts === undefined ? sql`${at(holds)} > 0` : sql`(${at(starts)} = 1 AND ${at(holds)} > 0)`;
+  });
+  return each.length === 1 ? each[0]! : sql`(${sql.join(each, sql` OR `)})`;
+}

package/src/connect.ts

@@ -1,30 +1,30 @@
 import { resolve } from 'node:path';
 
-import type { Client, ResultSet, Transaction as LibsqlTransaction, TransactionMode } from '@libsql/client';
-import pg from 'pg';
-
+import type { Client, InStatement, ResultSet, Transaction as LibsqlTransaction, TransactionMode } from '@libsql/client';
 import { createDatabase, type Database } from './database.ts';
 import type { Engine } from './dialect.ts';
 import { asPostgresDatabase } from './portable.ts';
-import { postgresConnection } from './postgres.ts';
+import { postgresClient } from './postgres.ts';
 
-export { postgresConnection } from './postgres.ts';
+export { postgresClient, postgresOptions, postgresSession, quoteIdentifier, quoteLiteral, SessionLost, type ClientOptions, type PostgresClient } from './postgres.ts';
 
 /**
  * Open a database from its URL, on a Node server:
  *
- *   postgres://… or postgresql://…   node-postgres
+ *   postgres://… or postgresql://…   postgres.js, a pool of up to 10 connections
  *   file:… or libsql:…                @libsql/client (SQLite)
  *
  * The SQLite driver loads only when asked for. The Worker does not
  * come through here; it builds its Postgres database from the Hyperdrive
- * pool with createDatabase.
+ * pool with createDatabase. `max`, for a pool of its own beside another,
+ * as the vault's checkpointer has (T169).
  */
-export async function openDatabase(url: string): Promise<OpenDatabase> {
+export async function openDatabase(url: string, options: { max?: number } = {}): Promise<OpenDatabase> {
   switch (engineOfUrl(url)) {
     case 'postgres': {
-      const pool = new pg.Pool(postgresConnection(url));
-      return { engine: 'postgres', db: createDatabase(pool), close: () => pool.end() };
+      // As node-postgres's pool was: 10 connections, each closed after 10 s idle.
+      const client = postgresClient(url, { max: options.max ?? 10, idle_timeout: 10 });
+      return { engine: 'postgres', db: createDatabase(client), close: () => client.end(), cut: () => client.end({ timeout: 0 }) };
     }
     case 'sqlite': {
       const [{ createClient }, { drizzle }, schema] = await Promise.all([
@@ -36,12 +36,13 @@ export async function openDatabase(url: string): Promise<OpenDatabase> {
       const client = createClient({ url, timeout: 5_000, intMode: 'bigint' });
       if (url.startsWith('file:')) await client.execute('PRAGMA journal_mode = WAL');
       const db = drizzle({ client: oneTransactionAtATime(client, writeQueueFor(url)), schema });
-      return { engine: 'sqlite', db: asPostgresDatabase(db), close: async () => client.close() };
+      return { engine: 'sqlite', db: asPostgresDatabase(db), close: async () => client.close(), cut: async () => client.close() };
     }
   }
 }
 
-export type OpenDatabase = { engine: Engine; db: Database; close: () => Promise<void> };
+/** `close` once what was asked has answered; `cut` at once, what is in flight failing (T169). */
+export type OpenDatabase = { engine: Engine; db: Database; close: () => Promise<void>; cut: () => Promise<void> };
 
 export function engineOfUrl(url: string): Engine {
   const scheme = url.slice(0, url.indexOf(':'));
@@ -61,6 +62,16 @@ export function engineOfUrl(url: string): Engine {
  * connections reach it. Each begins IMMEDIATE (libsql's default), taking the
  * write lock with its first statement, which is what makes a read inside it
  * as good as a locked one (see forUpdate).
+ *
+ * A lone statement that writes waits its turn too. It cannot wait for the
+ * lock itself: libsql's busy wait blocks the thread, so the transaction
+ * holding the lock, in this process, cannot go on to commit, and the write
+ * fails after `timeout`. A connection whose write failed that way still
+ * reads the file as it was then, until its statement is collected:
+ *
+ *   six MCP calls at once     the first's approval, in a transaction    BEGIN IMMEDIATE, then awaits
+ *   another's last_used_at    a lone UPDATE, outside the queue          the thread blocked 5 s, SQLITE_BUSY
+ *   it reads the approval     on that connection                        no row
  */
 class WriteQueue {
   #tail: Promise<void> = Promise.resolve();
@@ -89,7 +100,17 @@ function oneTransactionAtATime(client: Client, queue: WriteQueue): Client {
   return new Proxy(client, {
     get(target, key) {
       if (key === 'execute') {
-        return async (...args: Parameters<Client['execute']>) => numbers(await target.execute(...args));
+        return async (...args: Parameters<Client['execute']>) => {
+          // Parameters<> sees execute's last overload only, (sql, args); Drizzle calls the other, ({ sql, args }).
+          const [statement] = args as unknown as [InStatement];
+          if (!writes(typeof statement === 'string' ? statement : statement.sql)) return numbers(await target.execute(...args));
+          const release = await queue.acquire();
+          try {
+            return numbers(await target.execute(...args));
+          } finally {
+            release();
+          }
+        };
       }
       if (key === 'transaction') {
         return async (mode?: TransactionMode) => {
@@ -154,6 +175,39 @@ function settling(tx: LibsqlTransaction, release: () => void): LibsqlTransaction
   return tx;
 }
 
+/**
+ * Whether a lone statement may write: all but a query (SELECT or VALUES, or
+ * a WITH whose statement is one) and EXPLAIN, read from its words outside
+ * parentheses, strings, quoted names and comments.
+ *
+ *   select … from "mcp_approvals" where …                 reads
+ *   WITH policy AS (SELECT …) SELECT json_object(…)       reads
+ *   WITH old AS (SELECT …) DELETE FROM …                  writes
+ *   update "mcp_connections" set …                        writes
+ */
+export function writes(statement: string): boolean {
+  let depth = 0;
+  let first: string | null = null;
+  for (const [token] of statement.matchAll(/--[^\n]*|\/\*[\s\S]*?(?:\*\/|$)|'(?:[^']|'')*'?|"(?:[^"]|"")*"?|`[^`]*`?|\[[^\]]*\]?|[()]|[A-Za-z_][\w$]*/g)) {
+    if (token === '(') depth += 1;
+    else if (token === ')') depth -= 1;
+    else if (depth === 0 && /^[A-Za-z_]/.test(token)) {
+      const word = token.toLowerCase();
+      if (first === null) {
+        first = word;
+        if (word !== 'with') return !QUERIES.has(word);
+      } else if (STATEMENTS.has(word)) {
+        return !QUERIES.has(word);
+      }
+    }
+  }
+  return true;
+}
+
+const QUERIES = new Set(['select', 'values', 'explain']);
+/** The words a WITH's own statement starts with. */
+const STATEMENTS = new Set(['select', 'values', 'insert', 'update', 'delete', 'replace']);
+
 /** Keep large counters exact; Drizzle's booleans and dates still need safe numbers. */
 function numbers(result: ResultSet): ResultSet {
   result.rows = result.rows.map((row) => {