@huynle/hub 0.7.4 → 0.8.1

package/src/central/backend/postgres-blobs.ts

@@ -0,0 +1,513 @@
+// BlobStore in Postgres (cluster mode; HWA-22, decision tctkrik8): every pod reads and writes the same artifact
+// bytes, the contract in ../artifacts/blob-store.ts (the shared suite in test/blob-store-conformance.ts). It uses
+// the cluster's Postgres and migration framework (migration `artifact-blobs` in ./postgres-migrate): no new
+// service, and the database's backup covers the bytes.
+//
+// Tables (keyed by user_id first: blobs are per user, the tenant key; every statement names the user):
+//   artifact_blobs        (user_id, hash) → bytes, chunks, stored_at, touched_at   one row per visible blob
+//   artifact_blob_chunks  (user_id, hash, chunk) → data bytea                      its bytes, ≤ chunkBytes each,
+//                                                                                  deleted with the blob (cascade)
+//   artifact_blob_uploads (upload_id, chunk) → user_id, data, created_at           uploads in flight (staging)
+//
+// Writes: the body streams through readBlobBody (hashed and bounded as it comes) and is cut into chunks of
+// chunkBytes (default ARTIFACT_LIMITS.chunkBytes). Full chunks are staged in artifact_blob_uploads as they come,
+// so a pod holds at most one chunk of a body in memory and no connection while it reads a slow client; a body
+// under one chunk never touches the staging table. The commit is one transaction under a per-user advisory lock:
+// refresh an existing blob (the same bytes again: nothing new, never refused for quota), or check the quota,
+// insert the blob row, adopt the staged chunks, insert the last one and drop the staging rows. Readers never see
+// a partial blob: the row and all its chunks appear at COMMIT. The per-user lock makes one user's concurrent puts
+// (on any pod) check the quota one at a time, so they never overshoot it, and makes concurrent puts of the same
+// bytes one blob.
+//
+// Failures: a put that fails (too large, hash mismatch, quota, a database error) drops its staging rows; a pod
+// that dies mid-upload leaves rows the sweep removes (uploads whose newest chunk is older than uploadTtlMs; on put
+// at most once per SWEEP_INTERVAL_MS per pod, or sweepUploads()). A commit that finds its staged chunks gone rolls
+// back and fails the put (retry it). delete is one statement checking touchedBefore (atomic with the removal).
+// Reads fetch one chunk per query (no connection is held between them) and verify the length and sha256 of what
+// they stream: a blob deleted or changed mid-read fails the stream instead of ending it short.
+//
+// Retention: ArtifactStore.recover / purgeArchived (../artifacts/maintenance.ts, on a leader) decide what is
+// unreferenced and call delete with touchedBefore, as for the other stores; this store only sweeps its staging.
+//
+// The client connects on first use (the hub builds its backends synchronously), with its own small pool so blob
+// transfers never starve state queries, and first checks the schema (it never migrates unless told to, like
+// PostgresStateStore). The URL holds credentials: it stays in a private field and is never put in a message.
+//
+// The SQL sits behind BlobRows, so the store's logic (chunking, staging, failure cleanup, verified reads) runs in
+// unit tests against in-memory rows; PostgresBlobRows is covered by the HUB_IT_CLUSTER=1 suite.
+import { randomUUID } from "node:crypto"
+import { SQL } from "bun"
+import { ARTIFACT_LIMITS, isBlobHash, type BlobRef, type Page } from "../../protocol"
+import {
+  type BlobBody,
+  type BlobDeleteOptions,
+  type BlobInfo,
+  BlobInputError,
+  type BlobListOptions,
+  type BlobPutOptions,
+  BlobQuotaError,
+  type BlobRead,
+  type BlobStore,
+  type BlobUsage,
+} from "../artifacts/blob-store"
+import { listCursor, listWindow, putLimits, readBlobBody } from "../artifacts/blob-support"
+import { migrate, SCHEMA_VERSION, schemaVersion } from "./postgres-migrate"
+import { SchemaOutdatedError, statementTimeout, STATEMENT_TIMEOUT_MS } from "./postgres-state"
+import type { Clock } from "./types"
+
+/** Smallest chunk size accepted (tests use small chunks; production keeps the default). */
+export const MIN_CHUNK_BYTES = 1024
+/** Default idle time after which an upload's staging rows are swept (by its newest chunk). */
+export const UPLOAD_TTL_MS = 60 * 60_000
+/** Least time between two sweeps on put, per store. */
+export const SWEEP_INTERVAL_MS = 60_000
+/** Default pool size (blob transfers only). */
+export const BLOB_POOL_MAX = 4
+/** pg_advisory_xact_lock(namespace, hashtext(user)) namespace of blob commits ("hblb"). */
+export const BLOB_LOCK_NAMESPACE = 0x6862_6c62
+
+/** A visible blob's row. */
+export interface BlobRow extends BlobInfo {
+  readonly chunks: number
+}
+
+/** A commit: the blob, the staged chunks to adopt and the last chunk (when there is one). */
+export interface BlobCommit {
+  readonly userID: string
+  readonly hash: string
+  readonly bytes: number
+  readonly chunks: number
+  readonly uploadID: string
+  /** Chunks 0…staged-1 are staged under uploadID. */
+  readonly staged: number
+  /** The chunk after the staged ones, inserted directly. */
+  readonly tail?: { readonly chunk: number; readonly data: Uint8Array }
+  readonly at: number
+  readonly quotaBytes: number
+}
+
+export type CommitResult = { readonly kind: "stored" } | { readonly kind: "touched" } | { readonly kind: "quota"; readonly usedBytes: number }
+
+/** The SQL the store runs (PostgresBlobRows), behind a seam for unit tests. Every method names the user. */
+export interface BlobRows {
+  stage(uploadID: string, userID: string, chunk: number, data: Uint8Array, at: number): Promise<void>
+  /** Atomically: touch an existing blob, or check the quota and make the new blob visible (see the header). */
+  commit(commit: BlobCommit): Promise<CommitResult>
+  /** Drops an upload's staging rows. */
+  discard(uploadID: string, userID: string): Promise<void>
+  /** Drops the staging rows of uploads whose newest chunk is older than `before`; answers how many uploads. */
+  sweep(before: number): Promise<number>
+  row(userID: string, hash: string): Promise<BlobRow | undefined>
+  chunk(userID: string, hash: string, chunk: number): Promise<Uint8Array | undefined>
+  touch(userID: string, hash: string, at: number): Promise<boolean>
+  delete(userID: string, hash: string, touchedBefore?: number): Promise<boolean>
+  usage(userID: string): Promise<BlobUsage>
+  /** Up to `limit` rows with hash > after, by hash. */
+  list(userID: string, after: string | undefined, limit: number): Promise<BlobRow[]>
+  close(): Promise<void>
+}
+
+export interface PostgresBlobStoreOptions {
+  /** postgres:// or postgresql:// (with credentials). Exactly one of url and rows. */
+  readonly url?: string
+  /** Rows to use instead of a database (tests). */
+  readonly rows?: BlobRows
+  readonly now?: Clock
+  /** Chunk size, MIN_CHUNK_BYTES–ARTIFACT_LIMITS.chunkBytes (default ARTIFACT_LIMITS.chunkBytes). */
+  readonly chunkBytes?: number
+  /** Idle time after which an abandoned upload's staging rows are swept (default UPLOAD_TTL_MS, at least a minute). */
+  readonly uploadTtlMs?: number
+  /** Apply pending migrations on first use (default false: `hub-server migrate` does). */
+  readonly migrate?: boolean
+  /** Pool size, 1–100 (default BLOB_POOL_MAX). */
+  readonly max?: number
+  /** Seconds to wait for a connection (default Bun's). */
+  readonly connectionTimeoutSeconds?: number
+  /** Postgres statement_timeout of every connection, ms (default STATEMENT_TIMEOUT_MS; 0 turns it off). */
+  readonly statementTimeoutMs?: number
+}
+
+/** Checks the options; the messages never name the url. */
+export function postgresBlobOptions(options: PostgresBlobStoreOptions): { chunkBytes: number; uploadTtlMs: number; max: number; statementTimeoutMs: number } {
+  if ((options.url === undefined) === (options.rows === undefined)) throw new Error("PostgresBlobStore needs exactly one of url and rows")
+  if (options.url !== undefined && !/^postgres(ql)?:\/\//.test(options.url)) throw new Error("PostgresBlobStore url must be a postgres:// or postgresql:// URL")
+  const chunkBytes = options.chunkBytes ?? ARTIFACT_LIMITS.chunkBytes
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes < MIN_CHUNK_BYTES || chunkBytes > ARTIFACT_LIMITS.chunkBytes) {
+    throw new Error(`PostgresBlobStore chunkBytes must be ${MIN_CHUNK_BYTES}–${ARTIFACT_LIMITS.chunkBytes}`)
+  }
+  const uploadTtlMs = options.uploadTtlMs ?? UPLOAD_TTL_MS
+  if (!Number.isSafeInteger(uploadTtlMs) || uploadTtlMs < 60_000) throw new Error("PostgresBlobStore uploadTtlMs must be at least 60000")
+  const max = options.max ?? BLOB_POOL_MAX
+  if (!Number.isSafeInteger(max) || max < 1 || max > 100) throw new Error("PostgresBlobStore max must be 1–100")
+  if (options.connectionTimeoutSeconds !== undefined && !(options.connectionTimeoutSeconds > 0)) {
+    throw new Error("PostgresBlobStore connectionTimeoutSeconds must be positive")
+  }
+  const statementTimeoutMs = options.statementTimeoutMs ?? STATEMENT_TIMEOUT_MS
+  statementTimeout("PostgresBlobStore", statementTimeoutMs)
+  return { chunkBytes, uploadTtlMs, max, statementTimeoutMs }
+}
+
+export class PostgresBlobStore implements BlobStore {
+  readonly #rows: BlobRows
+  readonly #now: Clock
+  readonly #chunkBytes: number
+  readonly #uploadTtlMs: number
+  #lastSweep = Number.NEGATIVE_INFINITY
+
+  constructor(options: PostgresBlobStoreOptions) {
+    const { chunkBytes, uploadTtlMs, max, statementTimeoutMs } = postgresBlobOptions(options)
+    this.#now = options.now ?? Date.now
+    this.#chunkBytes = chunkBytes
+    this.#uploadTtlMs = uploadTtlMs
+    this.#rows =
+      options.rows ??
+      new PostgresBlobRows({
+        url: options.url!,
+        max,
+        statementTimeoutMs,
+        ...(options.migrate !== undefined ? { migrate: options.migrate } : {}),
+        ...(options.connectionTimeoutSeconds !== undefined ? { connectionTimeoutSeconds: options.connectionTimeoutSeconds } : {}),
+      })
+  }
+
+  async put(userID: string, body: BlobBody, mediaType: string, options: BlobPutOptions = {}): Promise<BlobRef> {
+    const limits = putLimits(mediaType, options)
+    await this.#maybeSweep()
+    const uploadID = randomUUID()
+    const chunker = new Chunker(this.#chunkBytes)
+    let staged = 0
+    try {
+      const { hash, bytes } = await readBlobBody(body, limits, async (chunk) => {
+        for (const full of chunker.push(chunk)) {
+          // Counted before the write: a failed write may still have landed, so the cleanup must run.
+          staged++
+          await this.#rows.stage(uploadID, userID, staged - 1, full, this.#now())
+        }
+      })
+      const last = chunker.rest()
+      const tail = last ? { chunk: staged, data: last } : undefined
+      const result = await this.#rows.commit({
+        userID,
+        hash,
+        bytes,
+        chunks: staged + (tail ? 1 : 0),
+        uploadID,
+        staged,
+        ...(tail ? { tail } : {}),
+        at: this.#now(),
+        quotaBytes: limits.quotaBytes,
+      })
+      if (result.kind === "quota") throw new BlobQuotaError(limits.quotaBytes, result.usedBytes)
+      return { hash, bytes, mediaType }
+    } catch (error) {
+      // A successful commit leaves no staging rows; anything else drops them here (or the sweep does later).
+      if (staged > 0) await this.#rows.discard(uploadID, userID).catch(() => {})
+      throw error
+    }
+  }
+
+  async get(userID: string, hash: string): Promise<BlobRead | undefined> {
+    if (!isBlobHash(hash)) return undefined
+    const row = await this.#rows.row(userID, hash)
+    return row && { ...info(row), body: this.#stream(userID, row) }
+  }
+
+  async stat(userID: string, hash: string): Promise<BlobInfo | undefined> {
+    if (!isBlobHash(hash)) return undefined
+    const row = await this.#rows.row(userID, hash)
+    return row && info(row)
+  }
+
+  async has(userID: string, hash: string): Promise<boolean> {
+    return (await this.stat(userID, hash)) !== undefined
+  }
+
+  async touch(userID: string, hash: string): Promise<boolean> {
+    return isBlobHash(hash) && this.#rows.touch(userID, hash, this.#now())
+  }
+
+  async delete(userID: string, hash: string, options: BlobDeleteOptions = {}): Promise<boolean> {
+    if (!isBlobHash(hash)) return false
+    if (options.touchedBefore !== undefined && !Number.isFinite(options.touchedBefore)) throw new BlobInputError("touchedBefore must be a time")
+    return this.#rows.delete(userID, hash, options.touchedBefore)
+  }
+
+  usage(userID: string): Promise<BlobUsage> {
+    return this.#rows.usage(userID)
+  }
+
+  async list(userID: string, options: BlobListOptions = {}): Promise<Page<BlobInfo>> {
+    const { limit, after } = listWindow(options)
+    const rows = await this.#rows.list(userID, after, limit + 1)
+    const items = rows.slice(0, limit).map(info)
+    return rows.length > limit ? { items, cursor: listCursor(items[items.length - 1]!.hash) } : { items }
+  }
+
+  /** Drops the staging rows of uploads idle for uploadTtlMs (crashed pods); answers how many uploads. */
+  async sweepUploads(): Promise<number> {
+    this.#lastSweep = this.#now()
+    return this.#rows.sweep(this.#lastSweep - this.#uploadTtlMs)
+  }
+
+  /** Closes the connection pool (a later call opens a new one). */
+  close(): Promise<void> {
+    return this.#rows.close()
+  }
+
+  /** Sweeps on put at most once per SWEEP_INTERVAL_MS; a failed sweep never fails the put. */
+  async #maybeSweep(): Promise<void> {
+    if (this.#now() - this.#lastSweep < SWEEP_INTERVAL_MS) return
+    await this.sweepUploads().catch(() => {})
+  }
+
+  /** The blob's chunks, one query each, verified against its length and hash. */
+  #stream(userID: string, row: BlobRow): ReadableStream<Uint8Array> {
+    const rows = this.#rows
+    const hasher = new Bun.CryptoHasher("sha256")
+    let next = 0
+    let read = 0
+    return new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        try {
+          if (next < row.chunks) {
+            const data = await rows.chunk(userID, row.hash, next++)
+            if (!data) throw new Error("blob was removed while it was read")
+            read += data.byteLength
+            if (read > row.bytes) throw new Error("blob is larger than recorded")
+            hasher.update(data)
+            if (data.byteLength > 0) controller.enqueue(data)
+            return
+          }
+          if (read !== row.bytes || `sha256:${hasher.digest("hex")}` !== row.hash) throw new Error("blob bytes do not match their hash")
+          controller.close()
+        } catch (cause) {
+          controller.error(cause)
+        }
+      },
+    })
+  }
+}
+
+const info = (row: BlobRow): BlobInfo => ({ hash: row.hash, bytes: row.bytes, storedAt: row.storedAt, touchedAt: row.touchedAt })
+
+/** Re-cuts a byte stream into chunks of exactly `size` (the last one shorter). */
+class Chunker {
+  #parts: Uint8Array[] = []
+  #bytes = 0
+  constructor(private readonly size: number) {}
+
+  /** The full chunks this input completes. */
+  push(input: Uint8Array): Uint8Array[] {
+    const full: Uint8Array[] = []
+    let rest = input
+    while (rest.byteLength > 0) {
+      const take = Math.min(this.size - this.#bytes, rest.byteLength)
+      this.#parts.push(rest.slice(0, take))
+      this.#bytes += take
+      rest = rest.subarray(take)
+      if (this.#bytes === this.size) full.push(this.#take())
+    }
+    return full
+  }
+
+  /** What is left (undefined when nothing). */
+  rest(): Uint8Array | undefined {
+    return this.#bytes > 0 ? this.#take() : undefined
+  }
+
+  #take(): Uint8Array {
+    const parts = this.#parts
+    const bytes = this.#bytes
+    this.#parts = []
+    this.#bytes = 0
+    if (parts.length === 1) return parts[0]!
+    const out = new Uint8Array(bytes)
+    let offset = 0
+    for (const part of parts) {
+      out.set(part, offset)
+      offset += part.byteLength
+    }
+    return out
+  }
+}
+
+// ---- Postgres --------------------------------------------------------------------------------------------------
+
+interface PostgresBlobRowsOptions {
+  readonly url: string
+  readonly max: number
+  readonly migrate?: boolean
+  readonly connectionTimeoutSeconds?: number
+  readonly statementTimeoutMs: number
+}
+
+interface SqlRow {
+  hash: string
+  bytes: number
+  chunks: number
+  stored_at: number
+  touched_at: number
+}
+
+const fromSql = (row: SqlRow): BlobRow => ({ hash: row.hash, bytes: row.bytes, chunks: row.chunks, storedAt: row.stored_at, touchedAt: row.touched_at })
+const bytea = (data: Uint8Array): Buffer => Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+
+/** BlobRows on Postgres (covered by the HUB_IT_CLUSTER=1 suite in test/central-backend-postgres-blobs.test.ts). */
+export class PostgresBlobRows implements BlobRows {
+  readonly #url: string
+  readonly #options: Omit<PostgresBlobRowsOptions, "url">
+  #sql?: SQL
+  #ready?: Promise<void>
+
+  constructor(options: PostgresBlobRowsOptions) {
+    const { url, ...rest } = options
+    this.#url = url
+    this.#options = rest
+  }
+
+  async stage(uploadID: string, userID: string, chunk: number, data: Uint8Array, at: number): Promise<void> {
+    const sql = await this.#client()
+    await sql`
+      INSERT INTO artifact_blob_uploads (upload_id, chunk, user_id, data, created_at)
+      VALUES (${uploadID}::uuid, ${chunk}, ${userID}, ${bytea(data)}, ${at})`
+  }
+
+  async commit(c: BlobCommit): Promise<CommitResult> {
+    const sql = await this.#client()
+    const conn = await sql.reserve()
+    try {
+      // BEGIN/COMMIT by hand, as migrate does (Bun 1.3.5's reserved-connection begin() leaves failures unhandled).
+      await conn.unsafe("BEGIN")
+      try {
+        await conn`SELECT pg_advisory_xact_lock(${BLOB_LOCK_NAMESPACE}::int, hashtext(${c.userID}))`
+        const touched = await conn`
+          UPDATE artifact_blobs SET touched_at = ${c.at} WHERE user_id = ${c.userID} AND hash = ${c.hash} RETURNING hash`
+        if (touched.length > 0) {
+          if (c.staged > 0) await conn`DELETE FROM artifact_blob_uploads WHERE upload_id = ${c.uploadID}::uuid AND user_id = ${c.userID}`
+          await conn.unsafe("COMMIT")
+          return { kind: "touched" }
+        }
+        const [used] = (await conn`
+          SELECT coalesce(sum(bytes), 0)::float8 AS bytes FROM artifact_blobs WHERE user_id = ${c.userID}`) as { bytes: number }[]
+        const usedBytes = used?.bytes ?? 0
+        if (usedBytes + c.bytes > c.quotaBytes) {
+          await conn.unsafe("ROLLBACK")
+          return { kind: "quota", usedBytes }
+        }
+        await conn`
+          INSERT INTO artifact_blobs (user_id, hash, bytes, chunks, stored_at, touched_at)
+          VALUES (${c.userID}, ${c.hash}, ${c.bytes}, ${c.chunks}, ${c.at}, ${c.at})`
+        if (c.staged > 0) {
+          const adopted = await conn`
+            INSERT INTO artifact_blob_chunks (user_id, hash, chunk, data)
+            SELECT user_id, ${c.hash}, chunk, data FROM artifact_blob_uploads
+            WHERE upload_id = ${c.uploadID}::uuid AND user_id = ${c.userID} AND chunk < ${c.staged}
+            RETURNING chunk`
+          if (adopted.length !== c.staged) throw new Error("the upload's staged chunks are gone (swept or interrupted); try again")
+          await conn`DELETE FROM artifact_blob_uploads WHERE upload_id = ${c.uploadID}::uuid AND user_id = ${c.userID}`
+        }
+        if (c.tail) {
+          await conn`
+            INSERT INTO artifact_blob_chunks (user_id, hash, chunk, data)
+            VALUES (${c.userID}, ${c.hash}, ${c.tail.chunk}, ${bytea(c.tail.data)})`
+        }
+        await conn.unsafe("COMMIT")
+        return { kind: "stored" }
+      } catch (error) {
+        await conn.unsafe("ROLLBACK").catch(() => {})
+        throw error
+      }
+    } finally {
+      conn.release()
+    }
+  }
+
+  async discard(uploadID: string, userID: string): Promise<void> {
+    const sql = await this.#client()
+    await sql`DELETE FROM artifact_blob_uploads WHERE upload_id = ${uploadID}::uuid AND user_id = ${userID}`
+  }
+
+  async sweep(before: number): Promise<number> {
+    const sql = await this.#client()
+    const rows = (await sql`
+      WITH stale AS (
+        SELECT upload_id FROM artifact_blob_uploads GROUP BY upload_id HAVING max(created_at) < ${before}
+      )
+      DELETE FROM artifact_blob_uploads u USING stale WHERE u.upload_id = stale.upload_id
+      RETURNING u.upload_id::text AS id`) as { id: string }[]
+    return new Set(rows.map((r) => r.id)).size
+  }
+
+  async row(userID: string, hash: string): Promise<BlobRow | undefined> {
+    const sql = await this.#client()
+    const [row] = (await sql`
+      SELECT hash, bytes::float8 AS bytes, chunks, stored_at::float8 AS stored_at, touched_at::float8 AS touched_at
+      FROM artifact_blobs WHERE user_id = ${userID} AND hash = ${hash}`) as SqlRow[]
+    return row && fromSql(row)
+  }
+
+  async chunk(userID: string, hash: string, chunk: number): Promise<Uint8Array | undefined> {
+    const sql = await this.#client()
+    const [row] = (await sql`
+      SELECT data FROM artifact_blob_chunks WHERE user_id = ${userID} AND hash = ${hash} AND chunk = ${chunk}`) as { data: Uint8Array }[]
+    return row && new Uint8Array(row.data.buffer, row.data.byteOffset, row.data.byteLength)
+  }
+
+  async touch(userID: string, hash: string, at: number): Promise<boolean> {
+    const sql = await this.#client()
+    const rows = await sql`UPDATE artifact_blobs SET touched_at = ${at} WHERE user_id = ${userID} AND hash = ${hash} RETURNING hash`
+    return rows.length > 0
+  }
+
+  async delete(userID: string, hash: string, touchedBefore?: number): Promise<boolean> {
+    const sql = await this.#client()
+    const rows =
+      touchedBefore === undefined
+        ? await sql`DELETE FROM artifact_blobs WHERE user_id = ${userID} AND hash = ${hash} RETURNING hash`
+        : await sql`DELETE FROM artifact_blobs WHERE user_id = ${userID} AND hash = ${hash} AND touched_at < ${touchedBefore} RETURNING hash`
+    return rows.length > 0
+  }
+
+  async usage(userID: string): Promise<BlobUsage> {
+    const sql = await this.#client()
+    const [row] = (await sql`
+      SELECT count(*)::int AS blobs, coalesce(sum(bytes), 0)::float8 AS bytes FROM artifact_blobs WHERE user_id = ${userID}`) as BlobUsage[]
+    return { blobs: row?.blobs ?? 0, bytes: row?.bytes ?? 0 }
+  }
+
+  async list(userID: string, after: string | undefined, limit: number): Promise<BlobRow[]> {
+    const sql = await this.#client()
+    const rows = (await sql`
+      SELECT hash, bytes::float8 AS bytes, chunks, stored_at::float8 AS stored_at, touched_at::float8 AS touched_at
+      FROM artifact_blobs WHERE user_id = ${userID} AND hash > ${after ?? ""}
+      ORDER BY hash LIMIT ${limit}`) as SqlRow[]
+    return rows.map(fromSql)
+  }
+
+  async close(): Promise<void> {
+    const sql = this.#sql
+    this.#sql = undefined
+    this.#ready = undefined
+    await sql?.close()
+  }
+
+  /** The pool, created on first use, once the schema is current; a failed check is retried by the next call. */
+  async #client(): Promise<SQL> {
+    const sql = (this.#sql ??= new SQL(this.#url, {
+      max: this.#options.max,
+      ...(this.#options.connectionTimeoutSeconds !== undefined ? { connectionTimeout: this.#options.connectionTimeoutSeconds } : {}),
+      ...statementTimeout("PostgresBlobStore", this.#options.statementTimeoutMs),
+    }))
+    this.#ready ??= this.#checkSchema(sql).catch((error: unknown) => {
+      this.#ready = undefined
+      throw error
+    })
+    await this.#ready
+    return sql
+  }
+
+  async #checkSchema(sql: SQL): Promise<void> {
+    const version = this.#options.migrate ? (await migrate(sql)).version : await schemaVersion(sql)
+    if (version < SCHEMA_VERSION) throw new SchemaOutdatedError(version, SCHEMA_VERSION)
+  }
+}

