@raybase/core 0.0.2 → 0.3.4

package/dist/backup-archive.js

@@ -0,0 +1,2068 @@
+import { sha256Hex } from "./audit-archive.js";
+import { audit, parseStoredAppRoles, raybaseAuthExecutor } from "./auth.js";
+import { assertRaybasePasswordSecretParticipantsReady, createRaybasePasswordWrapParticipants, listRaybasePasswordSecretReadiness, raybasePasswordSecretPurpose } from "./auth-password-secret.js";
+import { createDeploymentBackupKeyProvider, backupProviderLimits, generateBackupDek, RaybaseBackupError, unwrapBackupDek, wrapBackupDek } from "./backup-crypto.js";
+import { BackupLogicalDecoder, backupArchiveMagic, backupBinaryContentType, backupFrameHeaderBytes, backupFrameTagBytes, backupFormatLimits, canonicalBackupJson, createBackupArchiveDecryptor, createBackupArchiveEncryptor, createBackupSha256Digest, decodeBackupArchiveHeader, encodeBackupArchiveHeader, encodeBackupLogicalRecord } from "./backup-format.js";
+import { backupDatabaseProtocolLimits, dataStub, retryConsistentBackupSnapshot } from "./db.js";
+import { pitrUnavailableReason, recoverInterruptedBackupRestore } from "./pitr.js";
+export const backupSqlContentType = "application/sql; charset=utf-8";
+export const backupRootManifestKey = "backups/manifest.json";
+export const coreBackupManifestKey = "backups/core/manifest.json";
+export const coreBackupPrefix = "backups/core/";
+export const backupTemporaryPrefix = "backups/.temporary/";
+export const backupTemporaryRetentionMs = 24 * 60 * 60 * 1000;
+export const backupLegacyUploadMaximumBytes = 16 * 1024 * 1024;
+export const backupMultipartMinimumPartBytes = 5 * 1024 * 1024;
+export const backupMultipartDefaultPartBytes = 8 * 1024 * 1024;
+export const backupMultipartMaximumParts = 10_000;
+export const backupMultipartMaximumPartBytes = 5 * 1024 * 1024 * 1024;
+export const backupMultipartMaximumBufferedPartBytes = 64 * 1024 * 1024;
+export const backupMultipartMaximumObjectBytes = 5 * 1024 * 1024 * 1024 * 1024;
+export const backupArchiveDiscoveryMaximumObjects = 10_000;
+const defaultRetention = 30;
+const backupArchiveDiscoveryMaximumWarnings = 20;
+const backupArchiveDataFrameKind = 1;
+const backupArchiveFinalFrameKind = 2;
+const backupArchiveFinalFrameMaximumBytes = 4096;
+function normalizedFlag(value) {
+    const trimmed = value?.trim().toLowerCase();
+    return trimmed ? trimmed : null;
+}
+export function backupsEnabled(env) {
+    const value = normalizedFlag(env.RAYBASE_BACKUPS_ENABLED);
+    if (value && ["false", "0", "no", "off"].includes(value))
+        return false;
+    if (value)
+        return ["true", "1", "yes", "on"].includes(value);
+    return Boolean(env.RAYBASE_BACKUPS);
+}
+export function parseBackupRetention(value) {
+    if (value === undefined || value.trim() === "")
+        return defaultRetention;
+    const retention = Number(value);
+    if (!Number.isInteger(retention) || retention < 1) {
+        throw new Error("RAYBASE_BACKUPS_RETAIN must be a positive integer");
+    }
+    return retention;
+}
+function backupBytesToHex(value) {
+    return Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function retainedDeploymentSecrets(value) {
+    return (value ?? "")
+        .split(/[\s,]+/)
+        .map((secret) => secret.trim())
+        .filter(Boolean);
+}
+async function backupProviderSet(env, backups) {
+    const currentSecret = env.RAYBASE_BACKUPS_KEY?.trim();
+    const deploymentProvider = currentSecret
+        ? await createDeploymentBackupKeyProvider({
+            currentSecret,
+            retainedSecrets: retainedDeploymentSecrets(env.RAYBASE_BACKUPS_KEY_RETAINED)
+        })
+        : undefined;
+    return {
+        ...(backups?.keyProvider ? { keyProvider: backups.keyProvider } : {}),
+        ...(deploymentProvider ? { deploymentProvider } : {})
+    };
+}
+function selectedBackupProvider(providers) {
+    return providers.keyProvider ?? providers.deploymentProvider;
+}
+function backupReadinessContext(environment) {
+    return {
+        archiveId: crypto.randomUUID(),
+        product: "core",
+        target: "core",
+        targetId: "core",
+        createdAt: new Date().toISOString(),
+        purpose: "readiness",
+        signal: new AbortController().signal,
+        ...(environment ? { environment } : {})
+    };
+}
+async function probeBackupProviderForCreation(env, providers, context) {
+    const dek = generateBackupDek();
+    const selected = selectedBackupProvider(providers);
+    const wrapParticipants = selected
+        ? await resolvePasswordParticipantsForWrap(env, selected, context)
+        : { participants: Object.freeze([]), release() { } };
+    try {
+        return await wrapBackupDek({ providers, context, dek, participants: wrapParticipants.participants });
+    }
+    finally {
+        wrapParticipants.release();
+        dek.fill(0);
+    }
+}
+const participantDirectoryStringPattern = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+function validatedDirectoryStrings(value, label, allowNull = false) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 32) {
+        throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", `${label} must contain at most 32 values`);
+    }
+    const values = value.map((item) => {
+        if (allowNull && item === null)
+            return null;
+        if (typeof item !== "string" ||
+            !participantDirectoryStringPattern.test(item) ||
+            new TextEncoder().encode(item).byteLength > backupProviderLimits.identifierBytes) {
+            throw new RaybaseBackupError("BACKUP_PROVIDER_ENVELOPE_INVALID", `${label} contains an invalid value`);
+        }
+        return item;
+    });
+    if (new Set(values).size !== values.length) {
+        throw new RaybaseBackupError("BACKUP_PROVIDER_ENVELOPE_INVALID", `${label} contains duplicate values`);
+    }
+    return values;
+}
+function createPasswordParticipantDirectory(env, provider) {
+    const lifecycle = provider.passwordSecrets;
+    if (!lifecycle) {
+        throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "The backup provider has no password lifecycle");
+    }
+    const purpose = `${raybasePasswordSecretPurpose}:${provider.id}`;
+    const lifecycleVersion = lifecycle.version.trim();
+    return Object.freeze({
+        async find(request = {}) {
+            const limit = request.limit ?? 50;
+            if (!Number.isInteger(limit) || limit < 1 || limit > backupProviderLimits.participantDirectoryPageRecords) {
+                throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", `Backup participant directory pages support 1-${backupProviderLimits.participantDirectoryPageRecords} records`);
+            }
+            const afterUserId = request.afterUserId?.trim();
+            if (request.afterUserId !== undefined &&
+                (!afterUserId || new TextEncoder().encode(afterUserId).byteLength > 256)) {
+                throw new RaybaseBackupError("BACKUP_PROVIDER_ENVELOPE_INVALID", "Backup participant directory cursor is invalid");
+            }
+            const filter = request.filter ?? {};
+            const allRoles = validatedDirectoryStrings(filter.appRoles?.all, "Backup participant all-role filter");
+            const anyRoles = validatedDirectoryStrings(filter.appRoles?.any, "Backup participant any-role filter");
+            const noRoles = validatedDirectoryStrings(filter.appRoles?.none, "Backup participant excluded-role filter");
+            const operatorRoles = validatedDirectoryStrings(filter.operatorRoles, "Backup participant operator-role filter", true);
+            const lifecycleEligibility = filter.lifecycleEligibility === undefined
+                ? []
+                : [...filter.lifecycleEligibility];
+            if (lifecycleEligibility.length > 2 ||
+                new Set(lifecycleEligibility).size !== lifecycleEligibility.length ||
+                lifecycleEligibility.some((value) => value !== "ready" && value !== "not-ready")) {
+                throw new RaybaseBackupError("BACKUP_PROVIDER_ENVELOPE_INVALID", "Backup participant lifecycle filter is invalid");
+            }
+            const where = [`COALESCE("banned", 0) = 0`];
+            const parameters = [provider.id, lifecycleVersion, purpose];
+            if (afterUserId) {
+                where.push(`"userId" > ?`);
+                parameters.push(afterUserId);
+            }
+            for (const role of allRoles) {
+                if (role === "user")
+                    continue;
+                where.push(`EXISTS (SELECT 1 FROM json_each(COALESCE("appRoles", '["user"]')) WHERE value = ?)`);
+                parameters.push(role);
+            }
+            if (anyRoles.length && !anyRoles.includes("user")) {
+                where.push(`EXISTS (SELECT 1 FROM json_each(COALESCE("appRoles", '["user"]')) WHERE value IN (${anyRoles.map(() => "?").join(", ")}))`);
+                parameters.push(...anyRoles);
+            }
+            for (const role of noRoles) {
+                if (role === "user") {
+                    where.push("0 = 1");
+                    continue;
+                }
+                where.push(`NOT EXISTS (SELECT 1 FROM json_each(COALESCE("appRoles", '["user"]')) WHERE value = ?)`);
+                parameters.push(role);
+            }
+            if (operatorRoles.length) {
+                const nonNull = operatorRoles.filter((value) => value !== null);
+                const choices = [];
+                if (nonNull.length) {
+                    choices.push(`"operatorRole" IN (${nonNull.map(() => "?").join(", ")})`);
+                    parameters.push(...nonNull);
+                }
+                if (operatorRoles.includes(null))
+                    choices.push(`"operatorRole" IS NULL`);
+                where.push(`(${choices.join(" OR ")})`);
+            }
+            if (lifecycleEligibility.length) {
+                where.push(`"lifecycleEligibility" IN (${lifecycleEligibility.map(() => "?").join(", ")})`);
+                parameters.push(...lifecycleEligibility);
+            }
+            parameters.push(limit);
+            const rows = await raybaseAuthExecutor(env).all(`WITH "participantDirectory" AS (
+           SELECT u."id" AS "userId", u."appRoles",
+             CASE WHEN u."operatorRole" IS NULL OR u."operatorRole" IN ('', 'none')
+               THEN NULL ELSE u."operatorRole" END AS "operatorRole",
+             u."banned",
+             CASE WHEN s."providerId" = ? AND s."providerVersion" = ?
+                    AND s."lastFailureCode" IS NULL
+                    AND s."readiness" IN ('ready', 'reset-destructive')
+               THEN 'ready' ELSE 'not-ready' END AS "lifecycleEligibility"
+           FROM "_auth_users" u
+           LEFT JOIN "_auth_password_secret_state" s
+             ON s."userId" = u."id" AND s."purpose" = ?
+           -- Host users (RaybaseHostAuth) have no password and hold no roles.
+           WHERE u."id" NOT LIKE 'hostuser\\_%' ESCAPE '\\'
+         )
+         SELECT "userId", "appRoles", "operatorRole", "lifecycleEligibility"
+         FROM "participantDirectory"
+         WHERE ${where.join(" AND ")}
+         ORDER BY "userId" ASC
+         LIMIT ?`, parameters);
+            return Object.freeze(rows.map((row) => Object.freeze({
+                userId: row.userId,
+                appRoles: Object.freeze(parseStoredAppRoles(row.appRoles)),
+                operatorRole: row.operatorRole,
+                lifecycleEligibility: row.lifecycleEligibility
+            })));
+        }
+    });
+}
+async function requiredPasswordParticipantUserIds(env, provider, context) {
+    const lifecycle = provider.passwordSecrets;
+    if (!lifecycle)
+        return null;
+    if (lifecycle.resolveRequiredParticipants && lifecycle.requiredParticipantUserIds) {
+        throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "The password-coupled backup provider declares conflicting participant resolvers");
+    }
+    if (!lifecycle.resolveRequiredParticipants && !lifecycle.requiredParticipantUserIds) {
+        throw new RaybaseBackupError("BACKUP_THRESHOLD_UNMET", "The password-coupled backup provider does not declare its required participants");
+    }
+    let raw;
+    try {
+        raw = lifecycle.resolveRequiredParticipants
+            ? await lifecycle.resolveRequiredParticipants(Object.freeze({
+                context,
+                directory: createPasswordParticipantDirectory(env, provider)
+            }))
+            : await lifecycle.requiredParticipantUserIds(context);
+    }
+    catch {
+        throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "The backup key provider could not resolve required password-secret participants");
+    }
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > backupProviderLimits.wrappedKeyRecords) {
+        throw new RaybaseBackupError("BACKUP_THRESHOLD_UNMET", `Password-coupled backup providers must declare 1-${backupProviderLimits.wrappedKeyRecords} participants`);
+    }
+    const ids = raw.map((value) => typeof value === "string" ? value.trim() : "");
+    if (ids.some((value) => !value || new TextEncoder().encode(value).byteLength > 256) || new Set(ids).size !== ids.length) {
+        throw new RaybaseBackupError("BACKUP_THRESHOLD_UNMET", "The password-coupled backup provider returned invalid or duplicate participant ids");
+    }
+    return ids;
+}
+async function resolvePasswordParticipantsForWrap(env, provider, context) {
+    if (!provider.passwordSecrets)
+        return { participants: Object.freeze([]), release() { } };
+    const ids = await requiredPasswordParticipantUserIds(env, provider, context);
+    if (!ids)
+        return { participants: Object.freeze([]), release() { } };
+    if (provider.mode !== "wrapping") {
+        await assertRaybasePasswordSecretParticipantsReady(raybaseAuthExecutor(env), { providerId: provider.id, lifecycle: provider.passwordSecrets }, ids);
+        return { participants: Object.freeze([]), release() { } };
+    }
+    return createRaybasePasswordWrapParticipants(raybaseAuthExecutor(env), { providerId: provider.id, lifecycle: provider.passwordSecrets }, ids);
+}
+async function passwordParticipantReadiness(env, provider, context, assertReady) {
+    if (!provider.passwordSecrets)
+        return undefined;
+    let ids;
+    try {
+        ids = (await requiredPasswordParticipantUserIds(env, provider, context)) ?? [];
+    }
+    catch (error) {
+        if (assertReady)
+            throw error;
+        return {
+            declared: false,
+            readyForNewBackups: false,
+            required: null,
+            ready: null,
+            statuses: {},
+            reason: error instanceof RaybaseBackupError
+                ? error.message
+                : "Password-secret participant readiness could not be determined."
+        };
+    }
+    const registration = { providerId: provider.id, lifecycle: provider.passwordSecrets };
+    let readiness;
+    try {
+        readiness = assertReady
+            ? await assertRaybasePasswordSecretParticipantsReady(raybaseAuthExecutor(env), registration, ids)
+            : await listRaybasePasswordSecretReadiness(raybaseAuthExecutor(env), registration, ids);
+    }
+    catch (error) {
+        if (assertReady) {
+            if (error instanceof RaybaseBackupError)
+                throw error;
+            throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "Password-secret participant readiness could not be determined");
+        }
+        return {
+            declared: true,
+            readyForNewBackups: false,
+            required: ids.length,
+            ready: null,
+            statuses: {},
+            reason: "Password-secret participant readiness could not be determined."
+        };
+    }
+    const byUser = new Map(readiness.map((item) => [item.userId, item]));
+    const statuses = {};
+    let ready = 0;
+    for (const id of ids) {
+        const item = byUser.get(id);
+        const status = item?.status ?? "missing";
+        statuses[status] = (statuses[status] ?? 0) + 1;
+        if (item?.readyForNewBackups)
+            ready += 1;
+    }
+    return {
+        declared: true,
+        readyForNewBackups: ready === ids.length,
+        required: ids.length,
+        ready,
+        statuses,
+        ...(ready === ids.length
+            ? {}
+            : { reason: `Password-secret participants are not ready (${ids.length - ready} unavailable).` })
+    };
+}
+export async function readCoreBackupRestoreRuntimeStatus(env) {
+    const unavailable = pitrUnavailableReason(env);
+    const maintenance = env.RAYBASE_DATA ? await dataStub(env).backupRestoreStatus() : null;
+    return {
+        pitrAvailable: unavailable === null,
+        ...(unavailable ? { pitrUnavailableReason: unavailable } : {}),
+        maintenance
+    };
+}
+export async function prepareCoreBackupRestore(env, options) {
+    const runtime = await readCoreBackupRestoreRuntimeStatus(env);
+    if (runtime.maintenance?.active) {
+        if (!runtime.pitrAvailable) {
+            throw new RaybaseBackupError("BACKUP_RESTORE_MAINTENANCE_REQUIRED", `Interrupted restore maintenance requires production PITR recovery. ${runtime.pitrUnavailableReason ?? "PITR is unavailable."}`);
+        }
+        const recovered = await recoverInterruptedBackupRestore({ stub: dataStub(env) });
+        if (recovered.recoveryRequested) {
+            throw new RaybaseBackupError("BACKUP_RESTORE_MAINTENANCE_REQUIRED", "Interrupted restore rollback was requested. Retry after the database Durable Object restarts.");
+        }
+    }
+    if (options.requirePitr && !runtime.pitrAvailable) {
+        throw new RaybaseBackupError("BACKUP_RESTORE_MAINTENANCE_REQUIRED", `Encrypted restore requires production PITR recovery support. ${runtime.pitrUnavailableReason ?? "PITR is unavailable."}`);
+    }
+}
+/**
+ * Consume exact encrypted archive bytes into legal R2 multipart parts while
+ * independently hashing the bytes submitted to the upload session. All
+ * non-final parts meet R2's 5 MiB floor and uploads are deliberately
+ * sequential, bounding retained memory to one configured part plus one input
+ * chunk owned by the upstream stream.
+ */
+export async function uploadBackupMultipartStream(upload, stream, options = {}) {
+    const partBytes = options.partBytes ?? backupMultipartDefaultPartBytes;
+    const maximumParts = options.maximumParts ?? backupMultipartMaximumParts;
+    const abortUpload = async () => {
+        try {
+            await upload.abort();
+        }
+        catch {
+            // Preserve the primary configuration, stream, or upload failure.
+        }
+    };
+    try {
+        if (!Number.isSafeInteger(partBytes) ||
+            partBytes < backupMultipartMinimumPartBytes ||
+            partBytes > backupMultipartMaximumPartBytes) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", `R2 multipart parts must contain ${backupMultipartMinimumPartBytes}-${backupMultipartMaximumPartBytes} bytes`);
+        }
+        if (partBytes > backupMultipartMaximumBufferedPartBytes) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", `Core bounds in-memory backup parts to ${backupMultipartMaximumBufferedPartBytes} bytes`);
+        }
+        if (!Number.isInteger(maximumParts) ||
+            maximumParts < 1 ||
+            maximumParts > backupMultipartMaximumParts) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", `Backup multipart uploads support 1-${backupMultipartMaximumParts} parts`);
+        }
+    }
+    catch (error) {
+        await abortUpload();
+        throw error;
+    }
+    let digest;
+    let reader;
+    try {
+        digest = (options.digestFactory ?? createBackupSha256Digest)();
+        reader = stream.getReader();
+    }
+    catch (error) {
+        await abortUpload();
+        throw error;
+    }
+    const uploadedParts = [];
+    let pending;
+    try {
+        pending = new Uint8Array(partBytes);
+    }
+    catch (error) {
+        reader.releaseLock();
+        await digest.abort(error);
+        await abortUpload();
+        throw error;
+    }
+    let pendingLength = 0;
+    let bytes = 0;
+    let completed = false;
+    const uploadPart = async (part) => {
+        if (uploadedParts.length >= maximumParts) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup exceeds the R2 multipart part-count limit");
+        }
+        if (!Number.isSafeInteger(bytes + part.byteLength)) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup exceeds the safe byte-count limit");
+        }
+        if (bytes + part.byteLength > backupMultipartMaximumObjectBytes) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup exceeds the R2 object-size limit");
+        }
+        await digest.write(part);
+        const partNumber = uploadedParts.length + 1;
+        const uploaded = await upload.uploadPart(partNumber, part);
+        if (!uploaded ||
+            uploaded.partNumber !== partNumber ||
+            typeof uploaded.etag !== "string" ||
+            uploaded.etag.length === 0) {
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "R2 returned invalid multipart upload evidence");
+        }
+        uploadedParts.push({ partNumber, etag: uploaded.etag });
+        bytes += part.byteLength;
+    };
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            const chunk = result.value;
+            if (!(chunk instanceof Uint8Array)) {
+                throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup upload stream must emit Uint8Array chunks");
+            }
+            let offset = 0;
+            while (offset < chunk.byteLength) {
+                const take = Math.min(partBytes - pendingLength, chunk.byteLength - offset);
+                pending.set(chunk.subarray(offset, offset + take), pendingLength);
+                pendingLength += take;
+                offset += take;
+                if (pendingLength === partBytes) {
+                    const part = pending;
+                    try {
+                        await uploadPart(part);
+                    }
+                    finally {
+                        part.fill(0);
+                    }
+                    pending = new Uint8Array(partBytes);
+                    pendingLength = 0;
+                }
+            }
+        }
+        if (pendingLength > 0) {
+            const part = pending.slice(0, pendingLength);
+            pending.fill(0);
+            try {
+                await uploadPart(part);
+            }
+            finally {
+                part.fill(0);
+            }
+            pendingLength = 0;
+        }
+        if (uploadedParts.length === 0) {
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Encrypted backup archive emitted no bytes");
+        }
+        const sha256Bytes = await digest.finish();
+        const sha256 = backupBytesToHex(sha256Bytes);
+        sha256Bytes.fill(0);
+        const object = await upload.complete(uploadedParts);
+        completed = true;
+        return {
+            object,
+            uploadedParts,
+            partCount: uploadedParts.length,
+            bytes,
+            sha256
+        };
+    }
+    catch (error) {
+        pending.fill(0);
+        pendingLength = 0;
+        try {
+            await reader.cancel(error);
+        }
+        catch {
+            // Preserve the primary upload/encryption failure.
+        }
+        await digest.abort(error);
+        await abortUpload();
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+        pending.fill(0);
+        if (!completed)
+            pendingLength = 0;
+    }
+}
+export async function uploadBackupArchiveMultipart(bucket, key, stream, options = {}) {
+    const upload = await bucket.createMultipartUpload(key, options.r2);
+    return uploadBackupMultipartStream(upload, stream, options);
+}
+export function backupTimestamp(date = new Date()) {
+    return `${date.toISOString().slice(0, 19).replace(/:/g, "-")}Z`;
+}
+export function backupMetadataComment(metadata) {
+    return `-- raybase-backup: ${JSON.stringify(metadata)}`;
+}
+export function prependBackupMetadata(sql, metadata) {
+    return `${backupMetadataComment(metadata)}\n${sql}`;
+}
+export function parseBackupMetadata(sql) {
+    const firstLine = sql.split(/\r?\n/, 1)[0]?.trim() ?? "";
+    const match = firstLine.match(/^--\s*raybase-backup:\s*(\{.*\})$/);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[1]);
+        if (parsed.format !== 1)
+            return null;
+        if (parsed.product !== "core" && parsed.product !== "pro")
+            return null;
+        if (parsed.target !== "core" && parsed.target !== "control-plane" && parsed.target !== "app-data")
+            return null;
+        if (typeof parsed.createdAt !== "string" || !parsed.createdAt)
+            return null;
+        return {
+            format: 1,
+            product: parsed.product,
+            target: parsed.target,
+            createdAt: parsed.createdAt,
+            ...(typeof parsed.organizationId === "string" ? { organizationId: parsed.organizationId } : {})
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function validateCoreBackupSql(sql) {
+    const metadata = parseBackupMetadata(sql);
+    if (!metadata)
+        return;
+    if (metadata.product !== "core" || metadata.target !== "core") {
+        throw new Error(`Backup SQL targets ${metadata.product}/${metadata.target}; expected core/core`);
+    }
+}
+export function validateCoreBackupKey(key) {
+    const normalized = key.trim();
+    if (!normalized.startsWith(coreBackupPrefix) ||
+        (!normalized.endsWith(".sql") && !normalized.endsWith(".rbb")) ||
+        normalized.includes("..")) {
+        throw new Error("Backup key is outside the Core backup prefix");
+    }
+    return normalized;
+}
+function manifestObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function normalizeManifestCommon(value) {
+    const entry = manifestObject(value);
+    if (!entry)
+        return null;
+    if (typeof entry.key !== "string" ||
+        !entry.key ||
+        entry.key.includes("..") ||
+        typeof entry.date !== "string" ||
+        !Number.isFinite(Date.parse(entry.date)) ||
+        typeof entry.sha256 !== "string" ||
+        !/^[a-f0-9]{64}$/.test(entry.sha256) ||
+        typeof entry.bytes !== "number" ||
+        !Number.isSafeInteger(entry.bytes) ||
+        entry.bytes <= 0 ||
+        (entry.target !== "core" && entry.target !== "control-plane" && entry.target !== "app-data") ||
+        (entry.product !== "core" && entry.product !== "pro") ||
+        (entry.trigger !== "scheduled" && entry.trigger !== "manual")) {
+        return null;
+    }
+    return {
+        key: entry.key,
+        date: entry.date,
+        sha256: entry.sha256,
+        bytes: entry.bytes,
+        target: entry.target,
+        product: entry.product,
+        ...(typeof entry.organizationId === "string" ? { organizationId: entry.organizationId } : {}),
+        ...(typeof entry.organizationSlug === "string" ? { organizationSlug: entry.organizationSlug } : {}),
+        ...(typeof entry.actorId === "string" || entry.actorId === null ? { actorId: entry.actorId } : {}),
+        trigger: entry.trigger
+    };
+}
+/**
+ * Normalize both historical version-1 entries and version-2 entries into the
+ * discriminated archive model. Version-1 data gains only explicit routing
+ * facts (`archiveFormat`, `encrypted`, and `contentType`), never invented key
+ * or encryption metadata.
+ */
+export function normalizeBackupManifestEntry(value) {
+    const common = normalizeManifestCommon(value);
+    const entry = manifestObject(value);
+    if (!common || !entry)
+        return null;
+    if (entry.archiveFormat === 2 || entry.encrypted === true) {
+        if (entry.archiveFormat !== 2 ||
+            entry.encrypted !== true ||
+            entry.contentType !== backupBinaryContentType ||
+            typeof entry.archiveId !== "string" ||
+            typeof entry.targetId !== "string" ||
+            typeof entry.providerId !== "string" ||
+            typeof entry.kekKeyId !== "string") {
+            return null;
+        }
+        try {
+            const header = decodeBackupArchiveHeader(encodeBackupArchiveHeader({
+                format: 2,
+                archiveId: entry.archiveId,
+                product: common.product,
+                target: common.target,
+                targetId: entry.targetId,
+                createdAt: common.date,
+                logical: entry.logical,
+                encryption: entry.encryption,
+                keyEnvelope: entry.keyEnvelope
+            })).header;
+            if (header.keyEnvelope.providerId !== entry.providerId ||
+                header.keyEnvelope.kekKeyId !== entry.kekKeyId) {
+                return null;
+            }
+            return {
+                ...common,
+                archiveFormat: 2,
+                archiveId: entry.archiveId,
+                targetId: entry.targetId,
+                encrypted: true,
+                contentType: backupBinaryContentType,
+                encryption: header.encryption,
+                logical: header.logical,
+                providerId: entry.providerId,
+                kekKeyId: entry.kekKeyId,
+                keyEnvelope: header.keyEnvelope
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    if ((entry.archiveFormat !== undefined && entry.archiveFormat !== 1) ||
+        (entry.encrypted !== undefined && entry.encrypted !== false) ||
+        (entry.contentType !== undefined && entry.contentType !== backupSqlContentType)) {
+        return null;
+    }
+    return {
+        ...common,
+        archiveFormat: 1,
+        encrypted: false,
+        contentType: backupSqlContentType
+    };
+}
+function equalBytes(left, right) {
+    return left.byteLength === right.byteLength && left.every((value, index) => value === right[index]);
+}
+export function assertBackupManifestIdentity(entry, header) {
+    if (entry.archiveId !== header.archiveId ||
+        entry.product !== header.product ||
+        entry.target !== header.target ||
+        entry.targetId !== header.targetId ||
+        entry.date !== header.createdAt ||
+        entry.providerId !== header.keyEnvelope.providerId ||
+        entry.kekKeyId !== header.keyEnvelope.kekKeyId ||
+        !equalBytes(canonicalBackupJson({
+            encryption: entry.encryption,
+            logical: entry.logical,
+            keyEnvelope: entry.keyEnvelope
+        }), canonicalBackupJson({
+            encryption: header.encryption,
+            logical: header.logical,
+            keyEnvelope: header.keyEnvelope
+        }))) {
+        throw new RaybaseBackupError("BACKUP_ARCHIVE_IDENTITY_MISMATCH", "Backup archive header does not match its manifest entry");
+    }
+}
+async function readJsonObject(bucket, key) {
+    const object = await bucket.get(key);
+    if (!object)
+        return { value: null, found: false };
+    try {
+        return { value: (await object.json()), found: true };
+    }
+    catch (error) {
+        return {
+            value: null,
+            found: true,
+            warning: `Could not parse ${key}: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
+async function writeJsonObject(bucket, key, value) {
+    await bucket.put(key, `${JSON.stringify(value, null, 2)}\n`, {
+        httpMetadata: { contentType: "application/json; charset=utf-8" }
+    });
+}
+function emptyTargetManifest(descriptor, updatedAt) {
+    return {
+        version: 2,
+        updatedAt,
+        product: descriptor.product,
+        target: descriptor.target,
+        ...(descriptor.organizationId ? { organizationId: descriptor.organizationId } : {}),
+        ...(descriptor.organizationSlug ? { organizationSlug: descriptor.organizationSlug } : {}),
+        sourceOfTruth: "archive-objects",
+        entries: []
+    };
+}
+async function readTargetManifest(bucket, descriptor, now) {
+    const read = await readJsonObject(bucket, descriptor.manifestKey);
+    if (!read.value) {
+        return {
+            manifest: emptyTargetManifest(descriptor, now),
+            needsRepair: true,
+            ...(read.warning ? { warning: read.warning } : {})
+        };
+    }
+    const manifest = manifestObject(read.value);
+    const rawEntries = Array.isArray(manifest?.entries) ? manifest.entries : [];
+    const entries = rawEntries
+        .map(normalizeBackupManifestEntry)
+        .filter((entry) => Boolean(entry));
+    const structurallyValid = Boolean(manifest &&
+        (manifest.version === 1 || manifest.version === 2) &&
+        manifest.product === descriptor.product &&
+        manifest.target === descriptor.target &&
+        (manifest.organizationId ?? "") === (descriptor.organizationId ?? "") &&
+        Array.isArray(manifest.entries));
+    const invalidEntries = rawEntries.length - entries.length;
+    const warning = [
+        read.warning,
+        !structurallyValid ? `${descriptor.manifestKey} has invalid target-manifest metadata.` : undefined,
+        invalidEntries > 0 ? `${descriptor.manifestKey} contains ${invalidEntries} invalid ${invalidEntries === 1 ? "entry" : "entries"}.` : undefined
+    ].filter(Boolean).join(" ") || undefined;
+    return {
+        manifest: {
+            version: 2,
+            updatedAt: typeof manifest?.updatedAt === "string" && Number.isFinite(Date.parse(manifest.updatedAt)) ? manifest.updatedAt : now,
+            product: descriptor.product,
+            target: descriptor.target,
+            ...(descriptor.organizationId ? { organizationId: descriptor.organizationId } : {}),
+            ...(descriptor.organizationSlug ? { organizationSlug: descriptor.organizationSlug } : {}),
+            sourceOfTruth: "archive-objects",
+            entries
+        },
+        needsRepair: !read.found || !structurallyValid || invalidEntries > 0 || manifest?.version !== 2 || manifest?.sourceOfTruth !== "archive-objects",
+        ...(warning ? { warning } : {})
+    };
+}
+function emptyRootManifest(updatedAt) {
+    return { version: 2, updatedAt, sourceOfTruth: "archive-objects", lastSuccessfulFullRunAt: null, partialRun: null, targets: [] };
+}
+function normalizeRootTarget(value) {
+    const target = manifestObject(value);
+    if (!target)
+        return null;
+    if ((target.product !== "core" && target.product !== "pro") ||
+        (target.target !== "core" && target.target !== "control-plane" && target.target !== "app-data") ||
+        typeof target.manifestKey !== "string" ||
+        !target.manifestKey.startsWith("backups/") ||
+        !target.manifestKey.endsWith("/manifest.json") ||
+        target.manifestKey.includes("..") ||
+        (target.latestBackupAt !== undefined && target.latestBackupAt !== null &&
+            (typeof target.latestBackupAt !== "string" || !Number.isFinite(Date.parse(target.latestBackupAt))))) {
+        return null;
+    }
+    return {
+        product: target.product,
+        target: target.target,
+        ...(typeof target.organizationId === "string" ? { organizationId: target.organizationId } : {}),
+        ...(typeof target.organizationSlug === "string" ? { organizationSlug: target.organizationSlug } : {}),
+        manifestKey: target.manifestKey,
+        ...(target.latestBackupAt === null || typeof target.latestBackupAt === "string"
+            ? { latestBackupAt: target.latestBackupAt }
+            : {})
+    };
+}
+function normalizeRootPartialRun(value) {
+    if (value === null || value === undefined)
+        return null;
+    const partial = manifestObject(value);
+    if (!partial ||
+        typeof partial.runId !== "string" ||
+        typeof partial.startedAt !== "string" ||
+        !Number.isFinite(Date.parse(partial.startedAt)) ||
+        typeof partial.stoppedAt !== "string" ||
+        !Number.isFinite(Date.parse(partial.stoppedAt)) ||
+        !Number.isSafeInteger(partial.completedTargets) ||
+        partial.completedTargets < 0 ||
+        !Number.isSafeInteger(partial.remainingTargets) ||
+        partial.remainingTargets < 0 ||
+        partial.reason !== "wall-clock-budget") {
+        return null;
+    }
+    return {
+        runId: partial.runId,
+        startedAt: partial.startedAt,
+        stoppedAt: partial.stoppedAt,
+        completedTargets: partial.completedTargets,
+        remainingTargets: partial.remainingTargets,
+        reason: "wall-clock-budget"
+    };
+}
+async function readRootManifest(bucket, now) {
+    const read = await readJsonObject(bucket, backupRootManifestKey);
+    if (!read.value) {
+        return {
+            manifest: emptyRootManifest(now),
+            needsRepair: true,
+            ...(read.warning ? { warning: read.warning } : {})
+        };
+    }
+    const manifest = manifestObject(read.value);
+    const rawTargets = Array.isArray(manifest?.targets) ? manifest.targets : [];
+    const targets = rawTargets
+        .map(normalizeRootTarget)
+        .filter((target) => Boolean(target));
+    const partialRun = normalizeRootPartialRun(manifest?.partialRun);
+    const structurallyValid = Boolean(manifest &&
+        manifest.version === 2 &&
+        manifest.sourceOfTruth === "archive-objects" &&
+        Array.isArray(manifest.targets) &&
+        (manifest.partialRun === null || manifest.partialRun === undefined || partialRun));
+    const invalidTargets = rawTargets.length - targets.length;
+    const warning = [
+        read.warning,
+        !structurallyValid ? `${backupRootManifestKey} has invalid root-manifest metadata.` : undefined,
+        invalidTargets > 0 ? `${backupRootManifestKey} contains ${invalidTargets} invalid target ${invalidTargets === 1 ? "entry" : "entries"}.` : undefined
+    ].filter(Boolean).join(" ") || undefined;
+    return {
+        manifest: {
+            version: 2,
+            updatedAt: typeof manifest?.updatedAt === "string" && Number.isFinite(Date.parse(manifest.updatedAt)) ? manifest.updatedAt : now,
+            sourceOfTruth: "archive-objects",
+            lastSuccessfulFullRunAt: typeof manifest?.lastSuccessfulFullRunAt === "string" && Number.isFinite(Date.parse(manifest.lastSuccessfulFullRunAt))
+                ? manifest.lastSuccessfulFullRunAt
+                : null,
+            partialRun,
+            targets
+        },
+        needsRepair: !read.found || !structurallyValid || invalidTargets > 0,
+        ...(warning ? { warning } : {})
+    };
+}
+function upsertRootTarget(root, descriptor, latestBackupAt) {
+    const targets = root.targets.filter((target) => !(target.product === descriptor.product &&
+        target.target === descriptor.target &&
+        (target.organizationId ?? "") === (descriptor.organizationId ?? "")));
+    targets.push({
+        product: descriptor.product,
+        target: descriptor.target,
+        ...(descriptor.organizationId ? { organizationId: descriptor.organizationId } : {}),
+        ...(descriptor.organizationSlug ? { organizationSlug: descriptor.organizationSlug } : {}),
+        manifestKey: descriptor.manifestKey,
+        latestBackupAt
+    });
+    targets.sort((left, right) => `${left.target}:${left.organizationId ?? ""}`.localeCompare(`${right.target}:${right.organizationId ?? ""}`));
+    return { ...root, targets };
+}
+function verifyBackupObject(entry, object) {
+    if (!object)
+        throw new Error(`Backup R2 object was not found after upload: ${entry.key}`);
+    if (object.httpMetadata?.contentType !== entry.contentType) {
+        throw new Error(`Backup R2 object content type mismatch for ${entry.key}`);
+    }
+    const metadata = object.customMetadata ?? {};
+    const expected = {
+        "raybase-product": entry.product,
+        "raybase-target": entry.target,
+        "raybase-backup-date": entry.date,
+        "raybase-archive-format": String(entry.archiveFormat),
+        "raybase-encrypted": String(entry.encrypted),
+        "raybase-trigger": entry.trigger
+    };
+    if (entry.archiveFormat === 2) {
+        expected["raybase-archive-id"] = entry.archiveId;
+        expected["raybase-provider-id"] = entry.providerId;
+        expected["raybase-kek-key-id"] = entry.kekKeyId;
+    }
+    if (entry.organizationId)
+        expected["raybase-organization-id"] = entry.organizationId;
+    for (const [key, value] of Object.entries(expected)) {
+        if (metadata[key] !== value)
+            throw new Error(`Backup R2 object metadata mismatch for ${key}`);
+    }
+    if (typeof object.size === "number" && object.size !== entry.bytes) {
+        throw new Error(`Backup R2 object size mismatch for ${entry.key}`);
+    }
+}
+function backupObjectMetadata(entry) {
+    return {
+        "raybase-product": entry.product,
+        "raybase-target": entry.target,
+        "raybase-backup-date": entry.date,
+        "raybase-archive-format": String(entry.archiveFormat),
+        "raybase-encrypted": String(entry.encrypted),
+        "raybase-trigger": entry.trigger,
+        ...(entry.archiveFormat === 2
+            ? {
+                "raybase-archive-id": entry.archiveId,
+                "raybase-provider-id": entry.providerId,
+                "raybase-kek-key-id": entry.kekKeyId
+            }
+            : {})
+    };
+}
+function sameBytes(left, right) {
+    return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+function deferredValue() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}
+function snapshotLogicalStream(stub, operationId, consistency) {
+    const totals = deferredValue();
+    // The encryptor subscribes when it emits its terminal frame. A snapshot can
+    // fail earlier, however, so register a rejection observer immediately while
+    // preserving the rejected promise for that later await.
+    void totals.promise.catch(() => undefined);
+    const decoder = new BackupLogicalDecoder();
+    const digest = createBackupSha256Digest();
+    const mode = consistency?.mode === "write-gated" ? "write-gated" : "optimistic";
+    const descriptorPromise = stub.beginBackupSnapshot({ operationId, mode });
+    let descriptor = null;
+    let cursor = null;
+    let buffered = [];
+    let recordCount = 0;
+    let rowCount = 0;
+    let tableCount = 0;
+    let completed = false;
+    const acceptLogicalBytes = async (chunk) => {
+        await digest.write(chunk);
+        for (const record of decoder.push(chunk)) {
+            recordCount += 1;
+            if (record.kind === "row")
+                rowCount += 1;
+            if (record.kind === "table-end")
+                tableCount += 1;
+        }
+    };
+    const cancel = async (reason) => {
+        if (completed)
+            return;
+        completed = true;
+        await digest.abort(reason);
+        await stub.cancelBackupSnapshot({ operationId }).catch(() => undefined);
+        totals.reject(reason);
+    };
+    return {
+        totals: totals.promise,
+        stream: new ReadableStream({
+            async pull(controller) {
+                try {
+                    descriptor ??= await descriptorPromise;
+                    cursor ??= descriptor.cursor;
+                    if (buffered.length > 0) {
+                        controller.enqueue(buffered.shift());
+                        if (completed && buffered.length === 0)
+                            controller.close();
+                        return;
+                    }
+                    if (completed) {
+                        controller.close();
+                        return;
+                    }
+                    if (descriptor.recommendedMode === "small") {
+                        const small = await stub.readBackupSnapshotSmall({
+                            operationId,
+                            epoch: descriptor.epoch,
+                            generation: descriptor.generation,
+                            schemaFingerprint: descriptor.schemaFingerprint,
+                            maxBytes: backupDatabaseProtocolLimits.smallSnapshotLogicalBytes
+                        });
+                        const expectedEnd = await stub.finishBackupSnapshot({
+                            operationId,
+                            epoch: descriptor.epoch,
+                            generation: descriptor.generation,
+                            schemaFingerprint: descriptor.schemaFingerprint,
+                            recordCount: small.recordCount,
+                            rowCount: small.rowCount,
+                            tableCount: small.tableCount,
+                            plaintextSha256: small.plaintextSha256
+                        });
+                        const actualEnd = small.records.at(-1);
+                        if (!actualEnd || !sameBytes(actualEnd, expectedEnd.record)) {
+                            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Small snapshot logical end is inconsistent");
+                        }
+                        for (const record of small.records.slice(0, -1))
+                            await acceptLogicalBytes(record);
+                        const digestBytes = await digest.finish();
+                        const plaintextSha256 = backupBytesToHex(digestBytes);
+                        digestBytes.fill(0);
+                        if (plaintextSha256 !== small.plaintextSha256 ||
+                            recordCount !== small.recordCount ||
+                            rowCount !== small.rowCount ||
+                            tableCount !== small.tableCount) {
+                            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Small snapshot totals are inconsistent");
+                        }
+                        decoder.push(actualEnd);
+                        decoder.finish();
+                        buffered = small.records;
+                        completed = true;
+                        totals.resolve({ recordCount, rowCount, tableCount });
+                        controller.enqueue(buffered.shift());
+                        return;
+                    }
+                    const page = await stub.readBackupSnapshotPage({
+                        operationId,
+                        epoch: descriptor.epoch,
+                        generation: descriptor.generation,
+                        schemaFingerprint: descriptor.schemaFingerprint,
+                        cursor,
+                        maxBytes: backupDatabaseProtocolLimits.defaultPageBytes,
+                        maxRows: backupDatabaseProtocolLimits.defaultPageRows
+                    });
+                    cursor = page.nextCursor;
+                    for (const chunk of page.chunks)
+                        await acceptLogicalBytes(chunk);
+                    buffered = page.chunks;
+                    if (page.done) {
+                        const digestBytes = await digest.finish();
+                        const plaintextSha256 = backupBytesToHex(digestBytes);
+                        digestBytes.fill(0);
+                        const end = await stub.finishBackupSnapshot({
+                            operationId,
+                            epoch: descriptor.epoch,
+                            generation: descriptor.generation,
+                            schemaFingerprint: descriptor.schemaFingerprint,
+                            recordCount,
+                            rowCount,
+                            tableCount,
+                            plaintextSha256
+                        });
+                        decoder.push(end.record);
+                        decoder.finish();
+                        buffered.push(end.record);
+                        completed = true;
+                        totals.resolve({ recordCount, rowCount, tableCount });
+                    }
+                    if (buffered.length > 0)
+                        controller.enqueue(buffered.shift());
+                    if (completed && buffered.length === 0)
+                        controller.close();
+                }
+                catch (error) {
+                    await cancel(error);
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) {
+                await cancel(reason ?? new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Backup snapshot stream was cancelled"));
+            }
+        })
+    };
+}
+function validateCoreArchiveHeader(header) {
+    if (header.product !== "core" || header.target !== "core" || header.targetId !== "core") {
+        throw new RaybaseBackupError("BACKUP_ARCHIVE_IDENTITY_MISMATCH", `Backup targets ${header.product}/${header.target}/${header.targetId}; expected core/core/core`);
+    }
+}
+async function pruneEntries(bucket, entries, retention) {
+    const kept = entries.slice(0, retention);
+    const pruned = entries.slice(retention);
+    for (const entry of pruned) {
+        await bucket.delete(entry.key);
+    }
+    return { kept, pruned };
+}
+export async function pruneTemporaryBackupObjects(bucket, options = {}) {
+    const now = options.now ?? new Date();
+    const retentionMs = options.retentionMs ?? backupTemporaryRetentionMs;
+    if (!Number.isFinite(retentionMs) || retentionMs < 0) {
+        throw new Error("Temporary backup retention must be a non-negative number of milliseconds");
+    }
+    const cutoff = now.getTime() - retentionMs;
+    const deleted = [];
+    let cursor;
+    do {
+        const page = await bucket.list({
+            prefix: backupTemporaryPrefix,
+            ...(cursor ? { cursor } : {})
+        });
+        const expired = page.objects
+            .filter((object) => object.uploaded.getTime() <= cutoff)
+            .map((object) => object.key);
+        if (expired.length) {
+            await bucket.delete(expired);
+            deleted.push(...expired);
+        }
+        cursor = page.truncated ? page.cursor : undefined;
+    } while (cursor);
+    return deleted;
+}
+function coreDescriptor() {
+    return { product: "core", target: "core", manifestKey: coreBackupManifestKey, prefix: coreBackupPrefix };
+}
+function archiveDiscoveryWarning(warnings, warning) {
+    if (warnings.length < backupArchiveDiscoveryMaximumWarnings)
+        warnings.push(warning);
+}
+function targetArchiveObjectKey(descriptor, key) {
+    if (!key.startsWith(descriptor.prefix))
+        return false;
+    const basename = key.slice(descriptor.prefix.length);
+    return Boolean(basename) && !basename.includes("/") && (basename.endsWith(".rbb") || basename.endsWith(".sql"));
+}
+function expectedEncryptedArchiveKey(descriptor, identity) {
+    return `${descriptor.prefix}${backupTimestamp(new Date(identity.createdAt))}-${identity.archiveId}.rbb`;
+}
+function entryMatchesDescriptor(entry, descriptor) {
+    if (entry.product !== descriptor.product ||
+        entry.target !== descriptor.target ||
+        (entry.organizationId ?? "") !== (descriptor.organizationId ?? "") ||
+        !targetArchiveObjectKey(descriptor, entry.key)) {
+        return false;
+    }
+    if (entry.archiveFormat === 1)
+        return entry.key.endsWith(".sql");
+    return entry.targetId === (descriptor.organizationId ?? descriptor.target) &&
+        entry.key === expectedEncryptedArchiveKey(descriptor, { archiveId: entry.archiveId, createdAt: entry.date });
+}
+async function listTargetArchiveObjects(bucket, descriptor) {
+    const objects = [];
+    let cursor;
+    do {
+        const page = await bucket.list({
+            prefix: descriptor.prefix,
+            limit: 1_000,
+            ...(cursor ? { cursor } : {})
+        });
+        if (objects.length + page.objects.length > backupArchiveDiscoveryMaximumObjects) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", `Backup archive discovery exceeds ${backupArchiveDiscoveryMaximumObjects} objects under ${descriptor.prefix}`);
+        }
+        objects.push(...page.objects);
+        if (page.truncated && (!page.cursor || page.cursor === cursor)) {
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup archive discovery returned an invalid cursor");
+        }
+        cursor = page.truncated ? page.cursor : undefined;
+    } while (cursor);
+    return objects.filter((object) => targetArchiveObjectKey(descriptor, object.key));
+}
+function createBackupArchiveStructureValidator() {
+    // Discovery must work even when the historical provider/key is unavailable.
+    // Validate the canonical authenticated-header shape, routing metadata, frame
+    // sequence, terminal frame, and exact ciphertext digest here; restore still
+    // performs cryptographic header/frame authentication before any DB write.
+    let headerBuffer = new Uint8Array(backupArchiveMagic.byteLength + 4);
+    let headerLength = 0;
+    let headerRequired = headerBuffer.byteLength;
+    let header = null;
+    const frameHeader = new Uint8Array(backupFrameHeaderBytes);
+    let frameHeaderLength = 0;
+    let frameRemaining = 0;
+    let frameKind = 0;
+    let sequence = 0;
+    let ended = false;
+    const acceptHeaderBytes = (bytes, offset) => {
+        const take = Math.min(bytes.byteLength - offset, headerRequired - headerLength);
+        headerBuffer.set(bytes.subarray(offset, offset + take), headerLength);
+        headerLength += take;
+        if (headerLength !== headerRequired)
+            return take;
+        if (headerRequired === backupArchiveMagic.byteLength + 4) {
+            for (let index = 0; index < backupArchiveMagic.byteLength; index += 1) {
+                if (headerBuffer[index] !== backupArchiveMagic[index]) {
+                    throw new RaybaseBackupError("BACKUP_ARCHIVE_VERSION_UNSUPPORTED", "Backup archive magic is invalid");
+                }
+            }
+            const bodyLength = new DataView(headerBuffer.buffer, headerBuffer.byteOffset + backupArchiveMagic.byteLength, 4).getUint32(0, false);
+            if (bodyLength > backupFormatLimits.headerBytes) {
+                throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup archive header exceeds its byte limit");
+            }
+            const expanded = new Uint8Array(backupArchiveMagic.byteLength + 4 + bodyLength);
+            expanded.set(headerBuffer);
+            headerBuffer.fill(0);
+            headerBuffer = expanded;
+            headerRequired = expanded.byteLength;
+            if (headerLength !== headerRequired)
+                return take;
+        }
+        const decoded = decodeBackupArchiveHeader(headerBuffer);
+        if (decoded.bytesRead !== headerBuffer.byteLength) {
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup archive header has trailing bytes");
+        }
+        header = decoded.header;
+        headerBuffer.fill(0);
+        return take;
+    };
+    const acceptFrameHeader = () => {
+        if (!header)
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup frame appeared before its header");
+        const view = new DataView(frameHeader.buffer, frameHeader.byteOffset, frameHeader.byteLength);
+        const version = frameHeader[0];
+        const kind = frameHeader[1];
+        const flags = view.getUint16(2, false);
+        const encodedSequence = view.getUint32(4, false);
+        const plaintextBytes = view.getUint32(8, false);
+        if (version !== 1 || (kind !== backupArchiveDataFrameKind && kind !== backupArchiveFinalFrameKind) || flags !== 0) {
+            throw new RaybaseBackupError("BACKUP_FRAME_VERSION_UNSUPPORTED", "Backup frame header is unsupported");
+        }
+        if (encodedSequence !== sequence) {
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup frame sequence is missing, duplicated, or reordered");
+        }
+        if (kind === backupArchiveDataFrameKind && sequence >= 0xffff_ffff) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup frame sequence is exhausted before the final frame");
+        }
+        const maximum = kind === backupArchiveFinalFrameKind
+            ? backupArchiveFinalFrameMaximumBytes
+            : header.encryption.framePlaintextBytes;
+        if (plaintextBytes > maximum) {
+            throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup frame exceeds its plaintext byte limit");
+        }
+        frameKind = kind;
+        frameRemaining = plaintextBytes + backupFrameTagBytes;
+        frameHeader.fill(0);
+        frameHeaderLength = 0;
+    };
+    return {
+        push(bytes) {
+            let offset = 0;
+            while (offset < bytes.byteLength) {
+                if (!header) {
+                    offset += acceptHeaderBytes(bytes, offset);
+                    continue;
+                }
+                if (frameRemaining > 0) {
+                    const take = Math.min(bytes.byteLength - offset, frameRemaining);
+                    offset += take;
+                    frameRemaining -= take;
+                    if (frameRemaining === 0) {
+                        if (frameKind === backupArchiveFinalFrameKind)
+                            ended = true;
+                        sequence += 1;
+                    }
+                    continue;
+                }
+                if (ended) {
+                    throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup archive contains bytes after its final frame");
+                }
+                const take = Math.min(bytes.byteLength - offset, backupFrameHeaderBytes - frameHeaderLength);
+                frameHeader.set(bytes.subarray(offset, offset + take), frameHeaderLength);
+                frameHeaderLength += take;
+                offset += take;
+                if (frameHeaderLength === backupFrameHeaderBytes)
+                    acceptFrameHeader();
+            }
+        },
+        finish() {
+            if (!header)
+                throw new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Backup archive header is truncated");
+            if (frameHeaderLength > 0 || frameRemaining > 0) {
+                throw new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Backup archive frame is truncated");
+            }
+            if (!ended)
+                throw new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Backup archive final frame is missing");
+            return header;
+        }
+    };
+}
+async function reconstructEncryptedBackupEntry(bucket, descriptor, listed, options = {}) {
+    const object = await bucket.get(listed.key);
+    if (!object)
+        throw new Error("Backup object disappeared during manifest reconstruction");
+    if (object.size <= 0 || object.size > backupMultipartMaximumObjectBytes) {
+        throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup object size is outside the supported encrypted archive bounds");
+    }
+    const digest = createBackupSha256Digest();
+    const structure = createBackupArchiveStructureValidator();
+    const reader = object.body.getReader();
+    let bytes = 0;
+    let sha256;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            const chunk = result.value;
+            bytes += chunk.byteLength;
+            if (bytes > backupMultipartMaximumObjectBytes) {
+                throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", "Backup object exceeds the supported encrypted archive size");
+            }
+            await digest.write(chunk);
+            structure.push(chunk);
+        }
+        const digestBytes = await digest.finish();
+        sha256 = backupBytesToHex(digestBytes);
+        digestBytes.fill(0);
+    }
+    catch (error) {
+        await digest.abort(error);
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (bytes !== object.size || bytes !== listed.size) {
+        throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup object size changed during manifest reconstruction");
+    }
+    const header = structure.finish();
+    if (options.expectedIntegrity &&
+        (bytes !== options.expectedIntegrity.bytes || sha256 !== options.expectedIntegrity.sha256)) {
+        throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup object ciphertext integrity contradicts its existing manifest entry");
+    }
+    if (header.product !== descriptor.product ||
+        header.target !== descriptor.target ||
+        header.targetId !== (descriptor.organizationId ?? descriptor.target)) {
+        throw new RaybaseBackupError("BACKUP_ARCHIVE_IDENTITY_MISMATCH", `Backup object targets ${header.product}/${header.target}/${header.targetId}, not this manifest target`);
+    }
+    if (listed.key !== expectedEncryptedArchiveKey(descriptor, header)) {
+        throw new RaybaseBackupError("BACKUP_ARCHIVE_IDENTITY_MISMATCH", "Backup object key does not match its archive header");
+    }
+    const trigger = object.customMetadata?.["raybase-trigger"];
+    if (trigger !== "manual" && trigger !== "scheduled") {
+        throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup object trigger metadata is invalid");
+    }
+    const entry = {
+        key: listed.key,
+        date: header.createdAt,
+        sha256,
+        bytes,
+        product: header.product,
+        target: header.target,
+        ...(descriptor.organizationId ? { organizationId: descriptor.organizationId } : {}),
+        ...(descriptor.organizationSlug ? { organizationSlug: descriptor.organizationSlug } : {}),
+        trigger,
+        archiveFormat: 2,
+        archiveId: header.archiveId,
+        targetId: header.targetId,
+        encrypted: true,
+        contentType: backupBinaryContentType,
+        encryption: header.encryption,
+        logical: header.logical,
+        providerId: header.keyEnvelope.providerId,
+        kekKeyId: header.keyEnvelope.kekKeyId,
+        keyEnvelope: header.keyEnvelope
+    };
+    verifyBackupObject(entry, object);
+    const recordedProviderAvailable = [options.providers?.keyProvider, options.providers?.deploymentProvider]
+        .some((provider) => provider?.id === header.keyEnvelope.providerId);
+    if (recordedProviderAvailable && options.providers) {
+        const authenticationObject = await bucket.get(listed.key);
+        if (!authenticationObject)
+            throw new Error("Backup object disappeared during authenticated manifest reconstruction");
+        const decryptor = createBackupArchiveDecryptor({
+            providers: options.providers,
+            ...(options.environment ? { environment: options.environment } : {}),
+            expectedCiphertextBytes: bytes,
+            expectedCiphertextSha256: sha256,
+            validateHeader(candidate) {
+                if (!sameBytes(encodeBackupArchiveHeader(candidate), encodeBackupArchiveHeader(header))) {
+                    throw new RaybaseBackupError("BACKUP_ARCHIVE_IDENTITY_MISMATCH", "Backup header changed during authenticated manifest reconstruction");
+                }
+            }
+        });
+        const authenticatedReader = authenticationObject.body.pipeThrough(decryptor.transform).getReader();
+        try {
+            while (!(await authenticatedReader.read()).done) {
+                // Authentication is streaming and plaintext is deliberately discarded.
+            }
+            await Promise.all([decryptor.header, decryptor.completion]);
+        }
+        catch (error) {
+            await Promise.allSettled([decryptor.header, decryptor.completion]);
+            if (error instanceof RaybaseBackupError &&
+                (error.code === "BACKUP_PROVIDER_UNAVAILABLE" ||
+                    error.code === "BACKUP_KEY_UNAVAILABLE" ||
+                    error.code === "BACKUP_THRESHOLD_UNMET")) {
+                // Keep historical archives discoverable when their provider/key/share
+                // material is unavailable. Restore availability reports that state.
+            }
+            else {
+                throw error;
+            }
+        }
+        finally {
+            authenticatedReader.releaseLock();
+        }
+    }
+    return entry;
+}
+async function readTargetCatalog(bucket, descriptor, now, options = {}) {
+    const read = await readTargetManifest(bucket, descriptor, now);
+    const manifestEntries = new Map(read.manifest.entries
+        .filter((entry) => entryMatchesDescriptor(entry, descriptor))
+        .map((entry) => [entry.key, entry]));
+    const objects = await listTargetArchiveObjects(bucket, descriptor);
+    const entries = [];
+    const repairEntries = [];
+    const warnings = read.warning ? [read.warning] : [];
+    let ignoredWarnings = 0;
+    for (const object of objects.sort((left, right) => left.key.localeCompare(right.key))) {
+        const existing = manifestEntries.get(object.key);
+        try {
+            if (object.key.endsWith(".sql")) {
+                const legacy = existing;
+                if (!legacy || legacy.archiveFormat !== 1)
+                    continue;
+                verifyBackupObject(legacy, await bucket.head(object.key));
+                entries.push(legacy);
+                repairEntries.push(legacy);
+                continue;
+            }
+            const reconstructed = await reconstructEncryptedBackupEntry(bucket, descriptor, object, {
+                ...options,
+                ...(existing?.archiveFormat === 2
+                    ? { expectedIntegrity: { bytes: existing.bytes, sha256: existing.sha256 } }
+                    : {})
+            });
+            if (existing?.archiveFormat === 2 &&
+                existing.bytes === reconstructed.bytes &&
+                existing.sha256 === reconstructed.sha256) {
+                assertBackupManifestIdentity(existing, decodeBackupArchiveHeader(encodeBackupArchiveHeader({
+                    format: 2,
+                    archiveId: reconstructed.archiveId,
+                    product: reconstructed.product,
+                    target: reconstructed.target,
+                    targetId: reconstructed.targetId,
+                    createdAt: reconstructed.date,
+                    logical: reconstructed.logical,
+                    encryption: reconstructed.encryption,
+                    keyEnvelope: reconstructed.keyEnvelope
+                })).header);
+                const normalized = {
+                    ...reconstructed,
+                    ...(existing.actorId !== undefined ? { actorId: existing.actorId } : {})
+                };
+                entries.push(normalized);
+                repairEntries.push(normalized);
+            }
+            else {
+                entries.push(reconstructed);
+                repairEntries.push(reconstructed);
+            }
+        }
+        catch (error) {
+            if (existing)
+                repairEntries.push(existing);
+            const warning = `Ignored invalid backup object ${object.key}: ${error instanceof Error ? error.message : String(error)}`;
+            if (warnings.length < backupArchiveDiscoveryMaximumWarnings)
+                archiveDiscoveryWarning(warnings, warning);
+            else
+                ignoredWarnings += 1;
+        }
+    }
+    if (ignoredWarnings > 0)
+        warnings.push(`Ignored ${ignoredWarnings} additional invalid backup objects.`);
+    entries.sort((left, right) => right.date.localeCompare(left.date) || left.key.localeCompare(right.key));
+    repairEntries.sort((left, right) => right.date.localeCompare(left.date) || left.key.localeCompare(right.key));
+    const needsRepair = read.needsRepair || JSON.stringify(repairEntries) !== JSON.stringify(read.manifest.entries);
+    return {
+        manifest: {
+            ...read.manifest,
+            updatedAt: needsRepair ? now : read.manifest.updatedAt,
+            entries: repairEntries
+        },
+        entries,
+        needsRepair,
+        ...(warnings.length ? { warning: warnings.join(" ") } : {})
+    };
+}
+async function readAndRepairCoreBackupCatalog(bucket, now, options = {}) {
+    const descriptor = coreDescriptor();
+    const target = await readTargetCatalog(bucket, descriptor, now, options);
+    const warnings = target.warning ? [target.warning] : [];
+    if (target.needsRepair) {
+        try {
+            await writeJsonObject(bucket, descriptor.manifestKey, target.manifest);
+        }
+        catch (error) {
+            warnings.push(`Could not repair ${descriptor.manifestKey}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const rootRead = await readRootManifest(bucket, now);
+    if (rootRead.warning)
+        warnings.push(rootRead.warning);
+    const root = upsertRootTarget(rootRead.manifest, descriptor, target.entries[0]?.date ?? null);
+    const rootNeedsRepair = rootRead.needsRepair || JSON.stringify(root.targets) !== JSON.stringify(rootRead.manifest.targets);
+    const repairedRoot = {
+        ...root,
+        updatedAt: rootNeedsRepair ? now : root.updatedAt
+    };
+    if (rootNeedsRepair) {
+        try {
+            await writeJsonObject(bucket, backupRootManifestKey, repairedRoot);
+        }
+        catch (error) {
+            warnings.push(`Could not repair ${backupRootManifestKey}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        entries: target.entries,
+        root: repairedRoot,
+        ...(warnings.length ? { warning: warnings.join(" ") } : {})
+    };
+}
+export async function listCoreBackupEntries(env, backups, environment) {
+    if (!env.RAYBASE_BACKUPS)
+        throw new Error("RAYBASE_BACKUPS R2 binding is missing");
+    let providers = {};
+    try {
+        providers = await backupProviderSet(env, backups);
+    }
+    catch {
+        // Listing remains available when provider configuration is invalid; such
+        // archives receive structural validation and explicit restore readiness.
+    }
+    const catalog = await readAndRepairCoreBackupCatalog(env.RAYBASE_BACKUPS, new Date().toISOString(), {
+        providers,
+        ...(environment ?? env.RAYBASE_ENV ? { environment: environment ?? env.RAYBASE_ENV } : {})
+    });
+    return { entries: catalog.entries, ...(catalog.warning ? { warning: catalog.warning } : {}) };
+}
+export async function readBackupRestoreAvailability(env, entry, backups, runtimeStatus) {
+    const restore = runtimeStatus ?? await readCoreBackupRestoreRuntimeStatus(env);
+    if (restore.maintenance?.active) {
+        return {
+            available: false,
+            reason: `Restore maintenance is active (${restore.maintenance.phase ?? "unknown phase"}).`
+        };
+    }
+    if (entry.archiveFormat === 1) {
+        return {
+            available: entry.bytes <= backupLegacyUploadMaximumBytes,
+            ...(entry.bytes > backupLegacyUploadMaximumBytes
+                ? { reason: `Legacy plaintext restore exceeds the ${backupLegacyUploadMaximumBytes}-byte compatibility limit.` }
+                : {})
+        };
+    }
+    if (!restore.pitrAvailable) {
+        return {
+            available: false,
+            reason: `Encrypted restore requires production PITR recovery support. ${restore.pitrUnavailableReason ?? "PITR is unavailable."}`
+        };
+    }
+    try {
+        const providers = await backupProviderSet(env, backups);
+        const provider = [providers.keyProvider, providers.deploymentProvider]
+            .find((candidate) => candidate?.id === entry.providerId);
+        if (!provider) {
+            return { available: false, reason: `Backup provider ${entry.providerId} is unavailable.` };
+        }
+        const context = {
+            archiveId: entry.archiveId,
+            product: entry.product,
+            target: entry.target,
+            targetId: entry.targetId,
+            createdAt: entry.date,
+            purpose: "readiness",
+            signal: new AbortController().signal,
+            ...(env.RAYBASE_ENV ? { environment: env.RAYBASE_ENV } : {})
+        };
+        if (provider.passwordSecrets) {
+            const participantStatus = await passwordParticipantReadiness(env, provider, context, false);
+            if (participantStatus && !participantStatus.readyForNewBackups) {
+                return {
+                    available: false,
+                    reason: participantStatus.reason ?? "Password-secret participants are not ready."
+                };
+            }
+        }
+        const dek = await unwrapBackupDek({ providers, context, envelope: entry.keyEnvelope });
+        dek.fill(0);
+        return { available: true };
+    }
+    catch (error) {
+        if (error instanceof RaybaseBackupError && error.code === "BACKUP_KEY_UNAVAILABLE") {
+            return { available: false, reason: `Historical key ${entry.kekKeyId} is unavailable.` };
+        }
+        if (error instanceof RaybaseBackupError) {
+            return { available: false, reason: error.message };
+        }
+        return {
+            available: false,
+            reason: "Backup restore readiness could not be determined."
+        };
+    }
+}
+export async function readCoreBackupStatus(env, options = {}) {
+    const retention = parseBackupRetention(env.RAYBASE_BACKUPS_RETAIN);
+    const enabled = backupsEnabled(env);
+    const consistencyPolicy = options.backups?.consistency?.mode === "write-gated" ? "write-gated" : "optimistic";
+    const restore = await readCoreBackupRestoreRuntimeStatus(env);
+    const caveats = [
+        "New backups are envelope-encrypted format-2 archives; SHA-256 covers the stored ciphertext.",
+        "Backups include Durable Object table data and Raybase file metadata.",
+        ...(options.storageConfigured ? ["R2 file bytes are not included."] : []),
+        ...(options.vectorizeConfigured ? ["Vectorize indexes are not included."] : ["Vectorize indexes are not included when configured."]),
+        "Legacy plaintext format-1 SQL is restore-only and keeps its historical memory and statement-size limits.",
+        ...(consistencyPolicy === "write-gated"
+            ? ["The write-gated consistency policy temporarily rejects database mutations while a backup snapshot is read."]
+            : ["Hot databases are retried optimistically and fail closed when a consistent generation cannot be read."]),
+        ...(restore.pitrAvailable
+            ? ["Encrypted restores use a persistent maintenance gate and production PITR undo bookmark for interrupted-restore recovery."]
+            : [`Encrypted restore is unavailable: ${restore.pitrUnavailableReason ?? "production PITR recovery support is unavailable."}`]),
+        ...(restore.maintenance?.active
+            ? [`Restore maintenance is active in ${restore.maintenance.phase ?? "an unknown"} phase; normal database access remains gated until rollback recovery completes.`]
+            : [])
+    ];
+    let encryptionReady = false;
+    let provider = {
+        id: null,
+        mode: null,
+        keyId: null,
+        passwordCoupled: false
+    };
+    let encryptionWarning;
+    let catalogProviders = {};
+    try {
+        const providers = await backupProviderSet(env, options.backups);
+        catalogProviders = providers;
+        const selected = selectedBackupProvider(providers);
+        if (selected) {
+            const context = backupReadinessContext(options.environment ?? env.RAYBASE_ENV);
+            const participants = await passwordParticipantReadiness(env, selected, context, false);
+            const envelope = participants?.readyForNewBackups === false
+                ? null
+                : await probeBackupProviderForCreation(env, providers, context);
+            provider = {
+                id: selected.id,
+                mode: selected.mode,
+                keyId: envelope?.kekKeyId ?? null,
+                passwordCoupled: Boolean(selected.passwordSecrets),
+                ...(selected.passwordSecrets ? { passwordLifecycleVersion: selected.passwordSecrets.version } : {}),
+                ...(participants ? { passwordParticipants: participants } : {})
+            };
+            encryptionReady = participants?.readyForNewBackups ?? true;
+            if (participants && !participants.readyForNewBackups) {
+                encryptionWarning = participants.reason ?? "Password-secret participants are not ready for backup creation.";
+            }
+            if (selected.passwordSecrets) {
+                caveats.push("This app provider couples restore access to password-secret participant readiness; passwordless users may be ineligible, and password reset or loss can permanently destroy access to older protected shares.");
+            }
+        }
+        else {
+            encryptionWarning = "Encrypted backup creation requires an app key provider or RAYBASE_BACKUPS_KEY.";
+        }
+    }
+    catch (error) {
+        encryptionWarning = error instanceof RaybaseBackupError
+            ? error.message
+            : "Backup encryption provider readiness failed.";
+    }
+    if (!env.RAYBASE_BACKUPS) {
+        return {
+            enabled,
+            bindingPresent: false,
+            encryptionReady,
+            archiveFormat: 2,
+            consistencyPolicy,
+            provider,
+            restore,
+            retention,
+            rootManifestKey: backupRootManifestKey,
+            targets: [],
+            latestBackup: null,
+            caveats,
+            ...(encryptionWarning ? { warning: encryptionWarning } : {})
+        };
+    }
+    const now = new Date().toISOString();
+    const catalog = await readAndRepairCoreBackupCatalog(env.RAYBASE_BACKUPS, now, {
+        providers: catalogProviders,
+        ...(options.environment ?? env.RAYBASE_ENV ? { environment: options.environment ?? env.RAYBASE_ENV } : {})
+    });
+    return {
+        enabled,
+        bindingPresent: true,
+        encryptionReady,
+        archiveFormat: 2,
+        consistencyPolicy,
+        provider,
+        restore,
+        retention,
+        rootManifestKey: backupRootManifestKey,
+        targets: catalog.root.targets,
+        latestBackup: catalog.entries[0] ?? null,
+        caveats,
+        ...(catalog.warning || encryptionWarning
+            ? { warning: [catalog.warning, encryptionWarning].filter(Boolean).join(" ") }
+            : {})
+    };
+}
+export async function readCoreBackupSqlFromR2(env, key) {
+    if (!env.RAYBASE_BACKUPS)
+        throw new Error("RAYBASE_BACKUPS R2 binding is missing");
+    const normalized = validateCoreBackupKey(key);
+    if (!normalized.endsWith(".sql"))
+        throw new Error("Encrypted backup archives are binary, not SQL text");
+    const object = await env.RAYBASE_BACKUPS.get(normalized);
+    if (!object)
+        throw new Error("Backup object not found");
+    if (object.size > backupLegacyUploadMaximumBytes) {
+        throw new RaybaseBackupError("BACKUP_LIMIT_EXCEEDED", `Legacy plaintext restores are limited to ${backupLegacyUploadMaximumBytes} bytes`);
+    }
+    const sql = new TextDecoder("utf-8", { fatal: true }).decode(await object.arrayBuffer());
+    validateCoreBackupSql(sql);
+    return { key: normalized, sql, object };
+}
+export async function readCoreBackupObjectFromR2(env, key, backups, environment) {
+    if (!env.RAYBASE_BACKUPS)
+        throw new Error("RAYBASE_BACKUPS R2 binding is missing");
+    const normalized = validateCoreBackupKey(key);
+    const listed = await listCoreBackupEntries(env, backups, environment);
+    const entry = listed.entries.find((candidate) => candidate.key === normalized);
+    if (!entry)
+        throw new Error("Backup manifest entry not found");
+    const object = await env.RAYBASE_BACKUPS.get(normalized);
+    verifyBackupObject(entry, object);
+    if (!object)
+        throw new Error("Backup object not found");
+    return { key: normalized, entry, object };
+}
+async function consumeEncryptedBackup(object, providers, options) {
+    const decryptor = createBackupArchiveDecryptor({
+        providers,
+        ...(options.providerInput ? { providerInput: options.providerInput } : {}),
+        ...(options.environment ? { environment: options.environment } : {}),
+        ...(options.expectedCiphertextBytes !== undefined
+            ? { expectedCiphertextBytes: options.expectedCiphertextBytes }
+            : {}),
+        ...(options.expectedCiphertextSha256
+            ? { expectedCiphertextSha256: options.expectedCiphertextSha256 }
+            : {}),
+        validateHeader(header) {
+            validateCoreArchiveHeader(header);
+            if (options.expectedEntry)
+                assertBackupManifestIdentity(options.expectedEntry, header);
+            if (options.expectedHeader && !sameBytes(encodeBackupArchiveHeader(options.expectedHeader), encodeBackupArchiveHeader(header))) {
+                throw new RaybaseBackupError("BACKUP_ARCHIVE_IDENTITY_MISMATCH", "Backup header changed between restore passes");
+            }
+        }
+    });
+    const decoder = new BackupLogicalDecoder();
+    const logicalDigest = createBackupSha256Digest();
+    const reader = object.body.pipeThrough(decryptor.transform).getReader();
+    let logicalEnd = null;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done)
+                break;
+            for (const record of decoder.push(result.value)) {
+                if (record.kind === "logical-end") {
+                    if (logicalEnd)
+                        throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup has duplicate logical end records");
+                    const digestBytes = await logicalDigest.finish();
+                    const digestHex = backupBytesToHex(digestBytes);
+                    digestBytes.fill(0);
+                    if (digestHex !== record.plaintextSha256) {
+                        throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup logical plaintext digest does not match");
+                    }
+                    logicalEnd = record;
+                }
+                else {
+                    await logicalDigest.write(encodeBackupLogicalRecord(record));
+                }
+                await options.onRecord?.(record);
+            }
+        }
+        decoder.finish();
+        const header = await decryptor.header;
+        const completion = await decryptor.completion;
+        if (!logicalEnd)
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Backup logical end is missing");
+        if (completion.logicalTotals.recordCount !== logicalEnd.recordCount ||
+            completion.logicalTotals.rowCount !== logicalEnd.rowCount ||
+            completion.logicalTotals.tableCount !== logicalEnd.tableCount) {
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Authenticated frame totals do not match the logical archive");
+        }
+        if (!sameBytes(encodeBackupArchiveHeader(header), encodeBackupArchiveHeader(completion.header))) {
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_IDENTITY_MISMATCH", "Backup header completion is inconsistent");
+        }
+        return { completion, logicalEnd };
+    }
+    catch (error) {
+        await logicalDigest.abort(error);
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export async function restoreCoreEncryptedBackup(env, source, options = {}) {
+    const providers = await backupProviderSet(env, options.backups);
+    if (!selectedBackupProvider(providers)) {
+        throw new RaybaseBackupError("BACKUP_ENCRYPTION_NOT_CONFIGURED", "Encrypted restore requires the provider and historical key named by the archive");
+    }
+    const firstObject = await source.getObject();
+    const verified = await consumeEncryptedBackup(firstObject, providers, {
+        ...(options.providerInput ? { providerInput: options.providerInput } : {}),
+        ...(options.environment ?? env.RAYBASE_ENV ? { environment: options.environment ?? env.RAYBASE_ENV } : {}),
+        ...(source.entry ? { expectedEntry: source.entry } : {}),
+        ...(source.entry ? { expectedCiphertextBytes: source.entry.bytes, expectedCiphertextSha256: source.entry.sha256 } : {})
+    });
+    await prepareCoreBackupRestore(env, { requirePitr: true });
+    const stub = dataStub(env);
+    const operationId = crypto.randomUUID();
+    await stub.beginBackupRestore({
+        operationId,
+        sourceSha256: verified.completion.ciphertextSha256,
+        archiveId: verified.completion.header.archiveId,
+        targetId: verified.completion.header.targetId,
+        expectedRecordCount: verified.logicalEnd.recordCount,
+        expectedRowCount: verified.logicalEnd.rowCount,
+        expectedTableCount: verified.logicalEnd.tableCount,
+        plaintextSha256: verified.logicalEnd.plaintextSha256
+    });
+    let batch = [];
+    let batchBytes = 0;
+    let batchIndex = 0;
+    const flush = async () => {
+        if (!batch.length)
+            return;
+        const encoded = batch.map(encodeBackupLogicalRecord);
+        const joined = new Uint8Array(encoded.reduce((total, record) => total + record.byteLength, 0));
+        let offset = 0;
+        for (const record of encoded) {
+            joined.set(record, offset);
+            offset += record.byteLength;
+        }
+        const batchSha256 = await sha256Hex(joined);
+        joined.fill(0);
+        await stub.applyBackupRestoreBatch({ operationId, batchIndex, batchSha256, records: batch });
+        batch = [];
+        batchBytes = 0;
+        batchIndex += 1;
+    };
+    try {
+        const secondObject = await source.getObject();
+        await consumeEncryptedBackup(secondObject, providers, {
+            ...(options.providerInput ? { providerInput: options.providerInput } : {}),
+            ...(options.environment ?? env.RAYBASE_ENV ? { environment: options.environment ?? env.RAYBASE_ENV } : {}),
+            expectedHeader: verified.completion.header,
+            expectedCiphertextBytes: verified.completion.ciphertextBytes,
+            expectedCiphertextSha256: verified.completion.ciphertextSha256,
+            async onRecord(record) {
+                const encodedBytes = encodeBackupLogicalRecord(record).byteLength;
+                if (batch.length > 0 &&
+                    (batch.length >= backupDatabaseProtocolLimits.maximumRestoreBatchRecords ||
+                        batchBytes + encodedBytes > backupDatabaseProtocolLimits.maximumRestoreBatchBytes)) {
+                    await flush();
+                }
+                batch.push(record);
+                batchBytes += encodedBytes;
+                if (batch.length >= backupDatabaseProtocolLimits.maximumRestoreBatchRecords ||
+                    batchBytes >= backupDatabaseProtocolLimits.maximumRestoreBatchBytes) {
+                    await flush();
+                }
+            }
+        });
+        await flush();
+        await stub.finishBackupRestore({ operationId });
+    }
+    catch (error) {
+        await stub.failBackupRestore({
+            operationId,
+            error: error instanceof Error ? error.message : String(error)
+        }).catch(() => undefined);
+        try {
+            await recoverInterruptedBackupRestore({ stub });
+        }
+        catch (recoveryError) {
+            throw new RaybaseBackupError("BACKUP_RESTORE_MAINTENANCE_REQUIRED", `Restore failed and automatic PITR rollback could not complete: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`);
+        }
+        throw error;
+    }
+    return {
+        ok: true,
+        archiveFormat: 2,
+        encrypted: true,
+        archiveId: verified.completion.header.archiveId,
+        sourceSha256: verified.completion.ciphertextSha256,
+        recordCount: verified.logicalEnd.recordCount,
+        rowCount: verified.logicalEnd.rowCount,
+        tableCount: verified.logicalEnd.tableCount
+    };
+}
+export async function restoreCoreEncryptedBackupFromR2(env, key, options = {}) {
+    const stored = await readCoreBackupObjectFromR2(env, key, options.backups, options.environment);
+    if (stored.entry.archiveFormat !== 2)
+        throw new Error("Legacy SQL backups use the compatibility restore path");
+    return restoreCoreEncryptedBackup(env, {
+        entry: stored.entry,
+        async getObject() {
+            if (!env.RAYBASE_BACKUPS)
+                throw new Error("RAYBASE_BACKUPS R2 binding is missing");
+            const object = await env.RAYBASE_BACKUPS.get(stored.key);
+            if (!object)
+                throw new Error("Backup object not found");
+            return object;
+        }
+    }, options);
+}
+export async function archiveBackupToR2(env, options = {}) {
+    if (!backupsEnabled(env)) {
+        console.info("Raybase backup archive skipped", { reason: "disabled" });
+        return { ok: true, skipped: true, reason: "disabled", archived: false };
+    }
+    if (!env.RAYBASE_BACKUPS) {
+        console.info("Raybase backup archive skipped", { reason: "missing-r2-binding" });
+        return { ok: true, skipped: true, reason: "missing-r2-binding", archived: false };
+    }
+    await pruneTemporaryBackupObjects(env.RAYBASE_BACKUPS, { now: options.now }).catch((error) => {
+        console.warn("Temporary encrypted backup cleanup failed", error);
+    });
+    const providers = await backupProviderSet(env, options.backups);
+    if (!selectedBackupProvider(providers)) {
+        throw new RaybaseBackupError("BACKUP_ENCRYPTION_NOT_CONFIGURED", "Encrypted backups require an app key provider or RAYBASE_BACKUPS_KEY");
+    }
+    const now = options.now ?? new Date();
+    const date = now.toISOString();
+    const trigger = options.trigger ?? "scheduled";
+    const descriptor = coreDescriptor();
+    const maxAttempts = options.backups?.consistency?.mode === "write-gated"
+        ? 1
+        : options.backups?.consistency?.maxAttempts;
+    const entry = await retryConsistentBackupSnapshot(async () => {
+        const archiveId = crypto.randomUUID();
+        const key = `${descriptor.prefix}${backupTimestamp(now)}-${archiveId}.rbb`;
+        const identity = {
+            archiveId,
+            product: "core",
+            target: "core",
+            targetId: "core",
+            createdAt: date
+        };
+        const wrapContext = {
+            ...identity,
+            purpose: "wrap",
+            signal: new AbortController().signal,
+            ...(options.environment ?? env.RAYBASE_ENV ? { environment: options.environment ?? env.RAYBASE_ENV } : {})
+        };
+        const wrapParticipants = await resolvePasswordParticipantsForWrap(env, selectedBackupProvider(providers), wrapContext);
+        let snapshot;
+        let encryptor;
+        try {
+            encryptor = await createBackupArchiveEncryptor({
+                identity,
+                providers,
+                participants: wrapParticipants.participants,
+                logicalTotals: () => {
+                    if (!snapshot)
+                        throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup snapshot did not initialize");
+                    return snapshot.totals;
+                },
+                ...(options.environment ?? env.RAYBASE_ENV ? { environment: options.environment ?? env.RAYBASE_ENV } : {})
+            });
+        }
+        finally {
+            wrapParticipants.release();
+        }
+        const provisional = {
+            key,
+            date,
+            sha256: "0".repeat(64),
+            bytes: 0,
+            product: "core",
+            target: "core",
+            actorId: options.actorId ?? null,
+            trigger,
+            archiveFormat: 2,
+            archiveId,
+            targetId: "core",
+            encrypted: true,
+            contentType: backupBinaryContentType,
+            encryption: encryptor.header.encryption,
+            logical: encryptor.header.logical,
+            providerId: encryptor.header.keyEnvelope.providerId,
+            kekKeyId: encryptor.header.keyEnvelope.kekKeyId,
+            keyEnvelope: encryptor.header.keyEnvelope
+        };
+        const upload = await env.RAYBASE_BACKUPS.createMultipartUpload(key, {
+            httpMetadata: { contentType: backupBinaryContentType },
+            customMetadata: backupObjectMetadata(provisional)
+        });
+        snapshot = snapshotLogicalStream(dataStub(env), archiveId, options.backups?.consistency);
+        const ciphertext = snapshot.stream.pipeThrough(encryptor.transform);
+        const [uploaded, completion] = await Promise.all([
+            uploadBackupMultipartStream(upload, ciphertext),
+            encryptor.completion
+        ]);
+        if (uploaded.bytes !== completion.ciphertextBytes ||
+            uploaded.sha256 !== completion.ciphertextSha256) {
+            await env.RAYBASE_BACKUPS.delete(key).catch(() => undefined);
+            throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Uploaded backup bytes do not match encryption completion evidence");
+        }
+        return {
+            ...provisional,
+            bytes: uploaded.bytes,
+            sha256: uploaded.sha256
+        };
+    }, { ...(maxAttempts ? { maxAttempts } : {}) });
+    verifyBackupObject(entry, await env.RAYBASE_BACKUPS.head(entry.key));
+    const catalog = await readTargetCatalog(env.RAYBASE_BACKUPS, descriptor, date, {
+        providers,
+        ...(options.environment ?? env.RAYBASE_ENV ? { environment: options.environment ?? env.RAYBASE_ENV } : {})
+    });
+    const operationalEntries = [entry, ...catalog.entries.filter((existing) => existing.key !== entry.key)]
+        .sort((left, right) => right.date.localeCompare(left.date) || left.key.localeCompare(right.key));
+    const manifestEntries = [entry, ...catalog.manifest.entries.filter((existing) => existing.key !== entry.key)]
+        .sort((left, right) => right.date.localeCompare(left.date) || left.key.localeCompare(right.key));
+    const retention = parseBackupRetention(env.RAYBASE_BACKUPS_RETAIN);
+    await writeJsonObject(env.RAYBASE_BACKUPS, descriptor.manifestKey, {
+        ...catalog.manifest,
+        updatedAt: date,
+        entries: manifestEntries
+    });
+    const rootRead = await readRootManifest(env.RAYBASE_BACKUPS, date);
+    const root = upsertRootTarget(rootRead.manifest, descriptor, entry.date);
+    await writeJsonObject(env.RAYBASE_BACKUPS, backupRootManifestKey, {
+        ...root,
+        updatedAt: date,
+        lastSuccessfulFullRunAt: date,
+        partialRun: null
+    });
+    const pruned = await pruneEntries(env.RAYBASE_BACKUPS, operationalEntries, retention);
+    if (pruned.pruned.length) {
+        const prunedKeys = new Set(pruned.pruned.map((prunedEntry) => prunedEntry.key));
+        await writeJsonObject(env.RAYBASE_BACKUPS, descriptor.manifestKey, {
+            ...catalog.manifest,
+            updatedAt: date,
+            entries: manifestEntries.filter((manifestEntry) => !prunedKeys.has(manifestEntry.key))
+        });
+    }
+    await audit(raybaseAuthExecutor(env), options.actorId ?? null, `database.backup.${trigger}`, "raybase_database", undefined, {
+        key: entry.key,
+        bytes: entry.bytes,
+        sha256: entry.sha256,
+        archiveFormat: entry.archiveFormat,
+        encrypted: entry.encrypted,
+        providerId: entry.providerId,
+        kekKeyId: entry.kekKeyId
+    }).catch((error) => {
+        console.warn("Raybase backup archive audit failed", error);
+    });
+    console.info("Raybase backup archive complete", {
+        key: entry.key,
+        bytes: entry.bytes,
+        sha256: entry.sha256,
+        providerId: entry.providerId,
+        kekKeyId: entry.kekKeyId,
+        trigger: entry.trigger
+    });
+    return { ok: true, skipped: false, archived: true, entry, pruned: pruned.pruned };
+}
+//# sourceMappingURL=backup-archive.js.map