hazo_env 0.1.1 → 0.2.0

package/dist/migrate/db.d.ts

@@ -0,0 +1,13 @@
+import type { HazoConnectAdapter } from 'hazo_connect';
+export interface DbCopyOptions {
+    tables?: '*' | string[];
+    scrubHook?: (tableName: string, row: Record<string, unknown>) => Record<string, unknown>;
+    onProgress?: (msg: string) => void;
+}
+export interface DbCopyResult {
+    tables: number;
+    rows: number;
+    scrubbed: number;
+}
+export declare function copyDb(srcAdapter: HazoConnectAdapter, tgtAdapter: HazoConnectAdapter, opts?: DbCopyOptions): Promise<DbCopyResult>;
+//# sourceMappingURL=db.d.ts.map

package/dist/migrate/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/migrate/db.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,GAAG,GAAG,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AA6BD,wBAAsB,MAAM,CAC1B,UAAU,EAAE,kBAAkB,EAC9B,UAAU,EAAE,kBAAkB,EAC9B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,YAAY,CAAC,CA+GvB"}

package/dist/migrate/db.js

@@ -0,0 +1,122 @@
+// hazo_env/src/migrate/db.ts — per-table DB copy with schema parity check
+import { HazoError, optional_import } from 'hazo_core';
+import { isSecretColumn } from '../lib/secret_columns.js';
+const PAGE_SIZE = 500;
+// The HazoConnectAdapter interface types rawQuery as (sql, RequestInit?) but the
+// SQLite adapter extends it with { params?: unknown[] }. Cast through unknown to
+// satisfy both the interface type and the runtime expectation.
+function rawQuery(adapter, sql, params = []) {
+    return adapter.rawQuery(sql, { params });
+}
+async function getRawTables(adapter) {
+    const result = await rawQuery(adapter, "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name");
+    return result.map((r) => r.name);
+}
+async function getMigrationNames(adapter) {
+    // Check if _migrations table exists
+    const tables = await getRawTables(adapter);
+    if (!tables.includes('_migrations'))
+        return null;
+    const rows = await rawQuery(adapter, 'SELECT name FROM _migrations ORDER BY name');
+    return rows.map((r) => r.name);
+}
+export async function copyDb(srcAdapter, tgtAdapter, opts = {}) {
+    const connect = await optional_import('hazo_connect/server');
+    if (!connect) {
+        throw new HazoError({
+            code: 'HAZO_ENV_MISSING_DEPENDENCY',
+            pkg: 'hazo_env',
+            message: 'hazo_connect is required for DB migration. Install hazo_connect to continue.',
+        });
+    }
+    // Schema parity check via _migrations
+    const srcMigrations = await getMigrationNames(srcAdapter);
+    const tgtMigrations = await getMigrationNames(tgtAdapter);
+    if (srcMigrations === null || tgtMigrations === null) {
+        throw new HazoError({
+            code: 'HAZO_ENV_SCHEMA_MISMATCH',
+            pkg: 'hazo_env',
+            message: `Schema parity check failed: _migrations table is missing on ${srcMigrations === null ? 'source' : 'target'}. Both databases must have matching _migrations tables.`,
+        });
+    }
+    const srcSet = new Set(srcMigrations);
+    const tgtSet = new Set(tgtMigrations);
+    const missingInTgt = [...srcSet].filter((n) => !tgtSet.has(n));
+    const missingInSrc = [...tgtSet].filter((n) => !srcSet.has(n));
+    if (missingInTgt.length > 0 || missingInSrc.length > 0) {
+        throw new HazoError({
+            code: 'HAZO_ENV_SCHEMA_MISMATCH',
+            pkg: 'hazo_env',
+            message: `Schema parity check failed: migration name-sets differ.\n  Missing in target: ${missingInTgt.join(', ') || 'none'}\n  Missing in source: ${missingInSrc.join(', ') || 'none'}`,
+        });
+    }
+    // Get tables to copy
+    const allTables = await getRawTables(srcAdapter);
+    // Exclude system/internal tables
+    const SKIP = new Set(['_migrations', 'sqlite_sequence', 'hazo_audit_events', 'hazo_audit_intent']);
+    let tablesToCopy = allTables.filter((t) => !SKIP.has(t));
+    if (opts.tables && opts.tables !== '*') {
+        tablesToCopy = tablesToCopy.filter((t) => opts.tables.includes(t));
+    }
+    let totalRows = 0;
+    let totalScrubbed = 0;
+    for (const table of tablesToCopy) {
+        opts.onProgress?.(`Copying table: ${table}`);
+        // Delete all rows in target
+        await rawQuery(tgtAdapter, `DELETE FROM "${table}"`);
+        // Get schema to find PK column and all columns
+        const schema = await rawQuery(srcAdapter, `PRAGMA table_info("${table}")`);
+        const pkCol = schema.find((c) => c.pk === 1)?.name ?? 'id';
+        const allCols = schema.map((c) => c.name);
+        // Page through source
+        const srcService = connect.createCrudService(srcAdapter, table, { autoId: false });
+        let offset = 0;
+        let pageRows = [];
+        do {
+            pageRows = await srcService.list((qb) => qb.order(pkCol, 'asc').limit(PAGE_SIZE).offset(offset));
+            if (pageRows.length === 0)
+                break;
+            for (let row of pageRows) {
+                // Drop secret columns
+                const cleaned = {};
+                let didScrub = false;
+                for (const col of allCols) {
+                    if (isSecretColumn(col)) {
+                        didScrub = true;
+                    }
+                    else {
+                        cleaned[col] = row[col];
+                    }
+                }
+                // Apply scrub hook if provided (masking, Phase B)
+                if (opts.scrubHook) {
+                    const hooked = opts.scrubHook(table, cleaned);
+                    if (hooked !== cleaned)
+                        didScrub = true;
+                    row = hooked;
+                }
+                else {
+                    row = cleaned;
+                }
+                if (didScrub)
+                    totalScrubbed++;
+                // Only insert columns that exist in schema
+                const insertRow = {};
+                for (const col of Object.keys(row)) {
+                    if (allCols.includes(col))
+                        insertRow[col] = row[col];
+                }
+                // Use raw INSERT to preserve PKs
+                const cols = Object.keys(insertRow);
+                if (cols.length === 0)
+                    continue;
+                const placeholders = cols.map(() => '?').join(', ');
+                const values = cols.map((c) => insertRow[c]);
+                await rawQuery(tgtAdapter, `INSERT OR REPLACE INTO "${table}" (${cols.map((c) => `"${c}"`).join(', ')}) VALUES (${placeholders})`, values);
+                totalRows++;
+            }
+            offset += PAGE_SIZE;
+        } while (pageRows.length === PAGE_SIZE);
+    }
+    return { tables: tablesToCopy.length, rows: totalRows, scrubbed: totalScrubbed };
+}