package/src/central/backend/postgres-migrate.ts

@@ -35,6 +35,39 @@ export const MIGRATIONS: readonly Migration[] = [
       );
     `,
   },
+  {
+    // Artifact blobs (HWA-22, ./postgres-blobs): additive, so the previous release keeps working.
+    version: 2,
+    name: "artifact-blobs",
+    up: `
+      CREATE TABLE artifact_blobs (
+        user_id text COLLATE "C" NOT NULL,
+        hash text COLLATE "C" NOT NULL CHECK (hash ~ '^sha256:[0-9a-f]{64}$'),
+        bytes bigint NOT NULL CHECK (bytes >= 0),
+        chunks integer NOT NULL CHECK (chunks >= 0),
+        stored_at bigint NOT NULL,
+        touched_at bigint NOT NULL,
+        PRIMARY KEY (user_id, hash)
+      );
+      CREATE TABLE artifact_blob_chunks (
+        user_id text COLLATE "C" NOT NULL,
+        hash text COLLATE "C" NOT NULL,
+        chunk integer NOT NULL CHECK (chunk >= 0),
+        data bytea NOT NULL,
+        PRIMARY KEY (user_id, hash, chunk),
+        FOREIGN KEY (user_id, hash) REFERENCES artifact_blobs (user_id, hash) ON DELETE CASCADE
+      );
+      CREATE TABLE artifact_blob_uploads (
+        upload_id uuid NOT NULL,
+        chunk integer NOT NULL CHECK (chunk >= 0),
+        user_id text COLLATE "C" NOT NULL,
+        data bytea NOT NULL,
+        created_at bigint NOT NULL,
+        PRIMARY KEY (upload_id, chunk)
+      );
+      CREATE INDEX artifact_blob_uploads_created ON artifact_blob_uploads (created_at);
+    `,
+  },
 ]
 
 /** The schema version this code needs. */

package/src/central/backend/postgres-state.ts

@@ -21,6 +21,22 @@ export interface PostgresStateStoreOptions {
   readonly max?: number
   /** Seconds to wait for a connection (default Bun's). */
   readonly connectionTimeoutSeconds?: number
+  /** Postgres statement_timeout of every connection, ms (default STATEMENT_TIMEOUT_MS; 0 turns it off). */
+  readonly statementTimeoutMs?: number
+}
+
+/**
+ * Default statement_timeout (ms): a statement stuck on the server (a lock that is never released, an overloaded
+ * database) fails with an error instead of holding its caller and a pooled connection for ever. The hub's
+ * statements are small; migrations run under it too.
+ */
+export const STATEMENT_TIMEOUT_MS = 30_000
+
+/** Checks statementTimeoutMs and answers Bun.SQL's `connection` option (startup parameters) for it. */
+export function statementTimeout(owner: string, ms: number | undefined): { connection?: { statement_timeout: number } } {
+  const value = ms ?? STATEMENT_TIMEOUT_MS
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${owner} statementTimeoutMs must be a non-negative integer (0 turns it off)`)
+  return value > 0 ? { connection: { statement_timeout: value } } : {}
 }
 
 /** The database is behind the schema this hub needs. The message names no URL. */
