@supacloud/lite 0.7.3 → 0.8.1

package/dist/index.js

@@ -85,8 +85,8 @@ function randomToken(bytes = 32) {
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.7.3",
-  description: "Bun-native, single-project Supabase-compatible backend powered by PGlite",
+  version: "0.8.1",
+  description: "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   type: "module",
   license: "Apache-2.0",
   bin: {
@@ -122,6 +122,10 @@ var package_default = {
     dev: "bun run src/cli.ts start",
     start: "bun run src/cli.ts start",
     test: "bun test --timeout 20000",
+    "test:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun test test/native-engine.test.ts --timeout 180000",
+    parity: "bun run parity/harness.ts",
+    "parity:native": "SUPACLOUD_LITE_TEST_NATIVE=1 bun run parity/harness.ts --engine native",
+    "check:native": "bun run test:native && bun run parity:native",
     "test:package": "bun run scripts/package-smoke.ts",
     "test:standalone": "bun run scripts/standalone-smoke.ts",
     prepack: "bun run build",
@@ -1297,7 +1301,8 @@ class AuthHandler {
         return await this.oauth.authorize(url);
       }
       if (path === "callback" && (method === "GET" || method === "POST")) {
-        return await this.oauth.callback(url, (userId) => this.sessionTokensFor(userId));
+        const callbackUrl = method === "POST" ? await this.oauthCallbackUrl(req, url) : url;
+        return await this.oauth.callback(callbackUrl, (userId) => this.oauthSessionTokensFor(userId));
       }
       if (path.startsWith("admin/"))
         return await this.admin(req, ctx, path, method);
@@ -1307,6 +1312,16 @@ class AuthHandler {
       return authError(500, "unexpected_failure", msg);
     }
   }
+  async oauthCallbackUrl(req, url) {
+    const callbackUrl = new URL(url);
+    const form = await req.formData();
+    for (const field of ["code", "state"]) {
+      const value = form.get(field);
+      if (typeof value === "string" && value)
+        callbackUrl.searchParams.set(field, value);
+    }
+    return callbackUrl;
+  }
   async signup(req) {
     const body = await req.json().catch(() => ({}));
     if (!body.email && !body.password) {
@@ -1384,7 +1399,7 @@ class AuthHandler {
       if (!userId)
         return authError(403, "flow_state_not_found", "invalid or expired auth code");
       const ures = await this.db.query(`select * from auth.users where id = $1`, [userId]);
-      return json(200, await this.sessionFor(ures.rows[0]));
+      return json(200, await this.sessionForOAuth(ures.rows[0]));
     }
     return authError(400, "invalid_grant", `unsupported grant_type: ${grantType}`);
   }
@@ -1429,17 +1444,18 @@ class AuthHandler {
       sets.push(`is_anonymous = false`);
       sets.push(`raw_app_meta_data = coalesce(raw_app_meta_data, '{}'::jsonb) || '{"provider":"email","providers":["email"]}'::jsonb`);
     }
-    if (sets.length === 0)
-      return json(200, this.userJson(user));
-    params.push(user.id);
-    const res = await this.db.query(`update auth.users set ${sets.join(", ")}, updated_at = now() where id = $${params.length} returning *`, params);
-    const updated = res.rows[0];
-    if (upgradingAnon) {
-      await this.db.query(`insert into auth.identities (user_id, provider, provider_id, identity_data)
-         values ($1, 'email', $2, $3)
-         on conflict (provider, provider_id) do nothing`, [updated.id, updated.id, JSON.stringify({ sub: updated.id, email: updated.email })]);
+    if (sets.length === 0) {
+      return json(200, this.userJson(user, await this.getUserFactors(user.id), await this.getUserIdentities(user.id)));
     }
-    return json(200, this.userJson(updated));
+    params.push(user.id);
+    const payload = await this.db.transaction(async (query) => {
+      const res = await query(`update auth.users set ${sets.join(", ")}, updated_at = now() where id = $${params.length} returning *`, params);
+      const updated = res.rows[0];
+      if (body.email)
+        await this.ensureEmailIdentity(updated, query);
+      return this.userJsonWithRelations(updated, query);
+    });
+    return json(200, payload);
   }
   async logout(req, url) {
     const claims = await this.claimsFromBearer(req);
@@ -1469,7 +1485,7 @@ class AuthHandler {
     let user = res.rows[0];
     if (!user) {
       if (!createUser)
-        return authError(422, "otp_disabled", "Signups not allowed for otp");
+        return json(200, {});
       if (this.settings.disableSignup)
         return authError(422, "signup_disabled", "Signups not allowed for this instance");
       res = await this.db.query(`insert into auth.users (aud, role, email, raw_app_meta_data, raw_user_meta_data)
@@ -1801,6 +1817,8 @@ Or sign in with this link: ${link}`
     }
     const idMatch = path.match(/^admin\/users\/([0-9a-f-]{36})$/);
     const exportMatch = path.match(/^admin\/users\/([0-9a-f-]{36})\/export$/);
+    const factorsMatch = path.match(/^admin\/users\/([0-9a-f-]{36})\/factors$/);
+    const factorMatch = path.match(/^admin\/users\/([0-9a-f-]{36})\/factors\/([0-9a-f-]{36})$/);
     if (path === "admin/generate_link" && method === "POST") {
       return await this.generateAdminMagicLink(req);
     }
@@ -1812,32 +1830,49 @@ Or sign in with this link: ${link}`
     if (exportMatch && method === "GET") {
       return await this.exportUser(exportMatch[1]);
     }
+    if (factorsMatch && method === "GET") {
+      const user = await this.db.query(`select 1 from auth.users where id = $1`, [factorsMatch[1]]);
+      if (user.rows.length === 0)
+        return authError(404, "user_not_found", "User not found");
+      return json(200, await this.getUserFactors(factorsMatch[1]));
+    }
+    if (factorMatch && method === "DELETE") {
+      const deleted = await this.db.query(`delete from auth.mfa_factors where user_id = $1 and id = $2 returning id`, [factorMatch[1], factorMatch[2]]);
+      if (deleted.rows.length === 0)
+        return authError(404, "mfa_factor_not_found", "MFA factor not found");
+      return json(200, { id: factorMatch[2] });
+    }
     if (path === "admin/users" && method === "GET") {
       const res = await this.db.query(`select * from auth.users order by created_at desc limit 1000`);
-      return json(200, { users: res.rows.map((u) => this.userJson(u)), aud: "authenticated" });
+      return json(200, { users: res.rows.map((user) => this.userJson(user)), aud: "authenticated" });
     }
     if (path === "admin/users" && method === "POST") {
       const body = await req.json().catch(() => ({}));
       if (!body.email)
         return authError(400, "validation_failed", "email is required");
       const hashed = body.password ? await hashPassword(body.password) : null;
-      const res = await this.db.query(`insert into auth.users
-           (aud, role, email, encrypted_password, email_confirmed_at, raw_app_meta_data, raw_user_meta_data)
-         values ('authenticated', 'authenticated', $1, $2, case when $3 then now() else null end, $4, $5)
-         returning *`, [
-        body.email.toLowerCase().trim(),
-        hashed,
-        body.email_confirm ?? true,
-        JSON.stringify({ provider: "email", providers: ["email"], ...body.app_metadata ?? {} }),
-        JSON.stringify(body.user_metadata ?? {})
-      ]);
-      return json(200, this.userJson(res.rows[0]));
+      const created = await this.db.transaction(async (query) => {
+        const res = await query(`insert into auth.users
+             (aud, role, email, encrypted_password, email_confirmed_at, raw_app_meta_data, raw_user_meta_data)
+           values ('authenticated', 'authenticated', $1, $2, case when $3 then now() else null end, $4, $5)
+           returning *`, [
+          body.email.toLowerCase().trim(),
+          hashed,
+          body.email_confirm ?? true,
+          JSON.stringify({ provider: "email", providers: ["email"], ...body.app_metadata ?? {} }),
+          JSON.stringify(body.user_metadata ?? {})
+        ]);
+        const user = res.rows[0];
+        await this.ensureEmailIdentity(user, query);
+        return this.userJsonWithRelations(user, query);
+      });
+      return json(200, created);
     }
     if (idMatch && method === "GET") {
       const res = await this.db.query(`select * from auth.users where id = $1`, [idMatch[1]]);
       if (res.rows.length === 0)
         return authError(404, "user_not_found", "User not found");
-      return json(200, this.userJson(res.rows[0]));
+      return json(200, await this.userJsonWithRelations(res.rows[0]));
     }
     if (idMatch && method === "PUT") {
       const body = await req.json().catch(() => ({}));
@@ -1864,10 +1899,18 @@ Or sign in with this link: ${link}`
       if (sets.length === 0)
         return authError(400, "validation_failed", "nothing to update");
       params.push(idMatch[1]);
-      const res = await this.db.query(`update auth.users set ${sets.join(", ")}, updated_at = now() where id = $${params.length} returning *`, params);
-      if (res.rows.length === 0)
+      const updated = await this.db.transaction(async (query) => {
+        const res = await query(`update auth.users set ${sets.join(", ")}, updated_at = now() where id = $${params.length} returning *`, params);
+        const user = res.rows[0];
+        if (!user)
+          return null;
+        if (typeof body.email === "string")
+          await this.ensureEmailIdentity(user, query);
+        return this.userJsonWithRelations(user, query);
+      });
+      if (!updated)
         return authError(404, "user_not_found", "User not found");
-      return json(200, this.userJson(res.rows[0]));
+      return json(200, updated);
     }
     if (idMatch && method === "DELETE") {
       return await this.eraseUser(idMatch[1]);
@@ -2063,17 +2106,26 @@ Or sign in with this link: ${link}`
     if (!await verifyTotp(factor.secret, body.code ?? "")) {
       return authError(422, "mfa_verification_failed", "Invalid TOTP code entered");
     }
-    await this.db.query(`update auth.mfa_challenges set verified_at = now() where id = $1`, [challenge.id]);
-    if (factor.status !== "verified") {
-      await this.db.query(`update auth.mfa_factors set status = 'verified', updated_at = now() where id = $1`, [factorId]);
-    }
-    const session = await this.sessionFor(user, undefined, {
-      aal: "aal2",
-      amr: [
-        { method: "password", timestamp: Math.floor(Date.now() / 1000) },
-        { method: "totp", timestamp: Math.floor(Date.now() / 1000) }
-      ]
+    const session = await this.db.transaction(async (query) => {
+      const claimed = await query(`update auth.mfa_challenges set verified_at = now()
+         where id = $1 and factor_id = $2 and verified_at is null and expires_at >= now()
+         returning id`, [challenge.id, factorId]);
+      if (claimed.rows.length === 0)
+        return null;
+      if (factor.status !== "verified") {
+        await query(`update auth.mfa_factors set status = 'verified', updated_at = now() where id = $1`, [factorId]);
+      }
+      return this.sessionFor(user, undefined, {
+        aal: "aal2",
+        amr: [
+          { method: "password", timestamp: Math.floor(Date.now() / 1000) },
+          { method: "totp", timestamp: Math.floor(Date.now() / 1000) }
+        ]
+      }, query);
     });
+    if (!session) {
+      return authError(422, "mfa_verification_failed", "This challenge has already been verified");
+    }
     return json(200, session);
   }
   async unenrollFactor(req, factorId) {
@@ -2111,6 +2163,17 @@ Or sign in with this link: ${link}`
       updated_at: iso(r.updated_at)
     }));
   }
+  async ensureEmailIdentity(user, query = (sql, params) => this.db.query(sql, params)) {
+    if (!user.email)
+      return;
+    await query(`insert into auth.identities (user_id, provider, provider_id, identity_data)
+       values ($1::uuid, 'email', $1::text, $2::jsonb)
+       on conflict (provider, provider_id) do update
+       set identity_data = excluded.identity_data, updated_at = now()`, [user.id, JSON.stringify({ sub: user.id, email: user.email })]);
+  }
+  async userJsonWithRelations(user, query = (sql, params) => this.db.query(sql, params)) {
+    return this.userJson(user, await this.getUserFactors(user.id, query), await this.getUserIdentities(user.id, query));
+  }
   async rotateRefreshToken(token) {
     return this.db.transaction(async (query) => {
       const claimedToken = await this.claimRefreshToken(query, token);
@@ -2184,9 +2247,14 @@ Or sign in with this link: ${link}`
       is_anonymous: u.is_anonymous ?? false
     };
   }
-  async sessionTokensFor(userId) {
+  sessionForOAuth(user) {
+    return this.sessionFor(user, undefined, {
+      amr: [{ method: "oauth", timestamp: Math.floor(Date.now() / 1000) }]
+    });
+  }
+  async oauthSessionTokensFor(userId) {
     const res = await this.db.query(`select * from auth.users where id = $1`, [userId]);
-    const session = await this.sessionFor(res.rows[0]);
+    const session = await this.sessionForOAuth(res.rows[0]);
     return { access_token: session.access_token, refresh_token: session.refresh_token, expires_in: session.expires_in };
   }
   async sessionFor(user, parentToken, opts, query = (sql, params) => this.db.query(sql, params)) {
@@ -3550,41 +3618,1158 @@ $pgmq$;
 revoke all on all functions in schema pgmq from public, anon, authenticated;
 grant execute on all functions in schema pgmq to service_role;
 
-create schema if not exists pgmq_public;
-grant usage on schema pgmq_public to anon, authenticated, service_role;
-
-create or replace function pgmq_public.send(queue_name text, message jsonb, sleep_seconds integer default 0)
-returns setof bigint language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
-  select * from pgmq.send(queue_name, message, sleep_seconds);
-$pgmq_public$;
-
-create or replace function pgmq_public.send_batch(queue_name text, messages jsonb[], sleep_seconds integer default 0)
-returns setof bigint language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
-  select * from pgmq.send_batch(queue_name, messages, sleep_seconds);
-$pgmq_public$;
-
-create or replace function pgmq_public.read(queue_name text, sleep_seconds integer, n integer)
-returns setof pgmq.message_record language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
-  select * from pgmq.read(queue_name, sleep_seconds, n);
-$pgmq_public$;
-
-create or replace function pgmq_public.pop(queue_name text)
-returns setof pgmq.message_record language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
-  select * from pgmq.pop(queue_name);
-$pgmq_public$;
-
-create or replace function pgmq_public.archive(queue_name text, message_id bigint)
-returns boolean language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
-  select pgmq.archive(queue_name, message_id);
-$pgmq_public$;
-
-create or replace function pgmq_public."delete"(queue_name text, message_id bigint)
-returns boolean language sql volatile security definer set search_path = pgmq, pg_catalog, public as $pgmq_public$
-  select pgmq.delete(queue_name, message_id);
-$pgmq_public$;
-
-revoke all on all functions in schema pgmq_public from public;
-grant execute on all functions in schema pgmq_public to anon, authenticated, service_role;
+-- supacloud:sql-module:pgmq-public:start
+DO $pgmq_extension$
+BEGIN
+  IF to_regprocedure('pgmq.send(text,jsonb,integer)') IS NULL THEN
+    EXECUTE 'CREATE EXTENSION IF NOT EXISTS pgmq';
+  END IF;
+END
+$pgmq_extension$;
+
+CREATE SCHEMA IF NOT EXISTS pgmq_public;
+GRANT USAGE ON SCHEMA pgmq_public TO anon, authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION pgmq_public.require_public_queue(queue_name text)
+RETURNS text
+LANGUAGE plpgsql
+IMMUTABLE
+SET search_path = ''
+AS $$
+DECLARE
+  normalized_queue_name text := lower(btrim(queue_name));
+BEGIN
+  IF normalized_queue_name IS NULL
+     OR left(normalized_queue_name, char_length('supacloud_internal_')) = 'supacloud_internal_' THEN
+    RAISE EXCEPTION 'SUPACLOUD_QUEUE_NAME_RESERVED' USING ERRCODE = '42501';
+  END IF;
+  RETURN normalized_queue_name;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION pgmq_public.send(queue_name text, message jsonb, sleep_seconds integer DEFAULT 0)
+RETURNS SETOF bigint
+LANGUAGE sql
+VOLATILE
+SECURITY DEFINER
+SET search_path = ''
+AS $$ SELECT * FROM pgmq.send(pgmq_public.require_public_queue(queue_name), message, sleep_seconds); $$;
+
+CREATE OR REPLACE FUNCTION pgmq_public.send_batch(queue_name text, messages jsonb[], sleep_seconds integer DEFAULT 0)
+RETURNS SETOF bigint
+LANGUAGE sql
+VOLATILE
+SECURITY DEFINER
+SET search_path = ''
+AS $$ SELECT * FROM pgmq.send_batch(pgmq_public.require_public_queue(queue_name), messages, sleep_seconds); $$;
+
+CREATE OR REPLACE FUNCTION pgmq_public.read(queue_name text, sleep_seconds integer, n integer)
+RETURNS SETOF pgmq.message_record
+LANGUAGE sql
+VOLATILE
+SECURITY DEFINER
+SET search_path = ''
+AS $$ SELECT * FROM pgmq.read(pgmq_public.require_public_queue(queue_name), sleep_seconds, n); $$;
+
+CREATE OR REPLACE FUNCTION pgmq_public.pop(queue_name text)
+RETURNS SETOF pgmq.message_record
+LANGUAGE sql
+VOLATILE
+SECURITY DEFINER
+SET search_path = ''
+AS $$ SELECT * FROM pgmq.pop(pgmq_public.require_public_queue(queue_name)); $$;
+
+CREATE OR REPLACE FUNCTION pgmq_public.archive(queue_name text, message_id bigint)
+RETURNS boolean
+LANGUAGE sql
+VOLATILE
+SECURITY DEFINER
+SET search_path = ''
+AS $$ SELECT pgmq.archive(pgmq_public.require_public_queue(queue_name), message_id); $$;
+
+CREATE OR REPLACE FUNCTION pgmq_public."delete"(queue_name text, message_id bigint)
+RETURNS boolean
+LANGUAGE sql
+VOLATILE
+SECURITY DEFINER
+SET search_path = ''
+AS $$ SELECT pgmq.delete(pgmq_public.require_public_queue(queue_name), message_id); $$;
+
+REVOKE ALL ON ALL FUNCTIONS IN SCHEMA pgmq_public FROM PUBLIC;
+GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA pgmq_public TO anon, authenticated, service_role;
+-- supacloud:sql-module:pgmq-public:end
+`;
+var WORKFLOWS_SQL = `
+-- supacloud:sql-module:workflows-public:start
+DO $pgmq_extension$
+BEGIN
+  IF to_regprocedure('pgmq.send(text,jsonb,integer)') IS NULL THEN
+    EXECUTE 'CREATE EXTENSION IF NOT EXISTS pgmq';
+  END IF;
+END
+$pgmq_extension$;
+CREATE SCHEMA IF NOT EXISTS supacloud_workflows;
+REVOKE ALL ON SCHEMA supacloud_workflows FROM PUBLIC, anon, authenticated;
+GRANT USAGE ON SCHEMA supacloud_workflows TO service_role;
+
+SELECT pgmq.create('supacloud_internal_workflows');
+
+CREATE TABLE IF NOT EXISTS supacloud_workflows.runs (
+  id uuid PRIMARY KEY,
+  workflow_name text NOT NULL
+    CHECK (workflow_name ~ '^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$'),
+  workflow_version text NOT NULL
+    CHECK (char_length(workflow_version) BETWEEN 1 AND 80),
+  status text NOT NULL DEFAULT 'queued'
+    CHECK (status IN ('queued', 'running', 'completed', 'failed', 'cancelled')),
+  input jsonb NOT NULL DEFAULT '{}'::jsonb
+    CHECK (jsonb_typeof(input) = 'object'),
+  output jsonb NOT NULL DEFAULT '{}'::jsonb
+    CHECK (jsonb_typeof(output) = 'object'),
+  error_message text NOT NULL DEFAULT ''
+    CHECK (char_length(error_message) <= 4000),
+  row_version bigint NOT NULL DEFAULT 1 CHECK (row_version > 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  started_at timestamptz,
+  completed_at timestamptz,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS supacloud_workflows.steps (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  run_id uuid NOT NULL REFERENCES supacloud_workflows.runs(id) ON DELETE CASCADE,
+  step_key text NOT NULL
+    CHECK (step_key ~ '^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$'),
+  status text NOT NULL DEFAULT 'queued'
+    CHECK (status IN ('queued', 'running', 'completed', 'failed', 'dead_lettered', 'cancelled')),
+  input jsonb NOT NULL DEFAULT '{}'::jsonb
+    CHECK (jsonb_typeof(input) = 'object'),
+  output jsonb NOT NULL DEFAULT '{}'::jsonb
+    CHECK (jsonb_typeof(output) = 'object'),
+  error_message text NOT NULL DEFAULT ''
+    CHECK (char_length(error_message) <= 4000),
+  attempts integer NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+  max_attempts integer NOT NULL DEFAULT 3 CHECK (max_attempts BETWEEN 1 AND 100),
+  retry_delay_seconds integer NOT NULL DEFAULT 0
+    CHECK (retry_delay_seconds BETWEEN 0 AND 86400),
+  queue_message_id bigint NOT NULL UNIQUE,
+  claimed_by text,
+  claimed_at timestamptz,
+  completed_at timestamptz,
+  next_step_key text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (run_id, step_key)
+);
+
+ALTER TABLE supacloud_workflows.steps
+  ADD COLUMN IF NOT EXISTS retry_delay_seconds integer NOT NULL DEFAULT 0
+    CHECK (retry_delay_seconds BETWEEN 0 AND 86400);
+
+CREATE UNIQUE INDEX IF NOT EXISTS supacloud_workflows_one_active_step_idx
+  ON supacloud_workflows.steps (run_id)
+  WHERE status IN ('queued', 'running');
+
+CREATE INDEX IF NOT EXISTS supacloud_workflows_runs_status_idx
+  ON supacloud_workflows.runs (status, updated_at DESC, id);
+
+CREATE INDEX IF NOT EXISTS supacloud_workflows_steps_run_idx
+  ON supacloud_workflows.steps (run_id, created_at, id);
+
+CREATE TABLE IF NOT EXISTS supacloud_workflows.events (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  run_id uuid NOT NULL REFERENCES supacloud_workflows.runs(id) ON DELETE CASCADE,
+  step_id uuid REFERENCES supacloud_workflows.steps(id) ON DELETE CASCADE,
+  event_type text NOT NULL
+    CHECK (event_type IN (
+      'run_started', 'step_claimed', 'step_retried', 'step_completed',
+      'step_failed', 'step_dead_lettered', 'run_completed', 'run_cancelled'
+    )),
+  attempt integer CHECK (attempt IS NULL OR attempt > 0),
+  details jsonb NOT NULL DEFAULT '{}'::jsonb
+    CHECK (jsonb_typeof(details) = 'object'),
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS supacloud_workflows_events_run_idx
+  ON supacloud_workflows.events (run_id, id);
+
+CREATE UNIQUE INDEX IF NOT EXISTS supacloud_workflows_retry_receipt_idx
+  ON supacloud_workflows.events (step_id, attempt)
+  WHERE event_type IN ('step_retried', 'step_dead_lettered')
+    AND details ->> 'operation' = 'retry';
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.snapshot(
+  p_run_id uuid,
+  p_idempotent boolean DEFAULT false
+) RETURNS jsonb
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $$
+  SELECT jsonb_build_object(
+    'runId', run.id,
+    'workflowName', run.workflow_name,
+    'workflowVersion', run.workflow_version,
+    'status', run.status,
+    'input', run.input,
+    'output', run.output,
+    'errorMessage', run.error_message,
+    'rowVersion', run.row_version::text,
+    'createdAt', run.created_at,
+    'startedAt', run.started_at,
+    'completedAt', run.completed_at,
+    'updatedAt', run.updated_at,
+    'idempotent', p_idempotent,
+    'steps', coalesce((
+      SELECT jsonb_agg(jsonb_build_object(
+        'stepId', step.id,
+        'stepKey', step.step_key,
+        'status', step.status,
+        'input', step.input,
+        'output', step.output,
+        'errorMessage', step.error_message,
+        'attempts', step.attempts,
+        'maxAttempts', step.max_attempts,
+        'retryDelaySeconds', step.retry_delay_seconds,
+        'queueMessageId', step.queue_message_id::text,
+        'claimedBy', step.claimed_by,
+        'claimedAt', step.claimed_at,
+        'completedAt', step.completed_at,
+        'nextStepKey', step.next_step_key,
+        'createdAt', step.created_at,
+        'updatedAt', step.updated_at
+      ) ORDER BY step.created_at, step.id)
+      FROM supacloud_workflows.steps step
+      WHERE step.run_id = run.id
+    ), '[]'::jsonb)
+  )
+  FROM supacloud_workflows.runs run
+  WHERE run.id = p_run_id
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.enqueue_step(
+  p_run_id uuid,
+  p_step_key text,
+  p_input jsonb,
+  p_max_attempts integer
+) RETURNS supacloud_workflows.steps
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  normalized_step_key text := nullif(btrim(p_step_key), '');
+  step_id uuid := gen_random_uuid();
+  message_id bigint;
+  created_step supacloud_workflows.steps%ROWTYPE;
+BEGIN
+  IF normalized_step_key IS NULL
+     OR normalized_step_key !~ '^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$'
+     OR jsonb_typeof(p_input) IS DISTINCT FROM 'object'
+     OR p_max_attempts NOT BETWEEN 1 AND 100 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STEP_INVALID' USING ERRCODE = '22023';
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM supacloud_workflows.runs run
+    WHERE run.id = p_run_id AND run.status IN ('queued', 'running')
+  ) THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RUN_NOT_ACTIVE' USING ERRCODE = '55000';
+  END IF;
+
+  SELECT queued_id INTO message_id
+  FROM pgmq.send(
+    'supacloud_internal_workflows',
+    jsonb_build_object('run_id', p_run_id, 'step_id', step_id),
+    0
+  ) AS queued_id;
+
+  INSERT INTO supacloud_workflows.steps (
+    id, run_id, step_key, input, max_attempts, queue_message_id
+  ) VALUES (
+    step_id, p_run_id, normalized_step_key, p_input, p_max_attempts, message_id
+  ) RETURNING * INTO created_step;
+
+  RETURN created_step;
+END;
+$$;
+
+-- Clean-code exception: private transitions keep typed PostgreSQL arguments and
+-- the complete lock/queue/ledger/event mutation in one transaction. The public
+-- contract already uses one JSON request; revisit if a private routine gains a
+-- second caller or any transition can be decomposed without weakening atomicity.
+CREATE OR REPLACE FUNCTION supacloud_workflows.start_run(
+  p_run_id uuid,
+  p_workflow_name text,
+  p_workflow_version text,
+  p_first_step_key text,
+  p_input jsonb,
+  p_max_attempts integer
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  normalized_name text := nullif(btrim(p_workflow_name), '');
+  normalized_version text := nullif(btrim(p_workflow_version), '');
+  normalized_first_step_key text := nullif(btrim(p_first_step_key), '');
+  existing_run supacloud_workflows.runs%ROWTYPE;
+  existing_step supacloud_workflows.steps%ROWTYPE;
+  first_step supacloud_workflows.steps%ROWTYPE;
+BEGIN
+  IF p_run_id IS NULL
+     OR normalized_name IS NULL
+     OR normalized_name !~ '^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$'
+     OR normalized_version IS NULL
+     OR char_length(normalized_version) > 80
+     OR normalized_first_step_key IS NULL
+     OR normalized_first_step_key !~ '^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$'
+     OR jsonb_typeof(p_input) IS DISTINCT FROM 'object'
+     OR p_max_attempts NOT BETWEEN 1 AND 100 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_START_INVALID' USING ERRCODE = '22023';
+  END IF;
+
+  PERFORM pg_advisory_xact_lock(hashtextextended(p_run_id::text, 0));
+  SELECT * INTO existing_run FROM supacloud_workflows.runs WHERE id = p_run_id;
+  IF FOUND THEN
+    SELECT * INTO existing_step
+    FROM supacloud_workflows.steps
+    WHERE run_id = p_run_id
+    ORDER BY created_at, id
+    LIMIT 1;
+    IF NOT FOUND THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_IDEMPOTENCY_CONFLICT' USING ERRCODE = '23505';
+    END IF;
+    IF existing_run.workflow_name <> normalized_name
+       OR existing_run.workflow_version <> normalized_version
+       OR existing_run.input <> p_input
+       OR existing_step.step_key <> normalized_first_step_key
+       OR existing_step.input <> p_input
+       OR existing_step.max_attempts <> p_max_attempts THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_IDEMPOTENCY_CONFLICT' USING ERRCODE = '23505';
+    END IF;
+    RETURN supacloud_workflows.snapshot(p_run_id, true);
+  END IF;
+
+  INSERT INTO supacloud_workflows.runs (
+    id, workflow_name, workflow_version, input
+  ) VALUES (
+    p_run_id, normalized_name, normalized_version, p_input
+  );
+  first_step := supacloud_workflows.enqueue_step(
+    p_run_id, normalized_first_step_key, p_input, p_max_attempts
+  );
+  INSERT INTO supacloud_workflows.events (run_id, step_id, event_type)
+  VALUES (p_run_id, first_step.id, 'run_started');
+  RETURN supacloud_workflows.snapshot(p_run_id, false);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.claim_step(
+  p_worker_id text,
+  p_visibility_timeout_seconds integer
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  normalized_worker_id text := nullif(btrim(p_worker_id), '');
+  queued_message pgmq.message_record;
+  message_run_id text;
+  message_step_id text;
+  candidate_run_id uuid;
+  claimed_step supacloud_workflows.steps%ROWTYPE;
+  claimed_run supacloud_workflows.runs%ROWTYPE;
+BEGIN
+  IF normalized_worker_id IS NULL
+     OR char_length(normalized_worker_id) > 200
+     OR p_visibility_timeout_seconds NOT BETWEEN 15 AND 3600 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_CLAIM_INVALID' USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO queued_message
+  FROM pgmq.read('supacloud_internal_workflows', p_visibility_timeout_seconds, 1)
+  LIMIT 1;
+  IF NOT FOUND THEN RETURN NULL; END IF;
+
+  message_run_id := queued_message.message ->> 'run_id';
+  message_step_id := queued_message.message ->> 'step_id';
+  IF jsonb_typeof(queued_message.message) IS DISTINCT FROM 'object'
+     OR message_run_id IS NULL
+     OR message_step_id IS NULL
+     OR message_run_id !~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
+     OR message_step_id !~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' THEN
+    PERFORM pgmq.archive('supacloud_internal_workflows', queued_message.msg_id);
+    RETURN jsonb_build_object(
+      'status', 'discarded',
+      'reason', 'invalid_message',
+      'messageId', queued_message.msg_id::text
+    );
+  END IF;
+
+  SELECT step.run_id INTO candidate_run_id
+  FROM supacloud_workflows.steps step
+  WHERE step.id::text = lower(message_step_id)
+    AND step.run_id::text = lower(message_run_id)
+    AND step.queue_message_id = queued_message.msg_id;
+  IF NOT FOUND THEN
+    PERFORM pgmq.archive('supacloud_internal_workflows', queued_message.msg_id);
+    RETURN jsonb_build_object(
+      'status', 'discarded',
+      'reason', 'orphaned_message',
+      'messageId', queued_message.msg_id::text
+    );
+  END IF;
+
+  IF NOT pg_try_advisory_xact_lock(hashtextextended(candidate_run_id::text, 0)) THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_CLAIM_RETRY' USING ERRCODE = '40001';
+  END IF;
+  SELECT * INTO claimed_step
+  FROM supacloud_workflows.steps
+  WHERE id::text = lower(message_step_id)
+    AND run_id = candidate_run_id
+    AND queue_message_id = queued_message.msg_id
+  FOR UPDATE;
+  IF NOT FOUND THEN
+    PERFORM pgmq.archive('supacloud_internal_workflows', queued_message.msg_id);
+    RETURN jsonb_build_object(
+      'status', 'discarded',
+      'reason', 'orphaned_message',
+      'messageId', queued_message.msg_id::text
+    );
+  END IF;
+
+  SELECT * INTO claimed_run
+  FROM supacloud_workflows.runs
+  WHERE id = claimed_step.run_id
+  FOR UPDATE;
+  IF claimed_run.status NOT IN ('queued', 'running')
+     OR claimed_step.status NOT IN ('queued', 'running') THEN
+    PERFORM pgmq.archive('supacloud_internal_workflows', queued_message.msg_id);
+    RETURN jsonb_build_object(
+      'status', 'discarded',
+      'reason', 'step_not_claimable',
+      'runId', claimed_step.run_id,
+      'stepId', claimed_step.id,
+      'messageId', queued_message.msg_id::text
+    );
+  END IF;
+
+  IF queued_message.read_ct > claimed_step.max_attempts THEN
+    UPDATE supacloud_workflows.steps
+    SET status = 'dead_lettered', attempts = queued_message.read_ct,
+        error_message = 'maximum attempts exceeded', completed_at = now(), updated_at = now()
+    WHERE id = claimed_step.id;
+    UPDATE supacloud_workflows.runs
+    SET status = 'failed', error_message = 'maximum attempts exceeded',
+        completed_at = now(), updated_at = now(), row_version = row_version + 1
+    WHERE id = claimed_step.run_id;
+    PERFORM pgmq.archive('supacloud_internal_workflows', queued_message.msg_id);
+    INSERT INTO supacloud_workflows.events (
+      run_id, step_id, event_type, attempt, details
+    ) VALUES (
+      claimed_step.run_id, claimed_step.id, 'step_dead_lettered', queued_message.read_ct,
+      jsonb_build_object('errorMessage', 'maximum attempts exceeded')
+    );
+    RETURN jsonb_build_object(
+      'status', 'dead_lettered',
+      'runId', claimed_step.run_id,
+      'stepId', claimed_step.id,
+      'stepKey', claimed_step.step_key,
+      'messageId', queued_message.msg_id::text,
+      'attempt', queued_message.read_ct,
+      'maxAttempts', claimed_step.max_attempts
+    );
+  END IF;
+
+  UPDATE supacloud_workflows.steps
+  SET status = 'running', attempts = queued_message.read_ct,
+      retry_delay_seconds = 0, claimed_by = normalized_worker_id,
+      claimed_at = now(), updated_at = now()
+  WHERE id = claimed_step.id;
+  UPDATE supacloud_workflows.runs
+  SET status = 'running', started_at = coalesce(started_at, now()),
+      updated_at = now(), row_version = row_version + 1
+  WHERE id = claimed_step.run_id;
+  INSERT INTO supacloud_workflows.events (run_id, step_id, event_type, attempt, details)
+  VALUES (
+    claimed_step.run_id, claimed_step.id, 'step_claimed', queued_message.read_ct,
+    jsonb_build_object('workerId', normalized_worker_id)
+  );
+
+  RETURN jsonb_build_object(
+    'status', 'claimed',
+    'runId', claimed_step.run_id,
+    'workflowName', claimed_run.workflow_name,
+    'workflowVersion', claimed_run.workflow_version,
+    'stepId', claimed_step.id,
+    'stepKey', claimed_step.step_key,
+    'input', claimed_step.input,
+    'messageId', queued_message.msg_id::text,
+    'attempt', queued_message.read_ct,
+    'maxAttempts', claimed_step.max_attempts,
+    'workerId', normalized_worker_id
+  );
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.lock_step(
+  p_step_id uuid
+) RETURNS supacloud_workflows.steps
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  candidate_run_id uuid;
+  active_step supacloud_workflows.steps%ROWTYPE;
+BEGIN
+  SELECT step.run_id INTO candidate_run_id
+  FROM supacloud_workflows.steps step
+  WHERE step.id = p_step_id;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STEP_NOT_FOUND' USING ERRCODE = 'P0002';
+  END IF;
+  PERFORM pg_advisory_xact_lock(hashtextextended(candidate_run_id::text, 0));
+  SELECT * INTO active_step
+  FROM supacloud_workflows.steps
+  WHERE id = p_step_id
+  FOR UPDATE;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STEP_NOT_FOUND' USING ERRCODE = 'P0002';
+  END IF;
+  RETURN active_step;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.lock_step_attempt(
+  p_step_id uuid,
+  p_message_id bigint,
+  p_attempt integer,
+  p_worker_id text
+) RETURNS supacloud_workflows.steps
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  active_step supacloud_workflows.steps%ROWTYPE;
+  normalized_worker_id text := nullif(btrim(p_worker_id), '');
+BEGIN
+  active_step := supacloud_workflows.lock_step(p_step_id);
+  IF normalized_worker_id IS NULL
+     OR p_message_id IS NULL
+     OR p_attempt IS NULL
+     OR active_step.queue_message_id IS DISTINCT FROM p_message_id
+     OR active_step.attempts IS DISTINCT FROM p_attempt
+     OR active_step.claimed_by IS DISTINCT FROM normalized_worker_id THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STALE_ATTEMPT' USING ERRCODE = '40001';
+  END IF;
+  RETURN active_step;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.advance_step(
+  p_step_id uuid,
+  p_message_id bigint,
+  p_attempt integer,
+  p_worker_id text,
+  p_output jsonb,
+  p_next_step_key text,
+  p_next_input jsonb,
+  p_next_max_attempts integer
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  current_step supacloud_workflows.steps%ROWTYPE;
+  next_step supacloud_workflows.steps%ROWTYPE;
+  normalized_next_step_key text := nullif(btrim(p_next_step_key), '');
+  archived boolean;
+BEGIN
+  IF jsonb_typeof(p_output) IS DISTINCT FROM 'object'
+     OR jsonb_typeof(p_next_input) IS DISTINCT FROM 'object'
+     OR normalized_next_step_key IS NULL
+     OR normalized_next_step_key !~ '^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$'
+     OR p_next_max_attempts NOT BETWEEN 1 AND 100 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_ADVANCE_INVALID' USING ERRCODE = '22023';
+  END IF;
+  current_step := supacloud_workflows.lock_step_attempt(
+    p_step_id, p_message_id, p_attempt, p_worker_id
+  );
+
+  IF current_step.status = 'completed' THEN
+    SELECT * INTO next_step
+    FROM supacloud_workflows.steps
+    WHERE run_id = current_step.run_id AND step_key = normalized_next_step_key;
+    IF NOT FOUND
+       OR current_step.output IS DISTINCT FROM p_output
+       OR current_step.next_step_key IS DISTINCT FROM normalized_next_step_key
+       OR next_step.input IS DISTINCT FROM p_next_input
+       OR next_step.max_attempts IS DISTINCT FROM p_next_max_attempts THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_IDEMPOTENCY_CONFLICT' USING ERRCODE = '23505';
+    END IF;
+    RETURN supacloud_workflows.snapshot(current_step.run_id, true);
+  END IF;
+  IF current_step.status <> 'running' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STALE_ATTEMPT' USING ERRCODE = '40001';
+  END IF;
+
+  SELECT pgmq.archive('supacloud_internal_workflows', p_message_id) INTO archived;
+  IF archived IS DISTINCT FROM true THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_QUEUE_MESSAGE_MISSING' USING ERRCODE = '55000';
+  END IF;
+  UPDATE supacloud_workflows.steps
+  SET status = 'completed', output = p_output, error_message = '',
+      completed_at = now(), next_step_key = normalized_next_step_key, updated_at = now()
+  WHERE id = current_step.id;
+  INSERT INTO supacloud_workflows.events (
+    run_id, step_id, event_type, attempt, details
+  ) VALUES (
+    current_step.run_id, current_step.id, 'step_completed', p_attempt,
+    jsonb_build_object('nextStepKey', normalized_next_step_key)
+  );
+  next_step := supacloud_workflows.enqueue_step(
+    current_step.run_id, normalized_next_step_key, p_next_input, p_next_max_attempts
+  );
+  RETURN supacloud_workflows.snapshot(current_step.run_id, false);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.complete_run(
+  p_step_id uuid,
+  p_message_id bigint,
+  p_attempt integer,
+  p_worker_id text,
+  p_step_output jsonb,
+  p_run_output jsonb
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  current_step supacloud_workflows.steps%ROWTYPE;
+  current_run supacloud_workflows.runs%ROWTYPE;
+  archived boolean;
+BEGIN
+  IF jsonb_typeof(p_step_output) IS DISTINCT FROM 'object'
+     OR jsonb_typeof(p_run_output) IS DISTINCT FROM 'object' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_COMPLETION_INVALID' USING ERRCODE = '22023';
+  END IF;
+  current_step := supacloud_workflows.lock_step_attempt(
+    p_step_id, p_message_id, p_attempt, p_worker_id
+  );
+  SELECT * INTO current_run
+  FROM supacloud_workflows.runs
+  WHERE id = current_step.run_id
+  FOR UPDATE;
+
+  IF current_step.status = 'completed' THEN
+    IF current_step.next_step_key IS NOT NULL
+       OR current_step.output IS DISTINCT FROM p_step_output
+       OR current_run.status IS DISTINCT FROM 'completed'
+       OR current_run.output IS DISTINCT FROM p_run_output THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_IDEMPOTENCY_CONFLICT' USING ERRCODE = '23505';
+    END IF;
+    RETURN supacloud_workflows.snapshot(current_step.run_id, true);
+  END IF;
+  IF current_step.status <> 'running' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STALE_ATTEMPT' USING ERRCODE = '40001';
+  END IF;
+  IF current_run.status <> 'running' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RUN_NOT_ACTIVE' USING ERRCODE = '55000';
+  END IF;
+
+  SELECT pgmq.archive('supacloud_internal_workflows', p_message_id) INTO archived;
+  IF archived IS DISTINCT FROM true THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_QUEUE_MESSAGE_MISSING' USING ERRCODE = '55000';
+  END IF;
+  UPDATE supacloud_workflows.steps
+  SET status = 'completed', output = p_step_output, error_message = '',
+      completed_at = now(), updated_at = now()
+  WHERE id = current_step.id;
+  UPDATE supacloud_workflows.runs
+  SET status = 'completed', output = p_run_output, error_message = '',
+      completed_at = now(), updated_at = now(), row_version = row_version + 1
+  WHERE id = current_step.run_id AND status = 'running';
+  INSERT INTO supacloud_workflows.events (run_id, step_id, event_type, attempt)
+  VALUES (current_step.run_id, current_step.id, 'step_completed', p_attempt);
+  INSERT INTO supacloud_workflows.events (run_id, step_id, event_type, attempt)
+  VALUES (current_step.run_id, current_step.id, 'run_completed', p_attempt);
+  RETURN supacloud_workflows.snapshot(current_step.run_id, false);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.retry_step(
+  p_step_id uuid,
+  p_message_id bigint,
+  p_attempt integer,
+  p_worker_id text,
+  p_error_message text,
+  p_delay_seconds integer
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  current_step supacloud_workflows.steps%ROWTYPE;
+  normalized_error text := nullif(btrim(p_error_message), '');
+  normalized_worker_id text := nullif(btrim(p_worker_id), '');
+  retry_receipt jsonb;
+  queue_message_updated boolean;
+  archived boolean;
+BEGIN
+  IF normalized_error IS NULL OR char_length(normalized_error) > 4000
+     OR p_delay_seconds NOT BETWEEN 0 AND 86400 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RETRY_INVALID' USING ERRCODE = '22023';
+  END IF;
+  current_step := supacloud_workflows.lock_step(p_step_id);
+  SELECT event.details INTO retry_receipt
+  FROM supacloud_workflows.events event
+  WHERE event.step_id = current_step.id
+    AND event.attempt = p_attempt
+    AND event.event_type IN ('step_retried', 'step_dead_lettered')
+    AND event.details ->> 'operation' = 'retry'
+  ORDER BY event.id DESC
+  LIMIT 1;
+  IF FOUND THEN
+    IF retry_receipt ->> 'messageId' IS DISTINCT FROM p_message_id::text
+       OR retry_receipt ->> 'workerId' IS DISTINCT FROM normalized_worker_id
+       OR retry_receipt ->> 'errorMessage' IS DISTINCT FROM normalized_error
+       OR (retry_receipt ->> 'delaySeconds')::integer IS DISTINCT FROM p_delay_seconds THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_IDEMPOTENCY_CONFLICT' USING ERRCODE = '23505';
+    END IF;
+    RETURN supacloud_workflows.snapshot(current_step.run_id, true);
+  END IF;
+  IF normalized_worker_id IS NULL
+     OR p_message_id IS NULL
+     OR p_attempt IS NULL
+     OR current_step.queue_message_id IS DISTINCT FROM p_message_id
+     OR current_step.attempts IS DISTINCT FROM p_attempt
+     OR current_step.claimed_by IS DISTINCT FROM normalized_worker_id
+     OR current_step.status <> 'running' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STALE_ATTEMPT' USING ERRCODE = '40001';
+  END IF;
+
+  IF current_step.attempts >= current_step.max_attempts THEN
+    SELECT pgmq.archive('supacloud_internal_workflows', p_message_id) INTO archived;
+    IF archived IS DISTINCT FROM true THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_QUEUE_MESSAGE_MISSING' USING ERRCODE = '55000';
+    END IF;
+    UPDATE supacloud_workflows.steps
+    SET status = 'dead_lettered', error_message = normalized_error,
+        completed_at = now(), updated_at = now()
+    WHERE id = current_step.id;
+    UPDATE supacloud_workflows.runs
+    SET status = 'failed', error_message = normalized_error,
+        completed_at = now(), updated_at = now(), row_version = row_version + 1
+    WHERE id = current_step.run_id AND status = 'running';
+    IF NOT FOUND THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RUN_NOT_ACTIVE' USING ERRCODE = '55000';
+    END IF;
+    INSERT INTO supacloud_workflows.events (
+      run_id, step_id, event_type, attempt, details
+    ) VALUES (
+      current_step.run_id, current_step.id, 'step_dead_lettered', p_attempt,
+      jsonb_build_object(
+        'operation', 'retry',
+        'messageId', p_message_id::text,
+        'workerId', normalized_worker_id,
+        'errorMessage', normalized_error,
+        'delaySeconds', p_delay_seconds
+      )
+    );
+    RETURN supacloud_workflows.snapshot(current_step.run_id, false);
+  END IF;
+
+  SELECT EXISTS (
+    SELECT 1 FROM pgmq.set_vt('supacloud_internal_workflows', p_message_id, p_delay_seconds)
+  ) INTO queue_message_updated;
+  IF queue_message_updated IS DISTINCT FROM true THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_QUEUE_MESSAGE_MISSING' USING ERRCODE = '55000';
+  END IF;
+  UPDATE supacloud_workflows.steps
+  SET status = 'queued', error_message = normalized_error,
+      retry_delay_seconds = p_delay_seconds, updated_at = now()
+  WHERE id = current_step.id;
+  INSERT INTO supacloud_workflows.events (
+    run_id, step_id, event_type, attempt, details
+  ) VALUES (
+    current_step.run_id, current_step.id, 'step_retried', p_attempt,
+    jsonb_build_object(
+      'operation', 'retry',
+      'messageId', p_message_id::text,
+      'workerId', normalized_worker_id,
+      'errorMessage', normalized_error,
+      'delaySeconds', p_delay_seconds
+    )
+  );
+  RETURN supacloud_workflows.snapshot(current_step.run_id, false);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.fail_step(
+  p_step_id uuid,
+  p_message_id bigint,
+  p_attempt integer,
+  p_worker_id text,
+  p_error_message text
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  current_step supacloud_workflows.steps%ROWTYPE;
+  current_run supacloud_workflows.runs%ROWTYPE;
+  normalized_error text := nullif(btrim(p_error_message), '');
+  archived boolean;
+BEGIN
+  IF normalized_error IS NULL OR char_length(normalized_error) > 4000 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_FAILURE_INVALID' USING ERRCODE = '22023';
+  END IF;
+  current_step := supacloud_workflows.lock_step_attempt(
+    p_step_id, p_message_id, p_attempt, p_worker_id
+  );
+  SELECT * INTO current_run
+  FROM supacloud_workflows.runs
+  WHERE id = current_step.run_id
+  FOR UPDATE;
+
+  IF current_step.status = 'failed' THEN
+    IF current_step.error_message IS DISTINCT FROM normalized_error
+       OR current_run.status IS DISTINCT FROM 'failed'
+       OR current_run.error_message IS DISTINCT FROM normalized_error THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_IDEMPOTENCY_CONFLICT' USING ERRCODE = '23505';
+    END IF;
+    RETURN supacloud_workflows.snapshot(current_step.run_id, true);
+  END IF;
+  IF current_step.status <> 'running' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_STALE_ATTEMPT' USING ERRCODE = '40001';
+  END IF;
+  IF current_run.status <> 'running' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RUN_NOT_ACTIVE' USING ERRCODE = '55000';
+  END IF;
+
+  SELECT pgmq.archive('supacloud_internal_workflows', p_message_id) INTO archived;
+  IF archived IS DISTINCT FROM true THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_QUEUE_MESSAGE_MISSING' USING ERRCODE = '55000';
+  END IF;
+  UPDATE supacloud_workflows.steps
+  SET status = 'failed', error_message = normalized_error,
+      completed_at = now(), updated_at = now()
+  WHERE id = current_step.id;
+  UPDATE supacloud_workflows.runs
+  SET status = 'failed', error_message = normalized_error,
+      completed_at = now(), updated_at = now(), row_version = row_version + 1
+  WHERE id = current_step.run_id AND status = 'running';
+  INSERT INTO supacloud_workflows.events (
+    run_id, step_id, event_type, attempt, details
+  ) VALUES (
+    current_step.run_id, current_step.id, 'step_failed', p_attempt,
+    jsonb_build_object('errorMessage', normalized_error)
+  );
+  RETURN supacloud_workflows.snapshot(current_step.run_id, false);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.cancel_run(
+  p_run_id uuid,
+  p_reason text
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  normalized_reason text := nullif(btrim(p_reason), '');
+  locked_run supacloud_workflows.runs%ROWTYPE;
+  active_step supacloud_workflows.steps%ROWTYPE;
+BEGIN
+  IF p_run_id IS NULL OR normalized_reason IS NULL OR char_length(normalized_reason) > 4000 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_CANCEL_INVALID' USING ERRCODE = '22023';
+  END IF;
+  PERFORM pg_advisory_xact_lock(hashtextextended(p_run_id::text, 0));
+  SELECT * INTO locked_run FROM supacloud_workflows.runs WHERE id = p_run_id FOR UPDATE;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RUN_NOT_FOUND' USING ERRCODE = 'P0002';
+  END IF;
+  IF locked_run.status = 'cancelled' THEN
+    IF locked_run.error_message IS DISTINCT FROM normalized_reason THEN
+      RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_IDEMPOTENCY_CONFLICT' USING ERRCODE = '23505';
+    END IF;
+    RETURN supacloud_workflows.snapshot(p_run_id, true);
+  END IF;
+  IF locked_run.status NOT IN ('queued', 'running') THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RUN_NOT_ACTIVE' USING ERRCODE = '55000';
+  END IF;
+  SELECT * INTO active_step
+  FROM supacloud_workflows.steps
+  WHERE run_id = p_run_id AND status IN ('queued', 'running')
+  FOR UPDATE;
+  IF FOUND THEN
+    PERFORM pgmq.archive('supacloud_internal_workflows', active_step.queue_message_id);
+    UPDATE supacloud_workflows.steps
+    SET status = 'cancelled', error_message = normalized_reason,
+        completed_at = now(), updated_at = now()
+    WHERE id = active_step.id;
+  END IF;
+  UPDATE supacloud_workflows.runs
+  SET status = 'cancelled', error_message = normalized_reason,
+      completed_at = now(), updated_at = now(), row_version = row_version + 1
+  WHERE id = p_run_id;
+  INSERT INTO supacloud_workflows.events (
+    run_id, step_id, event_type, details
+  ) VALUES (
+    p_run_id, active_step.id, 'run_cancelled',
+    jsonb_build_object('reason', normalized_reason)
+  );
+  RETURN supacloud_workflows.snapshot(p_run_id, false);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.run_events(
+  p_run_id uuid,
+  p_after_event_id bigint,
+  p_limit integer
+) RETURNS jsonb
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $$
+  SELECT coalesce(jsonb_agg(jsonb_build_object(
+    'eventId', page.id::text,
+    'runId', page.run_id,
+    'stepId', page.step_id,
+    'eventType', page.event_type,
+    'attempt', page.attempt,
+    'details', page.details,
+    'createdAt', page.created_at
+  ) ORDER BY page.id), '[]'::jsonb)
+  FROM (
+    SELECT event.*
+    FROM supacloud_workflows.events event
+    WHERE event.run_id = p_run_id AND event.id > p_after_event_id
+    ORDER BY event.id
+    LIMIT p_limit
+  ) page
+$$;
+
+CREATE OR REPLACE FUNCTION supacloud_workflows.request_uuid(
+  request jsonb,
+  key text
+) RETURNS uuid
+LANGUAGE plpgsql IMMUTABLE SET search_path = '' AS $$
+DECLARE
+  uuid_text text;
+BEGIN
+  IF jsonb_typeof(request) IS DISTINCT FROM 'object' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_REQUEST_INVALID' USING ERRCODE = '22023';
+  END IF;
+  uuid_text := request ->> key;
+  IF uuid_text IS NULL
+     OR uuid_text !~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_REQUEST_INVALID' USING ERRCODE = '22023';
+  END IF;
+  RETURN uuid_text::uuid;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_start(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  max_attempts integer;
+BEGIN
+  max_attempts := coalesce((request ->> 'maxAttempts')::integer, 3);
+  RETURN supacloud_workflows.start_run(
+    supacloud_workflows.request_uuid(request, 'runId'),
+    request ->> 'workflowName',
+    request ->> 'workflowVersion',
+    request ->> 'firstStepKey',
+    coalesce(request -> 'input', '{}'::jsonb),
+    max_attempts
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation OR numeric_value_out_of_range THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_START_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_claim(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  visibility_timeout_seconds integer;
+BEGIN
+  IF jsonb_typeof(request) IS DISTINCT FROM 'object' THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_CLAIM_INVALID' USING ERRCODE = '22023';
+  END IF;
+  visibility_timeout_seconds := coalesce((request ->> 'visibilityTimeoutSeconds')::integer, 300);
+  RETURN supacloud_workflows.claim_step(
+    request ->> 'workerId', visibility_timeout_seconds
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation OR numeric_value_out_of_range THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_CLAIM_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_advance(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  message_id bigint;
+  attempt integer;
+  next_max_attempts integer;
+BEGIN
+  message_id := (request ->> 'messageId')::bigint;
+  attempt := (request ->> 'attempt')::integer;
+  next_max_attempts := coalesce((request ->> 'nextMaxAttempts')::integer, 3);
+  IF message_id <= 0 OR attempt <= 0 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_ADVANCE_INVALID' USING ERRCODE = '22023';
+  END IF;
+  RETURN supacloud_workflows.advance_step(
+    supacloud_workflows.request_uuid(request, 'stepId'),
+    message_id,
+    attempt,
+    request ->> 'workerId',
+    coalesce(request -> 'output', '{}'::jsonb),
+    request ->> 'nextStepKey',
+    coalesce(request -> 'nextInput', '{}'::jsonb),
+    next_max_attempts
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation OR numeric_value_out_of_range THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_ADVANCE_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_complete(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  message_id bigint;
+  attempt integer;
+BEGIN
+  message_id := (request ->> 'messageId')::bigint;
+  attempt := (request ->> 'attempt')::integer;
+  IF message_id <= 0 OR attempt <= 0 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_COMPLETION_INVALID' USING ERRCODE = '22023';
+  END IF;
+  RETURN supacloud_workflows.complete_run(
+    supacloud_workflows.request_uuid(request, 'stepId'),
+    message_id,
+    attempt,
+    request ->> 'workerId',
+    coalesce(request -> 'stepOutput', '{}'::jsonb),
+    coalesce(request -> 'runOutput', '{}'::jsonb)
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation OR numeric_value_out_of_range THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_COMPLETION_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_retry(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  message_id bigint;
+  attempt integer;
+  delay_seconds integer;
+BEGIN
+  message_id := (request ->> 'messageId')::bigint;
+  attempt := (request ->> 'attempt')::integer;
+  delay_seconds := coalesce((request ->> 'delaySeconds')::integer, 0);
+  IF message_id <= 0 OR attempt <= 0 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RETRY_INVALID' USING ERRCODE = '22023';
+  END IF;
+  RETURN supacloud_workflows.retry_step(
+    supacloud_workflows.request_uuid(request, 'stepId'),
+    message_id,
+    attempt,
+    request ->> 'workerId',
+    request ->> 'errorMessage',
+    delay_seconds
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation OR numeric_value_out_of_range THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_RETRY_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_fail(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  message_id bigint;
+  attempt integer;
+BEGIN
+  message_id := (request ->> 'messageId')::bigint;
+  attempt := (request ->> 'attempt')::integer;
+  IF message_id <= 0 OR attempt <= 0 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_FAILURE_INVALID' USING ERRCODE = '22023';
+  END IF;
+  RETURN supacloud_workflows.fail_step(
+    supacloud_workflows.request_uuid(request, 'stepId'),
+    message_id,
+    attempt,
+    request ->> 'workerId',
+    request ->> 'errorMessage'
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation OR numeric_value_out_of_range THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_FAILURE_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_cancel(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql VOLATILE SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  RETURN supacloud_workflows.cancel_run(
+    supacloud_workflows.request_uuid(request, 'runId'),
+    request ->> 'reason'
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_CANCEL_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_get(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  RETURN supacloud_workflows.snapshot(
+    supacloud_workflows.request_uuid(request, 'runId'), false
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_GET_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.supacloud_workflow_events(request jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  after_event_id bigint;
+  event_limit integer;
+BEGIN
+  after_event_id := coalesce((request ->> 'afterEventId')::bigint, 0);
+  event_limit := coalesce((request ->> 'limit')::integer, 100);
+  IF after_event_id < 0 OR event_limit NOT BETWEEN 1 AND 500 THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_EVENTS_INVALID' USING ERRCODE = '22023';
+  END IF;
+  RETURN supacloud_workflows.run_events(
+    supacloud_workflows.request_uuid(request, 'runId'), after_event_id, event_limit
+  );
+EXCEPTION
+  WHEN invalid_parameter_value OR invalid_text_representation OR numeric_value_out_of_range THEN
+    RAISE EXCEPTION 'SUPACLOUD_WORKFLOW_EVENTS_INVALID' USING ERRCODE = '22023';
+END;
+$$;
+
+REVOKE ALL ON ALL TABLES IN SCHEMA supacloud_workflows
+  FROM PUBLIC, anon, authenticated, service_role;
+REVOKE ALL ON ALL SEQUENCES IN SCHEMA supacloud_workflows
+  FROM PUBLIC, anon, authenticated, service_role;
+REVOKE ALL ON ALL FUNCTIONS IN SCHEMA supacloud_workflows
+  FROM PUBLIC, anon, authenticated, service_role;
+
+REVOKE ALL ON FUNCTION public.supacloud_workflow_start(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_claim(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_advance(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_complete(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_retry(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_fail(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_cancel(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_get(jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.supacloud_workflow_events(jsonb) FROM PUBLIC, anon, authenticated;
+
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_start(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_claim(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_advance(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_complete(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_retry(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_fail(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_cancel(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_get(jsonb) TO service_role;
+GRANT EXECUTE ON FUNCTION public.supacloud_workflow_events(jsonb) TO service_role;
+-- supacloud:sql-module:workflows-public:end
 `;
 var CRON_SQL = `
 create schema if not exists cron;
@@ -3911,12 +5096,32 @@ function pickTag(text, base) {
   return tag;
 }
 
-// src/runtime/db/pglite-engine.ts
-import { mkdir, open, unlink as unlink2 } from "fs/promises";
-import { dirname, resolve } from "path";
-
 // src/runtime/db/data-dir-lock.ts
-import { readFile, unlink } from "fs/promises";
+import { mkdir, open, readFile, unlink } from "fs/promises";
+import { dirname, resolve } from "path";
+async function acquireDataDirLock(dataDir, engineName = "database") {
+  if (!dataDir || dataDir.includes("://"))
+    return async () => {};
+  const absoluteDataDir = resolve(dataDir);
+  const lockPath = `${absoluteDataDir}.supacloud-lite.lock`;
+  await mkdir(dirname(absoluteDataDir), { recursive: true, mode: 448 });
+  const nonce = crypto.randomUUID();
+  const handle = await createDataDirLock(absoluteDataDir, lockPath, nonce, engineName);
+  let released = false;
+  return async () => {
+    if (released)
+      return;
+    released = true;
+    await handle.close();
+    const owner = await readDataDirLockOwner(lockPath);
+    if (owner?.nonce !== nonce)
+      return;
+    await unlink(lockPath).catch((error) => {
+      if (error.code !== "ENOENT")
+        throw error;
+    });
+  };
+}
 async function recoverStaleDataDirLock(lockPath) {
   const lockState = await inspectDataDirLock(lockPath);
   if (lockState.kind !== "stale")
@@ -3934,6 +5139,38 @@ async function readDataDirLockOwner(lockPath) {
   const lockState = await inspectDataDirLock(lockPath);
   return lockState.kind === "active" || lockState.kind === "stale" ? lockState.owner : null;
 }
+async function createDataDirLock(absoluteDataDir, lockPath, nonce, engineName) {
+  for (let attempt = 0;attempt < 3; attempt++) {
+    try {
+      return await writeDataDirLock(lockPath, nonce);
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      const lockState = await recoverStaleDataDirLock(lockPath);
+      if (lockState.kind === "active") {
+        throw new Error(`${engineName} data directory is already in use: ${absoluteDataDir} (pid ${lockState.owner.pid})`);
+      }
+      if (lockState.kind === "unreadable")
+        throw unreadableLockError(lockPath, engineName);
+    }
+  }
+  throw unreadableLockError(lockPath, engineName);
+}
+async function writeDataDirLock(lockPath, nonce) {
+  const handle = await open(lockPath, "wx", 384);
+  try {
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, nonce, createdAt: new Date().toISOString() })}
+`);
+    return handle;
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await unlink(lockPath).catch(() => {});
+    throw error;
+  }
+}
+function unreadableLockError(lockPath, engineName) {
+  return new Error(`${engineName} data directory has an unreadable lock: ${lockPath}. ` + "Confirm no SupaCloud Lite process is using it, then remove the lock manually.");
+}
 async function inspectDataDirLock(lockPath) {
   let contents;
   try {
@@ -3987,7 +5224,7 @@ begin
 end $$;
 `;
 async function createPgliteEngine(dataDir) {
-  const releaseLock = await acquireDataDirLock(dataDir);
+  const releaseLock = await acquireDataDirLock(dataDir, "PGlite");
   let PGlite, extensions;
   const standaloneAssets = getStandaloneAssets();
   let cleanupStandaloneBundles = async () => {};
@@ -4111,63 +5348,6 @@ async function removePreparedBundles(cleanup) {
     console.error("Unable to remove temporary PGlite extension bundles:", error);
   }
 }
-async function acquireDataDirLock(dataDir) {
-  if (!dataDir || dataDir.includes("://"))
-    return async () => {};
-  const absoluteDataDir = resolve(dataDir);
-  const lockPath = `${absoluteDataDir}.supacloud-lite.lock`;
-  await mkdir(dirname(absoluteDataDir), { recursive: true, mode: 448 });
-  const nonce = crypto.randomUUID();
-  const handle = await createDataDirLock(absoluteDataDir, lockPath, nonce);
-  let released = false;
-  return async () => {
-    if (released)
-      return;
-    released = true;
-    await handle?.close();
-    const owner = await readDataDirLockOwner(lockPath);
-    if (owner?.nonce !== nonce)
-      return;
-    await unlink2(lockPath).catch((error) => {
-      if (error.code !== "ENOENT")
-        throw error;
-    });
-  };
-}
-async function createDataDirLock(absoluteDataDir, lockPath, nonce) {
-  for (let attempt = 0;attempt < 3; attempt++) {
-    try {
-      return await writeDataDirLock(lockPath, nonce);
-    } catch (error) {
-      if (error.code !== "EEXIST")
-        throw error;
-      const lockState = await recoverStaleDataDirLock(lockPath);
-      if (lockState.kind === "active")
-        throw lockInUseError(absoluteDataDir, lockState.owner.pid);
-      if (lockState.kind === "unreadable")
-        throw unreadableLockError(lockPath);
-    }
-  }
-  throw unreadableLockError(lockPath);
-}
-async function writeDataDirLock(lockPath, nonce) {
-  const handle = await open(lockPath, "wx", 384);
-  try {
-    await handle.writeFile(`${JSON.stringify({ pid: process.pid, nonce, createdAt: new Date().toISOString() })}
-`);
-    return handle;
-  } catch (error) {
-    await handle.close().catch(() => {});
-    await unlink2(lockPath).catch(() => {});
-    throw error;
-  }
-}
-function lockInUseError(dataDir, pid) {
-  return new Error(`PGlite data directory is already in use: ${dataDir} (pid ${pid})`);
-}
-function unreadableLockError(lockPath) {
-  return new Error(`PGlite data directory has an unreadable lock: ${lockPath}. Confirm no SupaCloud Lite process is using it, then remove the lock manually.`);
-}
 
 // src/runtime/db/database.ts
 var DEFAULT_SEARCH_PATH_SQL = `set search_path to "$user", public, extensions`;
@@ -4185,20 +5365,30 @@ class Database {
   }
   static async create(dataDirOrEngine, opts) {
     const engine = dataDirOrEngine && typeof dataDirOrEngine === "object" ? dataDirOrEngine : await createPgliteEngine(dataDirOrEngine);
-    if (engine.minimalBootstrap) {
-      await engine.exec(MINIMAL_BOOTSTRAP_SQL);
-    } else {
-      await engine.exec(BOOTSTRAP_SQL);
-      await engine.exec(PGMQ_SQL);
-      await engine.exec(CRON_SQL);
-      await engine.exec(NET_SQL);
-      await engine.exec(EXT_COMPAT_SQL);
-      await engine.exec(VAULT_SQL);
-      if (opts?.vaultKey) {
-        await engine.query(`select set_config('app.settings.vault_key', $1, false)`, [opts.vaultKey]);
+    try {
+      if (engine.minimalBootstrap) {
+        await engine.exec(MINIMAL_BOOTSTRAP_SQL);
+      } else {
+        await engine.exec(BOOTSTRAP_SQL);
+        await engine.exec(PGMQ_SQL);
+        await engine.exec(WORKFLOWS_SQL);
+        await engine.exec(CRON_SQL);
+        await engine.exec(NET_SQL);
+        await engine.exec(EXT_COMPAT_SQL);
+        await engine.exec(VAULT_SQL);
+        if (opts?.vaultKey) {
+          await engine.query(`select set_config('app.settings.vault_key', $1, false)`, [opts.vaultKey]);
+        }
+      }
+      return new Database(engine);
+    } catch (error) {
+      try {
+        await engine.close();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "database bootstrap and cleanup failed");
       }
+      throw error;
     }
-    return new Database(engine);
   }
   query(sql, params) {
     return this.engine.query(sql, params);
@@ -5937,6 +7127,25 @@ function parsePrefer(header) {
   }
   return prefer;
 }
+function applyRequestRange(query, request) {
+  const range = request.headers.get("range");
+  if (!range || query.limits.has("") || query.offsets.has(""))
+    return;
+  const unit = request.headers.get("range-unit");
+  if (unit !== null && unit.toLowerCase() !== "items")
+    throw new ParseError(`unsupported range unit: ${unit}`);
+  const match = range.match(/^(\d+)-(\d*)$/);
+  if (!match)
+    throw new ParseError(`invalid range: ${range}`);
+  const start = Number(match[1]);
+  const end = match[2] ? Number(match[2]) : undefined;
+  if (!Number.isSafeInteger(start) || end !== undefined && (!Number.isSafeInteger(end) || end < start)) {
+    throw new ParseError(`invalid range: ${range}`);
+  }
+  query.offsets.set("", start);
+  if (end !== undefined)
+    query.limits.set("", end - start + 1);
+}
 var OBJECT_MEDIA = "application/vnd.pgrst.object+json";
 var CSV_MEDIA = "text/csv";
 var PLAN_MEDIA = "application/vnd.pgrst.plan";
@@ -6013,6 +7222,8 @@ class RestHandler {
     const wantsObject = accept.includes(OBJECT_MEDIA);
     const wantsCsv = accept.includes(CSV_MEDIA);
     const q = parseQuery(url.searchParams);
+    if (method === "GET" || method === "HEAD")
+      applyRequestRange(q, req);
     if (this.maxRows !== undefined && (method === "GET" || method === "HEAD")) {
       const requested = q.limits.get("");
       q.limits.set("", requested === undefined ? this.maxRows : Math.min(requested, this.maxRows));
@@ -6055,10 +7266,11 @@ class RestHandler {
           }
           return { rows: res.rows[0].body, count: count2 };
         });
+        const offset = q.offsets.get("") ?? 0;
         return this.dataResponse(rows, {
-          status: 200,
+          status: count !== null && (offset > 0 || rows.length < count) ? 206 : 200,
           count,
-          offset: q.offsets.get("") ?? 0,
+          offset,
           wantsObject,
           wantsCsv,
           head: method === "HEAD"
@@ -6489,8 +7701,10 @@ function applyResize(image, metadata, options) {
   const proportionalWidth = Math.max(1, Math.round(metadata.width * options.height / metadata.height));
   image.resize(proportionalWidth);
 }
-async function transformImage(bytes, options) {
-  if (bytes.byteLength > MAX_TRANSFORM_BYTES) {
+async function transformImage(source, options, knownSourceSize) {
+  const actualSourceSize = source instanceof Uint8Array ? source.byteLength : await Promise.resolve(source.size);
+  const sourceSize = Math.max(knownSourceSize ?? 0, actualSourceSize);
+  if (sourceSize > MAX_TRANSFORM_BYTES) {
     return {
       ok: false,
       status: 413,
@@ -6498,9 +7712,10 @@ async function transformImage(bytes, options) {
       message: "The source image exceeds the 25MB transformation limit"
     };
   }
+  const image = new Bun.Image(source, { maxPixels: MAX_TRANSFORM_PIXELS });
   let metadata;
   try {
-    metadata = await new Bun.Image(bytes, { maxPixels: MAX_TRANSFORM_PIXELS }).metadata();
+    metadata = await image.metadata();
   } catch (error) {
     return mapImageError(error);
   }
@@ -6517,7 +7732,6 @@ async function transformImage(bytes, options) {
       message: `The source format ${outputFormat} is not supported by this runtime`
     };
   }
-  const image = new Bun.Image(bytes, { maxPixels: MAX_TRANSFORM_PIXELS });
   applyResize(image, metadata, options);
   if (options.format === "jpeg" || options.format === "origin" && outputFormat === "jpeg" && options.quality !== undefined) {
     image.jpeg(options.quality === undefined ? undefined : { quality: options.quality });
@@ -6527,12 +7741,127 @@ async function transformImage(bytes, options) {
     image.webp(options.quality === undefined ? undefined : { quality: options.quality });
   }
   try {
-    return { ok: true, bytes: await image.bytes(), contentType };
+    const bytes = await image.bytes();
+    if (bytes.byteLength > MAX_TRANSFORM_BYTES) {
+      return {
+        ok: false,
+        status: 413,
+        error: "ImageTooLarge",
+        message: "The transformed image exceeds the 25MB transformation limit"
+      };
+    }
+    return { ok: true, bytes, contentType };
   } catch (error) {
     return mapImageError(error);
   }
 }
 
+// src/runtime/storage/image-transform-cache.ts
+var DEFAULT_MAX_CACHE_BYTES = 64 * 1024 * 1024;
+var DEFAULT_MAX_CACHE_ENTRIES = 128;
+var OBJECT_VERSION_PREFIX = "v2-";
+
+class Semaphore {
+  limit;
+  active = 0;
+  waiters = [];
+  constructor(limit) {
+    this.limit = limit;
+  }
+  async run(operation) {
+    await this.acquire();
+    try {
+      return await operation();
+    } finally {
+      this.release();
+    }
+  }
+  async acquire() {
+    if (this.active < this.limit) {
+      this.active += 1;
+      return;
+    }
+    await new Promise((resolve2) => this.waiters.push(resolve2));
+  }
+  release() {
+    const next = this.waiters.shift();
+    if (next) {
+      next();
+      return;
+    }
+    this.active -= 1;
+  }
+}
+var globalImageTransformSemaphore = new Semaphore(1);
+function imageTransformCacheKey(version, options) {
+  if (!version?.startsWith(OBJECT_VERSION_PREFIX))
+    return null;
+  return [
+    version,
+    options.width ?? "",
+    options.height ?? "",
+    options.resize,
+    options.quality ?? "",
+    options.format
+  ].join("\x00");
+}
+
+class ImageTransformCache {
+  maxBytes;
+  maxEntries;
+  entries = new Map;
+  inFlight = new Map;
+  cachedBytes = 0;
+  constructor(maxBytes = DEFAULT_MAX_CACHE_BYTES, maxEntries = DEFAULT_MAX_CACHE_ENTRIES) {
+    this.maxBytes = maxBytes;
+    this.maxEntries = maxEntries;
+  }
+  async getOrTransform(key, operation) {
+    if (key === null)
+      return globalImageTransformSemaphore.run(operation);
+    const cached = this.entries.get(key);
+    if (cached) {
+      this.entries.delete(key);
+      this.entries.set(key, cached);
+      return cached.transform;
+    }
+    const pending = this.inFlight.get(key);
+    if (pending)
+      return pending;
+    const transform = globalImageTransformSemaphore.run(operation);
+    this.inFlight.set(key, transform);
+    try {
+      const transformResult = await transform;
+      if (transformResult.ok)
+        this.store(key, transformResult);
+      return transformResult;
+    } finally {
+      if (this.inFlight.get(key) === transform)
+        this.inFlight.delete(key);
+    }
+  }
+  store(key, transform) {
+    const size = transform.bytes.byteLength;
+    if (size > this.maxBytes || this.maxEntries === 0)
+      return;
+    const previous = this.entries.get(key);
+    if (previous) {
+      this.cachedBytes -= previous.size;
+      this.entries.delete(key);
+    }
+    this.entries.set(key, { transform, size });
+    this.cachedBytes += size;
+    while (this.entries.size > this.maxEntries || this.cachedBytes > this.maxBytes) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey === undefined)
+        break;
+      const oldest = this.entries.get(oldestKey);
+      this.entries.delete(oldestKey);
+      this.cachedBytes -= oldest.size;
+    }
+  }
+}
+
 // src/runtime/storage/handler.ts
 var MAX_SIGNED_URL_EXPIRY = 7 * 24 * 60 * 60;
 function clampExpiry(expiresIn) {
@@ -6611,7 +7940,7 @@ var MAX_COMPLETED_TUS_UPLOADS = 64;
 var COMPLETED_TUS_RETENTION_MS = 60 * 60 * 1000;
 var PREFLIGHT_ROLLBACK = Symbol("storage-preflight-rollback");
 var INTERNAL_STORAGE_BUCKET = ".supacloud-lite";
-var OBJECT_VERSION_PREFIX = "v2-";
+var OBJECT_VERSION_PREFIX2 = "v2-";
 
 class StorageHandler {
   db;
@@ -6619,6 +7948,7 @@ class StorageHandler {
   config;
   tusUploads = new Map;
   mutationTail = Promise.resolve();
+  imageTransforms = new ImageTransformCache;
   constructor(db, driver, config) {
     this.db = db;
     this.driver = driver;
@@ -6661,15 +7991,21 @@ class StorageHandler {
         const bucket2 = parts[3];
         const key2 = parts.slice(4).join("/");
         if (kind === "public" && (method === "GET" || method === "HEAD")) {
-          const source = await this.downloadPublic(bucket2, key2, false);
+          const source = await this.loadPublicObject(bucket2, key2);
+          if (source instanceof Response)
+            return source;
           return await this.transformImageResponse(source, url, method === "HEAD");
         }
         if (kind === "authenticated" && (method === "GET" || method === "HEAD")) {
-          const source = await this.download(ctx, bucket2, key2, false);
+          const source = await this.loadAuthenticatedObject(ctx, bucket2, key2);
+          if (source instanceof Response)
+            return source;
           return await this.transformImageResponse(source, url, method === "HEAD");
         }
         if (kind === "sign" && method === "GET") {
-          const source = await this.redeemSignedUrl(url, bucket2, key2);
+          const source = await this.loadSignedObject(url, bucket2, key2);
+          if (source instanceof Response)
+            return source;
           return await this.transformImageResponse(source, url, false);
         }
         return storageError(404, "not_found", `unknown render endpoint: ${rest}`);
@@ -6882,21 +8218,31 @@ class StorageHandler {
       throw e;
     }
   }
-  async transformImageResponse(source, url, head) {
-    if (!source.ok)
-      return source;
+  async transformImageResponse(row, url, head) {
     const parsed = parseImageTransform(url.searchParams);
     if (!parsed.ok)
       return storageError(parsed.status, parsed.error, parsed.message);
-    const result = await transformImage(new Uint8Array(await source.arrayBuffer()), parsed.value);
+    let result;
+    try {
+      result = await this.imageTransforms.getOrTransform(imageTransformCacheKey(row.version, parsed.value), async () => {
+        const source = await this.readObjectSource(row);
+        if (source === null)
+          throw new StorageObjectMissingError;
+        return transformImage(source, parsed.value, objectSize(row));
+      });
+    } catch (error) {
+      if (error instanceof StorageObjectMissingError) {
+        return storageError(404, "not_found", "Object not found");
+      }
+      throw error;
+    }
     if (!result.ok)
       return storageError(result.status, result.error, result.message);
-    const headers = new Headers(source.headers);
+    const headers = objectHeaders(row, result.bytes.length);
     headers.delete("content-disposition");
     headers.delete("etag");
     headers.set("content-type", result.contentType);
-    headers.set("content-length", String(result.bytes.length));
-    return new Response(head ? null : result.bytes, { status: source.status, headers });
+    return new Response(head ? null : result.bytes, { status: 200, headers });
   }
   async persistObject(ctx, bucketId, key, bytes, contentType, cacheControl, upsert) {
     const metadata = objectMetadata(bytes.length, contentType, cacheControl);
@@ -7166,13 +8512,25 @@ class StorageHandler {
     return null;
   }
   async download(ctx, bucketId, key, head) {
+    const row = await this.loadAuthenticatedObject(ctx, bucketId, key);
+    if (row instanceof Response)
+      return row;
+    return this.serveObject(row, head);
+  }
+  async loadAuthenticatedObject(ctx, bucketId, key) {
     const res = await this.db.withContext(ctx, (q) => q(`select * from storage.objects where bucket_id = $1 and name = $2`, [bucketId, key]));
     const row = res.rows[0];
     if (!row)
       return storageError(404, "not_found", "Object not found");
-    return this.serveObject(row, head);
+    return row;
   }
   async downloadPublic(bucketId, key, head) {
+    const row = await this.loadPublicObject(bucketId, key);
+    if (row instanceof Response)
+      return row;
+    return this.serveObject(row, head);
+  }
+  async loadPublicObject(bucketId, key) {
     const bucket = await this.loadBucket(bucketId);
     if (!bucket?.public)
       return storageError(400, "not_found", "Bucket is not public");
@@ -7183,24 +8541,16 @@ class StorageHandler {
     const row = res.rows[0];
     if (!row)
       return storageError(404, "not_found", "Object not found");
-    return this.serveObject(row, head);
+    return row;
   }
   async serveObject(row, head) {
     const bytes = await this.readObjectBytes(row);
     if (bytes === null)
       return storageError(404, "not_found", "Object not found");
-    const meta = row.metadata ?? {};
-    const contentType = String(meta.mimetype ?? "application/octet-stream");
-    const headers = {
-      "content-type": contentType,
-      "content-length": String(bytes.length),
-      "cache-control": String(meta.cacheControl ?? "no-cache"),
-      etag: String(meta.eTag ?? '""'),
-      "last-modified": new Date(String(meta.lastModified ?? Date.now())).toUTCString(),
-      "x-content-type-options": "nosniff"
-    };
+    const contentType = String(row.metadata?.mimetype ?? "application/octet-stream");
+    const headers = objectHeaders(row, bytes.length);
     if (isRenderableActiveType(contentType))
-      headers["content-disposition"] = "attachment";
+      headers.set("content-disposition", "attachment");
     return new Response(head ? null : bytes, { status: 200, headers });
   }
   async removeObjects(req, ctx, bucketId) {
@@ -7311,9 +8661,11 @@ class StorageHandler {
     throw error;
   }
   async readObjectBytes(row) {
-    if (isVersionedObjectVersion(row.version))
-      return this.driver.get(objectVersionKey(row.version));
-    return this.driver.get(legacyObjectKey(row));
+    return this.driver.get(storageKey(row));
+  }
+  async readObjectSource(row) {
+    const key = storageKey(row);
+    return this.driver.getBlob ? this.driver.getBlob(key) : this.driver.get(key);
   }
   async cleanupObjectRows(rows) {
     const keys = rows.flatMap((row) => [
@@ -7416,6 +8768,12 @@ class StorageHandler {
     return json3(200, out);
   }
   async redeemSignedUrl(url, bucketId, key) {
+    const row = await this.loadSignedObject(url, bucketId, key);
+    if (row instanceof Response)
+      return row;
+    return this.serveObject(row, false);
+  }
+  async loadSignedObject(url, bucketId, key) {
     const token = url.searchParams.get("token") ?? "";
     const claims = await verifyJwt(token, this.config.jwtSecret);
     if (!claims || claims.url !== `${bucketId}/${key}` || claims.type !== "download") {
@@ -7428,7 +8786,7 @@ class StorageHandler {
     const row = res.rows[0];
     if (!row)
       return storageError(404, "not_found", "Object not found");
-    return this.serveObject(row, false);
+    return row;
   }
   async signUploadUrl(ctx, bucketId, key) {
     const keyErr = invalidObjectKey(key);
@@ -7486,6 +8844,9 @@ function objectJson(r) {
 
 class StorageValidationError extends Error {
 }
+
+class StorageObjectMissingError extends Error {
+}
 function parseSizeLimit(v) {
   if (v === null || v === undefined || v === "")
     return null;
@@ -7508,14 +8869,32 @@ function objectMetadata(size, contentType, cacheControl) {
     httpStatusCode: 200
   };
 }
+function objectHeaders(row, contentLength) {
+  const metadata = row.metadata ?? {};
+  return new Headers({
+    "content-type": String(metadata.mimetype ?? "application/octet-stream"),
+    "content-length": String(contentLength),
+    "cache-control": String(metadata.cacheControl ?? "no-cache"),
+    etag: String(metadata.eTag ?? '""'),
+    "last-modified": new Date(String(metadata.lastModified ?? Date.now())).toUTCString(),
+    "x-content-type-options": "nosniff"
+  });
+}
+function objectSize(row) {
+  const size = Number(row.metadata?.size);
+  return Number.isFinite(size) && size >= 0 ? size : undefined;
+}
 function objectVersionKey(version) {
   return `.supacloud-lite/objects/${version}`;
 }
+function storageKey(row) {
+  return isVersionedObjectVersion(row.version) ? objectVersionKey(row.version) : legacyObjectKey(row);
+}
 function createObjectVersion() {
-  return `${OBJECT_VERSION_PREFIX}${crypto.randomUUID()}`;
+  return `${OBJECT_VERSION_PREFIX2}${crypto.randomUUID()}`;
 }
 function isVersionedObjectVersion(version) {
-  return version?.startsWith(OBJECT_VERSION_PREFIX) ?? false;
+  return version?.startsWith(OBJECT_VERSION_PREFIX2) ?? false;
 }
 function isInternalStorageBucket(bucketId) {
   return bucketId === INTERNAL_STORAGE_BUCKET || bucketId.startsWith(`${INTERNAL_STORAGE_BUCKET}/`);
@@ -8767,6 +10146,21 @@ class S3StorageDriver {
       throw error;
     }
   }
+  async getBlob(key) {
+    const file = this.client.file(this.objectKey(key));
+    if (!await file.exists())
+      return null;
+    if (typeof file.arrayBuffer === "function")
+      return file;
+    try {
+      const bytes = Uint8Array.from(await file.bytes());
+      return new Blob([bytes.buffer]);
+    } catch (error) {
+      if (isNotFoundError(error))
+        return null;
+      throw error;
+    }
+  }
   async delete(key) {
     await this.client.file(this.objectKey(key)).delete();
   }
@@ -8816,6 +10210,10 @@ class FsStorageDriver {
       throw e;
     }
   }
+  async getBlob(key) {
+    const file = Bun.file(this.resolve(key));
+    return await file.exists() ? file : null;
+  }
   async delete(key) {
     await rm(this.resolve(key), { force: true });
   }
@@ -8870,20 +10268,787 @@ async function serveBun(backend, opts = {}) {
     }
   };
 }
+// src/runtime/node/native/engine.ts
+import { execFileSync, spawn } from "child_process";
+import { createHash as createHash2, randomBytes as randomBytes2 } from "crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "fs";
+import { writeFile as writeFile2 } from "fs/promises";
+import { homedir, tmpdir } from "os";
+import { join as join2 } from "path";
+import { extract as extractTar } from "tar";
+
+// src/runtime/node/native/wire.ts
+import { createConnection } from "net";
+import { createHash, createHmac, pbkdf2Sync, randomBytes } from "crypto";
+
+class PgWireError extends Error {
+  code;
+  detail;
+  hint;
+  severity;
+  constructor(fields) {
+    super(fields.get("M") ?? "postgres error");
+    this.code = fields.get("C");
+    this.detail = fields.get("D");
+    this.hint = fields.get("H");
+    this.severity = fields.get("S");
+  }
+}
+
+class PgWireClient {
+  socket;
+  buffer = Buffer.alloc(0);
+  pending = null;
+  queue = Promise.resolve();
+  closed = false;
+  onNotification = null;
+  static async connect(opts) {
+    const client = new PgWireClient;
+    await client.open(opts);
+    return client;
+  }
+  open(opts) {
+    return new Promise((resolve2, reject) => {
+      this.socket = opts.socketPath ? createConnection(opts.socketPath) : createConnection(opts.port ?? 5432, opts.host ?? "127.0.0.1");
+      this.socket.on("error", (e) => {
+        if (this.pending)
+          this.pending.reject(e);
+        reject(e);
+      });
+      this.socket.on("close", () => {
+        this.closed = true;
+        this.pending?.reject(new Error("connection closed"));
+      });
+      this.socket.on("connect", () => {
+        const params = `user\x00${opts.user}\x00database\x00${opts.database}\x00client_encoding\x00UTF8\x00\x00`;
+        const body = Buffer.from(params, "utf8");
+        const msg = Buffer.alloc(8 + body.length);
+        msg.writeInt32BE(8 + body.length, 0);
+        msg.writeInt32BE(196608, 4);
+        body.copy(msg, 8);
+        this.socket.write(msg);
+      });
+      let clientNonce = "";
+      let clientFirstBare = "";
+      let serverSignature = "";
+      const needPassword = () => {
+        if (opts.password == null) {
+          reject(new Error("the server requested a password but none was provided"));
+          return false;
+        }
+        return true;
+      };
+      const startupHandler = (chunk) => {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        let msg;
+        while ((msg = this.nextMessage()) !== null) {
+          const [type, payload] = msg;
+          if (type === 82) {
+            const code = payload.readInt32BE(0);
+            if (code === 0) {} else if (code === 3) {
+              if (!needPassword())
+                return;
+              this.socket.write(message(112, cstring(opts.password)));
+            } else if (code === 5) {
+              if (!needPassword())
+                return;
+              const salt = payload.subarray(4, 8);
+              const inner = md5Hex(Buffer.from(opts.password + opts.user, "utf8"));
+              const token = "md5" + md5Hex(Buffer.concat([Buffer.from(inner, "utf8"), salt]));
+              this.socket.write(message(112, cstring(token)));
+            } else if (code === 10) {
+              if (!needPassword())
+                return;
+              const mechs = payload.subarray(4).toString("utf8").split("\x00").filter(Boolean);
+              if (!mechs.includes("SCRAM-SHA-256")) {
+                reject(new Error(`no supported SASL mechanism (server offered: ${mechs.join(", ")})`));
+                return;
+              }
+              clientNonce = randomBytes(18).toString("base64");
+              clientFirstBare = `n=,r=${clientNonce}`;
+              const initial = Buffer.from(`n,,${clientFirstBare}`, "utf8");
+              this.socket.write(message(112, Buffer.concat([cstring("SCRAM-SHA-256"), int32(initial.length), initial])));
+            } else if (code === 11) {
+              const serverFirst = payload.subarray(4).toString("utf8");
+              const attrs = scramAttrs(serverFirst);
+              if (!attrs.r?.startsWith(clientNonce)) {
+                reject(new Error("SCRAM: server nonce does not extend client nonce"));
+                return;
+              }
+              const salt = Buffer.from(attrs.s, "base64");
+              const iterations = parseInt(attrs.i, 10);
+              const saltedPassword = pbkdf2Sync(opts.password, salt, iterations, 32, "sha256");
+              const clientKey = hmac(saltedPassword, "Client Key");
+              const storedKey = sha256(clientKey);
+              const finalNoProof = `c=biws,r=${attrs.r}`;
+              const authMessage = `${clientFirstBare},${serverFirst},${finalNoProof}`;
+              const clientSignature = hmac(storedKey, authMessage);
+              const proof = xorBuffers(clientKey, clientSignature);
+              serverSignature = hmac(hmac(saltedPassword, "Server Key"), authMessage).toString("base64");
+              const clientFinal = `${finalNoProof},p=${proof.toString("base64")}`;
+              this.socket.write(message(112, Buffer.from(clientFinal, "utf8")));
+            } else if (code === 12) {
+              const v = scramAttrs(payload.subarray(4).toString("utf8")).v;
+              if (v && serverSignature && v !== serverSignature) {
+                reject(new Error("SCRAM: server signature verification failed"));
+                return;
+              }
+            } else {
+              reject(new Error(`unsupported auth method ${code}`));
+              return;
+            }
+          } else if (type === 69) {
+            reject(new PgWireError(parseErrorFields(payload)));
+            return;
+          } else if (type === 90) {
+            this.socket.off("data", startupHandler);
+            this.socket.on("data", (c) => {
+              this.buffer = Buffer.concat([this.buffer, c]);
+              this.processMessages();
+            });
+            resolve2();
+            return;
+          }
+        }
+      };
+      this.socket.on("data", startupHandler);
+    });
+  }
+  run(send) {
+    const op = this.queue.then(() => new Promise((resolve2, reject) => {
+      if (this.closed)
+        return reject(new Error("connection closed"));
+      this.pending = { resolve: resolve2, reject, results: [], columns: [], error: null };
+      send();
+    }));
+    this.queue = op.catch(() => {});
+    return op;
+  }
+  async exec(sql) {
+    return this.run(() => this.socket.write(message(81, cstring(sql))));
+  }
+  async query(sql, params = []) {
+    const results = await this.run(() => {
+      const parse = message(80, Buffer.concat([cstring(""), cstring(sql), int16(0)]));
+      const paramBufs = [int16(0), int16(params.length)];
+      for (const p of params) {
+        if (p === null || p === undefined) {
+          paramBufs.push(int32(-1));
+        } else {
+          const b = Buffer.from(String(p), "utf8");
+          paramBufs.push(int32(b.length), b);
+        }
+      }
+      paramBufs.push(int16(0));
+      const bind = message(66, Buffer.concat([cstring(""), cstring(""), ...paramBufs]));
+      const describe = message(68, Buffer.concat([Buffer.from("P"), cstring("")]));
+      const execute = message(69, Buffer.concat([cstring(""), int32(0)]));
+      const sync = message(83, Buffer.alloc(0));
+      this.socket.write(Buffer.concat([parse, bind, describe, execute, sync]));
+    });
+    return results[0] ?? { rows: [] };
+  }
+  close() {
+    return new Promise((resolve2) => {
+      if (this.closed)
+        return resolve2();
+      this.socket.write(message(88, Buffer.alloc(0)));
+      this.socket.end(() => resolve2());
+    });
+  }
+  nextMessage() {
+    if (this.buffer.length < 5)
+      return null;
+    const type = this.buffer[0];
+    const length = this.buffer.readInt32BE(1);
+    if (this.buffer.length < 1 + length)
+      return null;
+    const payload = this.buffer.subarray(5, 1 + length);
+    this.buffer = this.buffer.subarray(1 + length);
+    return [type, Buffer.from(payload)];
+  }
+  processMessages() {
+    let msg;
+    while ((msg = this.nextMessage()) !== null) {
+      const [type, payload] = msg;
+      const p = this.pending;
+      switch (type) {
+        case 84: {
+          if (!p)
+            break;
+          const count = payload.readInt16BE(0);
+          let off = 2;
+          const columns = [];
+          for (let i = 0;i < count; i++) {
+            const end = payload.indexOf(0, off);
+            const name = payload.toString("utf8", off, end);
+            off = end + 1;
+            const typeOid = payload.readInt32BE(off + 6);
+            off += 18;
+            columns.push({ name, typeOid });
+          }
+          p.columns = columns;
+          break;
+        }
+        case 68: {
+          if (!p)
+            break;
+          const count = payload.readInt16BE(0);
+          let off = 2;
+          const row = {};
+          for (let i = 0;i < count; i++) {
+            const len = payload.readInt32BE(off);
+            off += 4;
+            let value = null;
+            if (len >= 0) {
+              value = decodeValue(payload.toString("utf8", off, off + len), p.columns[i]?.typeOid ?? 25);
+              off += len;
+            }
+            row[p.columns[i]?.name ?? `col${i}`] = value;
+          }
+          if (p.results.length === 0)
+            p.results.push({ rows: [] });
+          p.results[p.results.length - 1].rows.push(row);
+          break;
+        }
+        case 67: {
+          if (!p)
+            break;
+          const tag = payload.toString("utf8", 0, payload.length - 1);
+          const parts = tag.split(" ");
+          const affected = parseInt(parts[parts.length - 1], 10);
+          if (p.results.length === 0)
+            p.results.push({ rows: [] });
+          const current = p.results[p.results.length - 1];
+          if (!Number.isNaN(affected))
+            current.affectedRows = affected;
+          p.results.push({ rows: [] });
+          p.columns = [];
+          break;
+        }
+        case 69: {
+          if (p)
+            p.error = new PgWireError(parseErrorFields(payload));
+          break;
+        }
+        case 65: {
+          payload.readInt32BE(0);
+          const channelEnd = payload.indexOf(0, 4);
+          const channel = payload.toString("utf8", 4, channelEnd);
+          const payloadEnd = payload.indexOf(0, channelEnd + 1);
+          const body = payload.toString("utf8", channelEnd + 1, payloadEnd);
+          this.onNotification?.(channel, body);
+          break;
+        }
+        case 90: {
+          if (!p)
+            break;
+          this.pending = null;
+          if (p.error)
+            p.reject(p.error);
+          else {
+            const results = p.results.filter((r, i) => i < p.results.length - 1 || r.rows.length > 0 || r.affectedRows !== undefined);
+            p.resolve(results.length > 0 ? results : [{ rows: [] }]);
+          }
+          break;
+        }
+      }
+    }
+  }
+}
+var hmac = (key, data) => createHmac("sha256", key).update(data, "utf8").digest();
+var sha256 = (b) => createHash("sha256").update(b).digest();
+var md5Hex = (b) => createHash("md5").update(b).digest("hex");
+function xorBuffers(a, b) {
+  const out = Buffer.alloc(a.length);
+  for (let i = 0;i < a.length; i++)
+    out[i] = a[i] ^ b[i];
+  return out;
+}
+function scramAttrs(s) {
+  const out = {};
+  for (const part of s.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq > 0)
+      out[part.slice(0, eq)] = part.slice(eq + 1);
+  }
+  return out;
+}
+function message(type, body) {
+  const out = Buffer.alloc(5 + body.length);
+  out[0] = type;
+  out.writeInt32BE(4 + body.length, 1);
+  body.copy(out, 5);
+  return out;
+}
+var cstring = (s) => Buffer.from(s + "\x00", "utf8");
+var int16 = (n) => {
+  const b = Buffer.alloc(2);
+  b.writeInt16BE(n);
+  return b;
+};
+var int32 = (n) => {
+  const b = Buffer.alloc(4);
+  b.writeInt32BE(n);
+  return b;
+};
+function parseErrorFields(payload) {
+  const fields = new Map;
+  let off = 0;
+  while (off < payload.length && payload[off] !== 0) {
+    const key = String.fromCharCode(payload[off]);
+    const end = payload.indexOf(0, off + 1);
+    fields.set(key, payload.toString("utf8", off + 1, end));
+    off = end + 1;
+  }
+  return fields;
+}
+function decodeValue(text, oid) {
+  switch (oid) {
+    case 16:
+      return text === "t";
+    case 20: {
+      const n = Number(text);
+      return Number.isSafeInteger(n) ? n : text;
+    }
+    case 21:
+    case 23:
+    case 26:
+      return Number(text);
+    case 700:
+    case 701:
+      return Number(text);
+    case 114:
+    case 3802:
+      return JSON.parse(text);
+    case 1114:
+      return new Date(text.replace(" ", "T") + "Z");
+    case 1184: {
+      let iso3 = text.replace(" ", "T");
+      if (/[+-]\d\d$/.test(iso3))
+        iso3 += ":00";
+      return new Date(iso3);
+    }
+    case 1000:
+      return parsePgArray(text).map((v) => v === "t");
+    case 1007:
+      return parsePgArray(text).map((v) => v === null ? null : Number(v));
+    case 1016:
+      return parsePgArray(text).map((v) => {
+        if (v === null)
+          return null;
+        const n = Number(v);
+        return Number.isSafeInteger(n) ? n : v;
+      });
+    case 1003:
+    case 1009:
+    case 1015:
+      return parsePgArray(text);
+    default:
+      return text;
+  }
+}
+function parsePgArray(text) {
+  const out = [];
+  if (text.length < 2)
+    return out;
+  let i = 1;
+  while (i < text.length - 1) {
+    if (text[i] === ",") {
+      i++;
+      continue;
+    }
+    if (text[i] === '"') {
+      let value = "";
+      i++;
+      while (text[i] !== '"') {
+        if (text[i] === "\\")
+          i++;
+        value += text[i++];
+      }
+      i++;
+      out.push(value);
+    } else {
+      let value = "";
+      while (i < text.length - 1 && text[i] !== ",")
+        value += text[i++];
+      out.push(value === "NULL" ? null : value);
+    }
+  }
+  return out;
+}
+
+// src/runtime/db/engine.ts
+class Mutex {
+  tail = Promise.resolve();
+  async lock() {
+    let release;
+    const next = new Promise((r) => release = r);
+    const prev = this.tail;
+    this.tail = this.tail.then(() => next);
+    await prev;
+    return release;
+  }
+  async run(fn) {
+    const release = await this.lock();
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+}
+
+// src/runtime/node/native/wire-engine.ts
+async function buildWireEngine(options) {
+  const queryClient = await options.connect();
+  let listenerClient;
+  try {
+    listenerClient = await options.connect();
+  } catch (error) {
+    await queryClient.close().catch(() => {});
+    throw error;
+  }
+  const queryMutex = new Mutex;
+  const listenerMutex = new Mutex;
+  const listeners = new Map;
+  listenerClient.onNotification = (channel, payload) => {
+    for (const listener of listeners.get(channel) ?? [])
+      listener(payload);
+  };
+  const transactionClient = {
+    async query(sql, params) {
+      const queryResult = await queryClient.query(sql, normalizeParams(params));
+      return { rows: queryResult.rows, affectedRows: queryResult.affectedRows };
+    },
+    async exec(sql) {
+      await queryClient.exec(sql);
+    }
+  };
+  let closePromise = null;
+  return {
+    query(sql, params) {
+      return queryMutex.run(() => transactionClient.query(sql, params));
+    },
+    exec(sql) {
+      return queryMutex.run(() => transactionClient.exec(sql));
+    },
+    transaction(callback) {
+      return queryMutex.run(async () => {
+        await queryClient.exec("begin");
+        try {
+          const response = await callback(transactionClient);
+          await queryClient.exec("commit");
+          return response;
+        } catch (error) {
+          await queryClient.exec("rollback").catch(() => {});
+          throw error;
+        }
+      });
+    },
+    async listen(channel, listener) {
+      return listenerMutex.run(async () => {
+        let channelListeners = listeners.get(channel);
+        if (!channelListeners) {
+          channelListeners = new Set;
+          await listenerClient.exec(`listen "${channel.replaceAll('"', '""')}"`);
+          listeners.set(channel, channelListeners);
+        }
+        channelListeners.add(listener);
+        return () => {
+          channelListeners.delete(listener);
+        };
+      });
+    },
+    close() {
+      closePromise ??= closeWireEngine(queryClient, listenerClient, options.onClose);
+      return closePromise;
+    }
+  };
+}
+async function closeWireEngine(queryClient, listenerClient, onClose) {
+  const closeResults = await Promise.allSettled([queryClient.close(), listenerClient.close()]);
+  let engineCleanupError;
+  try {
+    await onClose?.();
+  } catch (error) {
+    engineCleanupError = error;
+  }
+  const connectionErrors = closeResults.flatMap((closeResult) => closeResult.status === "rejected" ? [closeResult.reason] : []);
+  if (engineCleanupError !== undefined)
+    connectionErrors.push(engineCleanupError);
+  if (connectionErrors.length > 0)
+    throw new AggregateError(connectionErrors, "native database cleanup failed");
+}
+function normalizeParams(params) {
+  return params?.map((parameter) => {
+    if (parameter === null || parameter === undefined)
+      return null;
+    if (Array.isArray(parameter))
+      return toPgArrayLiteral(parameter);
+    if (parameter instanceof Date)
+      return parameter.toISOString();
+    if (typeof parameter === "object")
+      return JSON.stringify(parameter);
+    return parameter;
+  });
+}
+function toPgArrayLiteral(array) {
+  const encoded = array.map((element) => {
+    if (element === null || element === undefined)
+      return "NULL";
+    if (Array.isArray(element))
+      return toPgArrayLiteral(element);
+    if (typeof element === "number" || typeof element === "boolean")
+      return String(element);
+    const text = typeof element === "object" ? JSON.stringify(element) : String(element);
+    return `"${text.replaceAll("\\", "\\\\").replaceAll('"', "\\\"")}"`;
+  });
+  return `{${encoded.join(",")}}`;
+}
+
+// src/runtime/node/native/engine.ts
+var DEFAULT_PG_VERSION = "17.7.0";
+var NATIVE_POSTGRES_MAJOR = DEFAULT_PG_VERSION.split(".")[0];
+function isNativeEngineSupported() {
+  return (process.platform === "darwin" || process.platform === "linux") && (process.arch === "arm64" || process.arch === "x64") && (process.platform !== "linux" || isGlibcLinux());
+}
+function isGlibcLinux() {
+  try {
+    const version = execFileSync("ldd", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return /glibc|gnu libc/i.test(version);
+  } catch {
+    return false;
+  }
+}
+function target() {
+  const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "x86_64" : null;
+  if (!arch)
+    throw new Error(`unsupported architecture for native engine: ${process.arch}`);
+  if (process.platform === "darwin")
+    return `${arch}-apple-darwin`;
+  if (process.platform === "linux")
+    return `${arch}-unknown-linux-gnu`;
+  throw new Error(`unsupported platform for native engine: ${process.platform} (use the default PGlite engine)`);
+}
+function isCompleteInstall(dir) {
+  return existsSync(join2(dir, "bin", "postgres")) && existsSync(join2(dir, "share", "postgres.bki"));
+}
+var PINNED_SHA256 = {
+  "postgresql-17.7.0-x86_64-unknown-linux-gnu": "66ad03281a43624f955c8e16ac975cb0ab751e7edf8ba35308e3b08dd7d065c3",
+  "postgresql-17.7.0-aarch64-unknown-linux-gnu": "89cc2f089880cc8e5e6b7a29387829ec4e4779427855bc0b9fa187c8fce33c8b",
+  "postgresql-17.7.0-x86_64-apple-darwin": "0dd8c25173524bad4ae8ef6b970da1ac40f4c1f231150c416ccb8cd06feff8f2",
+  "postgresql-17.7.0-aarch64-apple-darwin": "727ac08d20a704014a0d51eb3300aa0c8e292c1cf0a1c99d4f4b1002e1420220"
+};
+async function verifyTarball(tarball, key, url) {
+  const actual = createHash2("sha256").update(readFileSync(tarball)).digest("hex");
+  const pinned = PINNED_SHA256[key];
+  if (pinned) {
+    if (actual !== pinned) {
+      throw new Error(`postgres binary checksum mismatch for ${key}: expected ${pinned}, got ${actual}`);
+    }
+    return;
+  }
+  const res = await fetchRelease(`${url}.sha256`);
+  if (!res.ok)
+    throw new Error(`could not fetch checksum for ${key}: HTTP ${res.status}`);
+  const expected = (await res.text()).trim().split(/\s+/)[0].toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(expected))
+    throw new Error(`malformed published checksum for ${key}`);
+  if (actual !== expected) {
+    throw new Error(`postgres binary checksum mismatch for ${key}: expected ${expected}, got ${actual}`);
+  }
+}
+async function ensurePostgres(version = DEFAULT_PG_VERSION, cacheDir, log) {
+  const t = target();
+  const root = cacheDir ?? join2(homedir(), ".cache", "supacloud-lite");
+  const dir = join2(root, `postgresql-${version}-${t}`);
+  if (isCompleteInstall(dir))
+    return dir;
+  const url = `https://github.com/theseus-rs/postgresql-binaries/releases/download/${version}/postgresql-${version}-${t}.tar.gz`;
+  mkdirSync(root, { recursive: true });
+  const uniq = `${process.pid}-${randomBytes2(6).toString("hex")}`;
+  const tarball = join2(root, `pg-${version}-${uniq}.tar.gz`);
+  const tmpDir = join2(root, `.tmp-${version}-${t}-${uniq}`);
+  try {
+    if (isCompleteInstall(dir))
+      return dir;
+    log?.(`downloading postgres ${version} (${t})\u2026`);
+    const res = await fetchRelease(url);
+    if (!res.ok)
+      throw new Error(`failed to download ${url}: HTTP ${res.status}`);
+    await writeFile2(tarball, Buffer.from(await res.arrayBuffer()));
+    await verifyTarball(tarball, `postgresql-${version}-${t}`, url);
+    mkdirSync(tmpDir, { recursive: true });
+    await extractTar({ cwd: tmpDir, file: tarball, gzip: true, preserveOwner: false, strict: true, strip: 1 });
+    if (!isCompleteInstall(tmpDir))
+      throw new Error("postgres archive extracted incompletely");
+    try {
+      renameSync(tmpDir, dir);
+    } catch {
+      if (!isCompleteInstall(dir)) {
+        rmSync(dir, { recursive: true, force: true });
+        renameSync(tmpDir, dir);
+      }
+    }
+    log?.(`postgres installed to ${dir}`);
+    return dir;
+  } finally {
+    rmSync(tarball, { force: true });
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+async function fetchRelease(url) {
+  let lastError;
+  for (let attempt = 1;attempt <= 3; attempt++) {
+    try {
+      const response = await fetch(url);
+      if (response.ok || response.status < 500)
+        return response;
+      lastError = new Error(`failed to download ${url}: HTTP ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+    if (attempt < 3)
+      await new Promise((resolve2) => setTimeout(resolve2, attempt * 500));
+  }
+  throw lastError instanceof Error ? lastError : new Error(`failed to download ${url}`);
+}
+var TUNED_CONF = `
+# supacloud-lite: memory-lean settings for an embedded, single-app Postgres
+listen_addresses = ''
+shared_buffers = 16MB
+dynamic_shared_memory_type = posix
+max_connections = 10
+wal_level = minimal
+max_wal_senders = 0
+logging_collector = off
+`;
+async function createNativeEngine(opts) {
+  const releaseLock = await acquireDataDirLock(opts.dataDir, "native PostgreSQL");
+  let socketDirectory;
+  let postgres;
+  let removeExitHandler;
+  try {
+    const installDir = await ensurePostgres(opts.version, opts.cacheDir, opts.log);
+    const bin = (name) => join2(installDir, "bin", name);
+    if (!existsSync(join2(opts.dataDir, "PG_VERSION"))) {
+      mkdirSync(opts.dataDir, { recursive: true });
+      try {
+        execFileSync(bin("initdb"), ["-U", "postgres", "-A", "trust", "-E", "UTF8", "-D", opts.dataDir], {
+          stdio: "pipe"
+        });
+      } catch (error) {
+        const stderr = error.stderr?.toString() ?? "";
+        throw new Error(`initdb failed:
+${stderr || error.message}`);
+      }
+      appendFileSync(join2(opts.dataDir, "postgresql.conf"), TUNED_CONF);
+    }
+    removeStalePidFile(join2(opts.dataDir, "postmaster.pid"));
+    socketDirectory = mkdtempSync(join2(tmpdir(), "scl-"));
+    chmodSync(socketDirectory, 448);
+    postgres = spawn(bin("postgres"), ["-D", opts.dataDir, "-k", socketDirectory, "-c", "timezone=UTC"], {
+      stdio: ["ignore", "ignore", "pipe"],
+      detached: false
+    });
+    let postgresExited = false;
+    let postgresStderr = "";
+    postgres.stderr?.on("data", (chunk) => {
+      postgresStderr = (postgresStderr + chunk.toString()).slice(-4000);
+    });
+    postgres.on("exit", () => postgresExited = true);
+    const killPostgres = () => {
+      if (!postgresExited)
+        postgres?.kill("SIGTERM");
+    };
+    process.once("exit", killPostgres);
+    removeExitHandler = () => process.off("exit", killPostgres);
+    const socketPath = join2(socketDirectory, ".s.PGSQL.5432");
+    const connect = async () => {
+      const deadline = Date.now() + 20000;
+      while (Date.now() <= deadline) {
+        try {
+          return await PgWireClient.connect({ socketPath, user: "postgres", database: "postgres" });
+        } catch (error) {
+          if (postgresExited) {
+            const detail = postgresStderr.trim();
+            throw new Error(`embedded postgres failed to start${detail ? `:
+${detail}` : " (no output)"}
+
+` + `data dir: ${opts.dataDir}
+` + "If a previous run is still holding it, stop it; or delete the data dir to start fresh.");
+          }
+          await new Promise((resolve2) => setTimeout(resolve2, 150));
+        }
+      }
+      throw new Error(`timed out waiting for embedded postgres at ${socketPath}`);
+    };
+    return await buildWireEngine({
+      connect,
+      onClose: async () => {
+        removeExitHandler?.();
+        await stopPostgres(postgres, () => postgresExited);
+        rmSync(socketDirectory, { recursive: true, force: true });
+        await releaseLock();
+      }
+    });
+  } catch (error) {
+    removeExitHandler?.();
+    if (postgres)
+      await stopPostgres(postgres, () => postgres.exitCode !== null);
+    if (socketDirectory)
+      rmSync(socketDirectory, { recursive: true, force: true });
+    await releaseLock();
+    throw error;
+  }
+}
+async function stopPostgres(postgres, hasExited) {
+  if (hasExited())
+    return;
+  postgres.kill("SIGINT");
+  await new Promise((resolve2) => {
+    const killTimeout = setTimeout(() => {
+      postgres.kill("SIGKILL");
+      resolve2();
+    }, 5000);
+    postgres.once("exit", () => {
+      clearTimeout(killTimeout);
+      resolve2();
+    });
+  });
+}
+function removeStalePidFile(pidPath) {
+  if (!existsSync(pidPath))
+    return;
+  try {
+    const pid = Number.parseInt(readFileSync(pidPath, "utf8").split(`
+`)[0]?.trim() ?? "", 10);
+    if (!pid) {
+      rmSync(pidPath, { force: true });
+      return;
+    }
+    try {
+      process.kill(pid, 0);
+    } catch {
+      rmSync(pidPath, { force: true });
+    }
+  } catch {}
+}
 // src/project-runtime.ts
-import { chmod, link, lstat, mkdir as mkdir4, readFile as readFile6, realpath as realpath2, unlink as unlink3, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname4, isAbsolute, join as join6, parse, relative, resolve as resolve2 } from "path";
+import { chmod, link, lstat, mkdir as mkdir4, readFile as readFile6, realpath as realpath2, unlink as unlink2, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname4, isAbsolute, join as join7, parse, relative, resolve as resolve2 } from "path";
 
 // src/runtime/node/config-toml.ts
-import { readFileSync } from "fs";
-import { join as join2 } from "path";
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join3 } from "path";
 function emptyTable() {
   return { values: new Map, children: new Map };
 }
 function loadConfigToml(projectDir, env = process.env) {
   let text;
   try {
-    text = readFileSync(join2(projectDir, "supabase", "config.toml"), "utf8");
+    text = readFileSync2(join3(projectDir, "supabase", "config.toml"), "utf8");
   } catch {
     return emptyTable();
   }
@@ -9249,15 +11414,15 @@ function readFunctions(root) {
 
 // src/runtime/node/load-functions.ts
 import { readdir, readFile as readFile4, realpath, rm as rm3, stat } from "fs/promises";
-import { dirname as dirname3, join as join4 } from "path";
+import { dirname as dirname3, join as join5 } from "path";
 import { pathToFileURL } from "url";
 
 // src/runtime/node/bundle-function.ts
-import { createHash } from "crypto";
-import { mkdir as mkdir3, readFile as readFile3, rm as rm2, writeFile as writeFile2 } from "fs/promises";
-import { existsSync } from "fs";
-import { tmpdir } from "os";
-import { join as join3 } from "path";
+import { createHash as createHash3 } from "crypto";
+import { mkdir as mkdir3, readFile as readFile3, rm as rm2, writeFile as writeFile3 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join4 } from "path";
 function rewriteRemoteSpecifier(spec) {
   if (spec.startsWith("npm:"))
     return `https://esm.sh/${spec.slice(4)}`;
@@ -9265,18 +11430,18 @@ function rewriteRemoteSpecifier(spec) {
     return `https://esm.sh/jsr/${spec.slice(4)}`;
   return spec;
 }
-var HTTP_CACHE = join3(tmpdir(), "supacloud-lite-fn-http");
+var HTTP_CACHE = join4(tmpdir2(), "supacloud-lite-fn-http");
 async function fetchModule(url) {
-  const key = createHash("sha256").update(url).digest("hex");
-  const cached = join3(HTTP_CACHE, key);
-  if (existsSync(cached))
+  const key = createHash3("sha256").update(url).digest("hex");
+  const cached = join4(HTTP_CACHE, key);
+  if (existsSync2(cached))
     return readFile3(cached, "utf8");
   const res = await fetch(url, { redirect: "follow" });
   if (!res.ok)
     throw new Error(`failed to fetch ${url}: HTTP ${res.status}`);
   const body = await res.text();
   await mkdir3(HTTP_CACHE, { recursive: true });
-  await writeFile2(cached, body);
+  await writeFile3(cached, body);
   return body;
 }
 function remotePlugin() {
@@ -9299,7 +11464,7 @@ function remotePlugin() {
   };
 }
 async function bundleFunction(entryPath, name) {
-  const outDir = join3(tmpdir(), "supacloud-lite-fn-bundle", name);
+  const outDir = join4(tmpdir2(), "supacloud-lite-fn-bundle", name);
   await mkdir3(outDir, { recursive: true });
   try {
     const buildOutput = await Bun.build({
@@ -9329,7 +11494,7 @@ async function bundleFunction(entryPath, name) {
 async function loadFunctionEnv(projectDir) {
   let text;
   try {
-    text = await readFile4(join4(projectDir, "supabase", "functions", ".env"), "utf8");
+    text = await readFile4(join5(projectDir, "supabase", "functions", ".env"), "utf8");
   } catch {
     return {};
   }
@@ -9368,7 +11533,7 @@ async function loadFunctions2(projectDir, options = {}) {
 }
 async function loadFunctionsUnlocked(projectDir, options) {
   const functions = new Map;
-  const root = join4(projectDir, "supabase", "functions");
+  const root = join5(projectDir, "supabase", "functions");
   let entries = [];
   try {
     entries = await readdir(root);
@@ -9381,10 +11546,10 @@ async function loadFunctionsUnlocked(projectDir, options) {
       continue;
     if (options[name]?.enabled === false)
       continue;
-    const dir = join4(root, name);
+    const dir = join5(root, name);
     if (!(await stat(dir)).isDirectory())
       continue;
-    const candidates = options[name]?.entrypoint ? [join4(projectDir, options[name].entrypoint)] : ["index.ts", "index.tsx", "index.js", "index.mjs"].map((f) => join4(dir, f));
+    const candidates = options[name]?.entrypoint ? [join5(projectDir, options[name].entrypoint)] : ["index.ts", "index.tsx", "index.js", "index.mjs"].map((f) => join5(dir, f));
     for (const path of candidates) {
       try {
         await stat(path);
@@ -9431,9 +11596,9 @@ async function loadFunctionsUnlocked(projectDir, options) {
 
 // src/runtime/node/project.ts
 import { readdir as readdir2, readFile as readFile5 } from "fs/promises";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 async function loadSupabaseProject(projectDir, seed = {}) {
-  const migrationsDir = join5(projectDir, "supabase", "migrations");
+  const migrationsDir = join6(projectDir, "supabase", "migrations");
   const migrations = [];
   let entries = [];
   try {
@@ -9445,19 +11610,19 @@ async function loadSupabaseProject(projectDir, seed = {}) {
   for (const entry of entries.sort()) {
     if (!entry.endsWith(".sql"))
       continue;
-    const sql = await readFile5(join5(migrationsDir, entry), "utf8");
+    const sql = await readFile5(join6(migrationsDir, entry), "utf8");
     migrations.push({ name: entry.replace(/\.sql$/, ""), sql });
   }
   let seedSql;
   if (seed.enabled !== false) {
     const parts = [];
-    const supabaseDir = join5(projectDir, "supabase");
+    const supabaseDir = join6(projectDir, "supabase");
     for (const configuredPath of seed.paths ?? ["seed.sql"]) {
       const pattern = configuredPath.replace(/^\.\//, "");
       const matches = /[*?[\]{}]/.test(pattern) ? [...new Bun.Glob(pattern).scanSync({ cwd: supabaseDir, onlyFiles: true })].sort() : [pattern];
       for (const relativePath of matches) {
         try {
-          parts.push(await readFile5(join5(supabaseDir, relativePath), "utf8"));
+          parts.push(await readFile5(join6(supabaseDir, relativePath), "utf8"));
         } catch (error) {
           if (!isNotFound(error))
             throw error;
@@ -9478,14 +11643,16 @@ function isNotFound(error) {
 function resolveProjectPaths(options = {}) {
   const projectDir = resolve2(options.projectDir ?? process.cwd());
   const stateDir = resolvePath(projectDir, options.stateDir ?? process.env.SUPACLOUD_LITE_STATE_DIR ?? ".supacloud-lite");
-  const dataDir = options.memory ? undefined : resolvePath(projectDir, options.dataDir ?? process.env.SUPACLOUD_LITE_DATA_DIR ?? join6(stateDir, "db"));
-  const storageDir = resolvePath(projectDir, options.storageDir ?? process.env.SUPACLOUD_LITE_STORAGE_DIR ?? join6(stateDir, "storage"));
+  const databaseEngine = resolveDatabaseEngine(options.engine, options.memory);
+  const dataDir = options.memory ? undefined : resolvePath(projectDir, options.dataDir ?? process.env.SUPACLOUD_LITE_DATA_DIR ?? join7(stateDir, databaseEngine === "native" ? "pgdata" : "db"));
+  const storageDir = resolvePath(projectDir, options.storageDir ?? process.env.SUPACLOUD_LITE_STORAGE_DIR ?? join7(stateDir, "storage"));
   return {
     projectDir,
     stateDir,
     dataDir,
     storageDir,
-    secretsFile: join6(stateDir, "secrets.json")
+    secretsFile: join7(stateDir, "secrets.json"),
+    databaseEngine
   };
 }
 async function ensureProjectSecrets(paths) {
@@ -9508,7 +11675,7 @@ async function ensureProjectSecrets(paths) {
     };
     const temporaryFile = `${paths.secretsFile}.${crypto.randomUUID()}.tmp`;
     try {
-      await writeFile3(temporaryFile, `${JSON.stringify(candidate, null, 2)}
+      await writeFile4(temporaryFile, `${JSON.stringify(candidate, null, 2)}
 `, { mode: 384, flag: "wx" });
       await link(temporaryFile, paths.secretsFile);
       stored = candidate;
@@ -9517,7 +11684,7 @@ async function ensureProjectSecrets(paths) {
         throw error2;
       stored = validateSecrets(JSON.parse(await readFile6(paths.secretsFile, "utf8")));
     } finally {
-      await unlink3(temporaryFile).catch((error2) => {
+      await unlink2(temporaryFile).catch((error2) => {
         if (error2.code !== "ENOENT")
           throw error2;
       });
@@ -9549,42 +11716,58 @@ async function createProjectBackend(options = {}) {
   const webhooks = options.includeWebhooks === false ? [] : await loadWebhooks(paths.projectDir);
   const configuredStorageBackend = options.storageDriver ? "fs" : resolveStorageBackend(options.storageBackend);
   const storageBackend = options.storageDriver ? "custom" : configuredStorageBackend;
+  const databaseEngine = paths.databaseEngine;
   if (paths.dataDir) {
     await mkdir4(paths.dataDir, { recursive: true, mode: 448 });
     await chmod(paths.dataDir, 448);
   }
   await mkdir4(paths.storageDir, { recursive: true, mode: 448 });
   await chmod(paths.storageDir, 448);
-  const backend = await createBackend({
-    dataDir: paths.dataDir,
-    jwtSecret: secrets.jwtSecret,
-    vaultKey: secrets.vaultKey,
-    apiUrl: url,
-    siteUrl: options.siteUrl ?? process.env.SUPACLOUD_LITE_SITE_URL ?? config.auth.siteUrl ?? url,
-    host,
-    jwtExpiry: config.auth.jwtExpiry,
-    uriAllowList: config.auth.uriAllowList,
-    authEnabled: config.auth.enabled,
-    authSettings: config.auth.settings,
-    authRateLimits: config.auth.rateLimits,
-    sessionTimeboxSeconds: config.auth.sessionTimeboxSeconds,
-    sessionInactivitySeconds: config.auth.sessionInactivitySeconds,
-    oauthProviders: config.auth.oauthProviders,
-    smsSender: options.smsSender,
-    dbSchemas: config.api.schemas,
-    maxRows: config.api.maxRows,
-    storageFileSizeLimit: config.storage.fileSizeLimit,
-    buckets: config.storage.buckets,
-    migrations: options.applyMigrations === false ? [] : project.migrations,
-    seedSql: options.applyMigrations === false || options.includeSeed === false ? undefined : project.seedSql,
-    functions,
-    functionVerifyJwt: Object.fromEntries(Object.entries(config.functions).map(([name, functionOptions]) => [name, functionOptions.verifyJwt !== false])),
-    functionEnv,
-    webhooks,
-    startRuntimeServices: options.startRuntimeServices,
-    storageDriver: options.storageDriver ?? createStorageDriver(configuredStorageBackend, paths.storageDir, options.s3),
-    log: options.log
-  });
+  const storageDriver = options.storageDriver ?? createStorageDriver(configuredStorageBackend, paths.storageDir, options.s3);
+  const engine = databaseEngine === "native" ? await createNativeEngine({ dataDir: paths.dataDir, log: options.log }) : undefined;
+  let backend;
+  try {
+    backend = await createBackend({
+      engine,
+      dataDir: databaseEngine === "pglite" ? paths.dataDir : undefined,
+      jwtSecret: secrets.jwtSecret,
+      vaultKey: secrets.vaultKey,
+      apiUrl: url,
+      siteUrl: options.siteUrl ?? process.env.SUPACLOUD_LITE_SITE_URL ?? config.auth.siteUrl ?? url,
+      host,
+      jwtExpiry: config.auth.jwtExpiry,
+      uriAllowList: config.auth.uriAllowList,
+      authEnabled: config.auth.enabled,
+      authSettings: config.auth.settings,
+      authRateLimits: config.auth.rateLimits,
+      sessionTimeboxSeconds: config.auth.sessionTimeboxSeconds,
+      sessionInactivitySeconds: config.auth.sessionInactivitySeconds,
+      oauthProviders: config.auth.oauthProviders,
+      smsSender: options.smsSender,
+      dbSchemas: config.api.schemas,
+      maxRows: config.api.maxRows,
+      storageFileSizeLimit: config.storage.fileSizeLimit,
+      buckets: config.storage.buckets,
+      migrations: options.applyMigrations === false ? [] : project.migrations,
+      seedSql: options.applyMigrations === false || options.includeSeed === false ? undefined : project.seedSql,
+      functions,
+      functionVerifyJwt: Object.fromEntries(Object.entries(config.functions).map(([name, functionOptions]) => [name, functionOptions.verifyJwt !== false])),
+      functionEnv,
+      webhooks,
+      startRuntimeServices: options.startRuntimeServices,
+      storageDriver,
+      log: options.log
+    });
+  } catch (error) {
+    if (engine) {
+      try {
+        await engine.close();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "project database startup cleanup failed");
+      }
+    }
+    throw error;
+  }
   return {
     backend,
     config,
@@ -9595,9 +11778,22 @@ async function createProjectBackend(options = {}) {
     migrationCount: project.migrations.length,
     functionNames: [...functions.keys()],
     webhookCount: webhooks.length,
-    storageBackend
+    storageBackend,
+    databaseEngine
   };
 }
+function resolveDatabaseEngine(value, memory = false) {
+  const configured = value ?? process.env.SUPACLOUD_LITE_ENGINE ?? "pglite";
+  if (configured !== "pglite" && configured !== "native") {
+    throw new Error(`unsupported SUPACLOUD_LITE_ENGINE: ${configured}`);
+  }
+  if (configured === "native" && memory)
+    throw new Error("--memory is only supported by the pglite engine");
+  if (configured === "native" && !isNativeEngineSupported()) {
+    throw new Error(`native PostgreSQL requires macOS or glibc Linux on x64/arm64; ` + `${process.platform}/${process.arch} must use --engine pglite`);
+  }
+  return configured;
+}
 function resolveStorageBackend(value) {
   const configured = value ?? process.env.SUPACLOUD_LITE_STORAGE_BACKEND ?? "fs";
   if (configured === "fs" || configured === "memory" || configured === "s3")
@@ -9652,7 +11848,7 @@ async function startProjectServer(options = {}) {
 }
 async function loadWebhooks(projectDir) {
   try {
-    const parsed = JSON.parse(await readFile6(join6(projectDir, "supabase", "webhooks.json"), "utf8"));
+    const parsed = JSON.parse(await readFile6(join7(projectDir, "supabase", "webhooks.json"), "utf8"));
     return Array.isArray(parsed) ? parsed : [];
   } catch (error) {
     if (error.code === "ENOENT")
@@ -9702,9 +11898,9 @@ async function findEphemeralPort(host = "127.0.0.1") {
   return port;
 }
 // src/snapshot.ts
-import { chmod as chmod2, copyFile, lstat as lstat2, mkdir as mkdir5, mkdtemp, readdir as readdir3, readFile as readFile7, rename as rename2, rm as rm4, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname5, join as join7, parse as parse2, relative as relative2, resolve as resolve3, sep as sep2 } from "path";
-import { create as createTar, extract as extractTar } from "tar";
+import { chmod as chmod2, copyFile, lstat as lstat2, mkdir as mkdir5, mkdtemp, readdir as readdir3, readFile as readFile7, rename as rename2, rm as rm4, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname5, join as join8, parse as parse2, relative as relative2, resolve as resolve3, sep as sep2 } from "path";
+import { create as createTar, extract as extractTar2 } from "tar";
 var SNAPSHOT_FORMAT = "supacloud-lite-snapshot";
 var SNAPSHOT_VERSION = 1;
 async function createSnapshot(options) {
@@ -9719,21 +11915,27 @@ async function createSnapshot(options) {
     storageBackend: options.storageBackend,
     includesDatabase: Boolean(paths.dataDir),
     includesLocalStorage: options.storageBackend === "fs",
-    includesSecrets: true
+    includesSecrets: true,
+    databaseEngine: paths.databaseEngine,
+    ...paths.databaseEngine === "native" ? {
+      platform: process.platform,
+      architecture: process.arch,
+      postgresMajor: await readPostgresMajor(paths.dataDir)
+    } : {}
   };
   const output = resolve3(options.output);
   if (await existingInfo(output))
     throw new Error(`snapshot output already exists: ${output}`);
   await mkdir5(dirname5(output), { recursive: true });
-  const stagingRoot = await mkdtemp(join7(dirname5(output), ".supacloud-lite-snapshot-"));
+  const stagingRoot = await mkdtemp(join8(dirname5(output), ".supacloud-lite-snapshot-"));
   try {
-    await writeFile4(join7(stagingRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
+    await writeFile5(join8(stagingRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}
 `);
-    await stageFile(paths.secretsFile, join7(stagingRoot, "secrets.json"));
+    await stageFile(paths.secretsFile, join8(stagingRoot, "secrets.json"));
     if (paths.dataDir)
-      await stageDirectory(paths.dataDir, join7(stagingRoot, "database"));
+      await stageDirectory(paths.dataDir, join8(stagingRoot, "database"));
     if (options.storageBackend === "fs")
-      await stageDirectory(paths.storageDir, join7(stagingRoot, "storage"));
+      await stageDirectory(paths.storageDir, join8(stagingRoot, "storage"));
     const entries = ["manifest.json", "secrets.json"];
     if (paths.dataDir)
       entries.push("database");
@@ -9754,13 +11956,13 @@ async function restoreSnapshot(options) {
   const paths = normalizePaths(options.paths);
   await assertSnapshotPaths(paths, { requireSecrets: false, allowMissingState: true });
   await assertNoDataDirectoryLock(paths);
-  const stagingRoot = await mkdtemp(join7(dirname5(paths.stateDir), ".supacloud-lite-restore-"));
-  const payloadRoot = join7(stagingRoot, "payload");
+  const stagingRoot = await mkdtemp(join8(dirname5(paths.stateDir), ".supacloud-lite-restore-"));
+  const payloadRoot = join8(stagingRoot, "payload");
   const rollbackId = crypto.randomUUID();
   const rollbackPaths = [];
   try {
     await mkdir5(payloadRoot, { recursive: true });
-    await extractTar({
+    await extractTar2({
       cwd: payloadRoot,
       file: resolve3(options.input),
       preserveOwner: false,
@@ -9785,6 +11987,7 @@ async function restoreSnapshot(options) {
     if (manifest.storageBackend !== options.storageBackend) {
       throw new Error(`snapshot storage backend is ${manifest.storageBackend}, but the target uses ${options.storageBackend}; ` + "restore with the matching --storage-backend value");
     }
+    assertDatabaseSnapshotCompatible(manifest, paths);
     if (manifest.includesDatabase !== Boolean(paths.dataDir)) {
       throw new Error("snapshot database mode does not match the target; do not restore a persistent snapshot into --memory");
     }
@@ -9793,27 +11996,27 @@ async function restoreSnapshot(options) {
     }
     await assertSnapshotPayload(payloadRoot, manifest);
     if (manifest.includesDatabase)
-      await mkdir5(join7(payloadRoot, "database"), { recursive: true });
+      await mkdir5(join8(payloadRoot, "database"), { recursive: true });
     if (manifest.includesLocalStorage)
-      await mkdir5(join7(payloadRoot, "storage"), { recursive: true });
+      await mkdir5(join8(payloadRoot, "storage"), { recursive: true });
     await assertRestoreTargets(paths, manifest, options.force === true);
-    const stateStage = join7(stagingRoot, "state");
+    const stateStage = join8(stagingRoot, "state");
     await mkdir5(stateStage, { recursive: true });
-    await copyEntry(join7(payloadRoot, "secrets.json"), join7(stateStage, "secrets.json"));
+    await copyEntry(join8(payloadRoot, "secrets.json"), join8(stateStage, "secrets.json"));
     if (paths.dataDir && isWithin(paths.stateDir, paths.dataDir)) {
-      await copyEntry(join7(payloadRoot, "database"), join7(stateStage, relative2(paths.stateDir, paths.dataDir)));
+      await copyEntry(join8(payloadRoot, "database"), join8(stateStage, relative2(paths.stateDir, paths.dataDir)));
     }
     if (options.storageBackend === "fs" && isWithin(paths.stateDir, paths.storageDir)) {
-      await copyEntry(join7(payloadRoot, "storage"), join7(stateStage, relative2(paths.stateDir, paths.storageDir)));
+      await copyEntry(join8(payloadRoot, "storage"), join8(stateStage, relative2(paths.stateDir, paths.storageDir)));
     }
     const swaps = [];
     try {
       await applyDirectorySwap(stateStage, paths.stateDir, options.force === true, rollbackId, swaps);
       if (paths.dataDir && !isWithin(paths.stateDir, paths.dataDir)) {
-        await applyDirectorySwap(join7(payloadRoot, "database"), paths.dataDir, options.force === true, rollbackId, swaps);
+        await applyDirectorySwap(join8(payloadRoot, "database"), paths.dataDir, options.force === true, rollbackId, swaps);
       }
       if (options.storageBackend === "fs" && !isWithin(paths.stateDir, paths.storageDir)) {
-        await applyDirectorySwap(join7(payloadRoot, "storage"), paths.storageDir, options.force === true, rollbackId, swaps);
+        await applyDirectorySwap(join8(payloadRoot, "storage"), paths.storageDir, options.force === true, rollbackId, swaps);
       }
     } catch (error) {
       await rollbackDirectorySwaps(swaps);
@@ -9849,7 +12052,7 @@ async function assertSnapshotPaths(paths, options = {}) {
   try {
     if (paths.stateDir === parse2(paths.stateDir).root)
       throw new Error("snapshot state directory must not be the filesystem root");
-    if (paths.secretsFile !== join7(paths.stateDir, "secrets.json"))
+    if (paths.secretsFile !== join8(paths.stateDir, "secrets.json"))
       throw new Error("snapshot secrets path must be inside the state directory");
     const stateInfo = await lstat2(paths.stateDir);
     if (!stateInfo.isDirectory() || stateInfo.isSymbolicLink())
@@ -9907,10 +12110,10 @@ async function stageDirectory(root, destination) {
     throw error;
   }
   await mkdir5(destination, { recursive: true });
-  const walk = async (current, target) => {
+  const walk = async (current, target2) => {
     for (const entry of await readdir3(current, { withFileTypes: true })) {
-      const fullPath = join7(current, entry.name);
-      const targetPath = join7(target, entry.name);
+      const fullPath = join8(current, entry.name);
+      const targetPath = join8(target2, entry.name);
       if (entry.isSymbolicLink())
         throw new Error(`snapshot refuses symbolic link: ${fullPath}`);
       if (entry.isDirectory()) {
@@ -9925,14 +12128,14 @@ async function stageDirectory(root, destination) {
   };
   await walk(root, destination);
 }
-async function stageFile(source, target) {
-  await mkdir5(dirname5(target), { recursive: true });
-  await copyFile(source, target);
+async function stageFile(source, target2) {
+  await mkdir5(dirname5(target2), { recursive: true });
+  await copyFile(source, target2);
 }
 async function readManifest(payloadRoot) {
   let parsed;
   try {
-    parsed = JSON.parse(await readFile7(join7(payloadRoot, "manifest.json"), "utf8"));
+    parsed = JSON.parse(await readFile7(join8(payloadRoot, "manifest.json"), "utf8"));
   } catch (error) {
     throw new Error(`invalid snapshot manifest: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -9944,13 +12147,38 @@ function isSnapshotManifest(value) {
   if (!value || typeof value !== "object")
     return false;
   const candidate = value;
-  return candidate.format === SNAPSHOT_FORMAT && candidate.version === SNAPSHOT_VERSION && typeof candidate.createdAt === "string" && typeof candidate.packageVersion === "string" && (candidate.storageBackend === "fs" || candidate.storageBackend === "s3" || candidate.storageBackend === "memory") && typeof candidate.includesDatabase === "boolean" && typeof candidate.includesLocalStorage === "boolean" && candidate.includesSecrets === true;
+  return candidate.format === SNAPSHOT_FORMAT && candidate.version === SNAPSHOT_VERSION && typeof candidate.createdAt === "string" && typeof candidate.packageVersion === "string" && (candidate.storageBackend === "fs" || candidate.storageBackend === "s3" || candidate.storageBackend === "memory") && typeof candidate.includesDatabase === "boolean" && typeof candidate.includesLocalStorage === "boolean" && candidate.includesSecrets === true && (candidate.databaseEngine === undefined || candidate.databaseEngine === "pglite" || candidate.databaseEngine === "native") && (candidate.platform === undefined || typeof candidate.platform === "string") && (candidate.architecture === undefined || typeof candidate.architecture === "string") && (candidate.postgresMajor === undefined || typeof candidate.postgresMajor === "string");
+}
+function assertDatabaseSnapshotCompatible(manifest, paths) {
+  const sourceEngine = manifest.databaseEngine ?? "pglite";
+  if (sourceEngine !== paths.databaseEngine) {
+    throw new Error(`snapshot database engine is ${sourceEngine}, but the target uses ${paths.databaseEngine}`);
+  }
+  if (sourceEngine !== "native")
+    return;
+  if (manifest.platform !== process.platform || manifest.architecture !== process.arch) {
+    throw new Error(`native PostgreSQL snapshots require the same platform and architecture; ` + `source is ${manifest.platform ?? "unknown"}/${manifest.architecture ?? "unknown"}, ` + `target is ${process.platform}/${process.arch}`);
+  }
+  if (manifest.postgresMajor !== NATIVE_POSTGRES_MAJOR) {
+    throw new Error(`native PostgreSQL snapshot major is ${manifest.postgresMajor ?? "unknown"}, ` + `but this Lite build uses ${NATIVE_POSTGRES_MAJOR}`);
+  }
+}
+async function readPostgresMajor(dataDir) {
+  if (!dataDir)
+    return;
+  try {
+    return (await readFile7(join8(dataDir, "PG_VERSION"), "utf8")).trim();
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return;
+    throw error;
+  }
 }
 async function assertSnapshotPayload(payloadRoot, manifest) {
   const required = ["manifest.json", "secrets.json"];
   for (const path of required) {
     try {
-      await lstat2(join7(payloadRoot, path));
+      await lstat2(join8(payloadRoot, path));
     } catch {
       throw new Error(`snapshot is missing required payload: ${path}`);
     }
@@ -9973,9 +12201,9 @@ async function assertRestoreTargets(paths, manifest, force) {
   if (manifest.includesLocalStorage && !isWithin(paths.stateDir, paths.storageDir))
     targets.push(paths.storageDir);
   if (!force) {
-    for (const target of targets) {
-      if (await directoryHasEntries(target))
-        throw new Error(`restore target is not empty: ${target}; pass --force to replace it`);
+    for (const target2 of targets) {
+      if (await directoryHasEntries(target2))
+        throw new Error(`restore target is not empty: ${target2}; pass --force to replace it`);
     }
   }
 }
@@ -9988,28 +12216,28 @@ async function directoryHasEntries(path) {
     throw error;
   }
 }
-async function applyDirectorySwap(source, target, force, rollbackId, swaps) {
-  const targetInfo = await existingInfo(target);
+async function applyDirectorySwap(source, target2, force, rollbackId, swaps) {
+  const targetInfo = await existingInfo(target2);
   if (targetInfo && !targetInfo.isDirectory())
-    throw new Error(`restore target is not a directory: ${target}`);
-  const swap = { target };
+    throw new Error(`restore target is not a directory: ${target2}`);
+  const swap = { target: target2 };
   if (targetInfo) {
     if (!force) {
-      if (await directoryHasEntries(target))
-        throw new Error(`restore target is not empty: ${target}; pass --force to replace it`);
-      await rm4(target, { recursive: true, force: true });
+      if (await directoryHasEntries(target2))
+        throw new Error(`restore target is not empty: ${target2}; pass --force to replace it`);
+      await rm4(target2, { recursive: true, force: true });
     } else {
-      swap.rollbackPath = join7(dirname5(target), `.${target.split(sep2).pop() ?? "state"}.restore-${rollbackId}`);
-      await rename2(target, swap.rollbackPath);
+      swap.rollbackPath = join8(dirname5(target2), `.${target2.split(sep2).pop() ?? "state"}.restore-${rollbackId}`);
+      await rename2(target2, swap.rollbackPath);
     }
   }
   try {
-    await mkdir5(dirname5(target), { recursive: true });
-    await rename2(source, target);
+    await mkdir5(dirname5(target2), { recursive: true });
+    await rename2(source, target2);
     swaps.push(swap);
   } catch (error) {
     if (swap.rollbackPath)
-      await rename2(swap.rollbackPath, target).catch(() => {});
+      await rename2(swap.rollbackPath, target2).catch(() => {});
     throw error;
   }
 }
@@ -10029,17 +12257,17 @@ async function existingInfo(path) {
     throw error;
   }
 }
-async function copyEntry(source, target) {
+async function copyEntry(source, target2) {
   const info = await lstat2(source);
   if (info.isSymbolicLink())
     throw new Error(`snapshot refuses symbolic link: ${source}`);
   if (info.isDirectory()) {
-    await mkdir5(target, { recursive: true });
+    await mkdir5(target2, { recursive: true });
     for (const entry of await readdir3(source))
-      await copyEntry(join7(source, entry), join7(target, entry));
+      await copyEntry(join8(source, entry), join8(target2, entry));
   } else if (info.isFile()) {
-    await mkdir5(dirname5(target), { recursive: true });
-    await Bun.write(target, Bun.file(source));
+    await mkdir5(dirname5(target2), { recursive: true });
+    await Bun.write(target2, Bun.file(source));
   } else
     throw new Error(`snapshot refuses unsupported filesystem entry: ${source}`);
 }
@@ -10050,7 +12278,7 @@ async function hardenRestoredTree(root) {
   if (info.isDirectory()) {
     await chmod2(root, 448);
     for (const entry of await readdir3(root))
-      await hardenRestoredTree(join7(root, entry));
+      await hardenRestoredTree(join8(root, entry));
     return;
   }
   if (info.isFile()) {
@@ -10061,7 +12289,7 @@ async function hardenRestoredTree(root) {
 }
 async function assertNoSymlinks(root) {
   for (const entry of await readdir3(root, { withFileTypes: true })) {
-    const fullPath = join7(root, entry.name);
+    const fullPath = join8(root, entry.name);
     if (entry.isSymbolicLink())
       throw new Error(`snapshot refuses symbolic link in archive: ${fullPath}`);
     if (entry.isDirectory())
@@ -10086,14 +12314,18 @@ export {
   restoreSnapshot,
   resolveStorageBackend,
   resolveProjectPaths,
+  resolveDatabaseEngine,
   mintProjectKeys,
+  isNativeEngineSupported,
   inspectDb,
   generateTypes,
   ensureProjectSecrets,
+  ensurePostgres,
   decodeJwt,
   createSnapshot,
   createProjectBackend,
   createPgliteEngine,
+  createNativeEngine,
   createBackend as createLiteBackend,
   SUPACLOUD_LITE_VERSION,
   S3StorageDriver,