@defrex/autobuild-postgres-store 0.8.0

package/README.md

@@ -0,0 +1,63 @@
+# `@defrex/autobuild-postgres-store`
+
+Serverless-safe Autobuild persistence using PostgreSQL and either an
+S3-compatible object store or Vercel Blob. This is a separate package: installing
+the `@defrex/autobuild` CLI does not install its database/blob provider
+dependencies. A project that embeds the adapter adds it directly:
+
+```sh
+bun add @defrex/autobuild-postgres-store
+```
+
+## Setup
+
+To run the migration from the hosted deployment's own checkout, choose the
+adapter-compatible tag shown in [GitHub Releases](https://github.com/defrex/autobuild/releases),
+then obtain and install that exact repository revision in a dedicated checkout:
+
+```sh
+git clone --depth 1 --branch v0.6.0 --single-branch https://github.com/defrex/autobuild.git autobuild-v0.6.0
+cd autobuild-v0.6.0
+bun install --frozen-lockfile
+DATABASE_URL=postgres://… bun run postgres:migrate
+```
+
+Replace `v0.6.0` with the selected release tag. The migration is idempotent.
+The adapter reads the conventional `DATABASE_URL`, which Vercel's Neon and
+Postgres storage integrations inject; set `AB_POSTGRES_URL` to override it
+explicitly.
+Schema diagnostics refer to the root `postgres:migrate` script in this pinned
+release checkout. The database identity needs permission to create tables,
+constraints, and migration markers during migration and to select, insert,
+update, and delete the resulting tables at runtime. The ticket schema has its
+own version/checksum marker, so migrating an existing BuildStore v1 database
+adds team-scoped tickets, comments, and blockers without replacing the
+established BuildStore marker. Opening against a missing, older/newer, or
+checksum-mismatched schema fails; schema creation is never implicit.
+
+## Concurrency
+
+Identity rows are created conflict-safely before being locked for subsequent
+work. Concurrent repository ensures are idempotent and all return the single
+stored record. Concurrent attempts to create the same build slug produce one
+winner; every other caller receives `build "<slug>" already exists` rather than
+a raw PostgreSQL uniqueness error.
+
+```ts
+import { openPostgresBuildStoreFromEnv } from '@defrex/autobuild-postgres-store'
+
+const store = await openPostgresBuildStoreFromEnv(process.env)
+```
+
+S3 credentials need `GetObject` and `PutObject` on the configured bucket/prefix.
+Only an object-store 404 is treated as absent; authorization and service errors
+are propagated. Vercel supports either a Blob read-write token or a Vercel OIDC
+token paired with its Blob store ID.
+
+`PostgresTicketDatabase.source({ teamKey, claimedState?, createState? })` creates
+a request-bound TicketSource view. The deployment supplies four distinct
+lifecycle names; the defaults are Triage, Ready, Doing, and Done. Ticket bodies
+are stored as PostgreSQL `text` and returned unchanged.
+
+For an authenticated HTTP deployment of this adapter, see the
+[`@defrex/autobuild-hosted-store-service` guide](../hosted-store-service/README.md).

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@defrex/autobuild-postgres-store",
+  "version": "0.8.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./env": {
+      "types": "./src/env.ts",
+      "import": "./src/env.ts"
+    }
+  },
+  "bin": {
+    "ab-postgres-store": "./src/bin.ts"
+  },
+  "peerDependencies": {
+    "@defrex/autobuild": ">=0.7.0"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@vercel/blob": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@defrex/autobuild": {
+      "optional": true
+    }
+  }
+}

package/src/auth-schema.ts

