settld 0.1.2 → 0.2.0

package/scripts/backup-restore/seed-workload.mjs

@@ -0,0 +1,235 @@
+/**
+ * Seeds a deterministic workload into Postgres using the in-process API.
+ *
+ * Outputs JSON with:
+ *  - tenantId
+ *  - jobIds
+ *  - month
+ */
+import { createBackupRestoreApiClient } from "./client.mjs";
+import { makeBookedPayload } from "../../test/api-test-harness.js";
+
+const DATABASE_URL = process.env.DATABASE_URL;
+if (!DATABASE_URL) throw new Error("DATABASE_URL is required");
+
+const TENANT_ID = process.env.TENANT_ID ?? "tenant_default";
+const MONTH = process.env.MONTH ?? "2026-01";
+const JOBS = Number(process.env.JOBS ?? "10");
+const SCHEMA = process.env.PROXY_PG_SCHEMA ?? "public";
+const requireMonthCloseRaw = String(process.env.BACKUP_RESTORE_REQUIRE_MONTH_CLOSE ?? "").trim().toLowerCase();
+const REQUIRE_MONTH_CLOSE = requireMonthCloseRaw === "" ? true : requireMonthCloseRaw === "1" || requireMonthCloseRaw === "true";
+
+function log(message, details = null) {
+  const at = new Date().toISOString();
+  if (details && typeof details === "object") {
+    process.stderr.write(`[seed-workload ${at}] ${message} ${JSON.stringify(details)}\n`);
+    return;
+  }
+  process.stderr.write(`[seed-workload ${at}] ${message}\n`);
+}
+
+if (!Number.isSafeInteger(JOBS) || JOBS <= 0) throw new Error("JOBS must be a positive integer");
+if (!/^\d{4}-\d{2}$/.test(MONTH)) throw new Error("MONTH must match YYYY-MM");
+
+let nowMs = Date.parse(`${MONTH}-15T10:00:00.000Z`);
+if (!Number.isFinite(nowMs)) throw new Error("invalid MONTH timestamp anchor");
+const nowIso = () => new Date(nowMs).toISOString();
+
+const { api, request, close, tenantId } = await createBackupRestoreApiClient({
+  databaseUrl: DATABASE_URL,
+  schema: SCHEMA,
+  tenantId: TENANT_ID,
+  now: nowIso
+});
+log("api client ready", { tenantId, schema: SCHEMA, jobs: JOBS, month: MONTH });
+
+log("upserting finance account map");
+const accountMap = await request({
+  method: "PUT",
+  path: "/ops/finance/account-map",
+  body: {
+    mapping: {
+      schemaVersion: "FinanceAccountMap.v1",
+      accounts: {
+        acct_cash: "1000",
+        acct_customer_escrow: "2100",
+        acct_platform_revenue: "4000",
+        acct_owner_payable: "2000",
+        acct_operator_payable: "2010",
+        acct_insurance_reserve: "2150",
+        acct_coverage_reserve: "2160",
+        acct_coverage_unearned: "2170",
+        acct_coverage_revenue: "4010",
+        acct_coverage_payout_expense: "5100",
+        acct_insurer_receivable: "1200",
+        acct_operator_chargeback_receivable: "1210",
+        acct_claims_expense: "5200",
+        acct_claims_payable: "2200",
+        acct_operator_labor_expense: "5300",
+        acct_operator_cost_accrued: "2210",
+        acct_developer_royalty_payable: "2020",
+        acct_sla_credits_expense: "4900",
+        acct_customer_credits_payable: "2110"
+      }
+    }
+  }
+});
+if (accountMap.statusCode !== 200) throw new Error(`ops finance account-map failed: ${accountMap.statusCode} ${accountMap.body}`);
+
+log("setting month close hold policy to ALLOW_WITH_DISCLOSURE");
+const govEventsRes = await request({
+  method: "GET",
+  path: "/ops/governance/events"
+});
+if (govEventsRes.statusCode !== 200) {
+  throw new Error(`governance events read failed: ${govEventsRes.statusCode} ${govEventsRes.body}`);
+}
+const govEvents = Array.isArray(govEventsRes.json?.events) ? govEventsRes.json.events : [];
+const govPrevChainHash = govEvents.length
+  ? (typeof govEvents[govEvents.length - 1]?.chainHash === "string" ? govEvents[govEvents.length - 1].chainHash : null)
+  : null;
+const govPolicyRes = await request({
+  method: "POST",
+  path: "/ops/governance/events",
+  headers: {
+    "x-proxy-expected-prev-chain-hash": govPrevChainHash ?? "null",
+    "x-idempotency-key": "backup_month_close_policy_allow_disclosure_v1"
+  },
+  body: {
+    type: "TENANT_POLICY_UPDATED",
+    scope: "tenant",
+    payload: {
+      effectiveFrom: `${MONTH}-01T00:00:00.000Z`,
+      policy: { finance: { monthCloseHoldPolicy: "ALLOW_WITH_DISCLOSURE" } },
+      reason: "backup-restore-drill"
+    }
+  }
+});
+if (govPolicyRes.statusCode !== 200 && govPolicyRes.statusCode !== 201) {
+  throw new Error(`month close policy update failed: ${govPolicyRes.statusCode} ${govPolicyRes.body}`);
+}
+
+log("registering backup robot");
+const regRobot = await request({
+  method: "POST",
+  path: "/robots/register",
+  headers: { "x-idempotency-key": "backup_robot_reg_1" },
+  body: { robotId: "rob_backup", trustScore: 0.9, homeZoneId: "zone_a" }
+});
+if (regRobot.statusCode !== 201) throw new Error(`robot register failed: ${regRobot.statusCode} ${regRobot.body}`);
+let robotPrev = regRobot.json?.robot?.lastChainHash ?? null;
+if (!robotPrev) throw new Error("robot registration missing lastChainHash");
+
+nowMs += 1_000;
+log("setting robot availability");
+const setAvail = await request({
+  method: "POST",
+  path: "/robots/rob_backup/availability",
+  headers: { "x-idempotency-key": "backup_robot_avail_1", "x-proxy-expected-prev-chain-hash": robotPrev },
+  body: { availability: [{ startAt: `${MONTH}-01T00:00:00.000Z`, endAt: `${MONTH}-28T23:59:59.999Z` }] }
+});
+if (setAvail.statusCode !== 201) throw new Error(`robot availability failed: ${setAvail.statusCode} ${setAvail.body}`);
+robotPrev = setAvail.json?.robot?.lastChainHash ?? robotPrev;
+
+const bookingStartAt = `${MONTH}-15T10:30:00.000Z`;
+const bookingEndAt = `${MONTH}-15T11:00:00.000Z`;
+
+const jobIds = [];
+
+for (let i = 0; i < JOBS; i += 1) {
+  if (i === 0 || i === JOBS - 1 || i % 10 === 0) {
+    log("seeding jobs progress", { current: i + 1, total: JOBS });
+  }
+  const created = await request({
+    method: "POST",
+    path: "/jobs",
+    headers: { "x-idempotency-key": `backup_job_create_${i}` },
+    body: { templateId: "reset_lite", constraints: { zoneId: "zone_a" } }
+  });
+  if (created.statusCode !== 201) throw new Error(`job create failed: ${created.statusCode} ${created.body}`);
+
+  const jobId = created.json?.job?.id;
+  let prev = created.json?.job?.lastChainHash;
+  if (!jobId || !prev) throw new Error("job create did not return id/lastChainHash");
+  jobIds.push(jobId);
+
+  const postServerEvent = async (type, payload, idempotencyKey) => {
+    const res = await request({
+      method: "POST",
+      path: `/jobs/${jobId}/events`,
+      headers: { "x-proxy-expected-prev-chain-hash": prev, "x-idempotency-key": idempotencyKey },
+      body: { type, actor: { type: "system", id: "backup" }, payload }
+    });
+    if (res.statusCode !== 201) throw new Error(`post ${type} failed: ${res.statusCode} ${res.body}`);
+    prev = res.json?.job?.lastChainHash;
+    return res;
+  };
+
+  nowMs += 1_000;
+  await postServerEvent("QUOTE_PROPOSED", { amountCents: 6500 + i, currency: "USD" }, `backup_quote_${i}`);
+  nowMs += 1_000;
+  await postServerEvent(
+    "BOOKED",
+    makeBookedPayload({
+      paymentHoldId: `hold_backup_${jobId}`,
+      startAt: bookingStartAt,
+      endAt: bookingEndAt,
+      environmentTier: "ENV_MANAGED_BUILDING",
+      requiresOperatorCoverage: false,
+      customerId: "cust_backup",
+      siteId: "site_backup"
+    }),
+    `backup_book_${i}`
+  );
+  nowMs += 1_000;
+  await postServerEvent("MATCHED", { robotId: "rob_backup", operatorPartyId: "pty_operator_backup" }, `backup_match_${i}`);
+  nowMs += 1_000;
+  await postServerEvent("JOB_CANCELLED", { jobId, cancelledAt: nowIso(), reason: "OPS", requestedBy: "ops" }, `backup_cancel_${i}`);
+  nowMs += 1_000;
+  await postServerEvent("SETTLED", { settlement: "backup" }, `backup_settle_${i}`);
+}
+
+log("draining job accounting queue");
+for (let i = 0; i < 50; i += 1) {
+  const tick = await api.tickJobAccounting({ maxMessages: 200 });
+  if (!Array.isArray(tick?.processed) || tick.processed.length === 0) break;
+}
+log("draining artifact queue");
+for (let i = 0; i < 50; i += 1) {
+  const tick = await api.tickArtifacts({ maxMessages: 200 });
+  if (!Array.isArray(tick?.processed) || tick.processed.length === 0) break;
+}
+
+if (REQUIRE_MONTH_CLOSE) {
+  nowMs += 1_000;
+  log("requesting month close");
+  const closeReq = await request({ method: "POST", path: "/ops/month-close", body: { month: MONTH } });
+  if (closeReq.statusCode !== 200 && closeReq.statusCode !== 202) {
+    throw new Error(`month close request failed: ${closeReq.statusCode} ${closeReq.body}`);
+  }
+
+  let closed = false;
+  log("polling month close status");
+  for (let i = 0; i < 240; i += 1) {
+    const tick = await api.tickMonthClose({ maxMessages: 50 });
+    const failedTick = Array.isArray(tick?.processed) ? tick.processed.find((row) => row?.status === "failed") : null;
+    if (failedTick) {
+      throw new Error(`month close tick failed: ${JSON.stringify(failedTick)}`);
+    }
+    await api.tickArtifacts({ maxMessages: 200 });
+    const status = await request({ method: "GET", path: `/ops/month-close?month=${encodeURIComponent(MONTH)}` });
+    if (status.statusCode === 200 && status.json?.monthClose?.status === "CLOSED") {
+      closed = true;
+      break;
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  if (!closed) throw new Error("month close did not reach CLOSED");
+} else {
+  log("skipping month close request (set BACKUP_RESTORE_REQUIRE_MONTH_CLOSE=1 to enforce)");
+}
+
+await close();
+log("seed workload complete");
+
+process.stdout.write(JSON.stringify({ tenantId, jobIds, month: MONTH }, null, 2) + "\n");

package/scripts/backup-restore/verify-state.mjs

@@ -0,0 +1,139 @@
+/**
+ * Verifies restored DB state matches expected digests.
+ */
+import assert from "node:assert/strict";
+import fs from "node:fs";
+
+const expectedPath = process.argv[2];
+if (!expectedPath) throw new Error("usage: node scripts/backup-restore/verify-state.mjs /path/to/expected.json");
+
+const expected = JSON.parse(fs.readFileSync(expectedPath, "utf8"));
+
+// Compute actual by reusing capture-state with the current env vars.
+// We inline-import capture-state and intercept stdout by calling its logic directly.
+import pg from "pg";
+import { canonicalJsonStringify } from "../../src/core/canonical-json.js";
+import { sha256Hex } from "../../src/core/crypto.js";
+import { normalizeTenantId } from "../../src/core/tenancy.js";
+
+const DATABASE_URL = process.env.DATABASE_URL;
+if (!DATABASE_URL) throw new Error("DATABASE_URL is required");
+const TENANT_ID = normalizeTenantId(process.env.TENANT_ID ?? expected?.tenantId ?? "tenant_default");
+const SCHEMA = (() => {
+  const raw = String(process.env.PROXY_PG_SCHEMA ?? "public").trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(raw)) {
+    throw new Error("PROXY_PG_SCHEMA must match [A-Za-z_][A-Za-z0-9_]*");
+  }
+  return raw;
+})();
+
+function digestRows(rows) {
+  return sha256Hex(canonicalJsonStringify(rows));
+}
+
+const { Client } = pg;
+const client = new Client({ connectionString: DATABASE_URL });
+await client.connect();
+await client.query(`SET search_path TO "${SCHEMA}", public`);
+
+const tenantCountRes = await client.query("SELECT COUNT(DISTINCT tenant_id)::int AS n FROM snapshots");
+const jobCountRes = await client.query("SELECT COUNT(*)::int AS n FROM snapshots WHERE tenant_id = $1 AND aggregate_type = 'job'", [TENANT_ID]);
+const ledgerEntryCountRes = await client.query("SELECT COUNT(*)::int AS n FROM ledger_entries WHERE tenant_id = $1", [TENANT_ID]);
+const allocationCountRes = await client.query("SELECT COUNT(*)::int AS n FROM ledger_allocations WHERE tenant_id = $1", [TENANT_ID]);
+const artifactCountRes = await client.query("SELECT COUNT(*)::int AS n FROM artifacts WHERE tenant_id = $1", [TENANT_ID]);
+const partyStatementCountRes = await client.query("SELECT COUNT(*)::int AS n FROM party_statements WHERE tenant_id = $1", [TENANT_ID]);
+
+const artifactsRes = await client.query(
+  `
+    SELECT artifact_id, artifact_type, artifact_hash
+    FROM artifacts
+    WHERE tenant_id = $1
+      AND artifact_type IN ('SettlementStatement.v1','MonthlyStatement.v1','PartyStatement.v1','PayoutInstruction.v1')
+    ORDER BY artifact_type ASC, artifact_id ASC
+  `,
+  [TENANT_ID]
+);
+const artifactsDigest = digestRows(
+  artifactsRes.rows.map((r) => ({
+    artifactId: String(r.artifact_id),
+    artifactType: String(r.artifact_type),
+    artifactHash: String(r.artifact_hash)
+  }))
+);
+
+const ledgerEntriesRes = await client.query(
+  `
+    SELECT entry_id, entry_json
+    FROM ledger_entries
+    WHERE tenant_id = $1
+    ORDER BY entry_id ASC
+  `,
+  [TENANT_ID]
+);
+const ledgerDigest = digestRows(
+  ledgerEntriesRes.rows.map((r) => ({
+    entryId: String(r.entry_id),
+    entry: r.entry_json ?? null
+  }))
+);
+
+const allocRes = await client.query(
+  `
+    SELECT entry_id, posting_id, account_id, party_id, party_role, currency, amount_cents
+    FROM ledger_allocations
+    WHERE tenant_id = $1
+    ORDER BY entry_id ASC, posting_id ASC, party_id ASC
+  `,
+  [TENANT_ID]
+);
+const allocationsDigest = digestRows(
+  allocRes.rows.map((r) => ({
+    entryId: String(r.entry_id),
+    postingId: String(r.posting_id),
+    accountId: r.account_id === null ? null : String(r.account_id),
+    partyId: String(r.party_id),
+    partyRole: String(r.party_role),
+    currency: String(r.currency),
+    amountCents: Number(r.amount_cents)
+  }))
+);
+
+const monthEventsRes = await client.query(
+  `
+    SELECT aggregate_id, seq, event_json
+    FROM events
+    WHERE tenant_id = $1 AND aggregate_type = 'month'
+    ORDER BY aggregate_id ASC, seq ASC
+  `,
+  [TENANT_ID]
+);
+const monthEventsDigest = digestRows(
+  monthEventsRes.rows.map((r) => ({
+    monthId: String(r.aggregate_id),
+    seq: Number(r.seq),
+    event: r.event_json ?? null
+  }))
+);
+
+await client.end();
+
+const actual = {
+  tenantId: TENANT_ID,
+  counts: {
+    tenants: Number(tenantCountRes.rows?.[0]?.n ?? 0),
+    jobs: Number(jobCountRes.rows?.[0]?.n ?? 0),
+    ledgerEntries: Number(ledgerEntryCountRes.rows?.[0]?.n ?? 0),
+    allocations: Number(allocationCountRes.rows?.[0]?.n ?? 0),
+    artifacts: Number(artifactCountRes.rows?.[0]?.n ?? 0),
+    partyStatements: Number(partyStatementCountRes.rows?.[0]?.n ?? 0)
+  },
+  digests: {
+    artifacts: artifactsDigest,
+    ledgerEntries: ledgerDigest,
+    allocations: allocationsDigest,
+    monthEvents: monthEventsDigest
+  }
+};
+
+assert.deepEqual(actual, expected, "state mismatch after restore");
+process.stdout.write("ok\n");

package/scripts/backup-restore-test.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "=== Settld Backup/Restore Verification ==="
+
+if [[ -z "${DATABASE_URL:-}" ]]; then
+  echo "DATABASE_URL is required" >&2
+  exit 2
+fi
+if [[ -z "${RESTORE_DATABASE_URL:-}" ]]; then
+  echo "RESTORE_DATABASE_URL is required" >&2
+  exit 2
+fi
+
+if ! command -v psql >/dev/null 2>&1; then
+  echo "psql is required on PATH" >&2
+  exit 2
+fi
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP="${TMPDIR:-/tmp}"
+RUN_ID="settld_backup_restore_$(date +%s)"
+SQL_DUMP="${TMP}/${RUN_ID}.sql"
+EXPECTED_JSON="${TMP}/${RUN_ID}.expected.json"
+STEP_TIMEOUT_SECONDS="${STEP_TIMEOUT_SECONDS:-600}"
+VERIFY_FINANCE_PACK_RAW="${BACKUP_RESTORE_VERIFY_FINANCE_PACK:-0}"
+VERIFY_FINANCE_PACK=0
+case "$(printf '%s' "${VERIFY_FINANCE_PACK_RAW}" | tr '[:upper:]' '[:lower:]')" in
+  1|true|yes) VERIFY_FINANCE_PACK=1 ;;
+  *) VERIFY_FINANCE_PACK=0 ;;
+esac
+
+export STORE=pg
+export NODE_ENV=production
+export PROXY_MIGRATE_ON_STARTUP=1
+
+# Make the seed workload isolated by schema (so repeated runs don't collide).
+# If the ambient env uses "public", force an isolated drill schema.
+REQUESTED_SCHEMA="${PROXY_PG_SCHEMA:-}"
+if [[ -z "${REQUESTED_SCHEMA}" || "${REQUESTED_SCHEMA}" == "public" ]]; then
+  export PROXY_PG_SCHEMA="backup_${RUN_ID}"
+else
+  export PROXY_PG_SCHEMA="${REQUESTED_SCHEMA}"
+fi
+export TENANT_ID="${TENANT_ID:-tenant_default}"
+export MONTH="${MONTH:-2026-01}"
+export JOBS="${JOBS:-10}"
+if [[ "${VERIFY_FINANCE_PACK}" -ne 1 ]]; then
+  export BACKUP_RESTORE_REQUIRE_MONTH_CLOSE=0
+  export BACKUP_RESTORE_REQUEST_MONTH_CLOSE=0
+fi
+
+SAME_DATABASE_URLS=0
+if [[ "${DATABASE_URL}" == "${RESTORE_DATABASE_URL}" ]]; then
+  SAME_DATABASE_URLS=1
+fi
+RESTORE_SCHEMA="${PROXY_PG_RESTORE_SCHEMA:-${PROXY_PG_SCHEMA}_restore}"
+if [[ "${#RESTORE_SCHEMA}" -gt 63 ]]; then
+  RESTORE_SCHEMA="${RESTORE_SCHEMA:0:63}"
+fi
+if [[ "${SAME_DATABASE_URLS}" -eq 1 && "${RESTORE_SCHEMA}" == "${PROXY_PG_SCHEMA}" ]]; then
+  RESTORE_SCHEMA="${PROXY_PG_SCHEMA}_r"
+fi
+
+step() {
+  local label="$1"
+  shift
+  local started
+  started="$(date +%s)"
+  echo "${label}"
+  if timeout "${STEP_TIMEOUT_SECONDS}" "$@"; then
+    local elapsed
+    elapsed="$(( $(date +%s) - started ))"
+    echo "    -> ok (${elapsed}s)"
+    return 0
+  else
+    local code="$?"
+    local elapsed
+    elapsed="$(( $(date +%s) - started ))"
+    echo "    -> failed (${elapsed}s, exit=${code})" >&2
+    return "${code}"
+  fi
+}
+
+dump_schema_to_file() {
+  local out_file="$1"
+  local err_file
+  err_file="$(mktemp "${TMP}/settld_pg_dump_err_${RUN_ID}_XXXX.txt")"
+
+  if command -v pg_dump >/dev/null 2>&1; then
+    if pg_dump --schema="${PROXY_PG_SCHEMA}" --no-owner --no-privileges "${DATABASE_URL}" > "${out_file}" 2>"${err_file}"; then
+      rm -f "${err_file}"
+      return 0
+    fi
+    if ! grep -qi "server version mismatch" "${err_file}"; then
+      cat "${err_file}" >&2
+      rm -f "${err_file}"
+      return 1
+    fi
+  fi
+
+  if ! command -v docker >/dev/null 2>&1; then
+    cat "${err_file}" >&2
+    rm -f "${err_file}"
+    return 1
+  fi
+
+  if ! docker run --rm postgres:17 pg_dump --schema="${PROXY_PG_SCHEMA}" --no-owner --no-privileges "${DATABASE_URL}" > "${out_file}" 2>"${err_file}"; then
+    cat "${err_file}" >&2
+    rm -f "${err_file}"
+    return 1
+  fi
+
+  rm -f "${err_file}"
+  return 0
+}
+
+clone_schema_in_place() {
+  local src_schema="$1"
+  local dst_schema="$2"
+  psql "${DATABASE_URL}" -v ON_ERROR_STOP=1 <<SQL >/dev/null
+DROP SCHEMA IF EXISTS "${dst_schema}" CASCADE;
+CREATE SCHEMA "${dst_schema}";
+DO \$\$
+DECLARE
+  t RECORD;
+BEGIN
+  FOR t IN
+    SELECT tablename
+    FROM pg_tables
+    WHERE schemaname = '${src_schema}'
+    ORDER BY tablename
+  LOOP
+    EXECUTE format(
+      'CREATE TABLE %I.%I (LIKE %I.%I INCLUDING DEFAULTS INCLUDING GENERATED INCLUDING IDENTITY)',
+      '${dst_schema}',
+      t.tablename,
+      '${src_schema}',
+      t.tablename
+    );
+    EXECUTE format('INSERT INTO %I.%I SELECT * FROM %I.%I', '${dst_schema}', t.tablename, '${src_schema}', t.tablename);
+  END LOOP;
+END
+\$\$;
+SQL
+}
+
+step "[1/8] Seed workload into source DB (schema=${PROXY_PG_SCHEMA})" \
+  node "${ROOT}/scripts/backup-restore/seed-workload.mjs"
+
+step "[2/8] Capture expected state" \
+  bash -lc "node \"${ROOT}/scripts/backup-restore/capture-state.mjs\" > \"${EXPECTED_JSON}\""
+
+FP_ZIP=""
+FP_SHA=""
+if [[ "${VERIFY_FINANCE_PACK}" -eq 1 ]]; then
+  echo "[3/8] Build FinancePackBundle and strict-verify (source DB)"
+  FINANCE_OUT="${TMP}/${RUN_ID}.finance_pack"
+  FP_ZIP="$(timeout "${STEP_TIMEOUT_SECONDS}" env DATABASE_URL="${DATABASE_URL}" TENANT_ID="${TENANT_ID}" PROXY_PG_SCHEMA="${PROXY_PG_SCHEMA}" node "${ROOT}/scripts/finance-pack/bundle.mjs" --period "${MONTH}" --out "${FINANCE_OUT}" --zip)"
+  step "    strict verify source finance pack" \
+    node "${ROOT}/packages/artifact-verify/bin/settld-verify.js" --strict --finance-pack "${FP_ZIP}" >/dev/null
+  FP_SHA="$(node -e "import fs from 'node:fs'; import crypto from 'node:crypto'; const b=fs.readFileSync(process.argv[1]); console.log(crypto.createHash('sha256').update(b).digest('hex'))" "${FP_ZIP}")"
+  echo "    -> ok ($(basename "${FP_ZIP}"))"
+else
+  echo "[3/8] Skip FinancePackBundle strict verification (set BACKUP_RESTORE_VERIFY_FINANCE_PACK=1 to enable)"
+fi
+
+if [[ "${SAME_DATABASE_URLS}" -eq 1 ]]; then
+  echo "[4/8] Clone source schema (${PROXY_PG_SCHEMA}) -> (${RESTORE_SCHEMA})"
+  clone_started="$(date +%s)"
+  if clone_schema_in_place "${PROXY_PG_SCHEMA}" "${RESTORE_SCHEMA}"; then
+    echo "    -> ok ($(( $(date +%s) - clone_started ))s)"
+  else
+    echo "    -> failed ($(( $(date +%s) - clone_started ))s, exit=1)" >&2
+    exit 1
+  fi
+  echo "[5/8] Restore into restore DB (same DB URL; schema clone used)"
+else
+  echo "[4/8] pg_dump source DB schema (${PROXY_PG_SCHEMA})"
+  dump_started="$(date +%s)"
+  if dump_schema_to_file "${SQL_DUMP}"; then
+    echo "    -> ok ($(( $(date +%s) - dump_started ))s)"
+  else
+    echo "    -> failed ($(( $(date +%s) - dump_started ))s, exit=1)" >&2
+    exit 1
+  fi
+
+  echo "[5/8] Restore into restore DB"
+  # Restore DB is assumed to exist and be empty-ish; caller can create it via CI setup.
+  step "    probe restore DB connectivity" \
+    psql "${RESTORE_DATABASE_URL}" -v ON_ERROR_STOP=1 -c "SELECT 1" >/dev/null
+  step "    restore SQL dump" \
+    psql "${RESTORE_DATABASE_URL}" -v ON_ERROR_STOP=1 -f "${SQL_DUMP}" >/dev/null
+fi
+
+step "[6/8] Verify restored state" \
+  env DATABASE_URL="${RESTORE_DATABASE_URL}" PROXY_PG_SCHEMA="${RESTORE_SCHEMA}" node "${ROOT}/scripts/backup-restore/verify-state.mjs" "${EXPECTED_JSON}"
+
+if [[ "${VERIFY_FINANCE_PACK}" -eq 1 ]]; then
+  echo "[7/8] Build FinancePackBundle and strict-verify (restored DB) + compare zip hash"
+  RESTORED_OUT="${TMP}/${RUN_ID}.finance_pack_restored"
+  FP_ZIP_RESTORED="$(timeout "${STEP_TIMEOUT_SECONDS}" env DATABASE_URL="${RESTORE_DATABASE_URL}" TENANT_ID="${TENANT_ID}" PROXY_PG_SCHEMA="${RESTORE_SCHEMA}" node "${ROOT}/scripts/finance-pack/bundle.mjs" --period "${MONTH}" --out "${RESTORED_OUT}" --zip)"
+  step "    strict verify restored finance pack" \
+    node "${ROOT}/packages/artifact-verify/bin/settld-verify.js" --strict --finance-pack "${FP_ZIP_RESTORED}" >/dev/null
+  FP_SHA_RESTORED="$(node -e "import fs from 'node:fs'; import crypto from 'node:crypto'; const b=fs.readFileSync(process.argv[1]); console.log(crypto.createHash('sha256').update(b).digest('hex'))" "${FP_ZIP_RESTORED}")"
+  if [[ "${FP_SHA}" != "${FP_SHA_RESTORED}" ]]; then
+    echo "FinancePack zip hash mismatch after restore:" >&2
+    echo "  source:   ${FP_SHA} (${FP_ZIP})" >&2
+    echo "  restored: ${FP_SHA_RESTORED} (${FP_ZIP_RESTORED})" >&2
+    exit 1
+  fi
+else
+  echo "[7/8] Skip FinancePackBundle restore hash comparison (set BACKUP_RESTORE_VERIFY_FINANCE_PACK=1 to enable)"
+fi
+
+echo "[8/8] Done"
+echo "=== Backup/Restore Verification PASSED ==="