@aopslabs/aops-server 0.2.24 → 0.2.25

package/scripts/owned-set-restore.mjs

@@ -0,0 +1,655 @@
+#!/usr/bin/env node
+/**
+ * Restores a first-party backup, in one of two explicit modes.
+ *
+ *   existing-exact-predecessor -- the schema is already the state the bundle was
+ *   taken from. Migrations are not re-applied and the ledgers are not touched;
+ *   the schema is verified to match exactly, then the owned data is replaced in
+ *   one transaction.
+ *
+ *   empty-disaster-target -- there is no schema. The embedded closure builds the
+ *   predecessor schema, the engine writes the ledgers as a side effect of
+ *   applying it, and only then is the data loaded. The bundle's ledger evidence
+ *   is compared against what the engine produced rather than replayed over it.
+ *
+ * Ledger rows are never inserted as data in either mode. A ledger row asserts
+ * that a migration ran; asserting that independently of the DDL produces a
+ * database that lies about its own history, and nothing downstream would catch
+ * it -- the schema would look right and the applied counts would look right.
+ *
+ * Expected integrity comes from the receipt OUTSIDE the bundle. A bundle that
+ * validates itself validates a coordinated edit too: an earlier version of this
+ * design accepted exactly that attack, with the chunk rewritten and the manifest
+ * rewritten to match.
+ */
+import { createHash } from 'node:crypto'
+import { gunzipSync } from 'node:zlib'
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const CONTRACT = 'aops.owned-set-backup/v2'
+const RECEIPT_CONTRACT = 'aops.backup-receipt/v1'
+const INSERT_BATCH = 500
+
+const quote = (id) => `"${String(id).replace(/"/g, '""')}"`
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest('hex')
+
+export const RESTORE_MODES = Object.freeze(['existing-exact-predecessor', 'empty-disaster-target'])
+
+/** Every chunk verified before anything is written. All-or-nothing starts here. */
+export function verifyBundle(bundleDirectory, anchorPath, { expectedProviderContractSha256 } = {}) {
+  const manifestPath = path.join(bundleDirectory, 'manifest.json')
+  let manifestBytes
+  try { manifestBytes = readFileSync(manifestPath) } catch { throw new Error('bundle_manifest_missing_or_unreadable') }
+  const manifest = JSON.parse(manifestBytes.toString('utf8'))
+  if (manifest.contract !== CONTRACT) throw new Error(`bundle_contract_mismatch:${manifest.contract}`)
+  if (manifest.identity?.identityMode !== 'semantic-owned-v1') {
+    throw new Error(`bundle_not_backup_eligible:identityMode=${String(manifest.identity?.identityMode)}`)
+  }
+
+  if (!anchorPath) throw new Error('bundle_unanchored:automatic_eligibility_denied')
+  let anchor
+  try { anchor = JSON.parse(readFileSync(anchorPath, 'utf8')) }
+  catch { throw new Error('bundle_anchor_missing_or_unreadable') }
+  if (anchor.contract !== RECEIPT_CONTRACT) throw new Error('anchor_contract_mismatch')
+  const measured = sha256(manifestBytes)
+  if (anchor.bundleSha256 !== measured) {
+    throw new Error(`bundle_sha_mismatch_vs_anchor:anchor=${String(anchor.bundleSha256).slice(0, 12)}:measured=${measured.slice(0, 12)}`)
+  }
+  if (anchor.backupSetId !== manifest.backupSetId) {
+    throw new Error(`bundle_set_id_mismatch_vs_anchor:${String(anchor.backupSetId)}:${String(manifest.backupSetId)}`)
+  }
+
+  // Three-way, and each leg refuses something the others cannot.
+  //
+  // The manifest says which provider contract produced this bundle. The anchor
+  // says the same thing from outside the bundle, so a coordinated edit of the
+  // bundle cannot move it. And the caller's expectation -- the value the lineage
+  // declares -- says the contract is the one this installation was reviewed
+  // under, not merely one that was internally consistent.
+  //
+  // A bundle produced before this field existed carries neither half. That is
+  // refused rather than tolerated: an unversioned backup restored into a
+  // contract-checked world is exactly the state nobody can reason about.
+  if (typeof manifest.providerContractSha256 !== 'string' || manifest.providerContractSha256.length !== 64) {
+    throw new Error('bundle_provider_contract_absent')
+  }
+  if (anchor.providerContractSha256 !== manifest.providerContractSha256) {
+    throw new Error('bundle_provider_contract_mismatch_vs_anchor:' +
+      `${String(anchor.providerContractSha256).slice(0, 12)}:${manifest.providerContractSha256.slice(0, 12)}`)
+  }
+  if (expectedProviderContractSha256 && expectedProviderContractSha256 !== manifest.providerContractSha256) {
+    throw new Error('bundle_provider_contract_mismatch_vs_expected:' +
+      `${expectedProviderContractSha256.slice(0, 12)}:${manifest.providerContractSha256.slice(0, 12)}`)
+  }
+
+  const rowsByRelation = new Map()
+  for (const chunk of manifest.chunks) {
+    const packed = readFileSync(path.join(bundleDirectory, chunk.file))
+    if (sha256(packed) !== chunk.compressedSha256) throw new Error(`chunk_compressed_sha_mismatch:${chunk.file}`)
+    if (packed.length !== chunk.compressedBytes) throw new Error(`chunk_compressed_size_mismatch:${chunk.file}`)
+    const plain = gunzipSync(packed)
+    if (sha256(plain) !== chunk.uncompressedSha256) throw new Error(`chunk_uncompressed_sha_mismatch:${chunk.file}`)
+    if (plain.length !== chunk.uncompressedBytes) throw new Error(`chunk_uncompressed_size_mismatch:${chunk.file}`)
+    const lines = plain.toString('utf8').split('\n').filter((line) => line.length > 0)
+    if (lines.length !== chunk.rowCount) throw new Error(`chunk_row_count_mismatch:${chunk.file}`)
+    if (!rowsByRelation.has(chunk.relation)) rowsByRelation.set(chunk.relation, [])
+    rowsByRelation.get(chunk.relation).push({ index: chunk.index, lines })
+  }
+  const onDisk = readdirSync(path.join(bundleDirectory, 'fragments')).filter((name) => name.endsWith('.gz'))
+  if (onDisk.length !== manifest.chunks.length) {
+    throw new Error(`bundle_chunk_count_mismatch:disk=${onDisk.length}:manifest=${manifest.chunks.length}`)
+  }
+  return { manifest, rowsByRelation, bundleSha256: measured }
+}
+
+/** The embedded closure, re-verified against the manifest before it is applied. */
+export function verifyEmbeddedClosure(bundleDirectory, manifest) {
+  if (!manifest.migrationSetEmbedded || !manifest.closure) {
+    throw new Error('bundle_closure_absent:not_disaster_recovery_eligible')
+  }
+  for (const file of manifest.closure.files) {
+    const target = path.join(bundleDirectory, 'closure', file.root, file.relativePath)
+    if (!existsSync(target)) throw new Error(`closure_file_missing:${file.root}:${file.relativePath}`)
+    const bytes = readFileSync(target)
+    if (sha256(bytes) !== file.sha256) throw new Error(`closure_file_sha_mismatch:${file.root}:${file.relativePath}`)
+    if (bytes.length !== file.byteLength) throw new Error(`closure_file_size_mismatch:${file.root}:${file.relativePath}`)
+  }
+  return { rootCount: manifest.closure.rootCount, fileCount: manifest.closure.fileCount }
+}
+
+async function assertTargetSchemaExact(client, manifest) {
+  const relations = Object.keys(manifest.shape)
+  const { rows } = await client.query(`
+    SELECT c.relname AS relation, a.attname AS column, a.atttypid::int AS typeOid
+    FROM pg_attribute a
+    JOIN pg_class c ON c.oid = a.attrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'public' AND c.relname = ANY($1)
+      AND a.attnum > 0 AND NOT a.attisdropped AND c.relkind IN ('r', 'p')
+    ORDER BY c.relname, a.attnum`, [relations])
+  const live = new Map()
+  for (const row of rows) {
+    if (!live.has(row.relation)) live.set(row.relation, [])
+    live.get(row.relation).push(`${row.column}:${row.typeoid}`)
+  }
+  for (const [relation, columns] of Object.entries(manifest.shape)) {
+    const actual = live.get(relation)
+    if (!actual) throw new Error(`target_relation_missing:${relation}`)
+    // Compared as a set of name:type pairs, not as an ordered list.
+    //
+    // Column order is not a property this restore depends on -- every INSERT names
+    // its columns explicitly -- and it legitimately differs between a database
+    // built by successive migrations and one rebuilt from a closure in one pass.
+    // Measured: `agent-sessions.missionId` is the last column in the production
+    // copy and the fourth in the closure-rebuilt schema, with identical names and
+    // type OIDs throughout. Requiring the order would reject a correct restore
+    // while catching nothing a set comparison misses.
+    const expected = [...columns.map((column) => `${column.column}:${column.typeOid}`)].sort()
+    const observed = [...actual].sort()
+    if (expected.join(',') !== observed.join(',')) {
+      const missing = expected.filter((entry) => !observed.includes(entry))
+      const extra = observed.filter((entry) => !expected.includes(entry))
+      throw new Error(`target_schema_mismatch:${relation}:missing=${missing.join('|')}:extra=${extra.join('|')}`)
+    }
+  }
+}
+
+/**
+ * Ledgers are compared, never replayed -- and compared by CONTENT, not by count.
+ *
+ * A row count answers "how many migrations does this database think it ran", which
+ * is the question two different histories can answer identically: swap one tag for
+ * another and the count is unchanged while the claim is completely different. The
+ * digest covers the ordered tags and their recorded hashes, so a same-count
+ * substitution fails here rather than passing as agreement.
+ */
+export async function readLedgerDigest(client, relation) {
+  const { rows } = await client.query(`
+    SELECT a.attname AS column, format_type(a.atttypid, a.atttypmod) AS type
+    FROM pg_attribute a
+    JOIN pg_class c ON c.oid = a.attrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'public' AND c.relname = $1 AND a.attnum > 0 AND NOT a.attisdropped
+    ORDER BY a.attnum`, [relation])
+  if (rows.length === 0) return { rowCount: 0, contentSha256: sha256(Buffer.alloc(0)) }
+  // `appliedAt` is excluded: it records when a migration ran on this machine, not
+  // which migration ran, and comparing it would make every legitimate restore
+  // look like drift.
+  // Timestamps are excluded BY TYPE, not by name. The column is `applied_at` in
+  // these ledgers and `appliedAt` elsewhere; excluding one spelling left the other
+  // in the digest, and every legitimately rebuilt ledger then differed from the
+  // one it was rebuilt from -- for no reason except that it was applied at a
+  // different moment, which is the one thing the digest must not care about.
+  const columns = rows
+    .filter((row) => !/^timestamp( |$)/.test(String(row.type)))
+    .map((row) => row.column)
+  const projection = columns.map((column) => `coalesce(${quote(column)}::text, '')`).join(` || '|' || `)
+  const digest = await client.query(`
+    SELECT count(*)::int AS rows,
+           coalesce(string_agg(line, E'\n' ORDER BY line), '') AS body
+    FROM (SELECT ${projection} AS line FROM public.${quote(relation)}) source`)
+  return {
+    rowCount: digest.rows[0].rows,
+    contentSha256: sha256(Buffer.from(digest.rows[0].body)),
+  }
+}
+
+async function assertLedgerEvidence(client, manifest) {
+  const mismatches = []
+  for (const [relation, evidence] of Object.entries(manifest.ledgerEvidence ?? {})) {
+    const observed = await readLedgerDigest(client, relation)
+    if (observed.rowCount !== evidence.rowCount) {
+      mismatches.push(`${relation}:count:expected=${evidence.rowCount}:actual=${observed.rowCount}`)
+      continue
+    }
+    if (!evidence.contentSha256) {
+      // An evidence record without a content digest cannot be checked for the
+      // substitution it exists to catch, so it is not weaker evidence -- it is
+      // absent evidence.
+      mismatches.push(`${relation}:content_digest_absent`)
+      continue
+    }
+    if (observed.contentSha256 !== evidence.contentSha256) {
+      mismatches.push(`${relation}:content:expected=${evidence.contentSha256.slice(0, 12)}:actual=${observed.contentSha256.slice(0, 12)}`)
+    }
+  }
+  if (mismatches.length > 0) throw new Error(`ledger_evidence_mismatch:${mismatches.join(',')}`)
+}
+
+/**
+ * The owned semantic identity of the live database, compared to the bundle's.
+ *
+ * Separate from the column check above on purpose. Columns and type OIDs can
+ * agree while the projection differs -- an index or a constraint moved -- and the
+ * projection can agree while a ledger disagrees. Collapsing them into one check
+ * would let either half mask the other's absence.
+ */
+async function assertOwnedSemanticIdentity(client, manifest, semanticIdentity) {
+  if (!semanticIdentity) {
+    // No way to measure it is not the same as measuring it and finding it equal.
+    throw new Error('restore_semantic_identity_unavailable:eligibility_denied')
+  }
+  const expected = manifest.identity?.ownedFingerprintSha256
+  if (!expected) throw new Error('bundle_owned_fingerprint_absent:eligibility_denied')
+  const projection = await semanticIdentity.readProjection(client)
+  const actual = semanticIdentity.fingerprint(projection, manifest.identity.ownedRelations)
+  if (actual !== expected) {
+    throw new Error(`predecessor_semantic_identity_mismatch:expected=${expected.slice(0, 12)}:actual=${actual.slice(0, 12)}`)
+  }
+}
+
+/**
+ * A policy whose migration roots point at the bundle's embedded closure instead of
+ * an installed package.
+ *
+ * This is what "bundle-only" means in practice: the engine resolves every root
+ * under the bundle directory, so applying it cannot reach a migration the bundle
+ * does not carry. Mixing the two would defeat the purpose -- a disaster restore
+ * that quietly used the locally installed migrations would rebuild whatever this
+ * machine happens to have rather than what the backup was taken from.
+ *
+ * The closure directory is named after the drizzle output subdirectory, which is
+ * not always the root id (`agentspace` lives in `agentspace-community`), so the
+ * mapping is taken from the policy's own path rather than assumed.
+ */
+export function bundleOnlyPolicy(basePolicy, manifest, bundleDirectory) {
+  if (!manifest.migrationSetEmbedded || !manifest.closure) {
+    throw new Error('bundle_closure_absent:not_disaster_recovery_eligible')
+  }
+  const embeddedRoots = new Set(manifest.closure.files.map((file) => file.root))
+  const policy = JSON.parse(JSON.stringify(basePolicy))
+  for (const root of policy.roots) {
+    const directoryName = root.migrationsDir.split('/').pop()
+    if (!embeddedRoots.has(directoryName)) {
+      throw new Error(`bundle_closure_root_missing:${root.id}:${directoryName}`)
+    }
+    root.migrationsDir = `closure/${directoryName}`
+
+    // The root's journal and migration list are rebuilt FROM THE EMBEDDED BYTES,
+    // not carried over from the current policy.
+    //
+    // Measured reason: the closure is the predecessor's, and the running policy
+    // describes the target. agentspace has one migration in the 0.3.24 closure and
+    // two in the current tree, so the current journal hash cannot match what the
+    // bundle carries -- the engine refuses with journal_hash_mismatch, correctly.
+    // Rewriting only the paths made the bundle "self-contained" in the sense that
+    // the SQL travelled with it, while the description that validates the SQL
+    // still came from this machine.
+    const journalPath = path.join(bundleDirectory, 'closure', directoryName, 'meta', '_journal.json')
+    const journalBytes = readFileSync(journalPath)
+    const journal = JSON.parse(journalBytes.toString('utf8'))
+    root.journalSha256 = sha256(journalBytes)
+    root.journalSha256History = [root.journalSha256]
+    root.migrations = journal.entries.map((entry) => {
+      const sqlPath = path.join(bundleDirectory, 'closure', directoryName, `${entry.tag}.sql`)
+      const declared = manifest.closure.files.find((file) =>
+        file.root === directoryName && file.relativePath === `${entry.tag}.sql`)
+      if (!declared) throw new Error(`bundle_closure_sql_undeclared:${directoryName}:${entry.tag}`)
+      const bytes = readFileSync(sqlPath)
+      const actual = sha256(bytes)
+      if (actual !== declared.sha256) {
+        throw new Error(`bundle_closure_sql_mismatch:${directoryName}:${entry.tag}`)
+      }
+      return { idx: entry.idx, tag: entry.tag, sha256: actual, risk: 'additive' }
+    })
+  }
+  // Only the bundle's own lineage survives. The others describe states this
+  // closure cannot produce -- `strict-v4` counts two agentspace migrations where
+  // the predecessor closure has one -- and a policy carrying them is invalid
+  // against its own roots. Keeping them would also mean a disaster restore could
+  // classify into a lineage whose migrations are not in the bundle.
+  const own = policy.lineages.find((lineage) => lineage.id === manifest.identity.lineageId)
+  if (!own) throw new Error(`bundle_lineage_not_in_policy:${manifest.identity.lineageId}`)
+  // Keep the lineages this closure can actually produce -- every record whose
+  // applied counts fit inside the rebuilt roots -- and drop the rest. The same
+  // release observed on another PostgreSQL major is such a record and belongs
+  // here; `strict-v4`, which counts migrations the predecessor closure does not
+  // contain, does not. The policy also requires more than one lineage, so keeping
+  // the producible siblings is both correct and what makes the policy valid.
+  const producible = policy.lineages.filter((lineage) =>
+    lineage.appliedCounts.every((count, index) => count <= (policy.roots[index]?.migrations.length ?? -1)))
+  if (!producible.some((lineage) => lineage.id === own.id)) {
+    throw new Error(`bundle_lineage_not_producible_by_closure:${own.id}`)
+  }
+  policy.lineages = producible.map((lineage) =>
+    (lineage.id === own.id ? { ...lineage, kind: 'strict' } : lineage))
+  policy.lineageReconciliations = []
+  policy.targetLineageId = manifest.identity.lineageId
+  // The contract is derived from the target state; a predecessor closure does not
+  // produce it, and leaving it in would compare the rebuilt schema to a shape it
+  // is not supposed to have yet.
+  delete policy.semanticContract
+  return policy
+}
+
+export async function restoreOwnedSet({
+  client, bundleDirectory, anchorPath, mode, confirmReplace = false, semanticIdentity,
+  expectedProviderContractSha256,
+}) {
+  if (!RESTORE_MODES.includes(mode)) throw new Error(`restore_mode_invalid:${String(mode)}`)
+  // Taken from the caller's explicit argument first, and from the semantic
+  // identity only as a fallback, so a caller that holds a reviewed expectation
+  // cannot have it silently replaced by whatever the identity happens to carry.
+  const expectedContract = expectedProviderContractSha256 ?? semanticIdentity?.providerContractSha256
+  const { manifest, rowsByRelation } = verifyBundle(bundleDirectory, anchorPath,
+    { expectedProviderContractSha256: expectedContract })
+
+  if (mode === 'empty-disaster-target') {
+    // The closure has to be present and intact before anything else is decided:
+    // this mode's whole premise is that the bundle can rebuild the schema.
+    verifyEmbeddedClosure(bundleDirectory, manifest)
+    const { rows } = await client.query(`
+      SELECT count(*)::int AS relations FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p')`)
+    if (rows[0].relations !== 0) {
+      throw new Error(`empty_disaster_target_not_empty:${rows[0].relations}`)
+    }
+    // Applying the closure is the engine's job, not this module's; it is invoked
+    // by the caller between verification and load so the engine writes the
+    // ledgers itself. Reaching here with a non-empty target is the failure.
+    return { mode, verifiedOnly: true, closure: manifest.closure.fileCount, chunks: manifest.chunks.length }
+  }
+
+  if (!confirmReplace) throw new Error('restore_replace_owned_data_requires_confirmation')
+  // Three gates, deliberately separate. Each can fail while the others pass, and
+  // one must never stand in for another: a ledger that agrees about which
+  // migrations ran says nothing about whether the schema those migrations
+  // produce is actually there, and vice versa.
+  await assertTargetSchemaExact(client, manifest)
+  await assertOwnedSemanticIdentity(client, manifest, semanticIdentity)
+  await assertLedgerEvidence(client, manifest)
+
+  const payloadRelations = manifest.restoreOrder.filter((relation) =>
+    !Object.hasOwn(manifest.ledgerEvidence ?? {}, relation))
+
+  await client.query('BEGIN')
+  try {
+    // One TRUNCATE naming exactly the owned payload. Never CASCADE: PostgreSQL
+    // requires every referencing relation in the same statement, so this single
+    // statement is itself the proof the set is closed -- a reference from outside
+    // makes it fail rather than quietly reaching past the boundary.
+    await client.query(`TRUNCATE TABLE ${payloadRelations.map((relation) => `public.${quote(relation)}`).join(', ')}`)
+    let written = 0
+    for (const relation of payloadRelations) {
+      const columns = manifest.shape[relation] ?? []
+      const chunks = (rowsByRelation.get(relation) ?? []).sort((a, b) => a.index - b.index)
+      const selfColumns = manifest.selfReferencing?.[relation] ?? []
+      const columnList = columns.map((column) => quote(column.column)).join(', ')
+      const secondPass = []
+      for (const chunk of chunks) {
+        for (let offset = 0; offset < chunk.lines.length; offset += INSERT_BATCH) {
+          const batch = chunk.lines.slice(offset, offset + INSERT_BATCH).map((line) => JSON.parse(line))
+          const parameters = []
+          const values = batch.map((row) => `(${columns.map((column, index) => {
+            if (selfColumns.includes(column.column)) return 'NULL'
+            parameters.push(row[index])
+            return `$${parameters.length}::${column.type}`
+          }).join(', ')})`)
+          await client.query(
+            `INSERT INTO public.${quote(relation)} (${columnList}) VALUES ${values.join(', ')}`, parameters)
+          if (selfColumns.length > 0) secondPass.push(...batch)
+          written += batch.length
+        }
+      }
+      // A self-reference cannot be satisfied on first insert, so it is loaded as
+      // NULL and linked once every row of that relation exists.
+      if (selfColumns.length > 0 && secondPass.length > 0) {
+        const key = columns[0]
+        for (const row of secondPass) {
+          const indexes = selfColumns.map((name) => columns.findIndex((column) => column.column === name))
+          if (indexes.every((index) => row[index] === null)) continue
+          const assignments = selfColumns.map((name, position) =>
+            `${quote(name)} = $${position + 2}::${columns[indexes[position]].type}`)
+          await client.query(
+            `UPDATE public.${quote(relation)} SET ${assignments.join(', ')} WHERE ${quote(key.column)} = $1::${key.type}`,
+            [row[0], ...indexes.map((index) => row[index])])
+        }
+      }
+    }
+    for (const sequence of manifest.sequences) {
+      if (sequence.lastValue === null) continue
+      // The name is quoted inside the literal rather than passed as a parameter.
+      // A parameter reaching `setval` is cast through regclass, which lowercases
+      // an unquoted identifier -- so any sequence with a capital in its name
+      // resolves to a relation that does not exist. Measured, not guessed: a
+      // bigserial column named "seqTest" produced
+      // relation "public.agent-sessions_seqtest_seq" does not exist.
+      await client.query(
+        `SELECT setval('public.${quote(sequence.name).replace(/'/g, "''")}',` +
+        ` GREATEST($1::bigint, (SELECT last_value FROM public.${quote(sequence.name)})), true)`,
+        [sequence.lastValue])
+    }
+    // Read back BEFORE the commit, not after. Writing setval and moving on is not
+    // the same as knowing it took -- a sequence left below its restored value
+    // collides on the next insert. But a check that runs after COMMIT can only
+    // report a database it can no longer repair: the data is already visible and
+    // the transaction that could have withdrawn it is gone. Inside the
+    // transaction the same failure rolls everything back.
+    const behind = []
+    for (const sequence of manifest.sequences) {
+      if (sequence.lastValue === null) continue
+      const { rows } = await client.query(`SELECT last_value FROM public.${quote(sequence.name)}`)
+      if (BigInt(rows[0].last_value) < BigInt(sequence.lastValue)) {
+        behind.push(`${sequence.name}:read=${rows[0].last_value}:expected=${sequence.lastValue}`)
+      }
+    }
+    if (behind.length > 0) throw new Error(`sequence_readback_mismatch:${behind.slice(0, 3).join(',')}`)
+
+    await client.query('COMMIT')
+
+    return {
+      mode,
+      relations: payloadRelations.length,
+      rows: written,
+      chunks: manifest.chunks.length,
+      sequencesVerified: manifest.sequences.filter((sequence) => sequence.lastValue !== null).length,
+    }
+  } catch (error) {
+    await client.query('ROLLBACK').catch(() => undefined)
+    throw error
+  }
+}
+
+/**
+ * The whole disaster-recovery path, as one product operation.
+ *
+ * It used to stop after verification and hand the engine and the load back to
+ * whoever called it. That left the interesting half -- does the embedded closure
+ * actually rebuild this schema, and does the data then fit it -- outside the
+ * product, provable only by a script somebody ran once. The steps are ordered so
+ * that each one's failure is cheap: verify bytes, refuse a non-empty target,
+ * build the schema, check the schema is the one the bundle claims, and only then
+ * write data into it.
+ *
+ * The engine is injected rather than imported so this module does not depend on
+ * the bootstrap package, and so a caller can see exactly which engine ran.
+ */
+export async function restoreDisasterRecovery({
+  connectionString, bundleDirectory, anchorPath, basePolicy, applySchema, semanticIdentity, clientFactory,
+  expectedProviderContractSha256,
+}) {
+  if (typeof applySchema !== 'function') throw new Error('disaster_recovery_engine_required')
+  if (typeof clientFactory !== 'function') throw new Error('disaster_recovery_client_factory_required')
+  if (!semanticIdentity) throw new Error('disaster_recovery_semantic_identity_required')
+
+  const expectedContract = expectedProviderContractSha256 ?? semanticIdentity?.providerContractSha256
+  const gate = await withClient(clientFactory, connectionString, (client) =>
+    restoreOwnedSet({
+      client, bundleDirectory, anchorPath, mode: 'empty-disaster-target',
+      expectedProviderContractSha256: expectedContract,
+    }))
+  const { manifest } = verifyBundle(bundleDirectory, anchorPath,
+    { expectedProviderContractSha256: expectedContract })
+  const policy = bundleOnlyPolicy(basePolicy, manifest, bundleDirectory)
+
+  // The engine writes the ledgers as a side effect of applying the closure. That
+  // is the whole reason the bundle carries them as evidence instead of as rows.
+  const applied = await applySchema({ repoUrl: connectionString, workspaceRoot: bundleDirectory, policy })
+  if (applied?.lineageId !== manifest.identity.lineageId) {
+    throw new Error(`disaster_recovery_lineage_mismatch:expected=${manifest.identity.lineageId}:actual=${String(applied?.lineageId)}`)
+  }
+
+  const schemaFingerprint = await withClient(clientFactory, connectionString, async (client) => {
+    const projection = await semanticIdentity.readProjection(client)
+    return semanticIdentity.fingerprint(projection, manifest.identity.ownedRelations)
+  })
+  if (schemaFingerprint !== manifest.identity.ownedFingerprintSha256) {
+    throw new Error(`disaster_recovery_schema_mismatch:expected=${manifest.identity.ownedFingerprintSha256.slice(0, 12)}:actual=${schemaFingerprint.slice(0, 12)}`)
+  }
+
+  const loaded = await withClient(clientFactory, connectionString, (client) =>
+    restoreOwnedSet({
+      client, bundleDirectory, anchorPath, mode: 'existing-exact-predecessor',
+      confirmReplace: true, semanticIdentity,
+    }))
+
+  return {
+    mode: 'empty-disaster-target',
+    lineageId: applied.lineageId,
+    schemaAction: applied.migrationPlan?.action ?? null,
+    closureFiles: gate.closure,
+    relations: loaded.relations,
+    rows: loaded.rows,
+    sequencesVerified: loaded.sequencesVerified,
+  }
+}
+
+async function withClient(clientFactory, connectionString, body) {
+  const client = clientFactory(connectionString)
+  await client.connect()
+  try { return await body(client) } finally { await client.end() }
+}
+
+/**
+ * A callable entry, because the snapshot's attestation has to name a restore
+ * that works.
+ *
+ * The update seam writes "here is the backup, here is the command that puts it
+ * back". While the only restore path was pg_dump-shaped, switching the backup to
+ * a first-party bundle would have made that sentence false — the same class of
+ * untruth as a receipt that says "verified" without saying how. So the bundle
+ * gets a real way back before anything starts producing bundles.
+ */
+async function restoreFromCli(options) {
+  const repoUrl = process.env.AOPS_PG_URL
+  if (!repoUrl) throw new Error('owned_set_restore_pg_url_absent')
+  for (const required of ['bundleDirectory', 'receiptPath', 'mode']) {
+    if (!options[required]) throw new Error(`owned_set_restore_${required}_required`)
+  }
+  // Replacing live data is never inferred from the mode alone.
+  if (options.mode === 'existing-exact-predecessor' && options.confirm !== 'confirm-data-rewind') {
+    throw new Error('owned_set_restore_confirmation_required:confirm-data-rewind')
+  }
+  const { Client } = await import('pg')
+  const bootstrap = await import('@aopslabs/aops-pg-bootstrap')
+  const policy = JSON.parse(readFileSync(
+    options.policyPath ?? path.join(path.dirname(fileURLToPath(import.meta.url)),
+      'community-migration-policy-package-v1.json'), 'utf8'))
+  // The provider contract binding is resolved from the bundle, not from a flag.
+  //
+  // It used to come from `policy.lineages.find(l => l.id === options.lineageId)`,
+  // so omitting `--lineage-id` produced `undefined`, the `??` fallback found no
+  // `providerContractSha256` on the identity object either, and `verifyBundle`
+  // guards the comparison with `if (expectedProviderContractSha256 && ...)` --
+  // three steps, each individually reasonable, whose combined effect was that
+  // the default invocation skipped the check entirely. A bundle taken under a
+  // different provider contract restored without a word. The end-to-end run that
+  // "proved" restore never passed the flag, so it exercised the path with its own
+  // gate switched off.
+  //
+  // So the lineage comes from the manifest the bundle declares, the policy must
+  // carry a record for it, and that record must carry a contract. A caller that
+  // holds a reviewed expectation may still pass `--lineage-id`, but it has to
+  // agree rather than select.
+  const manifestLineageId = (() => {
+    let parsed
+    try {
+      parsed = JSON.parse(readFileSync(path.join(options.bundleDirectory, 'manifest.json'), 'utf8'))
+    } catch { throw new Error('owned_set_restore_manifest_unreadable') }
+    const id = parsed?.identity?.lineageId
+    if (typeof id !== 'string' || !id) throw new Error('owned_set_restore_manifest_lineage_absent')
+    return id
+  })()
+  if (options.lineageId && options.lineageId !== manifestLineageId) {
+    throw new Error(`owned_set_restore_lineage_id_disagrees:${options.lineageId}:${manifestLineageId}`)
+  }
+  const boundLineage = policy.lineages.find((lineage) => lineage.id === manifestLineageId)
+  if (!boundLineage) throw new Error(`owned_set_restore_lineage_not_in_policy:${manifestLineageId}`)
+  const expectedProviderContractSha256 = boundLineage.providerContractSha256
+  if (typeof expectedProviderContractSha256 !== 'string' || expectedProviderContractSha256.length !== 64) {
+    throw new Error(`owned_set_restore_policy_contract_absent:${manifestLineageId}`)
+  }
+
+  // Both call sites hand this the owned relation list, and both compare the
+  // result against the bundle's `ownedFingerprintSha256` -- so the projection is
+  // part of the identity, not an optimisation. Fingerprinting the raw projection
+  // instead measures every ambient object the database happens to carry, which
+  // made `existing-exact-predecessor` unable to match any real installation: the
+  // operator's own database has five relations outside the owned set.
+  const semanticIdentity = {
+    readProjection: (pgClient) => bootstrap.readCommunityStrictCatalogProjection(pgClient),
+    fingerprint: (projection, ownedRelations) => bootstrap.fingerprintCommunityStrictSemanticCatalog(
+      bootstrap.projectCommunityStrictSemanticCatalog(projection, ownedRelations)),
+  }
+
+  // Disaster recovery is a different operation, not a mode flag on this one.
+  // `restoreOwnedSet` deliberately stops after refusing a non-empty target and
+  // returns `verifiedOnly`, because applying the closure is the engine's job --
+  // so calling it alone for this mode verified the bundle, rebuilt nothing,
+  // loaded no rows, and exited zero with a result that reads like success. The
+  // engine has to be handed in here, which is also the only place that may
+  // import the bootstrap package.
+  if (options.mode === 'empty-disaster-target') {
+    return await restoreDisasterRecovery({
+      connectionString: repoUrl,
+      bundleDirectory: options.bundleDirectory,
+      anchorPath: options.receiptPath,
+      basePolicy: policy,
+      applySchema: (params) => bootstrap.applyCommunityStrictPgSchema(params),
+      clientFactory: (connectionString) => new Client({ connectionString }),
+      semanticIdentity,
+      expectedProviderContractSha256,
+    })
+  }
+
+  const client = new Client({ connectionString: repoUrl })
+  await client.connect()
+  try {
+    return await restoreOwnedSet({
+      client,
+      bundleDirectory: options.bundleDirectory,
+      anchorPath: options.receiptPath,
+      mode: options.mode,
+      confirmReplace: options.confirm === 'confirm-data-rewind',
+      semanticIdentity,
+      expectedProviderContractSha256,
+    })
+  } finally {
+    await client.end()
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const value = (name) => {
+    const index = process.argv.indexOf(name)
+    return index >= 0 ? process.argv[index + 1] : undefined
+  }
+  restoreFromCli({
+    bundleDirectory: value('--bundle-dir'),
+    receiptPath: value('--receipt'),
+    mode: value('--mode'),
+    confirm: value('--confirm'),
+    lineageId: value('--lineage-id'),
+    policyPath: value('--policy'),
+  })
+    .then((result) => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`))
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+      process.exit(1)
+    })
+}
+
+export { CONTRACT, RECEIPT_CONTRACT, restoreFromCli }