@openlup/platform 0.29.0 → 0.30.0

package/dist/portability/filesystemObjects.d.ts

@@ -0,0 +1,12 @@
+import { type TransferObjectStore } from "./objects.js";
+/**
+ * Private local transfer store, exclusively controlled by its owner process/account.
+ * Metadata and bytes publish together through one directory rename. Concurrent use through
+ * this adapter is supported; hostile same-UID filesystem mutation is outside that guarantee.
+ */
+export declare function createFilesystemTransferObjects(options: {
+    root: string;
+    maximumObjectBytes: number;
+    /** Host label for this filesystem owner's private-read policy; other ACLs refuse. */
+    access: string;
+}): Promise<TransferObjectStore>;

package/dist/portability/filesystemObjects.js

@@ -0,0 +1,191 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { encodeTransferObject, normalizeObjectTransferError, ObjectTransferError, validateTransferObject, } from "./objects.js";
+// Covers bounded metadata JSON in UTF-8 plus JSON-escaped bounded identifiers.
+const maximumDescriptorBytes = 262144;
+/**
+ * Private local transfer store, exclusively controlled by its owner process/account.
+ * Metadata and bytes publish together through one directory rename. Concurrent use through
+ * this adapter is supported; hostile same-UID filesystem mutation is outside that guarantee.
+ */
+export async function createFilesystemTransferObjects(options) {
+    if (!isAbsolute(options.root) || !Number.isSafeInteger(options.maximumObjectBytes) || options.maximumObjectBytes < 0
+        || typeof options.access !== "string" || !options.access.trim()) {
+        throw new ObjectTransferError("invalid_input");
+    }
+    const root = resolve(options.root), maximum = options.maximumObjectBytes, access = options.access;
+    try {
+        if (await realpath(dirname(root)) !== dirname(root))
+            throw new ObjectTransferError("denied");
+        await mkdir(root, { mode: 0o700 }).catch(error => { if (errno(error) !== "EEXIST")
+            throw error; });
+        await privateDirectory(root, true);
+    }
+    catch (error) {
+        throw filesystemFailure(error);
+    }
+    const location = (key) => join(root, createHash("sha256").update(JSON.stringify(key)).digest("hex"));
+    return {
+        async read(key, expectedVersion) {
+            let body;
+            let published = false;
+            try {
+                await privateDirectory(root, true);
+                const directory = location(key);
+                await privateDirectory(directory);
+                published = true;
+                const metadata = await openPrivateFile(join(directory, "metadata.json"));
+                let object;
+                try {
+                    if ((await metadata.stat()).size > maximumDescriptorBytes)
+                        throw new ObjectTransferError("integrity_conflict");
+                    try {
+                        object = JSON.parse(await metadata.readFile("utf8"));
+                    }
+                    catch {
+                        throw new ObjectTransferError("integrity_conflict");
+                    }
+                }
+                finally {
+                    await metadata.close();
+                }
+                validateTransferObject(object);
+                if (object.access !== access)
+                    throw new ObjectTransferError("denied");
+                if (object.key !== key || (expectedVersion !== undefined && object.version !== expectedVersion))
+                    throw new ObjectTransferError("version_conflict");
+                if (object.bytes > maximum)
+                    throw new ObjectTransferError("invalid_input");
+                body = await openPrivateFile(join(directory, "bytes"));
+                if ((await body.stat()).size !== object.bytes)
+                    throw new ObjectTransferError("integrity_conflict");
+                await body.close();
+                body = undefined;
+                // Open lazily: descriptor refusal must not leave an unconsumed stream holding a file.
+                return { object, body: (async function* () {
+                        let opened;
+                        try {
+                            await privateDirectory(root, true);
+                            await privateDirectory(directory);
+                            opened = await openPrivateFile(join(directory, "bytes"));
+                            if ((await opened.stat()).size !== object.bytes)
+                                throw new ObjectTransferError("integrity_conflict");
+                            for await (const chunk of opened.createReadStream({ autoClose: false }))
+                                yield Buffer.from(chunk);
+                        }
+                        catch (error) {
+                            throw errno(error) === "ENOENT" ? new ObjectTransferError("integrity_conflict") : filesystemFailure(error);
+                        }
+                        finally {
+                            await opened?.close();
+                        }
+                    })() };
+            }
+            catch (error) {
+                await body?.close();
+                if (published && errno(error) === "ENOENT")
+                    throw new ObjectTransferError("integrity_conflict");
+                throw filesystemFailure(error);
+            }
+        },
+        async createIfAbsent(object, bytes) {
+            let temporary;
+            try {
+                const encoded = Buffer.from(encodeTransferObject(object));
+                if (encoded.byteLength > maximumDescriptorBytes)
+                    throw new ObjectTransferError("invalid_input");
+                if (object.access !== access)
+                    throw new ObjectTransferError("denied");
+                const key = object.key;
+                if (object.bytes > maximum || bytes.byteLength !== object.bytes
+                    || createHash("sha256").update(bytes).digest("hex") !== object.sha256)
+                    throw new ObjectTransferError("integrity_conflict");
+                await privateDirectory(root, true);
+                temporary = join(root, `.partial-${randomUUID()}`);
+                await mkdir(temporary, { mode: 0o700 });
+                await writePrivateFile(join(temporary, "metadata.json"), encoded);
+                await writePrivateFile(join(temporary, "bytes"), bytes);
+                const directoryHandle = await open(temporary, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    await directoryHandle.sync();
+                }
+                finally {
+                    await directoryHandle.close();
+                }
+                try {
+                    // Existing published objects are nonempty directories, so rename cannot replace them.
+                    // Check also refuses an empty directory or symlink occupying a target key.
+                    await lstat(location(key));
+                    throw new ObjectTransferError("version_conflict");
+                }
+                catch (error) {
+                    if (errno(error) !== "ENOENT")
+                        throw error;
+                }
+                await rename(temporary, location(key));
+                temporary = undefined;
+                const rootHandle = await open(root, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    await rootHandle.sync();
+                }
+                finally {
+                    await rootHandle.close();
+                }
+            }
+            catch (error) {
+                throw filesystemFailure(error);
+            }
+            finally {
+                if (temporary)
+                    await rm(temporary, { recursive: true, force: true });
+            }
+        },
+    };
+}
+async function privateDirectory(path, storeRoot = false) {
+    const stat = await lstat(path).catch(error => {
+        if (storeRoot && errno(error) === "ENOENT")
+            throw new ObjectTransferError("unavailable");
+        throw error;
+    });
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700 || stat.uid !== process.getuid?.()) {
+        throw new ObjectTransferError("denied");
+    }
+}
+async function openPrivateFile(path) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || stat.uid !== process.getuid?.())
+            throw new ObjectTransferError("denied");
+        return handle;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+async function writePrivateFile(path, bytes) {
+    const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function errno(error) { return error?.code; }
+function filesystemFailure(error) {
+    if (error instanceof ObjectTransferError)
+        return error;
+    if (errno(error) === "ENOENT")
+        return new ObjectTransferError("absent");
+    if (["EACCES", "EPERM", "ELOOP"].includes(errno(error) ?? ""))
+        return new ObjectTransferError("denied");
+    if (["EEXIST", "ENOTEMPTY"].includes(errno(error) ?? ""))
+        return new ObjectTransferError("version_conflict");
+    return normalizeObjectTransferError(error);
+}

package/dist/portability/index.d.ts

@@ -0,0 +1,5 @@
+export { copyTransferObjects, ObjectTransferError } from "./objects.js";
+export type { ObjectTransferFailure, TransferObject, TransferObjectRead, TransferObjectReader, TransferObjectStore, TransferObjectInventory, } from "./objects.js";
+export { createFilesystemTransferObjects } from "./filesystemObjects.js";
+export { captureCompatiblePostgresRows, restoreCompatiblePostgresRows, PostgresTransferError } from "./postgresRows.js";
+export type { CompatiblePostgresTable, TransferPostgresQuery, CompatiblePostgresSnapshot, CompatiblePostgresTarget, CompatiblePostgresPacket, PostgresTransferFailure, } from "./postgresRows.js";

package/dist/portability/index.js

@@ -0,0 +1,4 @@
+// Server-only, opt-in data movement. No executor, route or handover is activated.
+export { copyTransferObjects, ObjectTransferError } from "./objects.js";
+export { createFilesystemTransferObjects } from "./filesystemObjects.js";
+export { captureCompatiblePostgresRows, restoreCompatiblePostgresRows, PostgresTransferError } from "./postgresRows.js";

package/dist/portability/objects.d.ts

@@ -0,0 +1,63 @@
+export type ObjectTransferFailure = "absent" | "denied" | "unavailable" | "version_conflict" | "integrity_conflict" | "invalid_input";
+/** Adapters distinguish missing data from permission and availability failures. */
+export declare class ObjectTransferError extends Error {
+    readonly code: ObjectTransferFailure;
+    constructor(code: ObjectTransferFailure);
+}
+export interface TransferObject {
+    key: string;
+    /** Logical immutable source version; never a claim about a target provider's native version ID. */
+    version: string;
+    bytes: number;
+    sha256: string;
+    metadata: Readonly<Record<string, string>>;
+    /** An explicit access classification, never inferred from a public URL. */
+    access: string;
+    lineage?: {
+        sourceId: string;
+        snapshotId: string;
+        sourceVersion: string;
+    };
+}
+export interface TransferObjectRead {
+    object: TransferObject;
+    body: AsyncIterable<Uint8Array>;
+}
+export interface TransferObjectReader {
+    /** Must read the requested version or refuse, never silently read a newer one. */
+    read(key: string, expectedVersion?: string): Promise<TransferObjectRead>;
+}
+export interface TransferObjectStore extends TransferObjectReader {
+    /** Atomic publication; an existing key must refuse with version_conflict. */
+    createIfAbsent(object: TransferObject, bytes: Uint8Array): Promise<void>;
+}
+export interface TransferObjectInventory {
+    sourceId: string;
+    /** Host prerequisite: complete inventory and stable versioned reads, or a held write fence. */
+    snapshot: {
+        kind: "immutable" | "quiesced";
+        id: string;
+    };
+    objects: readonly TransferObject[];
+}
+/** Canonical descriptor encoding also preserves metadata independent of property order. */
+export declare function encodeTransferObject(object: TransferObject): string;
+export declare function validateTransferObject(object: TransferObject): void;
+/** Bounded in-memory object copy; ceilings are explicit and checked before any destination mutation. */
+export declare function copyTransferObjects(input: {
+    inventory: TransferObjectInventory;
+    source: TransferObjectReader;
+    destination: TransferObjectStore;
+    accessMapping: Readonly<Record<string, string>>;
+    maximumObjectBytes: number;
+    maximumTotalBytes: number;
+    /** Called only after destination descriptor and bytes have been read back successfully. */
+    checkpoint?: (object: TransferObject) => Promise<void>;
+}): Promise<{
+    copied: number;
+    replayed: number;
+    verifiedKeys: string[];
+}>;
+/** Read exactly the declared bytes and hash; never trust a successful HEAD alone. */
+export declare function verifyRead(read: TransferObjectRead, expected: TransferObject): Promise<Uint8Array>;
+export declare function normalizeObjectTransferError(error: unknown): ObjectTransferError;

package/dist/portability/objects.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+/** Adapters distinguish missing data from permission and availability failures. */
+export class ObjectTransferError extends Error {
+    code;
+    constructor(code) {
+        super(`object_transfer_${code}`);
+        this.code = code;
+        this.name = "ObjectTransferError";
+    }
+}
+/** Canonical descriptor encoding also preserves metadata independent of property order. */
+export function encodeTransferObject(object) {
+    validateTransferObject(object);
+    return JSON.stringify({
+        key: object.key, version: object.version, bytes: object.bytes, sha256: object.sha256,
+        metadata: Object.fromEntries(Object.entries(object.metadata).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)),
+        access: object.access,
+        ...(object.lineage ? { lineage: { sourceId: object.lineage.sourceId, snapshotId: object.lineage.snapshotId, sourceVersion: object.lineage.sourceVersion } } : {}),
+    });
+}
+export function validateTransferObject(object) {
+    if (!object || !text(object.key, 4096) || !text(object.version, 1024)
+        || !Number.isSafeInteger(object.bytes) || object.bytes < 0 || !/^[a-f0-9]{64}$/.test(object.sha256)
+        || !text(object.access, 1024) || !object.metadata || typeof object.metadata !== "object" || Array.isArray(object.metadata)
+        || Object.entries(object.metadata).some(([key, value]) => !text(key, 1024) || typeof value !== "string" || value.length > 8192)
+        || JSON.stringify(object.metadata).length > 65536
+        || (object.lineage !== undefined && (!object.lineage || !text(object.lineage.sourceId, 1024)
+            || !text(object.lineage.snapshotId, 1024) || !text(object.lineage.sourceVersion, 1024)))) {
+        throw new ObjectTransferError("invalid_input");
+    }
+}
+/** Bounded in-memory object copy; ceilings are explicit and checked before any destination mutation. */
+export async function copyTransferObjects(input) {
+    const { inventory } = input;
+    if (!inventory || !text(inventory.sourceId, 1024) || !inventory.snapshot
+        || !["immutable", "quiesced"].includes(inventory.snapshot.kind) || !text(inventory.snapshot.id, 1024)
+        || !Array.isArray(inventory.objects) || !input.accessMapping
+        || !ceiling(input.maximumObjectBytes) || !ceiling(input.maximumTotalBytes))
+        throw new ObjectTransferError("invalid_input");
+    // Snapshot inputs before the first await; a caller cannot change the plan during a copy.
+    const sourceId = inventory.sourceId, snapshotId = inventory.snapshot.id;
+    const keys = new Set();
+    let total = 0;
+    const plan = inventory.objects.map(object => {
+        const source = JSON.parse(encodeTransferObject(object));
+        const access = Object.hasOwn(input.accessMapping, source.access) ? input.accessMapping[source.access] : undefined;
+        total += source.bytes;
+        if (keys.has(source.key) || !text(access, 1024) || source.bytes > input.maximumObjectBytes
+            || !Number.isSafeInteger(total) || total > input.maximumTotalBytes)
+            throw new ObjectTransferError("invalid_input");
+        keys.add(source.key);
+        const target = { ...source, access, lineage: { sourceId, snapshotId, sourceVersion: source.version } };
+        return { source, target };
+    });
+    const result = { copied: 0, replayed: 0, verifiedKeys: [] };
+    for (const { source, target } of plan) {
+        let existing;
+        try {
+            existing = await input.destination.read(target.key);
+        }
+        catch (error) {
+            if (!failure(error, "absent"))
+                throw normalizeObjectTransferError(error);
+        }
+        if (existing) {
+            await verifyRead(existing, target);
+            result.replayed++;
+        }
+        else {
+            let read;
+            try {
+                read = await input.source.read(source.key, source.version);
+            }
+            catch (error) {
+                throw normalizeObjectTransferError(error);
+            }
+            const bytes = await verifyRead(read, source);
+            let writeFailure;
+            try {
+                await input.destination.createIfAbsent(target, bytes);
+            }
+            catch (error) {
+                // A competing writer or lost write acknowledgement still requires exact readback.
+                if (!failure(error, "version_conflict") && !failure(error, "unavailable"))
+                    throw normalizeObjectTransferError(error);
+                writeFailure = normalizeObjectTransferError(error);
+            }
+            try {
+                await verifyRead(await input.destination.read(target.key), target);
+            }
+            catch (error) {
+                throw failure(error, "absent") && writeFailure ? writeFailure : normalizeObjectTransferError(error);
+            }
+            if (writeFailure)
+                result.replayed++;
+            else
+                result.copied++;
+        }
+        await input.checkpoint?.(JSON.parse(encodeTransferObject(target)));
+        result.verifiedKeys.push(target.key);
+    }
+    return result;
+}
+/** Read exactly the declared bytes and hash; never trust a successful HEAD alone. */
+export async function verifyRead(read, expected) {
+    if (encodeTransferObject(read.object) !== encodeTransferObject(expected))
+        throw new ObjectTransferError("version_conflict");
+    const chunks = [];
+    const hash = createHash("sha256");
+    let bytes = 0;
+    try {
+        for await (const chunk of read.body) {
+            if (!(chunk instanceof Uint8Array))
+                throw new ObjectTransferError("integrity_conflict");
+            bytes += chunk.byteLength;
+            if (bytes > expected.bytes)
+                throw new ObjectTransferError("integrity_conflict");
+            const copy = Buffer.from(chunk);
+            chunks.push(copy);
+            hash.update(copy);
+        }
+    }
+    catch (error) {
+        throw normalizeObjectTransferError(error);
+    }
+    if (bytes !== expected.bytes || hash.digest("hex") !== expected.sha256)
+        throw new ObjectTransferError("integrity_conflict");
+    return Buffer.concat(chunks, bytes);
+}
+export function normalizeObjectTransferError(error) {
+    return error instanceof ObjectTransferError ? error : new ObjectTransferError("unavailable");
+}
+function text(value, maximum) {
+    return typeof value === "string" && value.length > 0 && value.length <= maximum
+        && !Array.from(value).some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+}
+function ceiling(value) { return Number.isSafeInteger(value) && value >= 0; }
+function failure(error, code) { return error instanceof ObjectTransferError && error.code === code; }

