@openlup/platform 0.0.0 → 0.15.0

package/dist/job-ledger/supabase.d.ts

@@ -0,0 +1,77 @@
+import type { PlatformJobFinishStatus, PlatformJobFinishSummary, PlatformJobInvocation, PlatformJobRunLedgerPort } from "./ports.js";
+export type PlatformJobDriver = "manual_admin" | "pg_cron" | "vercel_cron" | "worker";
+type RpcResult<T> = {
+    data: T | null;
+    error: {
+        message?: string;
+    } | null;
+};
+type PlatformJobMetadataQuery = {
+    select(columns: "metadata"): PlatformJobMetadataQuery;
+    eq(column: "job_name", value: string): PlatformJobMetadataQuery;
+    in(column: "status", values: readonly ["success", "failed"]): PlatformJobMetadataQuery;
+    not(column: "finished_at", operator: "is", value: null): PlatformJobMetadataQuery;
+    order(column: "started_at", options: {
+        ascending: false;
+    }): PlatformJobMetadataQuery;
+    limit(count: 1): PlatformJobMetadataQuery;
+    maybeSingle(): PromiseLike<{
+        data: {
+            metadata?: unknown;
+        } | null;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+};
+type PlatformJobControlQuery = {
+    select(columns: "last_status,last_success_at"): PlatformJobControlQuery;
+    eq(column: "job_name", value: string): PlatformJobControlQuery;
+    maybeSingle(): PromiseLike<{
+        data: {
+            last_status?: string | null;
+            last_success_at?: string | null;
+        } | null;
+        error: {
+            message?: string;
+        } | null;
+    }>;
+};
+export interface PlatformJobSupabaseClient {
+    rpc<T = unknown>(name: string, args: Record<string, unknown>): PromiseLike<RpcResult<T>>;
+    from(table: "platform_job_runs"): PlatformJobMetadataQuery;
+    from(table: "platform_job_controls"): PlatformJobControlQuery;
+}
+/** Minimal compatibility client for the legacy free-function surface. */
+export type PlatformJobClient = Pick<PlatformJobSupabaseClient, "rpc">;
+export declare function platformJobInvocationForDriver(driver: PlatformJobDriver): PlatformJobInvocation;
+export interface ManagedJobRunOptions {
+    /** Release and deployment identity merged into every claim and finish row's metadata. */
+    releaseCorrelation: () => Record<string, string | null>;
+    /** Failure reason recorded when a failed run's summary carries none. */
+    defaultFailureReason: string;
+}
+export interface SupabasePlatformJobRunLedgerOptions extends ManagedJobRunOptions {
+    /** Message of the error thrown when the backstop state cannot be read. */
+    backstopReadError: string;
+    /** Message of the error thrown when the latest terminal run cannot be read. */
+    checkpointReadError: string;
+}
+/** The managed v2/v3 compatibility calls, bound to the deployment's release correlation. */
+export declare function createManagedJobRunCalls(options: ManagedJobRunOptions): {
+    claimJobRun: (client: PlatformJobClient, jobName: string, driver: PlatformJobDriver, leaseSeconds?: number) => Promise<{
+        acquired: boolean;
+        runId: string | null;
+        reason: string;
+    }>;
+    claimJobRunV3: (client: PlatformJobClient, jobName: string, invocation: PlatformJobInvocation, leaseSeconds?: number) => Promise<{
+        acquired: boolean;
+        runId: string | null;
+        reason: string;
+    }>;
+    finishJobRun: (client: PlatformJobClient, jobName: string, runId: string, status: PlatformJobFinishStatus, result: PlatformJobFinishSummary, extraMetadata?: Record<string, unknown>) => Promise<boolean>;
+    finishJobRunV3: (client: PlatformJobClient, jobName: string, runId: string, status: PlatformJobFinishStatus, result: PlatformJobFinishSummary, extraMetadata?: Record<string, unknown>) => Promise<void>;
+};
+/** Managed adapter for the semantic job-run port. */
+export declare function createSupabasePlatformJobRunLedger(client: PlatformJobSupabaseClient, options: SupabasePlatformJobRunLedgerOptions): PlatformJobRunLedgerPort;
+export {};

package/dist/job-ledger/supabase.js

@@ -0,0 +1,202 @@
+// Managed (Supabase) adapter for the job-run ledger, and the managed v2/v3 compatibility calls.
+//
+// It speaks the managed job-control RPCs (`platform_claim_job_run`, `platform_finish_job_run_v2`
+// and their v3 forms) through an injected client. Every claim and finish row carries the
+// deployment's release correlation; the default failure reason and the two read-failure messages
+// are the deployment's own values.
+function triggerSourceForDriver(driver) {
+    switch (driver) {
+        case "vercel_cron": return "vercel_cron";
+        case "pg_cron": return "pg_cron_scheduler";
+        case "worker": return "worker";
+        case "manual_admin": return "manual_admin";
+    }
+}
+export function platformJobInvocationForDriver(driver) {
+    switch (driver) {
+        case "manual_admin": return { triggerKind: "operator", invocationSource: driver };
+        case "pg_cron":
+        case "vercel_cron": return { triggerKind: "scheduler", invocationSource: driver };
+        case "worker": return { triggerKind: "worker", invocationSource: driver };
+    }
+}
+function managedDriverForInvocation(invocation) {
+    if (!["worker", "scheduler", "operator"].includes(invocation.triggerKind)) {
+        throw new Error("platform_job_invalid_trigger_kind");
+    }
+    const source = invocation.invocationSource.trim();
+    const driver = source;
+    const expected = platformJobInvocationForDriver(driver);
+    if (!expected || expected.triggerKind !== invocation.triggerKind) {
+        throw new Error("platform_job_invalid_invocation");
+    }
+    return driver;
+}
+function claimResult(data) {
+    const row = Array.isArray(data) ? data[0] : data;
+    const record = plainRecord(row);
+    return {
+        acquired: record?.acquired === true,
+        runId: typeof record?.run_id === "string" ? record.run_id : null,
+        reason: typeof record?.reason === "string" ? record.reason : "unknown",
+    };
+}
+/** The managed v2/v3 compatibility calls, bound to the deployment's release correlation. */
+export function createManagedJobRunCalls(options) {
+    /** Compatibility surface for existing managed v2 consumers. */
+    async function claimJobRun(client, jobName, driver, leaseSeconds = 900) {
+        const { data, error } = await client.rpc("platform_claim_job_run", {
+            p_job_name: jobName,
+            p_driver: driver,
+            p_lease_seconds: leaseSeconds,
+            p_metadata: {
+                driver,
+                triggerSource: driver === "vercel_cron" ? "vercel_cron_manual" : driver,
+                ...options.releaseCorrelation(),
+            },
+        });
+        if (error)
+            throw new Error(error.message ?? "platform_claim_job_run failed");
+        return claimResult(data);
+    }
+    /** Compatibility surface for existing managed v3 consumers. */
+    async function claimJobRunV3(client, jobName, invocation, leaseSeconds = 900) {
+        const invocationSource = invocation.invocationSource.trim();
+        if (!invocationSource)
+            throw new Error("platform_job_invocation_source_required");
+        const { data, error } = await client.rpc("platform_claim_job_run_v3", {
+            p_job_name: jobName,
+            p_trigger_kind: invocation.triggerKind,
+            p_invocation_source: invocationSource,
+            p_lease_seconds: leaseSeconds,
+            p_metadata: {
+                triggerKind: invocation.triggerKind,
+                invocationSource,
+                ...options.releaseCorrelation(),
+            },
+        });
+        if (error)
+            throw new Error(error.message ?? "platform_claim_job_run_v3 failed");
+        return claimResult(data);
+    }
+    /** Compatibility surface for existing managed v2 consumers. */
+    async function finishJobRun(client, jobName, runId, status, result, extraMetadata) {
+        const { data, error } = await client.rpc("platform_finish_job_run_v2", {
+            p_job_name: jobName,
+            p_run_id: runId,
+            p_status: status,
+            p_checked: result.checked,
+            p_updated: result.updated,
+            p_error: status === "failed" ? result.reason ?? options.defaultFailureReason : null,
+            p_support_code: null,
+            p_metadata: {
+                driver: "manual_admin",
+                failures: result.failures,
+                skipped: result.skipped,
+                reason: result.reason ?? null,
+                ...options.releaseCorrelation(),
+                ...(extraMetadata ?? {}),
+            },
+        });
+        if (error)
+            throw new Error(error.message ?? "platform_finish_job_run_v2 failed");
+        return data === true;
+    }
+    /** Compatibility surface for existing managed v3 consumers. */
+    async function finishJobRunV3(client, jobName, runId, status, result, extraMetadata) {
+        const { error } = await client.rpc("platform_finish_job_run_v3", {
+            p_job_name: jobName,
+            p_run_id: runId,
+            p_status: status,
+            p_checked: result.checked,
+            p_updated: result.updated,
+            p_error: status === "failed" ? result.reason ?? options.defaultFailureReason : null,
+            p_support_code: null,
+            p_metadata: {
+                failures: result.failures,
+                skipped: result.skipped,
+                reason: result.reason ?? null,
+                ...options.releaseCorrelation(),
+                ...(extraMetadata ?? {}),
+            },
+        });
+        if (error)
+            throw new Error(error.message ?? "platform_finish_job_run_v3 failed");
+    }
+    return { claimJobRun, claimJobRunV3, finishJobRun, finishJobRunV3 };
+}
+/** Managed adapter for the semantic job-run port. */
+export function createSupabasePlatformJobRunLedger(client, options) {
+    return {
+        async claimJobRun(jobName, invocation, leaseSeconds = 900) {
+            const driver = managedDriverForInvocation(invocation);
+            const { data, error } = await client.rpc("platform_claim_job_run", {
+                p_job_name: jobName,
+                p_driver: driver,
+                p_lease_seconds: leaseSeconds,
+                p_metadata: {
+                    driver,
+                    triggerSource: triggerSourceForDriver(driver),
+                    ...options.releaseCorrelation(),
+                },
+            });
+            if (error)
+                throw new Error(error.message ?? "platform_claim_job_run failed");
+            return claimResult(data);
+        },
+        async finishJobRun(jobName, runId, invocation, status, result, extraMetadata) {
+            const driver = managedDriverForInvocation(invocation);
+            const { data, error } = await client.rpc("platform_finish_job_run_v2", {
+                p_job_name: jobName,
+                p_run_id: runId,
+                p_status: status,
+                p_checked: result.checked,
+                p_updated: result.updated,
+                p_error: status === "failed" ? result.reason ?? options.defaultFailureReason : null,
+                p_support_code: null,
+                p_metadata: {
+                    failures: result.failures,
+                    skipped: result.skipped,
+                    reason: result.reason ?? null,
+                    ...options.releaseCorrelation(),
+                    ...(extraMetadata ?? {}),
+                    driver,
+                },
+            });
+            if (error)
+                throw new Error(error.message ?? "platform_finish_job_run_v2 failed");
+            return data === true;
+        },
+        async readJobBackstopState(jobName) {
+            const { data, error } = await client
+                .from("platform_job_controls")
+                .select("last_status,last_success_at")
+                .eq("job_name", jobName)
+                .maybeSingle();
+            if (error)
+                throw new Error(options.backstopReadError);
+            return data ? {
+                lastStatus: data.last_status ?? null,
+                lastSuccessAt: data.last_success_at ?? null,
+            } : null;
+        },
+        async readLatestTerminalRunMetadata(jobName) {
+            const { data, error } = await client
+                .from("platform_job_runs")
+                .select("metadata")
+                .eq("job_name", jobName)
+                .in("status", ["success", "failed"])
+                .order("started_at", { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            if (error)
+                throw new Error(options.checkpointReadError);
+            return plainRecord(data?.metadata);
+        },
+    };
+}
+function plainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    return { ...value };
+}

package/dist/kernel/index.d.ts

@@ -0,0 +1 @@
+export { BLOB_CAPABILITIES, DEFAULT_PLATFORM_BUNDLE, ENV_MISSING_CODE, PLATFORM_BUNDLE_DESCRIPTORS, PLATFORM_BUNDLE_IDS, getBundleDescriptor, isPlatformBundleId, platformEnvSchema, resolveBlobCapability, resolveBundleId, type BlobCapability, type PlatformBundleDescriptor, type PlatformBundleId, type PlatformBundleReadiness, type PlatformEnv, } from "./platformKernel.js";

package/dist/kernel/index.js

@@ -0,0 +1 @@
+export { BLOB_CAPABILITIES, DEFAULT_PLATFORM_BUNDLE, ENV_MISSING_CODE, PLATFORM_BUNDLE_DESCRIPTORS, PLATFORM_BUNDLE_IDS, getBundleDescriptor, isPlatformBundleId, platformEnvSchema, resolveBlobCapability, resolveBundleId, } from "./platformKernel.js";

package/dist/kernel/platformKernel.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { type PlatformBundleDescriptor as CorePlatformBundleDescriptor, type PlatformBundleReadiness, type PlatformEnvInput } from "@openlup/core/platform-runtime";
+/** The bundles a deployment can select with `PLATFORM_BUNDLE`. */
+export declare const PLATFORM_BUNDLE_IDS: readonly ["vercel-supabase", "node-supabase", "node-postgres"];
+export type PlatformBundleId = (typeof PLATFORM_BUNDLE_IDS)[number];
+/** The bundle selected when `PLATFORM_BUNDLE` is absent or unknown. */
+export declare const DEFAULT_PLATFORM_BUNDLE: PlatformBundleId;
+export declare const isPlatformBundleId: import("@openlup/core/platform-runtime").PlatformBundleIdGuard<"vercel-supabase" | "node-supabase" | "node-postgres">;
+export type PlatformBundleDescriptor = CorePlatformBundleDescriptor & {
+    id: PlatformBundleId;
+};
+export type { PlatformBundleReadiness };
+/** The readiness code a bundle reports when a selected capability lacks its configuration. */
+export declare const ENV_MISSING_CODE = "OPENLUP_E_ENV_MISSING";
+/** The blob capabilities a deployment can select with `PLATFORM_BLOB`. */
+export declare const BLOB_CAPABILITIES: readonly ["filesystem", "s3", "supabase", "vercel-blob"];
+export type BlobCapability = (typeof BLOB_CAPABILITIES)[number];
+/**
+ * The blob capability in effect: a valid `PLATFORM_BLOB` selection, else the bundle's own. An
+ * invalid selection keeps the bundle's own here and is refused by readiness.
+ */
+export declare function resolveBlobCapability(descriptor: Pick<PlatformBundleDescriptor, "capabilities">, env: PlatformEnvInput): string;
+export declare const PLATFORM_BUNDLE_DESCRIPTORS: readonly PlatformBundleDescriptor[];
+export declare function getBundleDescriptor(id: PlatformBundleId): PlatformBundleDescriptor;
+export declare function resolveBundleId(env: PlatformEnvInput): PlatformBundleId;
+export declare const platformEnvSchema: z.ZodObject<{
+    APP_BASE_URL: z.ZodOptional<z.ZodString>;
+    PLATFORM_BUNDLE: z.ZodOptional<z.ZodEnum<{
+        "vercel-supabase": "vercel-supabase";
+        "node-supabase": "node-supabase";
+        "node-postgres": "node-postgres";
+    }>>;
+}, z.core.$strip>;
+export type PlatformEnv = z.infer<typeof platformEnvSchema>;

package/dist/kernel/platformKernel.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { createPlatformBundleRegistry, platformEnvSchema as corePlatformEnvSchema, createPlatformBundleIdGuard, } from "@openlup/core/platform-runtime";
+/** The bundles a deployment can select with `PLATFORM_BUNDLE`. */
+export const PLATFORM_BUNDLE_IDS = [
+    "vercel-supabase",
+    "node-supabase",
+    "node-postgres",
+];
+/** The bundle selected when `PLATFORM_BUNDLE` is absent or unknown. */
+export const DEFAULT_PLATFORM_BUNDLE = "vercel-supabase";
+export const isPlatformBundleId = createPlatformBundleIdGuard(PLATFORM_BUNDLE_IDS);
+/** The readiness code a bundle reports when a selected capability lacks its configuration. */
+export const ENV_MISSING_CODE = "OPENLUP_E_ENV_MISSING";
+/** The blob capabilities a deployment can select with `PLATFORM_BLOB`. */
+export const BLOB_CAPABILITIES = ["filesystem", "s3", "supabase", "vercel-blob"];
+/**
+ * The blob capability in effect: a valid `PLATFORM_BLOB` selection, else the bundle's own. An
+ * invalid selection keeps the bundle's own here and is refused by readiness.
+ */
+export function resolveBlobCapability(descriptor, env) {
+    const selected = env.PLATFORM_BLOB?.trim();
+    return selected && BLOB_CAPABILITIES.includes(selected) ? selected : descriptor.capabilities.blob;
+}
+/** The settings each blob capability needs; an alternative name may stand in for the first. */
+const BLOB_SETTINGS = {
+    "vercel-blob": [["BLOB_READ_WRITE_TOKEN"]],
+    supabase: [["SUPABASE_URL", "VITE_SUPABASE_URL"], ["SUPABASE_SERVICE_ROLE_KEY"], ["BLOB_SUPABASE_BUCKET"]],
+    filesystem: [["BLOB_FS_ROOT"], ["BLOB_FS_BASE_URL"]],
+    s3: [["BLOB_S3_BUCKET"], ["BLOB_S3_BASE_URL"]],
+};
+function present(env, name) {
+    return typeof env[name] === "string" && env[name].trim() !== "";
+}
+/**
+ * Per-capability readiness, in this order: an unknown PLATFORM_BUNDLE refuses (resolution itself
+ * keeps defaulting); a self-host bundle needs APP_BASE_URL; then every selected capability's
+ * missing settings are reported together under OPENLUP_E_ENV_MISSING: a scheduler needs
+ * CRON_SECRET, Node scheduling needs DATABASE_URL for its cluster lock (never a silent no-op lock),
+ * and the selected blob capability needs its settings. An unknown PLATFORM_BLOB refuses too.
+ */
+function capabilityReadiness(descriptor, selfHost) {
+    return (env) => {
+        const raw = env.PLATFORM_BUNDLE;
+        if (raw !== undefined && raw.trim() !== "" && !isPlatformBundleId(raw)) {
+            return { ok: false, error: `unknown PLATFORM_BUNDLE "${raw}"; expected one of ${PLATFORM_BUNDLE_IDS.join(", ")}` };
+        }
+        const selectedBlob = env.PLATFORM_BLOB;
+        if (selectedBlob !== undefined && selectedBlob.trim() !== "" && !BLOB_CAPABILITIES.includes(selectedBlob.trim())) {
+            return { ok: false, error: `unknown PLATFORM_BLOB "${selectedBlob}"; expected one of ${BLOB_CAPABILITIES.join(", ")}` };
+        }
+        if (selfHost && !present(env, "APP_BASE_URL")) {
+            return { ok: false, error: "APP_BASE_URL is required for self-host bundles" };
+        }
+        const { scheduler } = descriptor.capabilities;
+        const blob = resolveBlobCapability(descriptor, env);
+        const missing = [];
+        if (scheduler === "vercel-cron" || scheduler === "node-cron") {
+            if (!present(env, "CRON_SECRET"))
+                missing.push("CRON_SECRET (scheduler)");
+        }
+        if (scheduler === "node-cron" && !present(env, "DATABASE_URL"))
+            missing.push("DATABASE_URL (scheduler lock)");
+        for (const names of BLOB_SETTINGS[blob] ?? []) {
+            if (!names.some((name) => present(env, name)))
+                missing.push(`${names[0]} (blob: ${blob})`);
+        }
+        return missing.length === 0 ? { ok: true } : { ok: false, error: `${ENV_MISSING_CODE}: ${missing.join(", ")}` };
+    };
+}
+function descriptor(id, capabilities, selfHost) {
+    return { id, capabilities, readReadiness: capabilityReadiness({ capabilities }, selfHost) };
+}
+const DESCRIPTORS = [
+    descriptor("vercel-supabase", {
+        http: "vercel",
+        scheduler: "vercel-cron",
+        blob: "vercel-blob",
+        data: "supabase",
+        migrations: "supabase",
+        analytics: "vercel",
+        transactional: "application",
+    }, false),
+    descriptor("node-supabase", {
+        http: "node",
+        scheduler: "node-cron",
+        blob: "supabase",
+        data: "supabase",
+        migrations: "supabase",
+        analytics: "gtm",
+        transactional: "node",
+    }, true),
+    descriptor("node-postgres", {
+        http: "node",
+        scheduler: "node-cron",
+        blob: "filesystem",
+        data: "postgres",
+        migrations: "postgres",
+        analytics: "noop",
+        transactional: "node",
+    }, true),
+];
+const registry = createPlatformBundleRegistry({
+    descriptors: DESCRIPTORS,
+    defaultBundleId: DEFAULT_PLATFORM_BUNDLE,
+});
+export const PLATFORM_BUNDLE_DESCRIPTORS = registry.descriptors;
+export function getBundleDescriptor(id) {
+    return registry.getBundleDescriptor(id);
+}
+export function resolveBundleId(env) {
+    return registry.resolveBundleId(env);
+}
+export const platformEnvSchema = corePlatformEnvSchema.extend({
+    PLATFORM_BUNDLE: z.enum(PLATFORM_BUNDLE_IDS).optional(),
+});

package/dist/migrations/index.d.ts

@@ -0,0 +1 @@
+export { createPostgresMigrationRunner, resolvePostgresMigrationRunnerEnv, type PlatformMigrationFile, type PlatformMigrationManifest, type PlatformMigrationManifestEntry, type PlatformMigrationSource, type PostgresMigrationRunnerEnv, type PostgresMigrationRunnerOptions, } from "./postgresRunner.js";

package/dist/migrations/index.js

@@ -0,0 +1 @@
+export { createPostgresMigrationRunner, resolvePostgresMigrationRunnerEnv, } from "./postgresRunner.js";

package/dist/migrations/postgresRunner.d.ts

@@ -0,0 +1,50 @@
+import type { Pool, PoolClient } from "pg";
+import type { MigrationRunnerPort } from "@openlup/core/platform-runtime";
+export interface PostgresMigrationRunnerEnv {
+    connectionString: string;
+}
+/** One migration file of the deployment's platform catalogue. */
+export type PlatformMigrationFile = {
+    file: string;
+    content: string;
+};
+export type PlatformMigrationManifestEntry = {
+    file: string;
+    sha256: string;
+};
+/** The validated manifest: a baseline, its ordered forwards and the expected object inventory. */
+export type PlatformMigrationManifest = {
+    schemaVersion: 1;
+    baseline: PlatformMigrationManifestEntry;
+    forward: PlatformMigrationManifestEntry[];
+    objectInventorySha256: string;
+};
+/**
+ * The deployment's migration catalogue and its validator. `evaluate` returns every refusal for a
+ * manifest against the catalogue files and, when given, the live object-inventory payload.
+ */
+export interface PlatformMigrationSource {
+    readMigrations(root: string): {
+        migrations: PlatformMigrationFile[];
+        errors: string[];
+    };
+    readManifest(root: string): unknown | null;
+    evaluate(input: {
+        manifest: unknown;
+        migrations: readonly PlatformMigrationFile[];
+        objectInventoryPayload?: string;
+    }): string[];
+}
+export interface PostgresMigrationRunnerOptions {
+    /** Name of the PostgreSQL advisory lock that serializes migration sessions. */
+    lockName: string;
+    /** The deployment's migration catalogue. */
+    source: PlatformMigrationSource;
+    /** Serializes the live object inventory that the manifest's `objectInventorySha256` pins. */
+    catalogProjectionPayload: (client: PoolClient) => Promise<string>;
+    /** Catalogue root; defaults to process.cwd(). */
+    root?: string;
+    poolFactory?: (env: PostgresMigrationRunnerEnv) => Pool | Promise<Pool>;
+}
+export declare function createPostgresMigrationRunner(env: PostgresMigrationRunnerEnv, options: PostgresMigrationRunnerOptions): MigrationRunnerPort;
+export declare function resolvePostgresMigrationRunnerEnv(env: Record<string, string | undefined>): PostgresMigrationRunnerEnv;

package/dist/migrations/postgresRunner.js

@@ -0,0 +1,176 @@
+// Public-platform MigrationRunnerPort for the experimental node-postgres bundle.
+// The manifest and its exact SQL bytes are validated before a pool is created.
+// Applied rows are an exact prefix of that catalog; path, digest or position
+// drift is fatal. Only the caller's catalogue is applied; no other migration
+// history is selected or reachable through a default.
+const LEDGER = "public.platform_schema_migrations";
+const ACQUIRE_MIGRATION_LOCK = "SELECT pg_advisory_lock(hashtextextended($1, 0))";
+const RELEASE_MIGRATION_LOCK = "SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS unlocked";
+export function createPostgresMigrationRunner(env, options) {
+    const root = options.root ?? process.cwd();
+    let pool = null;
+    async function getPool() {
+        if (pool)
+            return pool;
+        const factory = options.poolFactory ?? defaultPoolFactory;
+        pool = await factory(env);
+        return pool;
+    }
+    return {
+        async status() {
+            assertConnectionString(env);
+            const plan = loadPlan(root, options.source);
+            return withMigrationSession(await getPool(), options.lockName, async (client) => {
+                const applied = await readAppliedPrefix(client, plan.units);
+                if (applied.length === plan.units.length)
+                    await assertObjectInventory(client, plan, options);
+                return {
+                    pending: plan.units.slice(applied.length).map((unit) => unit.catalogPath),
+                    applied: applied.map((unit) => unit.catalogPath),
+                };
+            });
+        },
+        async apply(opts) {
+            assertConnectionString(env);
+            const plan = loadPlan(root, options.source);
+            return withMigrationSession(await getPool(), options.lockName, async (client) => {
+                const already = await readAppliedPrefix(client, plan.units);
+                const pending = plan.units.slice(already.length);
+                if (opts?.dryRun) {
+                    if (pending.length === 0)
+                        await assertObjectInventory(client, plan, options);
+                    return { applied: pending.map((unit) => unit.catalogPath) };
+                }
+                const appliedNow = [];
+                for (const unit of pending) {
+                    await client.query("BEGIN");
+                    try {
+                        await client.query(unit.sql);
+                        await client.query(`INSERT INTO ${LEDGER} (catalog_path, sha256, position) VALUES ($1, $2, $3)`, [unit.catalogPath, unit.sha256, unit.position]);
+                        await client.query("COMMIT");
+                        appliedNow.push(unit.catalogPath);
+                    }
+                    catch (error) {
+                        await client.query("ROLLBACK").catch(() => { });
+                        throw new Error(`platform migration ${unit.catalogPath} failed: ${errorMessage(error)}`);
+                    }
+                }
+                const complete = await readAppliedPrefix(client, plan.units);
+                if (complete.length !== plan.units.length)
+                    throw new Error("platform migration ledger is incomplete after apply");
+                await assertObjectInventory(client, plan, options);
+                return { applied: appliedNow };
+            });
+        },
+    };
+}
+async function withMigrationSession(pool, lockName, operation) {
+    const client = await pool.connect();
+    let locked = false;
+    let failed = false;
+    let operationFailure;
+    let result;
+    try {
+        await client.query(ACQUIRE_MIGRATION_LOCK, [lockName]);
+        locked = true;
+        result = await operation(client);
+    }
+    catch (error) {
+        failed = true;
+        operationFailure = error;
+    }
+    let unlockFailure;
+    if (locked) {
+        try {
+            const unlocked = await client.query(RELEASE_MIGRATION_LOCK, [lockName]);
+            if (unlocked.rows[0]?.unlocked !== true)
+                throw new Error("PostgreSQL did not release the advisory lock");
+        }
+        catch (error) {
+            unlockFailure = error;
+        }
+    }
+    client.release(unlockFailure !== undefined || (failed && !locked));
+    if (failed) {
+        if (unlockFailure !== undefined) {
+            throw new Error(`platform migration operation failed: ${errorMessage(operationFailure)}; advisory lock release failed: ${errorMessage(unlockFailure)}`);
+        }
+        throw operationFailure;
+    }
+    if (unlockFailure !== undefined) {
+        throw new Error(`platform migration advisory lock release failed: ${errorMessage(unlockFailure)}`);
+    }
+    return result;
+}
+function assertConnectionString(env) {
+    if (env.connectionString.trim() === "") {
+        throw new Error("DATABASE_URL is required for node-postgres migrations");
+    }
+}
+function loadPlan(root, source) {
+    const catalog = source.readMigrations(root);
+    const rawManifest = source.readManifest(root);
+    const errors = [...catalog.errors];
+    if (rawManifest === null)
+        errors.push("platform migration manifest is missing");
+    else
+        errors.push(...source.evaluate({ manifest: rawManifest, migrations: catalog.migrations }));
+    if (errors.length > 0)
+        throw new Error(`platform migration catalog rejected: ${errors.join("; ")}`);
+    const manifest = rawManifest;
+    const byPath = new Map(catalog.migrations.map((migration) => [migration.file, migration.content]));
+    const entries = [manifest.baseline, ...manifest.forward];
+    const units = entries.map((entry, position) => Object.freeze({
+        catalogPath: entry.file,
+        sha256: entry.sha256,
+        position,
+        sql: byPath.get(entry.file),
+    }));
+    return Object.freeze({ manifest, migrations: catalog.migrations, units: Object.freeze(units) });
+}
+async function readAppliedPrefix(client, units) {
+    const exists = await client.query("SELECT to_regclass($1) IS NOT NULL AS ledger_exists", [LEDGER]);
+    if (exists.rows[0]?.ledger_exists !== true)
+        return [];
+    const result = await client.query(`SELECT catalog_path, sha256, position FROM ${LEDGER} ORDER BY position`);
+    if (result.rows.length > units.length)
+        throw new Error("platform migration ledger contains an extra row");
+    for (let index = 0; index < result.rows.length; index += 1) {
+        const row = result.rows[index];
+        const unit = units[index];
+        if (row.catalog_path !== unit.catalogPath || row.sha256 !== unit.sha256 || row.position !== unit.position) {
+            throw new Error(`platform migration ledger is not the exact manifest prefix at position ${index}`);
+        }
+    }
+    return units.slice(0, result.rows.length);
+}
+async function assertObjectInventory(client, plan, options) {
+    const payload = await options.catalogProjectionPayload(client);
+    const errors = options.source.evaluate({
+        manifest: plan.manifest,
+        migrations: plan.migrations,
+        objectInventoryPayload: payload,
+    });
+    if (errors.length > 0)
+        throw new Error(`platform migration inventory rejected: ${errors.join("; ")}`);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function defaultPoolFactory(env) {
+    const pg = await import("pg").catch(peerMissing);
+    const PoolCtor = (pg.default?.Pool ?? pg.Pool);
+    return new PoolCtor({ connectionString: env.connectionString });
+}
+export function resolvePostgresMigrationRunnerEnv(env) {
+    return { connectionString: env.DATABASE_URL ?? "" };
+}
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause) {
+    if (cause instanceof Error && "code" in cause
+        && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+        && /^Cannot find (?:package|module) ['"]pg['"]/.test(cause.message)) {
+        throw new Error("OPENLUP_E_PEER_MISSING: pg is required by the Postgres migration runner; install it alongside @openlup/platform", { cause });
+    }
+    throw cause;
+}