@@ -0,0 +1,238 @@
+import type { SQL } from 'bun'
+
+/** Better Auth 1.4.18 core + MCP/OIDC/JWT plugin PostgreSQL schema. Changes to
+ * the pinned auth package must deliberately update this marker and DDL.
+ *
+ * v3 notes the plugin's declared-schema drift: the pinned 1.4.18 MCP plugin's
+ * DCR endpoint writes `authenticationScheme`
+ * (node_modules/better-auth/dist/plugins/mcp/index.mjs:595) but its declared
+ * `oauthApplication` schema (dist/plugins/oidc-provider/schema.mjs) omits
+ * the field, so the adapter factory's transformInput drops it before either
+ * adapter persists it. Verified dropped, not rejected: the Postgres-gated
+ * MCP e2e passed 9/9 pre-fix and a live memory-adapter DCR probe stored a
+ * row with no `authenticationScheme`. The field declaration in
+ * hosted-store-service's createWebAuth restores it; this column persists it.
+ * Patching the plugin upstream is out of scope. */
+export const AUTH_SCHEMA_VERSION = 3
+
+/** The frozen v1 DDL, kept verbatim so a deployed v1 marker's checksum can be
+ * recognized and upgraded in place (see migratePostgres). */
+export const AUTH_SCHEMA_V1_DDL = `
+CREATE TABLE IF NOT EXISTS ab_auth_schema_migrations (
+  singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
+  version integer NOT NULL, checksum text NOT NULL, applied_at timestamptz NOT NULL
+);
+CREATE TABLE IF NOT EXISTS "user" (
+  id text PRIMARY KEY, name text NOT NULL, email text NOT NULL UNIQUE,
+  "emailVerified" boolean NOT NULL, image text,
+  "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL
+);
+CREATE TABLE IF NOT EXISTS session (
+  id text PRIMARY KEY, "expiresAt" timestamp NOT NULL, token text NOT NULL UNIQUE,
+  "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL,
+  "ipAddress" text, "userAgent" text, "userId" text NOT NULL
+    REFERENCES "user"(id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS account (
+  id text PRIMARY KEY, "accountId" text NOT NULL, "providerId" text NOT NULL,
+  "userId" text NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  "accessToken" text, "refreshToken" text, "idToken" text,
+  "accessTokenExpiresAt" timestamp, "refreshTokenExpiresAt" timestamp,
+  scope text, password text, "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL
+);
+CREATE TABLE IF NOT EXISTS verification (
+  id text PRIMARY KEY, identifier text NOT NULL, value text NOT NULL,
+  "expiresAt" timestamp NOT NULL, "createdAt" timestamp, "updatedAt" timestamp
+);
+CREATE INDEX IF NOT EXISTS session_user_id_idx ON session ("userId");
+CREATE INDEX IF NOT EXISTS account_user_id_idx ON account ("userId");
+CREATE INDEX IF NOT EXISTS verification_identifier_idx ON verification (identifier);`.trim()
+
+export const AUTH_SCHEMA_V1_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(AUTH_SCHEMA_V1_DDL)
+  .digest('hex')
+
+/** The frozen v2 DDL, kept verbatim so a deployed v2 marker's checksum can be
+ * recognized and upgraded in place (see migratePostgres). Byte-identical to
+ * the v2 AUTH_SCHEMA_DDL via the shared v1 interpolation above. */
+export const AUTH_SCHEMA_V2_DDL = `
+${AUTH_SCHEMA_V1_DDL}
+CREATE TABLE IF NOT EXISTS jwks (
+  id text PRIMARY KEY, "publicKey" text NOT NULL, "privateKey" text NOT NULL,
+  "createdAt" timestamp NOT NULL, "expiresAt" timestamp
+);
+CREATE TABLE IF NOT EXISTS "oauthApplication" (
+  id text PRIMARY KEY, name text NOT NULL, icon text, metadata text,
+  "clientId" text NOT NULL UNIQUE, "clientSecret" text,
+  "redirectUrls" text NOT NULL, type text NOT NULL,
+  disabled boolean NOT NULL DEFAULT false,
+  "userId" text REFERENCES "user"(id) ON DELETE CASCADE,
+  "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauthApplication_user_id_idx ON "oauthApplication" ("userId");
+CREATE TABLE IF NOT EXISTS "oauthAccessToken" (
+  id text PRIMARY KEY, "accessToken" text NOT NULL UNIQUE,
+  "refreshToken" text NOT NULL UNIQUE, "accessTokenExpiresAt" timestamp NOT NULL,
+  "refreshTokenExpiresAt" timestamp NOT NULL,
+  "clientId" text NOT NULL REFERENCES "oauthApplication"("clientId") ON DELETE CASCADE,
+  "userId" text REFERENCES "user"(id) ON DELETE CASCADE,
+  scopes text NOT NULL, "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauthAccessToken_client_id_idx ON "oauthAccessToken" ("clientId");
+CREATE INDEX IF NOT EXISTS oauthAccessToken_user_id_idx ON "oauthAccessToken" ("userId");
+CREATE TABLE IF NOT EXISTS "oauthConsent" (
+  id text PRIMARY KEY, "clientId" text NOT NULL
+    REFERENCES "oauthApplication"("clientId") ON DELETE CASCADE,
+  "userId" text NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  scopes text NOT NULL, "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL,
+  "consentGiven" boolean NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauthConsent_user_id_idx ON "oauthConsent" ("userId");`.trim()
+
+export const AUTH_SCHEMA_V2_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(AUTH_SCHEMA_V2_DDL)
+  .digest('hex')
+
+/** v2 adds the four MCP-plugin tables (jwks from the jwt companion): column
+ * names are exactly the camelCase quoted identifiers Better Auth's pg adapter
+ * writes.
+ *
+ * v3 adds the nullable `authenticationScheme` column to `oauthApplication`
+ * (see the header marker): legacy rows legitimately lack the field, so NULL
+ * means "field absent" (the builds.repo_origin precedent) — NOT NULL DEFAULT
+ * would invent scheme values for existing clients. The column rides last so
+ * fresh databases assert identically to v2 databases upgraded by the guarded
+ * ALTER in migratePostgres (the streams.creation_seq precedent). */
+export const AUTH_SCHEMA_DDL = `
+${AUTH_SCHEMA_V1_DDL}
+CREATE TABLE IF NOT EXISTS jwks (
+  id text PRIMARY KEY, "publicKey" text NOT NULL, "privateKey" text NOT NULL,
+  "createdAt" timestamp NOT NULL, "expiresAt" timestamp
+);
+CREATE TABLE IF NOT EXISTS "oauthApplication" (
+  id text PRIMARY KEY, name text NOT NULL, icon text, metadata text,
+  "clientId" text NOT NULL UNIQUE, "clientSecret" text,
+  "redirectUrls" text NOT NULL, type text NOT NULL,
+  disabled boolean NOT NULL DEFAULT false,
+  "userId" text REFERENCES "user"(id) ON DELETE CASCADE,
+  "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL,
+  "authenticationScheme" text
+);
+CREATE INDEX IF NOT EXISTS oauthApplication_user_id_idx ON "oauthApplication" ("userId");
+CREATE TABLE IF NOT EXISTS "oauthAccessToken" (
+  id text PRIMARY KEY, "accessToken" text NOT NULL UNIQUE,
+  "refreshToken" text NOT NULL UNIQUE, "accessTokenExpiresAt" timestamp NOT NULL,
+  "refreshTokenExpiresAt" timestamp NOT NULL,
+  "clientId" text NOT NULL REFERENCES "oauthApplication"("clientId") ON DELETE CASCADE,
+  "userId" text REFERENCES "user"(id) ON DELETE CASCADE,
+  scopes text NOT NULL, "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauthAccessToken_client_id_idx ON "oauthAccessToken" ("clientId");
+CREATE INDEX IF NOT EXISTS oauthAccessToken_user_id_idx ON "oauthAccessToken" ("userId");
+CREATE TABLE IF NOT EXISTS "oauthConsent" (
+  id text PRIMARY KEY, "clientId" text NOT NULL
+    REFERENCES "oauthApplication"("clientId") ON DELETE CASCADE,
+  "userId" text NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  scopes text NOT NULL, "createdAt" timestamp NOT NULL, "updatedAt" timestamp NOT NULL,
+  "consentGiven" boolean NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauthConsent_user_id_idx ON "oauthConsent" ("userId");`.trim()
+
+export const AUTH_SCHEMA_CHECKSUM = new Bun.CryptoHasher('sha256')
+  .update(AUTH_SCHEMA_DDL)
+  .digest('hex')
+
+export async function assertAuthSchema(sql: SQL): Promise<void> {
+  let rows: { version: number; checksum: string }[]
+  try {
+    rows = await sql`SELECT version, checksum FROM ab_auth_schema_migrations WHERE singleton = true`
+  } catch (error) {
+    const code =
+      (error as { code?: string; errno?: string }).errno ?? (error as { code?: string }).code
+    if (code === '42P01')
+      throw new Error('PostgreSQL auth schema is missing; run: bun run postgres:migrate')
+    throw error
+  }
+  const marker = rows[0]
+  if (
+    !marker ||
+    Number(marker.version) !== AUTH_SCHEMA_VERSION ||
+    marker.checksum !== AUTH_SCHEMA_CHECKSUM
+  ) {
+    throw new Error(
+      'PostgreSQL auth schema marker is incompatible; run the migration from this release',
+    )
+  }
+  const columns: { table_name: string; column_name: string }[] = await sql`
+    SELECT table_name, column_name FROM information_schema.columns
+    WHERE table_schema = current_schema()
+      AND table_name = ANY(ARRAY['user', 'session', 'account', 'verification', 'jwks',
+        'oauthApplication', 'oauthAccessToken', 'oauthConsent'])
+    ORDER BY table_name, ordinal_position`
+  const expected = {
+    account: [
+      'id',
+      'accountId',
+      'providerId',
+      'userId',
+      'accessToken',
+      'refreshToken',
+      'idToken',
+      'accessTokenExpiresAt',
+      'refreshTokenExpiresAt',
+      'scope',
+      'password',
+      'createdAt',
+      'updatedAt',
+    ],
+    jwks: ['id', 'publicKey', 'privateKey', 'createdAt', 'expiresAt'],
+    oauthApplication: [
+      'id',
+      'name',
+      'icon',
+      'metadata',
+      'clientId',
+      'clientSecret',
+      'redirectUrls',
+      'type',
+      'disabled',
+      'userId',
+      'createdAt',
+      'updatedAt',
+      // Rides last: the guarded v2→v3 ALTER appends it at the end, so
+      // migrated and fresh databases assert identically.
+      'authenticationScheme',
+    ],
+    oauthAccessToken: [
+      'id',
+      'accessToken',
+      'refreshToken',
+      'accessTokenExpiresAt',
+      'refreshTokenExpiresAt',
+      'clientId',
+      'userId',
+      'scopes',
+      'createdAt',
+      'updatedAt',
+    ],
+    oauthConsent: ['id', 'clientId', 'userId', 'scopes', 'createdAt', 'updatedAt', 'consentGiven'],
+    session: [
+      'id',
+      'expiresAt',
+      'token',
+      'createdAt',
+      'updatedAt',
+      'ipAddress',
+      'userAgent',
+      'userId',
+    ],
+    user: ['id', 'name', 'email', 'emailVerified', 'image', 'createdAt', 'updatedAt'],
+    verification: ['id', 'identifier', 'value', 'expiresAt', 'createdAt', 'updatedAt'],
+  }
+  for (const [table, names] of Object.entries(expected)) {
+    const actual = columns.filter((row) => row.table_name === table).map((row) => row.column_name)
+    if (JSON.stringify(actual) !== JSON.stringify(names)) {
+      throw new Error(`PostgreSQL auth schema table ${table} is missing or mismatched`)
+    }
+  }
+}