package/dist/portability/postgresRows.d.ts

@@ -0,0 +1,64 @@
+/** A finite compatible-row utility, not a complete-store migration profile. */
+declare const TABLES: readonly ["clients", "subscriptions", "subscription_events", "subscription_pause_windows", "subscription_renewal_terms", "subscription_renewal_term_lines", "subscription_renewal_operations", "subscription_cycles", "commerce_orders", "commerce_order_items", "commerce_settlement_intents", "commerce_settlement_transitions", "payment_truth_events", "payment_truth_reconciliation_evidence", "subscription_renewal_outcomes", "outbox_events", "invoicing_duties", "invoicing_fact_revisions", "invoicing_effect_receipts", "invoicing_capture_faults"];
+export type CompatiblePostgresTable = typeof TABLES[number];
+export interface TransferPostgresQuery {
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(sql: string, values?: readonly unknown[]): Promise<{
+        rows: Row[];
+    }>;
+}
+export interface CompatiblePostgresSnapshot {
+    /** Own one read-only, repeatable-read transaction for the complete callback. */
+    withSnapshot<T>(work: (db: TransferPostgresQuery) => Promise<T>): Promise<T>;
+}
+export interface CompatiblePostgresTarget {
+    /** Own one transaction; commit only after the complete callback succeeds. */
+    withTransaction<T>(work: (db: TransferPostgresQuery) => Promise<T>): Promise<T>;
+}
+type Column = {
+    name: string;
+    type: string;
+    key: boolean;
+};
+type TableRows = {
+    table: CompatiblePostgresTable;
+    columns: Column[];
+    rows: string[];
+};
+export interface CompatiblePostgresPacket {
+    format: "openlup.compatible-rows.v1";
+    sourceId: string;
+    /** Opaque selected-catalogue identity supplied by the validated host capability. */
+    catalogueId: string;
+    tables: TableRows[];
+    sha256: string;
+}
+export type PostgresTransferFailure = "invalid_input" | "unsupported_table" | "schema_conflict" | "insert_trigger_requires_owner" | "target_conflict" | "limit_exceeded" | "database_unavailable";
+export declare class PostgresTransferError extends Error {
+    readonly code: PostgresTransferFailure;
+    readonly table?: string | undefined;
+    constructor(code: PostgresTransferFailure, table?: string | undefined);
+}
+/** Data only: no schema, role, grant, migration ledger, control or provider-internal copy. */
+export declare function captureCompatiblePostgresRows(input: {
+    source: CompatiblePostgresSnapshot;
+    sourceId: string;
+    catalogueId: string;
+    tables: readonly CompatiblePostgresTable[];
+    maximumRows: number;
+    maximumBytes: number;
+}): Promise<CompatiblePostgresPacket>;
+/**
+ * Atomic insert and exact replay. A differing row refuses; there is no upsert,
+ * deletion scan, status reset or permission change. Existing parent rows remain
+ * prerequisites, and this utility never authorizes target effect execution.
+ */
+export declare function restoreCompatiblePostgresRows(input: {
+    target: CompatiblePostgresTarget;
+    catalogueId: string;
+    packet: CompatiblePostgresPacket;
+}): Promise<{
+    inserted: number;
+    replayed: number;
+    sha256: string;
+}>;
+export {};