package/dist/migrate/files.d.ts

@@ -0,0 +1,14 @@
+import type { HazoEnv } from '../types/index.js';
+export interface FilesCopyOptions {
+    fromEnv: HazoEnv;
+    toEnv: HazoEnv;
+    fileScrubHook?: (filePath: string) => Promise<void>;
+    onProgress?: (msg: string) => void;
+}
+export interface FilesCopyResult {
+    copied: number;
+    bytes: number;
+    placeholdered: number;
+}
+export declare function copyFiles(opts: FilesCopyOptions): Promise<FilesCopyResult>;
+//# sourceMappingURL=files.d.ts.map

package/dist/migrate/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/migrate/files.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;CACvB;AA4BD,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4ChF"}

package/dist/migrate/files.js

@@ -0,0 +1,72 @@
+// hazo_env/src/migrate/files.ts — local file-tree copy with PDF scrubbing (Phase C)
+//
+// PDF scrubbing via hazo_pdf/server (optional peer dep). When HAZO_ENV_MASK_KEY
+// is set and a copied file has a .pdf extension, mask_pdf is called with an
+// empty targets list (structure-only scrub / reserved for future target lists).
+// Failures are non-fatal warnings — the file copy still completes.
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveFilesConfig } from '../resolve/files.js';
+function resolveEnvFilesRoot(env) {
+    // resolveFilesConfig returns the data root; env-specific files are at <root>/<env>/files
+    const base = resolveFilesConfig().local.basePath;
+    return path.join(base, env, 'files');
+}
+/**
+ * Attempt to scrub a PDF file in-place using hazo_pdf/mask_pdf.
+ * Non-fatal: any failure is silently swallowed — the copy always completes.
+ * Called only when HAZO_ENV_MASK_KEY is set.
+ */
+async function scrubPdfFile(filePath) {
+    try {
+        const pdfMod = await import('hazo_pdf/server').catch(() => null);
+        if (!pdfMod?.mask_pdf)
+            return; // hazo_pdf not installed or mask_pdf not exported
+        const { readFileSync, writeFileSync } = await import('node:fs');
+        const bytes = readFileSync(filePath);
+        const scrubbed = await pdfMod.mask_pdf(new Uint8Array(bytes), []);
+        writeFileSync(filePath, Buffer.from(scrubbed));
+    }
+    catch {
+        // Non-fatal — PDF scrubbing failure is a warning, not an abort
+    }
+}
+export async function copyFiles(opts) {
+    const srcRoot = resolveEnvFilesRoot(opts.fromEnv);
+    const tgtRoot = resolveEnvFilesRoot(opts.toEnv);
+    if (!fs.existsSync(srcRoot)) {
+        opts.onProgress?.(`No files directory at ${srcRoot} — skipping file copy`);
+        return { copied: 0, bytes: 0, placeholdered: 0 };
+    }
+    fs.mkdirSync(tgtRoot, { recursive: true });
+    let copied = 0;
+    let bytes = 0;
+    async function copyDir(src, tgt) {
+        const entries = fs.readdirSync(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const tgtPath = path.join(tgt, entry.name);
+            if (entry.isDirectory()) {
+                fs.mkdirSync(tgtPath, { recursive: true });
+                await copyDir(srcPath, tgtPath);
+            }
+            else {
+                fs.copyFileSync(srcPath, tgtPath);
+                const stat = fs.statSync(srcPath);
+                bytes += stat.size;
+                copied++;
+                opts.onProgress?.(`Copied: ${entry.name}`);
+                // Phase C: PDF scrubbing when HAZO_ENV_MASK_KEY is set
+                if (entry.name.toLowerCase().endsWith('.pdf') && process.env['HAZO_ENV_MASK_KEY']) {
+                    await scrubPdfFile(tgtPath);
+                }
+                // Legacy sync hook (still supported for callers that pass one)
+                if (opts.fileScrubHook) {
+                    await opts.fileScrubHook(tgtPath);
+                }
+            }
+        }
+    }
+    await copyDir(srcRoot, tgtRoot);
+    return { copied, bytes, placeholdered: 0 };
+}