package/src/bin.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+import { describePostgresTarget, resolvePostgresUrl } from './env'
+import { migratePostgres } from './schema'
+
+async function main(): Promise<void> {
+  if (process.argv.length !== 3 || process.argv[2] !== 'migrate') {
+    throw new Error('usage: ab-postgres-store migrate')
+  }
+  const url = resolvePostgresUrl(process.env)
+  await migratePostgres(url)
+  console.log(`Autobuild PostgreSQL schema is ready on ${describePostgresTarget(url)}`)
+}
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+})

package/src/blobs.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test'
+import { GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3'
+import { describeBlobStoreContract } from '@defrex/autobuild/plugin-sdk'
+import { Buffer } from 'node:buffer'
+import { S3BlobStore } from './s3'
+import { VercelBlobStore } from './vercel'
+
+function s3Harness(): S3BlobStore {
+  const data = new Map<string, Uint8Array>()
+  const client = {
+    async send(command: unknown): Promise<unknown> {
+      if (command instanceof PutObjectCommand) {
+        data.set(String(command.input.Key), new Uint8Array(command.input.Body as Uint8Array))
+        return {}
+      }
+      if (command instanceof GetObjectCommand) {
+        const value = data.get(String(command.input.Key))
+        if (!value) {
+          const error = new Error('not found') as Error & { $metadata: { httpStatusCode: number } }
+          error.$metadata = { httpStatusCode: 404 }
+          throw error
+        }
+        return { Body: { transformToByteArray: async () => value.slice() } }
+      }
+      throw new Error('unexpected command')
+    },
+  }
+  return new S3BlobStore({ client: client as never, bucket: 'builds', prefix: '/ab//blobs/' })
+}
+
+function vercelHarness(): VercelBlobStore {
+  const data = new Map<string, Uint8Array>()
+  return new VercelBlobStore({
+    access: 'private',
+    prefix: 'ab/blobs',
+    put: (async (pathname: string, body: unknown) => {
+      if (!Buffer.isBuffer(body)) throw new TypeError('Vercel PutBody must be a Buffer')
+      data.set(pathname, Uint8Array.from(body))
+      return {
+        url: pathname,
+        downloadUrl: pathname,
+        pathname,
+        contentType: 'application/octet-stream',
+        contentDisposition: '',
+        size: 0,
+        uploadedAt: new Date(),
+      }
+    }) as never,
+    get: (async (pathname: string) => {
+      const value = data.get(pathname)
+      if (!value) return null
+      return {
+        statusCode: 200,
+        stream: new Blob([Uint8Array.from(value)]).stream(),
+        headers: new Headers(),
+        blob: {
+          url: pathname,
+          downloadUrl: pathname,
+          pathname,
+          contentType: 'application/octet-stream',
+          contentDisposition: '',
+          size: value.length,
+          uploadedAt: new Date(),
+          etag: 'x',
+          cacheControl: 'public',
+        },
+      }
+    }) as never,
+  })
+}
+
+describeBlobStoreContract('S3-compatible', async () => ({ blobs: s3Harness() }))
+describeBlobStoreContract('Vercel Blob', async () => ({ blobs: vercelHarness() }))
+
+describe('provider request mapping', () => {
+  test('S3 uses the configured bucket and normalized deterministic key', async () => {
+    let seen: PutObjectCommand | undefined
+    const blobs = new S3BlobStore({
+      bucket: 'bucket',
+      prefix: '//prefix//',
+      client: {
+        send: async (command: unknown) => {
+          seen = command as PutObjectCommand
+          return {}
+        },
+      } as never,
+    })
+    await blobs.put('abc', new Uint8Array([1]))
+    expect(seen?.input).toMatchObject({ Bucket: 'bucket', Key: 'prefix/abc' })
+  })
+
+  test('Vercel uploads binary bytes as a supported Buffer with deterministic options', async () => {
+    let pathname: string | undefined
+    let body: Buffer | undefined
+    let options: Record<string, unknown> | undefined
+    const blobs = new VercelBlobStore({
+      access: 'public',
+      prefix: '//prefix//',
+      token: 'secret',
+      put: (async (seenPath: string, seenBody: unknown, opts: Record<string, unknown>) => {
+        if (!Buffer.isBuffer(seenBody)) throw new TypeError('Vercel PutBody must be a Buffer')
+        pathname = seenPath
+        body = seenBody
+        options = opts
+        return {}
+      }) as never,
+      get: (async () => null) as never,
+    })
+    const bytes = new Uint8Array([0x00, 0x80, 0xff, 0x41])
+    await blobs.put('abc', bytes)
+    expect(pathname).toBe('prefix/abc')
+    expect(Buffer.isBuffer(body)).toBe(true)
+    expect([...body!]).toEqual([...bytes])
+    expect(options).toMatchObject({
+      access: 'public',
+      token: 'secret',
+      addRandomSuffix: false,
+      allowOverwrite: true,
+    })
+  })
+})

package/src/config.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from 'bun:test'
+import { parsePostgresStoreEnv } from './config'
+
+const base = { AB_POSTGRES_URL: 'postgres://db/app' }
+
+describe('PostgreSQL store environment', () => {
+  test('parses explicit S3-compatible configuration', () => {
+    expect(
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 's3',
+        AB_S3_BUCKET: 'bucket',
+        AB_S3_REGION: 'region',
+        AB_S3_ENDPOINT: 'https://objects.example',
+        AB_S3_ACCESS_KEY_ID: 'key',
+        AB_S3_SECRET_ACCESS_KEY: 'secret',
+        AB_S3_SESSION_TOKEN: 'session',
+        AB_S3_FORCE_PATH_STYLE: 'true',
+        AB_BLOB_PREFIX: '/builds/',
+      }),
+    ).toEqual({
+      url: 'postgres://db/app',
+      backend: 's3',
+      bucket: 'bucket',
+      region: 'region',
+      endpoint: 'https://objects.example',
+      accessKeyId: 'key',
+      secretAccessKey: 'secret',
+      sessionToken: 'session',
+      forcePathStyle: true,
+      prefix: '/builds/',
+    })
+  })
+
+  test('supports token and complete OIDC Vercel authentication', () => {
+    expect(
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 'vercel',
+        AB_VERCEL_BLOB_ACCESS: 'private',
+        BLOB_READ_WRITE_TOKEN: 'rw',
+      }),
+    ).toMatchObject({ backend: 'vercel', access: 'private', token: 'rw' })
+    expect(
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 'vercel',
+        AB_VERCEL_BLOB_ACCESS: 'public',
+        VERCEL_OIDC_TOKEN: 'oidc',
+        BLOB_STORE_ID: 'store',
+      }),
+    ).toMatchObject({ backend: 'vercel', access: 'public', oidcToken: 'oidc', storeId: 'store' })
+  })
+
+  test('rejects missing, malformed, and incomplete values', () => {
+    expect(() => parsePostgresStoreEnv({ AB_BLOB_BACKEND: 's3' })).toThrow('AB_POSTGRES_URL')
+    expect(() => parsePostgresStoreEnv({ ...base, AB_BLOB_BACKEND: 'other' })).toThrow('s3')
+    expect(() =>
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 's3',
+        AB_S3_BUCKET: 'b',
+        AB_S3_REGION: 'r',
+        AB_S3_ACCESS_KEY_ID: 'k',
+        AB_S3_SECRET_ACCESS_KEY: 's',
+        AB_S3_FORCE_PATH_STYLE: 'yes',
+      }),
+    ).toThrow('true')
+    expect(() =>
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 'vercel',
+        AB_VERCEL_BLOB_ACCESS: 'private',
+        VERCEL_OIDC_TOKEN: 'only',
+      }),
+    ).toThrow('BLOB_STORE_ID')
+  })
+
+  test('accepts the conventional DATABASE_URL but never ambient AWS credentials', () => {
+    expect(
+      parsePostgresStoreEnv({
+        DATABASE_URL: 'postgres://ambient',
+        AB_BLOB_BACKEND: 'vercel',
+        AB_VERCEL_BLOB_ACCESS: 'private',
+        BLOB_READ_WRITE_TOKEN: 'token',
+      }).url,
+    ).toBe('postgres://ambient')
+    expect(
+      parsePostgresStoreEnv({
+        ...base,
+        DATABASE_URL: 'postgres://ambient',
+        AB_BLOB_BACKEND: 'vercel',
+        AB_VERCEL_BLOB_ACCESS: 'private',
+        BLOB_READ_WRITE_TOKEN: 'token',
+      }).url,
+    ).toBe('postgres://db/app')
+    expect(() =>
+      parsePostgresStoreEnv({
+        DATABASE_URL: 'postgres://ambient',
+        AB_BLOB_BACKEND: 's3',
+        AB_S3_BUCKET: 'b',
+        AB_S3_REGION: 'r',
+        AWS_ACCESS_KEY_ID: 'ambient',
+        AWS_SECRET_ACCESS_KEY: 'ambient',
+      }),
+    ).toThrow('AB_S3_ACCESS_KEY_ID')
+    expect(() => parsePostgresStoreEnv({ AB_BLOB_BACKEND: 's3' })).toThrow(
+      'AB_POSTGRES_URL or DATABASE_URL',
+    )
+  })
+
+  test('AB_ARTIFACT_RETENTION_MAX_REVISIONS: absent means default, valid flows through, invalid rejected', () => {
+    // Absent ⇒ no retention override; the store's documented default applies.
+    expect(
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 'vercel',
+        AB_VERCEL_BLOB_ACCESS: 'private',
+        BLOB_READ_WRITE_TOKEN: 'rw',
+      }).retention,
+    ).toBeUndefined()
+
+    // A valid value flows through to the retention option on either backend.
+    expect(
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 's3',
+        AB_S3_BUCKET: 'bucket',
+        AB_S3_REGION: 'region',
+        AB_S3_ACCESS_KEY_ID: 'key',
+        AB_S3_SECRET_ACCESS_KEY: 'secret',
+        AB_ARTIFACT_RETENTION_MAX_REVISIONS: ' 50 ',
+      }).retention,
+    ).toEqual({ maxRevisions: 50 })
+    expect(
+      parsePostgresStoreEnv({
+        ...base,
+        AB_BLOB_BACKEND: 'vercel',
+        AB_VERCEL_BLOB_ACCESS: 'private',
+        BLOB_READ_WRITE_TOKEN: 'rw',
+        AB_ARTIFACT_RETENTION_MAX_REVISIONS: '1',
+      }).retention,
+    ).toEqual({ maxRevisions: 1 })
+
+    // Non-integer, zero, and negative values are rejected with the variable named.
+    // (A blank value is treated as absent, matching this file's optional() convention.)
+    for (const bad of ['zero', '0', '-5', '2.5']) {
+      expect(() =>
+        parsePostgresStoreEnv({
+          ...base,
+          AB_BLOB_BACKEND: 'vercel',
+          AB_VERCEL_BLOB_ACCESS: 'private',
+          BLOB_READ_WRITE_TOKEN: 'rw',
+          AB_ARTIFACT_RETENTION_MAX_REVISIONS: bad,
+        }),
+      ).toThrow('AB_ARTIFACT_RETENTION_MAX_REVISIONS')
+    }
+  })
+
+  test('root full-stack manifest has no blob provider SDK dependency', async () => {
+    const manifest = (await Bun.file('package.json').json()) as {
+      dependencies?: Record<string, string>
+    }
+    const names = Object.keys(manifest.dependencies ?? {})
+    expect(names).not.toContain('@aws-sdk/client-s3')
+    expect(names).not.toContain('@vercel/blob')
+    expect(names).not.toContain('pg')
+    expect(names).not.toContain('postgres')
+    const hosted = (await Bun.file('packages/hosted-store-service/package.json').json()) as {
+      dependencies?: Record<string, string>
+    }
+    expect(hosted.dependencies?.pg).toBe('8.18.0')
+  })
+})