@@ -48,6 +64,7 @@ export class PostgresStateStore implements StateStore {
   readonly #url: string
   readonly #options: Omit<PostgresStateStoreOptions, "url">
   readonly #now: Clock
+  readonly #timeout: { connection?: { statement_timeout: number } }
   #sql?: SQL
   #ready?: Promise<void>
 
@@ -55,6 +72,7 @@ export class PostgresStateStore implements StateStore {
     const { url, ...rest } = options
     this.#url = url
     this.#options = rest
+    this.#timeout = statementTimeout("PostgresStateStore", options.statementTimeoutMs)
     this.#now = options.now ?? Date.now
   }
 
@@ -181,6 +199,7 @@ export class PostgresStateStore implements StateStore {
     const sql = (this.#sql ??= new SQL(this.#url, {
       max: this.#options.max ?? 10,
       ...(this.#options.connectionTimeoutSeconds !== undefined ? { connectionTimeout: this.#options.connectionTimeoutSeconds } : {}),
+      ...this.#timeout,
     }))
     this.#ready ??= this.#checkSchema(sql).catch((error: unknown) => {
       this.#ready = undefined

package/src/central/backend/types.ts

@@ -229,6 +229,12 @@ export interface Catalog {
   entries(userID: string): Promise<CatalogEntry[]>
 }
 
+// ---- BlobStore --------------------------------------------------------------------------------------------
+
+/** Artifact bytes (HWA-20): the contract and its rules live in ../artifacts/blob-store; memory impl ./memory-blobs. */
+export type { BlobBody, BlobDeleteOptions, BlobInfo, BlobListOptions, BlobPutOptions, BlobRead, BlobStore, BlobUsage } from "../artifacts/blob-store"
+import type { BlobStore } from "../artifacts/blob-store"
+
 // ---- Bundle -----------------------------------------------------------------------------------------------
 
 export interface Backends {
@@ -241,6 +247,8 @@ export interface Backends {
   readonly locks: Locks
   readonly catalog: Catalog
   readonly kv: Kv
+  /** Artifact bytes (HWA-21: files standalone, memory in tests; absent in a cluster until HWA-22 → artifacts unsupported). */
+  readonly blobs?: BlobStore
   /** Closes the connections a networked bundle opened (cluster mode); the hub calls it on stop. */
   close?(): Promise<void>
 }