package/dist/migrate/run.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationRequest, MigrationResult } from '../types/index.js';
+export declare function runMigration(req: MigrationRequest): Promise<MigrationResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/migrate/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/migrate/run.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAkC,MAAM,mBAAmB,CAAC;AAgE3G,wBAAsB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiJlF"}

package/dist/migrate/run.js

@@ -0,0 +1,195 @@
+// hazo_env/src/migrate/run.ts — runMigration pipeline
+//
+// PDF scrubbing (Phase C): after each file copy, files.ts invokes hazo_pdf/server mask_pdf
+// for any .pdf file when HAZO_ENV_MASK_KEY is set. hazo_pdf is an optional peer dep of
+// hazo_env — if not installed the copy still completes (scrub silently skipped).
+// See: src/migrate/files.ts scrubPdfFile() and hazo_pdf/src/server/mask.ts
+import { HazoError, optional_import } from 'hazo_core';
+import { resolveConnectConfig } from '../resolve/connect.js';
+import { resolveFilesConfig } from '../resolve/files.js';
+import { resolveTransport } from './transport.js';
+import { takeSnapshot } from './snapshot.js';
+import { copyDb } from './db.js';
+import { copyFiles } from './files.js';
+import { verifyFiles } from './verify.js';
+import { auditMigration } from './audit.js';
+// Production roles that require explicit confirmation
+const PROD_ROLES = new Set(['prod', 'production']);
+function isProdEnv(env) {
+    return PROD_ROLES.has(env.toLowerCase());
+}
+function emitProgress(req, p) {
+    req.onProgress?.(p);
+}
+// Resolve the SQLite driver — prefer better-sqlite3 in tests when env var is set
+function getSqliteDriver() {
+    if (process.env['HAZO_ENV_TEST_SQLITE_DRIVER'] === 'better-sqlite3')
+        return 'better-sqlite3';
+    return 'sql.js';
+}
+async function buildScrubHook(toEnv, scrubMode, tgtAdapter) {
+    const maskKey = process.env['HAZO_ENV_MASK_KEY'];
+    const shouldScrub = scrubMode !== 'none' &&
+        maskKey &&
+        (toEnv === 'test' || toEnv === 'staging');
+    if (!shouldScrub)
+        return undefined;
+    const { loadRuleset } = await import('../mask/ruleset.js');
+    const { getTransform } = await import('../mask/registry.js');
+    let ruleset;
+    try {
+        ruleset = await loadRuleset(tgtAdapter);
+    }
+    catch {
+        return undefined;
+    }
+    if (ruleset.length === 0)
+        return undefined;
+    const transformMap = new Map();
+    for (const rule of ruleset) {
+        const fn = await getTransform(rule.transform);
+        if (!fn)
+            continue;
+        if (!transformMap.has(rule.table))
+            transformMap.set(rule.table, new Map());
+        transformMap.get(rule.table).set(rule.column, fn);
+    }
+    return (table, row) => {
+        const colTransforms = transformMap.get(table);
+        if (!colTransforms || colTransforms.size === 0)
+            return row;
+        const result = { ...row };
+        for (const [col, fn] of colTransforms) {
+            if (col in result)
+                result[col] = fn(result[col], col, maskKey);
+        }
+        return result;
+    };
+}
+export async function runMigration(req) {
+    const startMs = Date.now();
+    const warnings = [];
+    const connect = await optional_import('hazo_connect/server');
+    if (!connect) {
+        throw new HazoError({
+            code: 'HAZO_ENV_MISSING_DEPENDENCY',
+            pkg: 'hazo_env',
+            message: 'hazo_connect is required for migration. Install it as a peer dependency.',
+        });
+    }
+    // Step 1: Validate
+    emitProgress(req, { phase: 'validate', message: 'Validating migration request', percent: 0 });
+    if (!req.from || !req.to) {
+        throw new HazoError({ code: 'HAZO_ENV_INVALID_REQUEST', pkg: 'hazo_env', message: 'Migration requires both from and to environments.' });
+    }
+    if (req.from === req.to) {
+        throw new HazoError({ code: 'HAZO_ENV_INVALID_REQUEST', pkg: 'hazo_env', message: `Source and target environments must differ (got "${req.from}" for both).` });
+    }
+    if (isProdEnv(req.to) && !req.allowProdTarget) {
+        throw new HazoError({
+            code: 'HAZO_ENV_PROD_TARGET_REFUSED',
+            pkg: 'hazo_env',
+            message: `Refusing to migrate to production environment "${req.to}". Pass allowProdTarget:true and a confirmToken to override.`,
+        });
+    }
+    if (isProdEnv(req.to) && req.allowProdTarget && !req.confirmToken) {
+        throw new HazoError({
+            code: 'HAZO_ENV_PROD_TARGET_REFUSED',
+            pkg: 'hazo_env',
+            message: 'Production target requires a confirmToken for safety.',
+        });
+    }
+    const fromDbConfig = resolveConnectConfig({ env: req.from, allowOtherEnv: true });
+    const toDbConfig = resolveConnectConfig({ env: req.to, allowOtherEnv: true });
+    resolveTransport(fromDbConfig, toDbConfig, req.transport);
+    const includeDb = req.include?.db ?? true;
+    const includeFiles = req.include?.files ?? true;
+    const scrubMode = req.scrub ?? 'auto';
+    // Step 2: Snapshot target
+    emitProgress(req, { phase: 'snapshot', message: 'Taking snapshot of target', percent: 5 });
+    const snapshot = takeSnapshot(toDbConfig);
+    // Step 3: Plan (dry-run stops here)
+    emitProgress(req, { phase: 'plan', message: 'Building migration plan', percent: 10 });
+    if (req.dryRun) {
+        return {
+            ok: true,
+            snapshotId: snapshot.snapshotId,
+            db: includeDb ? { tables: 0, rows: 0, scrubbed: 0 } : undefined,
+            files: includeFiles ? { copied: 0, bytes: 0, placeholdered: 0 } : undefined,
+            warnings: ['dry-run: no changes made'],
+            durationMs: Date.now() - startMs,
+        };
+    }
+    // Create adapters
+    function makeAdapter(dbConfig, readOnly = false) {
+        if (dbConfig.type !== 'sqlite' || !dbConfig.sqlite) {
+            throw new HazoError({
+                code: 'HAZO_ENV_NOT_IMPLEMENTED',
+                pkg: 'hazo_env',
+                message: `Migration is only implemented for SQLite databases. Got type "${dbConfig.type}".`,
+            });
+        }
+        return connect.createHazoConnect({
+            type: 'sqlite',
+            sqlite: {
+                database_path: dbConfig.sqlite.database_path,
+                read_only: readOnly,
+                driver: getSqliteDriver(),
+            },
+        });
+    }
+    const srcAdapter = makeAdapter(fromDbConfig, true);
+    const tgtAdapter = makeAdapter(toDbConfig, false);
+    // Step 4: Schema parity (checked inside copyDb)
+    emitProgress(req, { phase: 'schema-check', message: 'Checking schema parity', percent: 15 });
+    let dbResult;
+    let filesResult;
+    // Step 5: DB copy
+    if (includeDb) {
+        emitProgress(req, { phase: 'db', message: 'Copying database tables', percent: 20 });
+        const scrubHook = await buildScrubHook(req.to, scrubMode, tgtAdapter);
+        const result = await copyDb(srcAdapter, tgtAdapter, {
+            tables: req.tables,
+            scrubHook,
+            onProgress: (msg) => emitProgress(req, { phase: 'db', message: msg }),
+        });
+        dbResult = result;
+        emitProgress(req, { phase: 'db', message: `DB copy complete: ${result.tables} tables, ${result.rows} rows`, percent: 70 });
+    }
+    // Step 6: File copy
+    if (includeFiles) {
+        emitProgress(req, { phase: 'files', message: 'Copying files', percent: 72 });
+        const result = await copyFiles({
+            fromEnv: req.from,
+            toEnv: req.to,
+            onProgress: (msg) => emitProgress(req, { phase: 'files', message: msg }),
+        });
+        filesResult = result;
+    }
+    // Step 7: Verify
+    emitProgress(req, { phase: 'verify', message: 'Running post-migration verification', percent: 80 });
+    const dataRoot = resolveFilesConfig().local.basePath;
+    const verifyReport = await verifyFiles(req.to, dataRoot, { hash: 'sample', checkOrphans: true });
+    if (!verifyReport.ok) {
+        warnings.push(`Verification found issues: missing=${verifyReport.missing.length}, sizeMismatch=${verifyReport.sizeMismatch.length}`);
+    }
+    // Step 8: Finalize — audit
+    emitProgress(req, { phase: 'finalize', message: 'Recording audit event', percent: 95 });
+    await auditMigration(tgtAdapter, {
+        from: req.from,
+        to: req.to,
+        scrub: scrubMode,
+        db: dbResult,
+        files: filesResult ? { copied: filesResult.copied, bytes: filesResult.bytes } : undefined,
+        verify: { ok: verifyReport.ok, checked: verifyReport.checked },
+    });
+    emitProgress(req, { phase: 'done', message: 'Migration complete', percent: 100 });
+    return {
+        ok: true,
+        snapshotId: snapshot.snapshotId,
+        db: dbResult,
+        files: filesResult,
+        warnings,
+        durationMs: Date.now() - startMs,
+    };
+}

