@dooer/dooer-test-env 1.0.0

package/lib/engine/seed.js

@@ -0,0 +1,1045 @@
+#!/usr/bin/env node
+/*
+ * seed-test-account.js — copy ALL customer-specific data for one Dooer organization into another.
+ *
+ * WHAT IT DOES
+ *   Reads every org-scoped table (schema-map.json, action:"copy") for the SOURCE org and inserts the
+ *   rows into the TARGET org, in the SAME database or ACROSS namespaces (e.g. read dooer-production,
+ *   write dooer-staging). The org identity is one uuid (organizationId == companies.companies_pk); the
+ *   source org uuid is remapped to the target org uuid, and every other copied uuid PK is remapped to a
+ *   fresh uuid so intra-org references rewire automatically. References to non-copied rows (users,
+ *   global templates) are left untouched. Emails are scrubbed so the source customer gets no mail.
+ *
+ * SAFETY
+ *   - DRY-RUN BY DEFAULT ("dummy" mode): prints the full plan and writes NOTHING. Pass --execute to write.
+ *   - Writing to the dooer-production namespace additionally requires --confirm-production.
+ *   - All writes run inside ONE transaction on the target; any error rolls the whole copy back.
+ *   - Referenced users missing from the target ARE copied (customer emails anonymized); existing users and
+ *     the target org's own account/owners are left as-is. Never creates brand-new login users.
+ *
+ * RESILIENCE (flaky VPN)
+ *   - Reads reconnect + retry on a dropped connection (pass-1, discovery, strategy/guard reads, file-id read).
+ *   - The remap salt is derived from (source, target), so RE-RUNNING the same copy yields identical ids.
+ *   - --only / --skip-tables copy a subset (pass-1 still scans all → cross-refs remap), so a big org can be
+ *     copied in survivable chunks; re-run with the same --target and --if-target-nonempty insert. See GUIDE.md.
+ *
+ * CONNECTION
+ *   Per namespace it reads the dooer-database ClusterIP and the postgres password from kubectl
+ *   (requires VPN access to the ClusterIP). Nothing is written to disk.
+ *
+ * USAGE   (see GUIDE.md for full examples)
+ *   node seed-test-account.js --source <uuid> --target <uuid> \
+ *        [--source-namespace dooer-staging] [--target-namespace dooer-staging] \
+ *        [--execute] [--confirm-production] [--email testcustomer@dooer.com]
+ *   node seed-test-account.js --source <uuid> --name "Copy of X" --owner-user <uuid> --execute
+ */
+
+const { execFileSync } = require('child_process')
+const crypto = require('crypto')
+const path = require('path')
+const { Client, types } = require('pg')
+const copyFrom = require('pg-copy-streams').from
+const Cursor = require('pg-cursor')
+const { Readable } = require('stream')
+const { pipeline } = require('stream/promises')
+const { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand } = require('@aws-sdk/client-s3')
+
+// Read date/timestamp columns as their raw Postgres text (no JS Date round-trip), so COPY writes them
+// back verbatim with no timezone drift. numeric/int8/uuid already come back as strings.
+types.setTypeParser(1082, (v) => v) // date
+types.setTypeParser(1114, (v) => v) // timestamp
+types.setTypeParser(1184, (v) => v) // timestamptz
+// Read json/jsonb as RAW TEXT too: node-pg parses a jsonb value of `null` into JS null, which is
+// indistinguishable from a SQL NULL — writing it back as SQL NULL breaks NOT-NULL jsonb columns.
+// Raw text keeps JSON null as the string "null" (distinct from a real SQL NULL, which stays JS null).
+types.setTypeParser(114, (v) => v) // json
+types.setTypeParser(3802, (v) => v) // jsonb
+
+// ── args ─────────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const a = {
+    emailScrub: 'testcustomer@dooer.com',
+    sourceNamespace: 'dooer-staging',
+    mapPath: path.join(__dirname, 'schema-map.json'),
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i]
+    const val = () => argv[++i]
+    if (k === '--source') a.source = val()
+    else if (k === '--target') a.target = val()
+    else if (k === '--name') a.name = val()
+    else if (k === '--owner-user') a.ownerUser = val()
+    else if (k === '--source-namespace') a.sourceNamespace = val()
+    else if (k === '--target-namespace') a.targetNamespace = val()
+    else if (k === '--email') a.emailScrub = val()
+    else if (k === '--map') a.mapPath = val()
+    else if (k === '--execute') a.execute = true
+    else if (k === '--skip-files') a.skipFiles = true
+    else if (k === '--skip-users') a.skipUsers = true
+    else if (k === '--confirm-production') a.confirmProduction = true
+    else if (k === '--if-target-nonempty') a.ifTargetNonempty = val()
+    // refuse (default) | insert
+    else if (k === '--salt') a.salt = val()
+    // extra entropy folded into the deterministic remap salt
+    else if (k === '--only')
+      a.only = val()
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    // copy ONLY these tables (pass-1 still scans all)
+    else if (k === '--skip-tables')
+      a.skipTables = val()
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    // copy all EXCEPT these
+    else if (k === '-h' || k === '--help') a.help = true
+    else throw new Error(`unknown argument: ${k}`)
+  }
+  if (!a.targetNamespace) a.targetNamespace = a.sourceNamespace
+  if (!a.ifTargetNonempty) a.ifTargetNonempty = 'refuse'
+  return a
+}
+
+const HELP = `seed-test-account — copy one Dooer org's data into another (test) org.
+
+Required:
+  --source <uuid>              org to copy FROM (the real company)
+  --target <uuid>              org to copy INTO (existing test entity)
+   ...or, to create a new target org:
+  --name "<string>"            name for a new target company row (source's row is cloned, name replaced)
+  --owner-user <uuid>          user to set as the new org's owner (companies2users) — REQUIRED when creating
+
+Optional:
+  --source-namespace <ns>      default dooer-staging
+  --target-namespace <ns>      default = source-namespace (set differently to copy across clusters,
+                               e.g. --source-namespace dooer-production --target-namespace dooer-staging)
+  --email <addr>               address to scrub every email column to (default testcustomer@dooer.com)
+  --skip-users                 do NOT copy referenced users missing from the target (default: copy them,
+                               anonymizing customer-role emails). Same-namespace copies are a no-op anyway.
+  --if-target-nonempty refuse|insert   what to do if a copy table already has target-org rows (default refuse)
+  --only <a.b,c.d>             copy ONLY these tables (pass-1 still scans all, so cross-refs remap). For
+                               resuming/chunking a big copy over a flaky link — re-run with the SAME
+                               --target and --if-target-nonempty insert. Keep transactions + its twins together.
+  --skip-tables <a.b,c.d>      copy all tables EXCEPT these (same chunking use)
+  --salt <string>              extra entropy folded into the remap salt (normally unneeded; the salt is
+                               already derived from source+target so re-runs are deterministic/resumable)
+  --execute                    actually write (default is DRY-RUN / "dummy": plan only, no writes)
+  --confirm-production         REQUIRED to write when --target-namespace is dooer-production
+  --map <path>                 schema map (default ./schema-map.json)
+`
+
+// ── kubectl-sourced connection ───────────────────────────────────────────────
+function sh(file, args) {
+  return execFileSync(file, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).trim()
+}
+function connInfo(namespace) {
+  const clusterIP = sh('kubectl', ['get', 'svc', 'dooer-database', '-n', namespace, '-o', 'jsonpath={.spec.clusterIP}'])
+  const b64 = sh('kubectl', [
+    'get',
+    'secret',
+    'postgres.dooer-database.credentials.postgresql.acid.zalan.do',
+    '-n',
+    namespace,
+    '-o',
+    'jsonpath={.data.password}',
+  ])
+  const password = Buffer.from(b64, 'base64').toString('utf8')
+  if (!clusterIP || !password) throw new Error(`could not read dooer-database conn info for namespace ${namespace}`)
+  return { host: clusterIP, port: 5432, user: 'postgres', password, database: 'dooer' }
+}
+async function rawConnect(namespace) {
+  const info = connInfo(namespace)
+  const client = new Client({
+    ...info,
+    ssl: { rejectUnauthorized: false },
+    statement_timeout: 0,
+    keepAlive: true, // TCP keepalive so an idle connection is not dropped during the long file phase
+    keepAliveInitialDelayMillis: 30000,
+  })
+  // An unexpected disconnect emits 'error'; unhandled it crashes the process. Swallow+log so the
+  // caller's next query surfaces the failure normally and we can reconnect. Marked so callers detect it.
+  client.on('error', (e) => {
+    client._seedDead = e
+    console.error(`\n[pg ${namespace}] connection error: ${e.message}`)
+  })
+  await client.connect()
+  return client
+}
+
+// A self-healing connection: `.query()` retries transient drops, reconnecting a dead client first, so a
+// flaky VPN (read ETIMEDOUT / "Connection terminated unexpectedly") doesn't kill a read. `.client`
+// exposes the live pg Client for the streaming paths (cursor / COPY), which are retried a level up (whole
+// table) since a mid-stream drop can't resume the same statement.
+async function connect(namespace) {
+  let client = await rawConnect(namespace)
+  return {
+    namespace,
+    get client() {
+      return client
+    },
+    async reconnect() {
+      try {
+        await client.end()
+      } catch (_) {}
+      client = await rawConnect(namespace)
+      return client
+    },
+    async query(sql, params) {
+      return withRetry(
+        async () => {
+          if (client._seedDead) await this.reconnect()
+          try {
+            return await client.query(sql, params)
+          } catch (e) {
+            if (isTransient(e)) await this.reconnect()
+            throw e
+          }
+        },
+        { label: `query ${namespace}` }
+      )
+    },
+    async end() {
+      try {
+        await client.end()
+      } catch (_) {}
+    },
+  }
+}
+
+// transient = a network/server hiccup worth retrying (vs a real SQL/logic error, which must surface)
+function isTransient(e) {
+  return /terminat|ECONNRESET|ETIMEDOUT|EPIPE|socket hang up|Connection terminated|timeout|503|500|InternalError|RequestTimeout|SlowDown|Client has encountered a connection error/i.test(
+    `${e.name} ${e.message} ${e.code || ''} ${e.$metadata?.httpStatusCode || ''}`
+  )
+}
+
+// run an async op with a few retries on transient network/S3 errors (exponential-ish backoff)
+async function withRetry(fn, { tries = 6, label = 'op' } = {}) {
+  let last
+  for (let i = 0; i < tries; i++) {
+    try {
+      return await fn()
+    } catch (e) {
+      last = e
+      if (i === tries - 1 || !isTransient(e)) throw e
+      const wait = Math.min(8000, 500 * 2 ** i)
+      process.stderr.write(`\n[retry ${label}] ${e.message} — attempt ${i + 2}/${tries} in ${wait}ms\n`)
+      await new Promise((r) => setTimeout(r, wait))
+    }
+  }
+  throw last
+}
+
+// ── S3 (Ceph RGW) file copy ──────────────────────────────────────────────────
+// The file bytes for a copied fileData row live in S3 keyed by the fileData id. We copy each object
+// from the SOURCE env bucket to the TARGET env bucket at its NEW key (= the copied fileData id), so the
+// copy owns its own files. Endpoint/bucket/credentials are read from the file-storage pod per namespace.
+function s3Config(namespace) {
+  const pods = sh('kubectl', [
+    'get',
+    'pods',
+    '-n',
+    namespace,
+    '-o',
+    'jsonpath={range .items[*]}{.metadata.name}{"\\n"}{end}',
+  ])
+    .split('\n')
+    .filter((p) => /^service-file-storage-[a-z0-9]+-[a-z0-9]+$/.test(p))
+  const pod = pods[0]
+  if (!pod) throw new Error(`no service-file-storage pod found in ${namespace} (needed for the S3 file copy)`)
+  const allEnv = sh('kubectl', ['exec', '-n', namespace, pod, '--', 'env'])
+  const env = (v) => {
+    const m = allEnv.match(new RegExp('^' + v + '=(.*)$', 'm'))
+    return m ? m[1] : ''
+  }
+  const svcName = env('AWS_ENDPOINT_URL_S3')
+    .replace(/^https?:\/\//, '')
+    .split('.')[0]
+  const clusterIP = sh('kubectl', ['get', 'svc', svcName, '-n', 'rook-ceph', '-o', 'jsonpath={.spec.clusterIP}'])
+  const endpoint = `http://${clusterIP}:80`
+  const mk = (ak, sk) =>
+    new S3Client({
+      endpoint,
+      region: 'us-east-1',
+      forcePathStyle: true,
+      credentials: { accessKeyId: ak, secretAccessKey: sk },
+    })
+  const cfg = {
+    primary: {
+      bucket: env('DOOER_STORAGE_PROVIDER_AMAZON_S3_BUCKET'),
+      client: mk(env('FILE_STORAGE_BUCKET_ACCESS_KEY_ID'), env('FILE_STORAGE_BUCKET_SECRET_ACCESS_KEY')),
+    },
+    fallback: null,
+  }
+  const fb = env('DOOER_STORAGE_PROVIDER_AMAZON_S3_BUCKET_FALLBACK')
+  const fak = env('FILE_STORAGE_FALLBACK_BUCKET_ACCESS_KEY_ID')
+  if (fb && fak) cfg.fallback = { bucket: fb, client: mk(fak, env('FILE_STORAGE_FALLBACK_BUCKET_SECRET_ACCESS_KEY')) }
+  return cfg
+}
+
+// get an object from a source config, trying the primary bucket then the fallback bucket
+async function s3Get(cfg, key) {
+  try {
+    return await cfg.primary.client.send(new GetObjectCommand({ Bucket: cfg.primary.bucket, Key: key }))
+  } catch (e) {
+    const notFound = e.name === 'NoSuchKey' || e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404
+    if (notFound && cfg.fallback)
+      return await cfg.fallback.client.send(new GetObjectCommand({ Bucket: cfg.fallback.bucket, Key: key }))
+    throw e
+  }
+}
+
+// copy the S3 object for every copied s3Blob row (old key → its remapped new key)
+async function copyFiles(src, args, map, remapUuid) {
+  const s3Tables = (map.s3BlobTables || [])
+    .map((k) => map.tables.find((t) => t.key === k))
+    .filter((t) => t && t.action === 'copy')
+  if (!s3Tables.length) return
+  const srcS3 = s3Config(args.sourceNamespace)
+  const tgtS3 = s3Config(args.targetNamespace)
+  for (const t of s3Tables) {
+    const f = filterClause(t, args.source)
+    // src is a self-healing connection — `.query` reconnects a client dropped during the long copy/txn
+    // and retries the read on its own.
+    const rows = await src.query(
+      `SELECT ${qIdent(t.pk.column)} AS id FROM ${qTable(t.schema, t.table)} WHERE ${f.sql}`,
+      f.params
+    )
+    const keys = rows.rows.map((r) => r.id).filter(Boolean)
+    console.log(
+      `\nS3: copying ${keys.length} ${t.key} objects (${srcS3.primary.bucket}[+fallback] → ${tgtS3.primary.bucket})…`
+    )
+    let done = 0,
+      missing = 0,
+      failed = 0,
+      idx = 0
+    const worker = async () => {
+      while (idx < keys.length) {
+        const oldKey = keys[idx++]
+        const newKey = remapUuid(oldKey)
+        try {
+          await withRetry(
+            async () => {
+              const obj = await s3Get(srcS3, oldKey) // primary then fallback
+              // buffer the body (streaming GetObject→PutObject fails against Ceph RGW)
+              const bytes = await obj.Body.transformToByteArray()
+              await tgtS3.primary.client.send(
+                new PutObjectCommand({
+                  Bucket: tgtS3.primary.bucket,
+                  Key: newKey,
+                  Body: bytes,
+                  ContentType: obj.ContentType,
+                })
+              )
+            },
+            { tries: 4, label: `S3 ${oldKey}` }
+          )
+          done++
+        } catch (e) {
+          if (e.name === 'NoSuchKey' || e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404) missing++
+          else if (++failed <= 5) console.error(`  S3 copy failed for ${oldKey}: ${e.name}`)
+        }
+        const n = done + missing + failed
+        if (n % 200 === 0)
+          process.stderr.write(`\r  S3 ${n}/${keys.length} (ok ${done}, missing ${missing}, failed ${failed})`)
+      }
+    }
+    await Promise.all(Array.from({ length: 12 }, worker))
+    process.stderr.write('\n')
+    console.log(`S3: ${t.key} — copied ${done}, missing-in-source ${missing}, failed ${failed}.`)
+    if (failed) throw new Error(`S3 copy had ${failed} failures for ${t.key} (see log)`)
+  }
+}
+
+// ── introspection helpers ────────────────────────────────────────────────────
+const qIdent = (s) => '"' + String(s).replace(/"/g, '""') + '"'
+const qTable = (schema, table) => `${qIdent(schema)}.${qIdent(table)}`
+
+async function tableExists(client, schema, table) {
+  const r = await client.query(
+    `SELECT 1 FROM information_schema.tables WHERE table_schema=$1 AND table_name=$2 AND table_type='BASE TABLE'`,
+    [schema, table]
+  )
+  return r.rowCount > 0
+}
+async function columnsOf(client, schema, table) {
+  const r = await client.query(
+    `SELECT column_name, data_type, udt_name, is_generated,
+            (column_default LIKE 'nextval(%') AS is_serial
+     FROM information_schema.columns WHERE table_schema=$1 AND table_name=$2 ORDER BY ordinal_position`,
+    [schema, table]
+  )
+  return r.rows.map((c) => ({
+    name: c.column_name,
+    type: c.data_type, // 'uuid' | 'ARRAY' | 'text' | 'integer' | ...
+    udt: c.udt_name, // '_uuid' for uuid[], 'uuid', 'text', ...
+    generated: c.is_generated !== 'NEVER',
+    serial: c.is_serial,
+  }))
+}
+const isUuid = (col) => col.type === 'uuid'
+const isUuidArray = (col) => col.type === 'ARRAY' && col.udt === '_uuid'
+const newUuid = () => crypto.randomUUID()
+
+// Deterministic derivation of a fresh uuid from a source uuid (v5-style). This lets us remap references
+// WITHOUT storing a giant old→new map: we keep only the SET of copied source uuids and recompute the
+// target uuid on demand. The salt is derived from (source, target, --salt) so RE-RUNNING the same copy
+// reproduces IDENTICAL target ids — which makes a copy idempotent/resumable over a flaky link. (Was
+// random per run.) A different target org gets different ids (its target uuid differs).
+let REMAP_SALT = crypto.randomBytes(16)
+function setRemapSalt(source, target, extra) {
+  REMAP_SALT = crypto
+    .createHash('sha256')
+    .update(`${source}|${target}|${extra || ''}`)
+    .digest()
+    .subarray(0, 16)
+}
+function deriveUuid(old) {
+  const h = crypto.createHash('sha1')
+  h.update(REMAP_SALT)
+  h.update(Buffer.from(old.replace(/-/g, ''), 'hex'))
+  const b = h.digest().subarray(0, 16)
+  b[6] = (b[6] & 0x0f) | 0x50 // version 5
+  b[8] = (b[8] & 0x3f) | 0x80 // variant
+  const x = b.toString('hex')
+  return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20, 32)}`
+}
+
+// ── uniqueness handling is CONFIG-DRIVEN (schema-map.json → uniquenessStrategies). NO column names or
+// strategies are hardcoded here; the two views below are derived from the config object.
+//   uuidRemapCols(map)     → Map("schema.table" -> [uuid col names])  (strategy: remap-uuid)
+//   nonUuidStrategies(map) → the config entries needing a per-column remap map (sequence/max-offset/text-suffix)
+function uuidRemapCols(map) {
+  const m = new Map()
+  for (const c of map.uniquenessStrategies.columns) {
+    if (c.type !== 'uuid' || c.strategy !== 'remap-uuid') continue
+    const k = `${c.schema}.${c.table}`
+    if (!m.has(k)) m.set(k, [])
+    m.get(k).push(c.column)
+  }
+  return m
+}
+const nonUuidStrategies = (map) =>
+  map.uniquenessStrategies.columns.filter((c) => c.type !== 'uuid' && c.strategy !== 'preserve')
+
+async function main(passedArgs) {
+  const args = passedArgs || parseArgs(process.argv.slice(2))
+  if (args.help) return void console.log(HELP)
+  if (!args.source) throw new Error('missing --source')
+  if (!args.target && !args.name) throw new Error('provide --target <uuid>, or --name to create a new target org')
+  if (!args.target && !args.ownerUser) throw new Error('creating a new target org requires --owner-user')
+  if (args.targetNamespace === 'dooer-production' && args.execute && !args.confirmProduction)
+    throw new Error('refusing to WRITE to dooer-production without --confirm-production')
+
+  const map = require(args.mapPath)
+  const copyTables = map.tables.filter((t) => t.action === 'copy')
+  const mode = args.execute ? 'EXECUTE' : 'DRY-RUN (dummy — no writes)'
+
+  console.log(`\n=== seed-test-account · ${mode} ===`)
+  console.log(`source: ${args.source}  @ ${args.sourceNamespace}`)
+  console.log(`target: ${args.target || `(create "${args.name}", owner ${args.ownerUser})`}  @ ${args.targetNamespace}`)
+  console.log(
+    `email scrub: ${args.emailScrub}  · copy tables: ${copyTables.length} · if-target-nonempty: ${args.ifTargetNonempty}\n`
+  )
+
+  // Always separate connections: pass 2 streams each table with a server-side cursor on `src` while
+  // COPYing into `tgt`, which cannot share one connection (even for a same-namespace copy).
+  const src = await connect(args.sourceNamespace)
+  const tgt = await connect(args.targetNamespace)
+
+  try {
+    // resolve / create the target org id
+    let targetOrg = args.target
+    let createdOrg = false
+    if (!targetOrg) {
+      targetOrg = newUuid()
+      createdOrg = true
+      // the owner user must already exist in the TARGET db (we never create users)
+      const u = await tgt.query(`SELECT 1 FROM service_accounts.users WHERE users_pk=$1`, [args.ownerUser])
+      if (!u.rowCount)
+        throw new Error(`--owner-user ${args.ownerUser} not found in service_accounts.users on ${args.targetNamespace}`)
+      console.log(
+        `${args.execute ? 'will create' : 'would create'} target org ${targetOrg} (name "${args.name}", owner ${
+          args.ownerUser
+        })`
+      )
+    } else {
+      const exists = await tgt.query(`SELECT 1 FROM service_accounts.companies WHERE companies_pk=$1`, [targetOrg])
+      if (!exists.rowCount)
+        throw new Error(
+          `target org ${targetOrg} has no service_accounts.companies row (create it first, or use --name)`
+        )
+    }
+
+    // Fix the remap salt from (source, target, --salt): re-running the same copy now derives IDENTICAL
+    // target ids, so a run interrupted by a dropped VPN can be resumed (re-run with the SAME --target)
+    // and `--only`/`--skip-tables` can copy a subset while cross-refs still remap consistently.
+    setRemapSalt(args.source, targetOrg, args.salt)
+
+    // The uuid remap keeps only the SET of copied source uuids (not a huge old→new map); the new value
+    // is derived on demand. The source org id maps to the (existing/new) target org id. `explicitRemap`
+    // pins specific old→new ids that are NOT derived — used for referenced users that already exist in
+    // the target under a different pk (matched by natural key), so refs point at the existing user.
+    const sourceUuids = new Set()
+    const explicitRemap = new Map()
+    const remapUuid = (v) =>
+      v === args.source
+        ? targetOrg
+        : explicitRemap.has(v)
+        ? explicitRemap.get(v)
+        : sourceUuids.has(v)
+        ? deriveUuid(v)
+        : v
+    const columnRemap = new Map() // "schema.table.column" -> Map(oldValueString -> newValue)
+    const uuidColsByTable = uuidRemapCols(map) // "schema.table" -> [uuid cols], from config
+
+    // PASS 1 — collect source PKs, allocate new ids (one query per table; progress to stderr)
+    const plan = []
+    let idx = 0
+    for (const t of copyTables) {
+      idx++
+      process.stderr.write(`\r[pass1 ${idx}/${copyTables.length}] ${t.key.slice(0, 52).padEnd(52)}`)
+      const okSrc = await tableExists(src, t.schema, t.table)
+      const okTgt = await tableExists(tgt, t.schema, t.table)
+      if (!okSrc || !okTgt) {
+        plan.push({ t, skipped: `missing in ${!okSrc ? 'source' : 'target'}`, count: 0 })
+        continue
+      }
+      const filters = filterClause(t, args.source)
+      if (!filters) {
+        plan.push({ t, skipped: 'no filter column', count: 0 })
+        continue
+      }
+      // cache the source columns (reused in pass 2); validate the config's uuid-remap columns exist here
+      const srcCols = await columnsOf(src, t.schema, t.table)
+      const srcColNames = new Set(srcCols.map((c) => c.name))
+      const freshen = (uuidColsByTable.get(t.key) || []).filter((c) => srcColNames.has(c))
+      let count
+      if (freshen.length) {
+        // one query fetches count + every unique-uuid value to add to the source-uuid set
+        const sel = freshen.map((c) => qIdent(c)).join(',')
+        const rows = await src.query(
+          `SELECT ${sel} FROM ${qTable(t.schema, t.table)} WHERE ${filters.sql}`,
+          filters.params
+        )
+        count = rows.rowCount
+        for (const row of rows.rows) for (const c of freshen) if (row[c]) sourceUuids.add(row[c])
+      } else {
+        const { rows } = await src.query(
+          `SELECT count(*)::int AS c FROM ${qTable(t.schema, t.table)} WHERE ${filters.sql}`,
+          filters.params
+        )
+        count = rows[0].c
+      }
+      plan.push({ t, count, srcCols })
+    }
+    process.stderr.write('\n')
+
+    const totalRows = plan.reduce((n, p) => n + (p.skipped ? 0 : p.count), 0)
+    console.log('--- plan (tables with rows) ---')
+    for (const p of plan.filter((p) => p.count > 0 || p.skipped)) {
+      if (p.skipped) console.log(`  SKIP  ${p.t.key.padEnd(48)} (${p.skipped})`)
+      else
+        console.log(
+          `  copy  ${p.t.key.padEnd(48)} ${String(p.count).padStart(8)} rows${
+            p.t.emailColumns.length ? `  [scrub ${p.t.emailColumns.join(',')}]` : ''
+          }${p.t.special ? '  [special]' : ''}`
+        )
+    }
+    console.log(`\ntotal rows to copy: ${totalRows} · distinct uuid values remapped: ${sourceUuids.size}`)
+
+    // PASS 1b — referenced users. Copied rows point at users (createdByUserId, fk_users_pk, …) that may
+    // not exist in the target namespace (cross-namespace copy) → resolvers like `createdByUser` dangle.
+    // Collect the ids in the configured user-ref columns, look each up in source (role) and target
+    // (existence), and copy ONLY the ones missing from the target — with a new id (added to the remap
+    // set so refs follow) and emails anonymized for `customer`-role users. Users already in the target
+    // are left untouched and their refs keep the original id.
+    const usersToCopy = [] // [{ oldId, role, anonymize }]
+    if (map.userTable && !args.skipUsers) {
+      const ut = map.userTable
+      const candidate = new Set()
+      for (const rc of map.userRefColumns || []) {
+        const p = plan.find((pp) => pp.t.key === `${rc.schema}.${rc.table}` && !pp.skipped && pp.count > 0)
+        if (!p || !(p.srcCols || []).some((c) => c.name === rc.column)) continue
+        const f = filterClause(p.t, args.source)
+        const { rows } = await withRetry(
+          () =>
+            src.query(
+              `SELECT DISTINCT ${qIdent(rc.column)} AS v FROM ${qTable(rc.schema, rc.table)} WHERE ${
+                f.sql
+              } AND ${qIdent(rc.column)} IS NOT NULL`,
+              f.params
+            ),
+          { label: `userref ${rc.table}.${rc.column}` }
+        )
+        for (const r of rows) if (r.v) candidate.add(r.v)
+      }
+      const ids = [...candidate]
+      let matched = 0
+      if (ids.length) {
+        const srcU = (
+          await src.query(
+            `SELECT ${qIdent(ut.pk)} AS id, ${qIdent(ut.roleColumn)} AS role, email, ${qIdent(
+              'id_number'
+            )} AS id_number FROM ${qTable(ut.schema, ut.table)} WHERE ${qIdent(ut.pk)} = ANY($1)`,
+            [ids]
+          )
+        ).rows
+        // (1) exact pk already in target → ref stays valid, do nothing
+        const tgtPk = new Set(
+          (
+            await tgt.query(
+              `SELECT ${qIdent(ut.pk)} AS id FROM ${qTable(ut.schema, ut.table)} WHERE ${qIdent(ut.pk)} = ANY($1)`,
+              [ids]
+            )
+          ).rows.map((r) => r.id)
+        )
+        const unresolved = srcU.filter((u) => !tgtPk.has(u.id))
+        // (2) non-customer users often exist in the target under a DIFFERENT pk (same person across
+        // namespaces). Match by the natural unique key (email|id_number, role) and pin the ref to the
+        // EXISTING target pk (never a duplicate → never a (email,role)/(id_number,role) unique clash).
+        const nonCust = unresolved.filter((u) => !(ut.anonymizeRoles || []).includes(u.role))
+        const emails = [...new Set(nonCust.map((u) => u.email).filter(Boolean))]
+        const idnums = [...new Set(nonCust.map((u) => u.id_number).filter(Boolean))]
+        const byEmail = new Map()
+        const byId = new Map()
+        if (emails.length || idnums.length) {
+          const tm = (
+            await tgt.query(
+              `SELECT ${qIdent(ut.pk)} AS id, ${qIdent(ut.roleColumn)} AS role, email, ${qIdent(
+                'id_number'
+              )} AS id_number FROM ${qTable(ut.schema, ut.table)} WHERE email = ANY($1) OR ${qIdent(
+                'id_number'
+              )} = ANY($2)`,
+              [emails, idnums]
+            )
+          ).rows
+          for (const m of tm) {
+            if (m.email) byEmail.set(`${m.role}|${m.email}`, m.id)
+            if (m.id_number) byId.set(`${m.role}|${m.id_number}`, m.id)
+          }
+        }
+        for (const u of unresolved) {
+          const anonymize = (ut.anonymizeRoles || []).includes(u.role)
+          const hit =
+            !anonymize &&
+            ((u.email && byEmail.get(`${u.role}|${u.email}`)) || (u.id_number && byId.get(`${u.role}|${u.id_number}`)))
+          if (hit) {
+            explicitRemap.set(u.id, hit) // ref → existing target user (no copy)
+            matched++
+            continue
+          }
+          sourceUuids.add(u.id) // will be copied with a new derived id → refs to it now remap
+          usersToCopy.push({ oldId: u.id, role: u.role, anonymize })
+        }
+      }
+      const anon = usersToCopy.filter((u) => u.anonymize).length
+      console.log(
+        `referenced users: ${candidate.size} distinct · matched to existing target users: ${matched} · copied new: ${
+          usersToCopy.length
+        } (customer-anonymized: ${anon}, as-is: ${usersToCopy.length - anon})`
+      )
+    }
+
+    // --only / --skip-tables filter the WRITE phase only (pass-1 already scanned EVERY table, so the uuid
+    // remap set is complete and cross-references into skipped tables still resolve). Lets a big org be
+    // copied in survivable chunks over a flaky link: re-run with the same --target (→ same salt) and a
+    // different --only, using --if-target-nonempty insert. Keep FK-linked int-key tables together —
+    // transactions + its 5 twins share a per-run sequence remap (see GUIDE.md).
+    const willCopy = (key) => (!args.only || args.only.includes(key)) && !(args.skipTables || []).includes(key)
+
+    // target-nonempty guard (only over the tables this run will actually write)
+    if (args.ifTargetNonempty === 'refuse') {
+      const nonEmpty = []
+      for (const p of plan) {
+        if (p.skipped || p.count === 0 || !willCopy(p.t.key)) continue
+        const f = filterClause(p.t, targetOrg)
+        const r = await tgt.query(
+          `SELECT count(*)::int AS c FROM ${qTable(p.t.schema, p.t.table)} WHERE ${f.sql}`,
+          f.params
+        )
+        if (r.rows[0].c > 0) nonEmpty.push(`${p.t.key} (${r.rows[0].c})`)
+      }
+      if (nonEmpty.length) {
+        console.log(
+          `\nTARGET NOT EMPTY in ${nonEmpty.length} copy table(s): ${nonEmpty.slice(0, 10).join(', ')}${
+            nonEmpty.length > 10 ? ' …' : ''
+          }`
+        )
+        if (args.execute)
+          throw new Error(
+            'refusing: target already has rows in copy tables (pass --if-target-nonempty insert to override)'
+          )
+      }
+    }
+
+    if (!args.execute) {
+      console.log('\nDRY-RUN complete — nothing was written. Re-run with --execute to perform the copy.\n')
+      return
+    }
+
+    // PASS 2 — write, inside one transaction, FK/triggers disabled for the load. Transactional statements
+    // use the RAW client (tgt.client): a mid-transaction drop must fail this run (→ rollback), never
+    // silently reconnect onto a fresh connection with no open transaction. (Resumable mode, which commits
+    // per table and can survive drops, is a separate path — see --resumable.)
+    await tgt.client.query('BEGIN')
+    await tgt.client.query("SET session_replication_role = 'replica'") // disable FK + user triggers for the bulk load
+    let written = 0
+
+    // --name: create the target org (clone the source companies row + link the owner) before copying
+    if (createdOrg) {
+      await createTargetOrg(src, tgt, args, targetOrg)
+      written += 2
+    }
+
+    // build a per-column old->new map for every non-uuid unique column, per its CONFIG strategy, and
+    // register it under the owning column AND every FK column that references it (so refs stay consistent).
+    for (const s of nonUuidStrategies(map)) {
+      const pe = plan.find((p) => p.t.key === `${s.schema}.${s.table}` && !p.skipped && p.count > 0)
+      if (!pe) continue
+      const f = filterClause(pe.t, args.source)
+      const srcRows = await src.query(
+        `SELECT ${qIdent(s.column)} AS v FROM ${qTable(s.schema, s.table)} WHERE ${f.sql} ORDER BY 1`,
+        f.params
+      )
+      const m = new Map()
+      if (s.strategy === 'sequence') {
+        // reserve all the fresh ids in ONE round-trip (was one nextval() per row)
+        const nonNull = srcRows.rows.filter((r) => r.v != null)
+        if (nonNull.length) {
+          const nv = await tgt.client.query(`SELECT nextval($1)::bigint AS v FROM generate_series(1, $2)`, [
+            s.sequenceName,
+            nonNull.length,
+          ])
+          nonNull.forEach((r, i) => m.set(String(r.v), Number(nv.rows[i].v)))
+        }
+      } else if (s.strategy === 'max-offset') {
+        const mx = await tgt.client.query(
+          `SELECT COALESCE(max(${qIdent(s.column)}), 0)::bigint AS m FROM ${qTable(s.schema, s.table)}`
+        )
+        let base = Number(mx.rows[0].m)
+        for (const r of srcRows.rows) if (r.v != null) m.set(String(r.v), ++base)
+      } else if (s.strategy === 'text-suffix') {
+        // deterministic suffix (hash of salt+value) so a re-run/chunk reproduces the same value
+        for (const r of srcRows.rows)
+          if (r.v != null)
+            m.set(
+              String(r.v),
+              `${r.v}-seedcopy-${crypto
+                .createHash('sha1')
+                .update(REMAP_SALT)
+                .update(String(r.v))
+                .digest('hex')
+                .slice(0, 8)}`
+            )
+      }
+      columnRemap.set(`${s.schema}.${s.table}.${s.column}`, m)
+      for (const ref of s.references || []) columnRemap.set(`${ref.schema}.${ref.table}.${ref.column}`, m)
+    }
+
+    const remapTextStoredUuids = map.options ? map.options.remapTextStoredUuids !== false : true
+
+    // referenced users missing from the target (discovered in pass 1b) — copy them before the data rows
+    // that reference them so every user ref resolves. New derived id + anonymized customer emails.
+    if (usersToCopy.length) {
+      const nu = await copyUsers(src, tgt, usersToCopy, map.userTable, {
+        remapUuid,
+        columnRemap,
+        targetOrg,
+        remapTextStoredUuids,
+        emailScrub: args.emailScrub,
+      })
+      written += nu
+      console.log(`copied ${nu} referenced user(s) into ${args.targetNamespace} (missing there before).`)
+    }
+
+    const toCopy = plan.filter((p) => !p.skipped && p.count > 0 && willCopy(p.t.key))
+    let ci = 0
+    for (const p of toCopy) {
+      ci++
+      process.stderr.write(
+        `\r[copy ${ci}/${toCopy.length}] ${p.t.key.slice(0, 46).padEnd(46)} ${String(p.count).padStart(8)} rows`
+      )
+      written += await copyTable(src, tgt, p, args, { remapUuid, columnRemap, targetOrg, remapTextStoredUuids })
+    }
+    process.stderr.write('\n')
+
+    await tgt.client.query("SET session_replication_role = 'origin'")
+    await tgt.client.query('COMMIT')
+    console.log(`\nEXECUTE complete — ${written} rows written to ${targetOrg} @ ${args.targetNamespace}.`)
+    if (createdOrg) console.log(`Created org ${targetOrg} ("${args.name}") with owner ${args.ownerUser} (role Owner).`)
+    // copy the actual files (S3) for every copied blob row — on by default (skip with --skip-files)
+    if (!args.skipFiles) await copyFiles(src, args, map, remapUuid)
+    else
+      console.log('(--skip-files: S3 objects NOT copied; copied documents will have broken file links until copied.)')
+  } catch (e) {
+    if (args.execute) {
+      try {
+        await tgt.client.query('ROLLBACK')
+      } catch (_) {}
+    }
+    throw e
+  } finally {
+    await src.end()
+    await tgt.end()
+  }
+}
+
+// build the `<col> IN (SELECT <parentCol> FROM <parent> WHERE …)` clause for an orphan's fkFilter.
+// Terminal hop: the parent has an org column (`parentOrgColumn=$1`). Multi-level: the parent is itself
+// an orphan (`parentFilter`) → recurse so the whole chain roots at an org-scoped ancestor.
+function fkFilterSql(f) {
+  const inner = f.parentOrgColumn ? `${qIdent(f.parentOrgColumn)}=$1` : fkFilterSql(f.parentFilter)
+  return `${qIdent(f.column)} IN (SELECT ${qIdent(f.parentColumn)} FROM ${qTable(
+    f.parentSchema,
+    f.parentTable
+  )} WHERE ${inner})`
+}
+
+// build a WHERE clause selecting the org's own rows (+ an optional per-table extraFilter, which may
+// reference $1 = the org id — e.g. restrict a big table to rows tied to an active task)
+function filterClause(t, orgId, { includeExtra = true } = {}) {
+  let sql
+  if (t.special && t.special.some((s) => s.startsWith('crossOrgRelation'))) {
+    sql = `(parent_company_id=$1 OR child_company_id=$1)`
+  } else if (t.fkFilter) {
+    // orphan child table (no org column): select rows whose FK points into a copied parent's org rows.
+    // A multi-level orphan (child of an orphan, e.g. document_files_converted → document_files →
+    // documents) carries a NESTED parentFilter instead of a terminal parentOrgColumn — recurse.
+    sql = fkFilterSql(t.fkFilter)
+  } else if (!t.filterColumn) {
+    return null
+  } else {
+    sql = `${qIdent(t.filterColumn)}=$1`
+  }
+  // extraFilter (e.g. the active-task restriction) narrows a COPY; a PURGE must remove ALL the org's rows,
+  // so callers deleting data pass includeExtra:false.
+  if (t.extraFilter && includeExtra) sql = `${sql} AND (${t.extraFilter})`
+  return { sql, params: [orgId] }
+}
+
+// --name path: create the target org by cloning the source companies row (fresh id / name / short_name
+// / api_uuid) and linking the given owner user with role 'Owner'. Never creates the user itself.
+async function createTargetOrg(src, tgt, args, targetOrg) {
+  const cols = (await columnsOf(src, 'service_accounts', 'companies')).filter((c) => !c.generated)
+  const row = (
+    await src.query(
+      `SELECT ${cols.map((c) => qIdent(c.name)).join(',')} FROM service_accounts.companies WHERE companies_pk=$1`,
+      [args.source]
+    )
+  ).rows[0]
+  if (!row) throw new Error(`source companies row ${args.source} not found`)
+  const slug =
+    args.name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 40) || 'org'
+  const overrides = {
+    companies_pk: targetOrg,
+    company_name: args.name,
+    short_name: `${slug}-${newUuid().slice(0, 8)}`, // short_name is UNIQUE
+    api_uuid: newUuid(),
+  }
+  const vals = cols.map((c) => {
+    if (Object.prototype.hasOwnProperty.call(overrides, c.name)) return overrides[c.name]
+    let v = row[c.name]
+    if ((c.type === 'jsonb' || c.type === 'json') && v != null) v = JSON.stringify(v)
+    return v
+  })
+  await tgt.client.query(
+    `INSERT INTO service_accounts.companies (${cols.map((c) => qIdent(c.name)).join(',')}) VALUES (${cols
+      .map((_, i) => `$${i + 1}`)
+      .join(',')})`,
+    vals
+  )
+  await tgt.client.query(
+    `INSERT INTO service_accounts.companies2users (fk_companies_pk, fk_users_pk, fk_user_roles_at_companies_pk, api_uuid) VALUES ($1,$2,'Owner',$3)`,
+    [targetOrg, args.ownerUser, newUuid()]
+  )
+}
+
+// ── COPY (text format) encoding — much faster than row-by-row INSERT ─────────
+// escape a field for COPY text format: backslash, tab, newline, CR
+const copyEscape = (s) => s.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')
+// Postgres array literal for a JS array (quote every element; NULL for null)
+function arrayLiteral(arr) {
+  return (
+    '{' +
+    arr
+      .map((el) =>
+        el === null || el === undefined ? 'NULL' : '"' + String(el).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+      )
+      .join(',') +
+    '}'
+  )
+}
+// encode one already-remapped value for its column's type into a COPY field
+function encodeCopyField(col, v) {
+  if (v === null || v === undefined) return '\\N'
+  if (col.type === 'ARRAY') return copyEscape(arrayLiteral(Array.isArray(v) ? v : [v]))
+  if (col.type === 'boolean') return v ? 't' : 'f'
+  if (col.type === 'jsonb' || col.type === 'json') return copyEscape(typeof v === 'string' ? v : JSON.stringify(v))
+  return copyEscape(String(v))
+}
+
+// copy one table's source rows into the target via COPY … FROM STDIN. Reads the source with a
+// server-side CURSOR in batches (constant memory regardless of table size) and streams each batch
+// into the COPY with backpressure. Requires src and tgt to be separate connections.
+const READ_BATCH = 2000
+async function copyTable(src, tgt, p, args, ctx) {
+  const { remapUuid, columnRemap, targetOrg, remapTextStoredUuids } = ctx
+  const t = p.t
+  const srcCols = p.srcCols || (await columnsOf(src, t.schema, t.table))
+  const tgtCols = await columnsOf(tgt, t.schema, t.table)
+  const tgtNames = new Set(tgtCols.map((c) => c.name))
+  // insertable columns = present in both, not generated
+  const cols = srcCols.filter((c) => tgtNames.has(c.name) && !c.generated)
+  const f = filterClause(t, args.source)
+  const colList = cols.map((c) => qIdent(c.name)).join(',')
+  const rctx = {
+    remapUuid,
+    columnRemap,
+    targetOrg,
+    emailSet: new Set(t.emailColumns || []),
+    emailScrub: args.emailScrub,
+    table: t,
+    remapTextStoredUuids,
+  }
+
+  const cursor = src.client.query(
+    new Cursor(`SELECT ${colList} FROM ${qTable(t.schema, t.table)} WHERE ${f.sql}`, f.params)
+  )
+  const readBatch = () =>
+    new Promise((resolve, reject) => cursor.read(READ_BATCH, (err, rows) => (err ? reject(err) : resolve(rows))))
+  const closeCursor = () => new Promise((resolve) => cursor.close(() => resolve()))
+
+  let n = 0
+  // async generator pulls a batch at a time from the cursor (constant memory) and yields COPY lines;
+  // pipeline() wires it to the COPY stream with backpressure AND one clean error path (any COPY/read
+  // error rejects here and is caught by the caller → transaction rollback).
+  async function* lines() {
+    for (let batch = await readBatch(); batch.length; batch = await readBatch()) {
+      for (const row of batch) {
+        yield cols.map((c) => encodeCopyField(c, remapValue(c, row[c.name], rctx))).join('\t') + '\n'
+      }
+      n += batch.length
+    }
+  }
+  try {
+    await pipeline(
+      Readable.from(lines()),
+      tgt.client.query(copyFrom(`COPY ${qTable(t.schema, t.table)} (${colList}) FROM STDIN`))
+    )
+  } finally {
+    await closeCursor()
+  }
+  return n
+}
+
+// copy specific referenced-user rows into the target (the ones missing there). Each gets a new derived
+// id (already added to sourceUuids, so refs follow); `customer`-role rows get a UNIQUE anonymized email
+// (per the `(email, role)` unique key) and their PII/credential columns (id_number, password_hash)
+// nulled. Every other column goes through the normal value remap. Small set → one plain SELECT, no cursor.
+async function copyUsers(src, tgt, users, ut, ctx) {
+  const { remapUuid } = ctx
+  const oldIds = users.map((u) => u.oldId)
+  const meta = new Map(users.map((u) => [u.oldId, u]))
+  const srcCols = (await columnsOf(src, ut.schema, ut.table)).filter((c) => !c.generated)
+  const tgtNames = new Set((await columnsOf(tgt, ut.schema, ut.table)).map((c) => c.name))
+  const cols = srcCols.filter((c) => tgtNames.has(c.name))
+  const colList = cols.map((c) => qIdent(c.name)).join(',')
+  const emailSet = new Set(ut.emailColumns || [])
+  const nullSet = new Set(ut.nullColumns || [])
+  const pattern = ut.anonymizedEmailPattern || 'testcustomer+u<id>@dooer.com'
+  // neutralise the generic email scrub — user emails are handled explicitly (unique per row) below
+  const rctx = { ...ctx, emailSet: new Set(), table: { key: `${ut.schema}.${ut.table}`, emailColumns: [] } }
+  const { rows } = await src.query(
+    `SELECT ${colList} FROM ${qTable(ut.schema, ut.table)} WHERE ${qIdent(ut.pk)} = ANY($1)`,
+    [oldIds]
+  )
+  function* lines() {
+    for (const row of rows) {
+      const m = meta.get(row[ut.pk])
+      const newId = remapUuid(row[ut.pk])
+      yield cols
+        .map((c) => {
+          if (m.anonymize && emailSet.has(c.name))
+            return encodeCopyField(c, row[c.name] == null ? null : pattern.replace('<id>', newId.replace(/-/g, '')))
+          if (m.anonymize && nullSet.has(c.name)) return encodeCopyField(c, null)
+          return encodeCopyField(c, remapValue(c, row[c.name], rctx))
+        })
+        .join('\t') + '\n'
+    }
+  }
+  await pipeline(
+    Readable.from(lines()),
+    tgt.client.query(copyFrom(`COPY ${qTable(ut.schema, ut.table)} (${colList}) FROM STDIN`))
+  )
+  return rows.length
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const looksLikeUuid = (s) => s.length === 36 && UUID_RE.test(s)
+// global: every uuid-shaped substring (for remapping uuids inside raw jsonb text)
+const UUID_SUBSTR_RE_G = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
+
+// remap a single column value: json, email scrub, config-driven per-column remap, uuid, uuid[]
+function remapValue(col, value, ctx) {
+  const { remapUuid, columnRemap, emailSet, emailScrub, table, remapTextStoredUuids } = ctx
+  if (value === null || value === undefined) return value
+  // json/jsonb arrives as RAW TEXT (see type parsers). Remap uuids directly in the text: replace every
+  // uuid-shaped substring that belongs to the copy with its derived uuid. A uuid → uuid replacement is
+  // same-length + valid chars, so the JSON stays valid. This avoids JSON.parse+walk+stringify — the
+  // per-row cost that made big taskAction/ocrData/documentField payloads slow and OOM the process.
+  if (col.type === 'jsonb' || col.type === 'json') {
+    const s = typeof value === 'string' ? value : JSON.stringify(value)
+    return s.replace(UUID_SUBSTR_RE_G, (m) => remapUuid(m))
+  }
+  // email scrub (type-aware): text -> scalar, uuid never, boolean/other skipped
+  if (emailSet.has(col.name)) {
+    if (col.type === 'ARRAY' && col.udt === '_text') return [emailScrub]
+    if (col.type === 'text' || col.type === 'character varying') return emailScrub
+    // non-string email-named column (e.g. boolean flag) — leave as-is
+  }
+  // config-driven per-column remap (non-uuid unique columns: sequence / max-offset / text-suffix, plus
+  // every FK column that references them — all registered in columnRemap by "schema.table.column")
+  const cm = columnRemap.get(`${table.key}.${col.name}`)
+  if (cm) {
+    const mapped = cm.get(String(value))
+    if (mapped !== undefined) return mapped
+  }
+  // uuid columns: rewrite if part of the copy (PKs, org id, internal FKs); leave external refs untouched
+  if (isUuid(col)) return remapUuid(value)
+  if (isUuidArray(col) && Array.isArray(value)) return value.map((v) => (v ? remapUuid(v) : v))
+  // a text/varchar value equal to a copied uuid is a reference (polymorphic id stored as text) → remap
+  // (only for uuid-shaped values, so we don't hash every ordinary text field)
+  if (remapTextStoredUuids && (col.type === 'text' || col.type === 'character varying') && looksLikeUuid(value))
+    return remapUuid(value)
+  return value
+}
+
+// helpers reused by sibling commands (purge, shred, db build)
+module.exports = {
+  main,
+  parseArgs,
+  HELP,
+  connect,
+  withRetry,
+  filterClause,
+  qIdent,
+  qTable,
+  columnsOf,
+  s3Config,
+  s3Get,
+  DeleteObjectCommand,
+}
+
+// still runnable standalone (node lib/engine/seed.js …) for now
+if (require.main === module) {
+  main().catch((e) => {
+    console.error(`\nERROR: ${e.message}\n`)
+    process.exit(1)
+  })
+}