package/dist/portability/postgresRows.js

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+/** A finite compatible-row utility, not a complete-store migration profile. */
+const TABLES = [
+    "clients", "subscriptions", "subscription_events", "subscription_pause_windows",
+    "subscription_renewal_terms", "subscription_renewal_term_lines", "subscription_renewal_operations",
+    "subscription_cycles", "commerce_orders", "commerce_order_items", "commerce_settlement_intents",
+    "commerce_settlement_transitions", "payment_truth_events", "payment_truth_reconciliation_evidence",
+    "subscription_renewal_outcomes", "outbox_events", "invoicing_duties", "invoicing_fact_revisions",
+    "invoicing_effect_receipts", "invoicing_capture_faults",
+];
+export class PostgresTransferError extends Error {
+    code;
+    table;
+    constructor(code, table) {
+        super(`postgres_transfer_${code}${table ? `:${table}` : ""}`);
+        this.code = code;
+        this.table = table;
+        this.name = "PostgresTransferError";
+    }
+}
+const LIMIT_ROWS = 10000, LIMIT_BYTES = 64 * 1024 * 1024;
+/** Data only: no schema, role, grant, migration ledger, control or provider-internal copy. */
+export async function captureCompatiblePostgresRows(input) {
+    const { sourceId, catalogueId, maximumRows, maximumBytes } = input;
+    if (!identity(sourceId) || !identity(catalogueId) || !ceiling(maximumRows, LIMIT_ROWS) || !ceiling(maximumBytes, LIMIT_BYTES))
+        fail("invalid_input");
+    const names = tableNames(input.tables);
+    try {
+        const tables = await input.source.withSnapshot(async (db) => {
+            const mode = (await db.query("SELECT current_setting('transaction_read_only') AS readonly, current_setting('transaction_isolation') AS isolation")).rows[0];
+            if (mode?.readonly !== "on" || mode.isolation !== "repeatable read")
+                fail("invalid_input");
+            await db.query("SET LOCAL TimeZone = 'UTC'");
+            let count = 0, bytes = 0;
+            const result = [];
+            for (const table of names) {
+                const columns = await inspect(db, table);
+                const order = columns.filter(column => column.key).map(column => quoted(column.name)).join(",");
+                // PostgreSQL serializes bigint, numeric, bytea and timestamp values.
+                // Retain that JSON text unchanged; a JS numeric round trip is lossy.
+                const rows = (await db.query(`SELECT to_jsonb(t)::text AS value FROM public.${quoted(table)} t ORDER BY ${order} LIMIT $1`, [maximumRows + 1])).rows.map(row => row.value);
+                for (const row of rows) {
+                    count++;
+                    bytes += Buffer.byteLength(row);
+                }
+                if (count > maximumRows || bytes > maximumBytes)
+                    fail("limit_exceeded", table);
+                result.push({ table, columns, rows });
+            }
+            return result;
+        });
+        const packet = { format: "openlup.compatible-rows.v1", sourceId, catalogueId, tables };
+        return { ...packet, sha256: digest(packet) };
+    }
+    catch (error) {
+        throw redacted(error);
+    }
+}
+/**
+ * Atomic insert and exact replay. A differing row refuses; there is no upsert,
+ * deletion scan, status reset or permission change. Existing parent rows remain
+ * prerequisites, and this utility never authorizes target effect execution.
+ */
+export async function restoreCompatiblePostgresRows(input) {
+    // Own immutable input bytes throughout async validation and writes.
+    let packet;
+    try {
+        packet = JSON.parse(JSON.stringify(input.packet));
+        validatePacket(packet);
+    }
+    catch (error) {
+        if (error instanceof PostgresTransferError)
+            throw error;
+        fail("invalid_input");
+    }
+    if (packet.catalogueId !== input.catalogueId)
+        fail("schema_conflict");
+    try {
+        return await input.target.withTransaction(async (db) => {
+            const mode = (await db.query("SELECT current_setting('session_replication_role') AS mode")).rows[0];
+            if (mode?.mode !== "origin")
+                fail("invalid_input");
+            await db.query("SET LOCAL TimeZone = 'UTC'");
+            // Serializes writers and prevents DDL between inspection and inserts.
+            // Fixed lock ordering avoids deadlock between overlapping packet imports.
+            for (const table of [...packet.tables].sort((a, b) => a.table.localeCompare(b.table))) {
+                await db.query(`LOCK TABLE public.${quoted(table.table)} IN SHARE ROW EXCLUSIVE MODE`);
+            }
+            for (const table of packet.tables) {
+                if (JSON.stringify(await inspect(db, table.table)) !== JSON.stringify(table.columns))
+                    fail("schema_conflict", table.table);
+                const triggers = (await db.query(`SELECT 1 FROM pg_catalog.pg_trigger
+          WHERE tgrelid=$1::regclass AND NOT tgisinternal AND (tgtype & 4) <> 0 AND tgenabled IN ('O','A')`, [`public.${table.table}`])).rows;
+                if (triggers.length)
+                    fail("insert_trigger_requires_owner", table.table);
+            }
+            let inserted = 0, replayed = 0;
+            for (const table of packet.tables) {
+                const name = `public.${quoted(table.table)}`;
+                const columns = table.columns.map(column => quoted(column.name)).join(",");
+                const keys = table.columns.filter(column => column.key).map(column => `t.${quoted(column.name)} IS NOT DISTINCT FROM p.${quoted(column.name)}`).join(" AND ");
+                for (const row of table.rows) {
+                    const write = await db.query(`INSERT INTO ${name} (${columns}) SELECT ${columns} FROM jsonb_populate_record(NULL::${name}, $1::jsonb)
+            ON CONFLICT DO NOTHING RETURNING 1 AS inserted`, [row]);
+                    const read = await db.query(`SELECT to_jsonb(t) = $1::jsonb AS identical FROM ${name} t,
+            jsonb_populate_record(NULL::${name}, $1::jsonb) p WHERE ${keys}`, [row]);
+                    if (read.rows.length !== 1 || read.rows[0]?.identical !== true)
+                        fail("target_conflict", table.table);
+                    if (write.rows.length)
+                        inserted++;
+                    else
+                        replayed++;
+                }
+            }
+            return { inserted, replayed, sha256: packet.sha256 };
+        });
+    }
+    catch (error) {
+        throw redacted(error);
+    }
+}
+async function inspect(db, table) {
+    const rows = (await db.query(`SELECT a.attname AS name,
+    pg_catalog.format_type(a.atttypid,a.atttypmod) AS type, COALESCE(a.attnum = ANY(i.indkey),false) AS key,
+    a.attgenerated AS generated, a.attidentity AS identity
+    FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid=a.attrelid
+    LEFT JOIN pg_catalog.pg_index i ON i.indrelid=c.oid AND i.indisprimary
+    WHERE a.attrelid=$1::regclass AND c.relkind='r' AND a.attnum>0 AND NOT a.attisdropped ORDER BY a.attnum`, [`public.${table}`])).rows;
+    if (!rows.length || !rows.some(row => row.key) || rows.some(row => row.generated || row.identity || !identifier(row.name)))
+        fail("schema_conflict", table);
+    return rows.map(({ name, type, key }) => ({ name, type, key }));
+}
+function tableNames(tables) {
+    if (!Array.isArray(tables) || !tables.length || new Set(tables).size !== tables.length)
+        fail("invalid_input");
+    for (const table of tables)
+        if (!TABLES.includes(table))
+            fail("unsupported_table");
+    return TABLES.filter(table => tables.includes(table));
+}
+function validatePacket(packet) {
+    if (!packet || packet.format !== "openlup.compatible-rows.v1" || !identity(packet.sourceId) || !identity(packet.catalogueId)
+        || !Array.isArray(packet.tables) || !/^[a-f0-9]{64}$/.test(packet.sha256))
+        fail("invalid_input");
+    const { sha256: _hash, ...payload } = packet;
+    if (digest(payload) !== packet.sha256)
+        fail("invalid_input");
+    const names = tableNames(packet.tables.map(table => table.table));
+    if (names.some((name, index) => name !== packet.tables[index]?.table))
+        fail("invalid_input");
+    let count = 0, bytes = 0;
+    for (const table of packet.tables) {
+        if (!Array.isArray(table.columns) || !table.columns.length || !table.columns.some(column => column.key)
+            || table.columns.some(column => !identifier(column.name) || !identity(column.type) || typeof column.key !== "boolean")
+            || new Set(table.columns.map(column => column.name)).size !== table.columns.length || !Array.isArray(table.rows))
+            fail("invalid_input");
+        for (const row of table.rows) {
+            if (typeof row !== "string")
+                fail("invalid_input");
+            // Inspect only field names. Never stringify parsed values back to SQL.
+            const parsed = JSON.parse(row);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+                || Object.keys(parsed).sort().join("\0") !== table.columns.map(column => column.name).sort().join("\0"))
+                fail("invalid_input");
+            count++;
+            bytes += Buffer.byteLength(row);
+        }
+    }
+    if (count > LIMIT_ROWS || bytes > LIMIT_BYTES)
+        fail("limit_exceeded");
+}
+function digest(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function identifier(value) { return /^[a-z][a-z0-9_]{0,62}$/.test(value); }
+function quoted(value) { if (!identifier(value))
+    fail("invalid_input"); return `"${value}"`; }
+function identity(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 1024
+        && !Array.from(value).some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+}
+function ceiling(value, maximum) { return Number.isSafeInteger(value) && value > 0 && value <= maximum; }
+function fail(code, table) { throw new PostgresTransferError(code, table); }
+function redacted(error) { return error instanceof PostgresTransferError ? error : new PostgresTransferError("database_unavailable"); }