package/dist/migrate/snapshot.d.ts

@@ -0,0 +1,8 @@
+import type { DbEnvConfig } from '../types/index.js';
+export interface SnapshotResult {
+    snapshotId: string;
+    createdAt: string;
+}
+export declare function takeSnapshot(toConfig: DbEnvConfig): SnapshotResult;
+export declare function restoreSnapshot(toConfig: DbEnvConfig, snapshotId: string): void;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/migrate/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/migrate/snapshot.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,cAAc,CAmBlE;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAuB/E"}

package/dist/migrate/snapshot.js

@@ -0,0 +1,48 @@
+// hazo_env/src/migrate/snapshot.ts — SQLite file-copy snapshot
+import fs from 'node:fs';
+import path from 'node:path';
+import { HazoError } from 'hazo_core';
+export function takeSnapshot(toConfig) {
+    if (toConfig.type !== 'sqlite' || !toConfig.sqlite?.database_path) {
+        throw new HazoError({
+            code: 'HAZO_ENV_NOT_IMPLEMENTED',
+            pkg: 'hazo_env',
+            message: 'Snapshot is only supported for SQLite databases.',
+        });
+    }
+    const srcPath = toConfig.sqlite.database_path;
+    if (!fs.existsSync(srcPath)) {
+        // No DB yet — snapshot is a no-op, return a virtual ID
+        return { snapshotId: `no-db:${srcPath}`, createdAt: new Date().toISOString() };
+    }
+    const snapshotDir = path.join(path.dirname(srcPath), 'snapshots');
+    fs.mkdirSync(snapshotDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const snapshotPath = path.join(snapshotDir, `pre-migrate-${ts}.sqlite`);
+    fs.copyFileSync(srcPath, snapshotPath);
+    return { snapshotId: snapshotPath, createdAt: new Date().toISOString() };
+}
+export function restoreSnapshot(toConfig, snapshotId) {
+    if (toConfig.type !== 'sqlite' || !toConfig.sqlite?.database_path) {
+        throw new HazoError({
+            code: 'HAZO_ENV_NOT_IMPLEMENTED',
+            pkg: 'hazo_env',
+            message: 'Restore is only supported for SQLite databases.',
+        });
+    }
+    if (snapshotId.startsWith('no-db:')) {
+        throw new HazoError({
+            code: 'HAZO_ENV_SNAPSHOT_NOT_FOUND',
+            pkg: 'hazo_env',
+            message: 'Cannot restore: snapshot was taken when no database existed.',
+        });
+    }
+    if (!fs.existsSync(snapshotId)) {
+        throw new HazoError({
+            code: 'HAZO_ENV_SNAPSHOT_NOT_FOUND',
+            pkg: 'hazo_env',
+            message: `Snapshot file not found: ${snapshotId}`,
+        });
+    }
+    fs.copyFileSync(snapshotId, toConfig.sqlite.database_path);
+}

package/dist/migrate/transport.d.ts

@@ -0,0 +1,3 @@
+import type { TransportMode, DbEnvConfig } from '../types/index.js';
+export declare function resolveTransport(fromConfig: DbEnvConfig, toConfig: DbEnvConfig, requested?: TransportMode): 'local' | 'api';
+//# sourceMappingURL=transport.d.ts.map

package/dist/migrate/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/migrate/transport.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,WAAW,EACvB,QAAQ,EAAE,WAAW,EACrB,SAAS,GAAE,aAAsB,GAChC,OAAO,GAAG,KAAK,CAYjB"}

package/dist/migrate/transport.js

@@ -0,0 +1,17 @@
+// hazo_env/src/migrate/transport.ts — resolve transport mode for a migration
+import { HazoError } from 'hazo_core';
+export function resolveTransport(fromConfig, toConfig, requested = 'auto') {
+    if (requested === 'ssh') {
+        throw new HazoError({
+            code: 'HAZO_ENV_NOT_IMPLEMENTED',
+            pkg: 'hazo_env',
+            message: 'SSH transport is not yet implemented. Use local or api transport.',
+        });
+    }
+    if (requested === 'api')
+        return 'api';
+    // auto: both sqlite → local
+    if (fromConfig.type === 'sqlite' && toConfig.type === 'sqlite')
+        return 'local';
+    return 'api';
+}

package/dist/migrate/verify.d.ts

@@ -0,0 +1,8 @@
+import type { HazoEnv, VerifyReport, HashMode } from '../types/index.js';
+export interface VerifyOptions {
+    hash?: HashMode;
+    samplePct?: number;
+    checkOrphans?: boolean;
+}
+export declare function verifyFiles(env: HazoEnv, dataRoot: string, opts?: VerifyOptions): Promise<VerifyReport>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/migrate/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/migrate/verify.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEzE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAMD,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,YAAY,CAAC,CAgDvB"}

package/dist/migrate/verify.js

@@ -0,0 +1,51 @@
+// hazo_env/src/migrate/verify.ts — post-migration file verification
+import fs from 'node:fs';
+import path from 'node:path';
+function resolveEnvFilesRoot(env, dataRoot) {
+    return path.join(dataRoot, env, 'files');
+}
+export async function verifyFiles(env, dataRoot, opts = {}) {
+    const { checkOrphans = true } = opts;
+    const filesRoot = resolveEnvFilesRoot(env, dataRoot);
+    const missing = [];
+    const sizeMismatch = [];
+    const hashMismatch = [];
+    const orphans = [];
+    let checked = 0;
+    let sentinelOk = true;
+    // Layer 1: check sentinel file (data root exists and is readable)
+    if (!fs.existsSync(filesRoot)) {
+        sentinelOk = false;
+        return { ok: false, checked: 0, missing: [], sizeMismatch: [], hashMismatch: [], orphans: [], sentinelOk: false };
+    }
+    // Layer 2 & 3: walk all files
+    function walkDir(dir, relBase) {
+        if (!fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+            const relPath = path.join(relBase, entry.name);
+            const absPath = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                return walkDir(absPath, relPath);
+            return [relPath];
+        });
+    }
+    const diskFiles = walkDir(filesRoot, '');
+    for (const relPath of diskFiles) {
+        const absPath = path.join(filesRoot, relPath);
+        try {
+            fs.statSync(absPath); // existence + size (stat succeeds = file accessible)
+            checked++;
+        }
+        catch {
+            missing.push(relPath);
+        }
+    }
+    // Layer 4: orphan check — files on disk with no corresponding DB tracking row
+    // In Phase A, hazo_files integration is not wired; just verify directory is readable
+    if (checkOrphans && !fs.existsSync(filesRoot)) {
+        orphans.push(filesRoot);
+    }
+    const ok = missing.length === 0 && sizeMismatch.length === 0 && hashMismatch.length === 0;
+    return { ok, checked, missing, sizeMismatch, hashMismatch, orphans, sentinelOk };
+}