hazo_env 0.2.0 → 0.4.0

package/CHANGE_LOG.md

@@ -1,5 +1,52 @@
 # hazo_env — Change Log
 
+## 0.4.0 — 2026-06-25
+
+### Added
+- `verifyFiles()` L2–L5 — DB-backed file existence (L2), size check (L3), hash check L4 (`full|sample|none`; sample = 1% + top-10 by size + top-10 by changed_at), orphan detection L5. Previously all layers were stubs.
+- `VerifyOptions.adapter` — pass a `HazoConnectAdapter` to enable DB-backed checks; without it verify falls back to sentinel-only (disk) and sets `report.skippedReason`.
+- `VerifyReport` — new fields: `hashed?: number`, `skippedReason?: string`.
+- `runMigration` — step 7 verify now passes `tgtAdapter`; emits detailed warning on `!ok` (counts + snapshotId) but continues (G2: warns-not-aborts).
+- CLI `hazo-env verify` — new `--hash full|sample|none` flag (default `sample`); exits 1 on failure (CI-safe).
+- `doctor()` — section 7a: `_migrations` parity check across all SQLite envs (`--probe --all`); section 7b: masking ruleset column validation against live schema.
+- `DoctorOptions.probe` + `DoctorOptions.all` — enable live DB reachability probes + multi-env checks.
+- `hazo_files` added as optional peer dependency (`^3.5.0`).
+
+### Changed
+- `DoctorReport.passed` replaces `DoctorReport.ok` (previously typo in docs).
+- `DoctorCheck.status` is `'ok'|'warn'|'error'` (not `boolean`).
+
+### Test-app
+- Seed script creates 7 `hazo_files` fixture rows (3 clean, 1 size-mismatch, 1 hash-mismatch, 1 missing, 1 orphan) + physical files under `data/test/files/`.
+- `/api/verify` route + `/verify` report page added.
+- `'verify-fixtures'` autotest scenario added (5 cases).
+
+## 0.3.0 — 2026-06-10
+
+### Added
+- `EnvRoleMap` type (`Record<string, HazoEnvRole>`) in `src/types/index.ts`
+- `roles?: EnvRoleMap` optional field on `EnvDescription` interface
+- `getRoleMap()` client + server: config-driven role map; merges `DEFAULT_ROLE_MAP` → `globalThis.__HAZO_ENV_ROLES__` (client) → `[env.roles]` INI section (server); invalid role values skipped silently
+- `[env.roles]` INI section support: arbitrary env names mapped to the four fixed roles (`development`, `test`, `staging`, `production`)
+- `describeEnv()` server version now includes `roles` field
+- Filesystem progress store: `writeMigrationProgress`, `readMigrationProgress`, `clearMigrationProgress` (`src/migrate/progress.ts`)
+- `MigrationRequest.jobId` + `MigrationRequest.progressDir` optional fields — when both present, `runMigration` writes each progress event to `<progressDir>/<jobId>.json`
+- `loadRuleset`, `syncRulesetFromIni`, `parseIniRules` masking ruleset functions now exported from package index
+- `MaskRule` type now exported from package index
+- `normalize()` utility now exported from package index (trim + lowercase env name string)
+
+### Changed
+- `getEnvRole()` rewritten to be config-driven via role map; unknown env names now default to `'development'` instead of `'production'` — this is a safe behavior fix (unknown names no longer silently get production-level protection)
+
+## 0.2.0 — 2026-06-09
+
+- feat: M2 migration engine — `runMigration`, `verifyFiles`, `takeSnapshot`, `restoreSnapshot`
+- feat: M3 PII masking — `registerMask`, built-in transforms (`mask_email`, `fake_name`, `mask_phone`, `jitter_date`, `hash`, `tokenize`, `drop`, `nullify`, `redact_pii`)
+- feat: masking ruleset management — `loadRuleset`, `syncRulesetFromIni`, `parseIniRules`, `MaskRule` (not yet exported from index — fixed in 0.3.0)
+- feat: `MaskTransform` type in `src/types/index.ts`
+- feat: CLI commands `migrate`, `verify`, `restore`, `mask sync`, `mask list`
+- chore: version bump to 0.2.0
+
 ## 0.1.1 — 2026-06-09
 
 - fix: provision `sql-wasm.wasm` into test-app `public/` via seed script (fixes Connect page error when SQLite adapter loads via sql.js WASM)

package/README.md

@@ -9,8 +9,8 @@ Canonical environment resolver for hazo apps. Typed env names, per-env DB/file/s
 - **Per-env file config** — `resolveFilesConfig()` maps the current env to a `hazo_files` config rooted at the declared `data_root`.
 - **Secrets** — `getSecret()` resolves from `.env.local` only; placeholders in `hazo_env_config.ini` are substituted at runtime without storing secrets.
 - **Migration engine** — `runMigration({ from, to })` copies a DB + files between envs. Validates → snapshots target → copies tables (paged, schema-checked) → copies files → verifies → writes hazo_audit entry. Prod target refused without an explicit confirm token.
-- **PII masking** — masking rules declared per table/column in `hazo_env_masking.ini` (seed) and synced to `hazo_app_config` at runtime. Built-in transforms: `mask_email`, `fake_name`, `mask_phone`, `jitter_date`, `hash`, `tokenize`, `drop`, `nullify`. Custom transforms via `registerMask()`. Applied automatically when the migration target role is `testing` or `staging`.
-- **Doctor** — `doctor()` / `hazo-env doctor` validates pattern, DB reachability, required secrets (no values printed), data_root writability, and schema level.
+- **PII masking** — masking rules declared per table/column in `hazo_env_masking.ini` (seed) and synced to `hazo_app_config` at runtime. Built-in transforms: `mask_email`, `fake_name`, `mask_phone`, `jitter_date`, `hash`, `tokenize`, `drop`, `nullify`. Custom transforms via `registerMask()`. Applied automatically when the migration target role is `test` or `staging`.
+- **Doctor** — `doctor()` / `hazo-env doctor` validates pattern, DB reachability, required secrets (no values printed), data_root writability, schema level, and (with `--probe --all`) migration parity across envs + masking ruleset column validation.
 - **CLI** — `hazo-env current | doctor | snapshot | migrate | verify | restore | mask`.
 
 ## Installation
@@ -64,18 +64,67 @@ const adapter = await createHazoConnect(resolveConnectConfig());
 ### Env resolution (client-safe — also in `hazo_env/client`)
 
 ```ts
-import { getEnv, getEnvRole, getPattern, listEnvs, assertEnv, describeEnv,
+import { getEnv, getEnvRole, getRoleMap, getPattern, listEnvs, assertEnv, describeEnv,
          isDev, isTest, isStaging, isProd } from 'hazo_env';
 
 getEnv()        // 'dev' | 'test' | 'staging' | 'prod'
-getEnvRole()    // 'development' | 'testing' | 'staging' | 'production'
+getEnvRole()    // 'development' | 'test' | 'staging' | 'production'
+getRoleMap()    // EnvRoleMap — full env→role mapping (config-driven; safe defaults)
 getPattern()    // e.g. 'dev_prod'
 listEnvs()      // ['dev', 'prod'] — valid envs for the declared pattern
 assertEnv()     // throws HazoError(ENV_INVALID) if HAZO_ENV is outside the pattern
-describeEnv()   // { env, role }
+describeEnv()   // { env, role, pattern, app, dataRoot, hostHint, roles? }
 isDev() / isTest() / isStaging() / isProd()
 ```
 
+`getEnvRole()` uses a config-driven role map so custom env names (e.g. `preview`, `qa`) resolve to the correct broad role. Unknown names default to `'development'` — never silently treated as production. Configure custom mappings in `[env.roles]`:
+
+```ini
+[env.roles]
+preview = staging
+qa      = test
+```
+
+### Configuring environment roles
+
+Canonical env names (`dev`, `test`, `staging`, `prod`) are pre-mapped and require no configuration. Non-canonical names (anything else) must declare their role in the `[env.roles]` INI section, or `doctor` will flag an error. Unknown names without a declaration fall back to `'development'` (safe: no masking, no prod-protection).
+
+```ini
+[env.roles]
+; Map arbitrary env names to the four fixed roles:
+;   development | test | staging | production
+qa   = test
+live = production
+rc   = staging
+```
+
+Valid role values: `development`, `test`, `staging`, `production`.
+
+#### Client-side global injection
+
+On the client (browser), the INI file is not available. Inject the resolved values at render time using `globalThis` globals — the same pattern used for the env pattern:
+
+```ts
+// In your Next.js layout server component or _app (server-side):
+// globalThis.__HAZO_ENV_PATTERN__ = 'dev,prod';                  // comma-separated pattern
+// globalThis.__HAZO_ENV_ROLES__   = { live: 'production', qa: 'test' };
+
+// Client bundle reads these automatically:
+import { getPattern, getRoleMap } from 'hazo_env/client';
+getPattern()   // reads __HAZO_ENV_PATTERN__
+getRoleMap()   // merges DEFAULT_ROLE_MAP → __HAZO_ENV_ROLES__
+```
+
+Both globals are optional; omitting them makes the client fall back to canonical defaults.
+
+### Utility
+
+```ts
+import { normalize } from 'hazo_env';
+
+normalize('  Dev ')  // → 'dev'  (trim + lowercase)
+```
+
 ### Resolvers (server-only)
 
 ```ts
@@ -98,15 +147,18 @@ getSecret('POSTGREST_API_KEY', { required: true })
 ```ts
 import { doctor } from 'hazo_env';
 
-const report = await doctor();
-// report.ok        boolean
-// report.checks    DoctorCheck[] — { label, ok, message }
+const report = await doctor({ probe: true, all: true });
+// report.passed    boolean
+// report.checks    DoctorCheck[] — { label, status: 'ok'|'warn'|'error', detail? }
+// Migration-readiness checks (--probe --all): _migrations parity across envs,
+// masking ruleset column validation against live schema.
 ```
 
 ### Migration engine (server-only)
 
 ```ts
-import { runMigration, verifyFiles, takeSnapshot, restoreSnapshot } from 'hazo_env';
+import { runMigration, verifyFiles, takeSnapshot, restoreSnapshot,
+         writeMigrationProgress, readMigrationProgress, clearMigrationProgress } from 'hazo_env';
 
 // Copy prod → staging (with PII masking applied automatically)
 const result = await runMigration({
@@ -116,19 +168,39 @@ const result = await runMigration({
   // allowProdTarget: true,              // required when `to` is 'prod'
   // confirmToken: '<token>',            // required together with allowProdTarget
   onProgress: (p) => console.log(p.phase, p.message),
+  // jobId: '<id>',                      // optional — persist progress to progressDir/<id>.json
+  // progressDir: '/tmp/hazo_jobs',      // required when jobId is set
 });
 // result.ok, result.db, result.files, result.snapshotId, result.warnings, result.durationMs
 
-// Stand-alone verification
-await verifyFiles('staging', dataRoot, { hash: 'sample' });
+// Stand-alone verification (with optional hazo_connect adapter for L2–L5 checks)
+await verifyFiles('staging', dataRoot, { hash: 'sample', checkOrphans: true, adapter });
+// report.ok, report.checked, report.hashed, report.missing[], report.sizeMismatch[],
+// report.hashMismatch[], report.orphans[], report.skippedReason?
 
 // Manual snapshot / restore
 const snap = takeSnapshot(connectConfig);   // returns { snapshotId }
 restoreSnapshot(connectConfig, snapshotId);
+
+// Filesystem progress store (used by hazo_jobs integration)
+writeMigrationProgress(dir, jobId, progress);
+readMigrationProgress(dir, jobId);    // → MigrationProgress | null
+clearMigrationProgress(dir, jobId);
 ```
 
 **Masking** — customize per table/column in `config/hazo_env_masking.ini`. Sync to the DB with `hazo-env mask sync`. Register custom transforms with `registerMask(name, fn)`.
 
+**Masking ruleset API** — load, parse, and sync rulesets programmatically:
+
+```ts
+import { loadRuleset, syncRulesetFromIni, parseIniRules } from 'hazo_env';
+import type { MaskRule } from 'hazo_env';
+
+const rules: MaskRule[] = parseIniRules(iniText);           // parse INI text → rules array
+const loaded  = await loadRuleset(adapter);                 // read from hazo_app_config DB
+await syncRulesetFromIni(adapter, '/path/to/masking.ini'); // write parsed rules to DB
+```
+
 ## CLI
 
 ```
@@ -163,12 +235,6 @@ Key sections:
 
 Secret placeholders use `${ENV_VAR_NAME}` syntax — hazo_env substitutes them from `.env.local` at runtime.
 
-## Tailwind v4 (`@source` required if consuming UI)
-
-```css
-@source "../node_modules/hazo_env/dist";
-```
-
 ## License
 
 MIT

package/SETUP_CHECKLIST.md

@@ -33,6 +33,16 @@ api_key  = ${POSTGREST_API_KEY}
 
 **Never put secret values directly in the ini file** — use `${ENV_VAR_NAME}` placeholders.
 
+**Custom env names** — if your pattern uses names other than `dev`/`test`/`staging`/`prod` (e.g. `preview`, `qa`), add an `[env.roles]` section to map them to broad roles:
+
+```ini
+[env.roles]
+preview = staging
+qa      = testing
+```
+
+Without this, unknown env names default to `'development'` role (never silently production).
+
 ## 3. Create `.env.local` (gitignored)
 
 One file per deployment (dev machine, staging host, prod host). Contains the secrets referenced by `${…}` placeholders in the ini:
@@ -84,6 +94,12 @@ All checks should be green before going to production. The doctor validates:
 - All required secrets are present in `.env.local` (values are never printed)
 - `data_root` exists and is writable
 
+Add `--probe --all` for migration-readiness checks:
+```bash
+npx hazo-env doctor --probe --all
+```
+This additionally checks: live DB reachability for all envs, `_migrations` table parity across envs, masking ruleset column validation against live schema.
+
 ## 8. (Next.js) Ensure `hazo_env` is in `transpilePackages`
 
 ```js
@@ -137,3 +153,19 @@ Review row counts and scrub counts before running without `--dry-run`. The migra
 ```bash
 npx hazo-env restore staging --snapshot <snapshot-id>
 ```
+
+## 10. (Required for non-canonical env names) Declare roles in `[env.roles]`
+
+If your pattern uses any env name other than `dev`, `test`, `staging`, or `prod` (e.g. `qa`, `preview`, `live`, `rc`), add an `[env.roles]` section to `config/hazo_env_config.ini` to map each name to one of the four fixed roles:
+
+```ini
+[env.roles]
+qa      = test
+preview = staging
+live    = production
+rc      = staging
+```
+
+Valid role values: `development`, `test`, `staging`, `production`.
+
+Without this declaration, undeclared non-canonical names default to `'development'` (safe — no masking, no prod-protection) **and `hazo-env doctor` will flag an error** until the mapping is added. Run `npx hazo-env doctor` to verify all env names have a declared role.

package/config/hazo_env_config.ini.sample

@@ -10,6 +10,22 @@ pattern = dev, test, staging, prod
 ; Application name (used in log output and doctor reports)
 app = myapp
 
+; ─── Environment role map ─────────────────────────────────────────────────────
+; Map each environment NAME to one of the four fixed ROLES.
+; Roles drive behavior: masking fires for test+staging roles;
+; prod-protection fires for the production role.
+; The four canonical names default automatically — list them only to be explicit.
+; Non-canonical names MUST be declared here or doctor will flag an error
+; and the role will default to 'development' (safe but unintended).
+[env.roles]
+; dev = development     (default — no declaration needed)
+; test = test           (default)
+; staging = staging     (default)
+; prod = production     (default)
+qa = test
+preview = staging
+; live = production     (example: a production env with a different name)
+
 [data]
 ; Base directory for all local file storage (relative to app root or absolute)
 ; Default: app_data

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // hazo_env/src/cli.ts — CLI entry: hazo-env current | doctor | snapshot | migrate | verify | restore
 import pc from 'picocolors';
-import { getEnv, getEnvRole } from './index.client.js';
-import { describeEnv } from './env.server.js';
+import { getEnv } from './index.client.js';
+import { describeEnv, getEnvRole, getPattern } from './env.server.js';
 import { doctor } from './doctor.js';
 const [, , command, ...args] = process.argv;
 function statusIcon(status) {
@@ -20,7 +20,7 @@ async function runCurrent() {
     catch {
         // Fallback if no config file
         const env = getEnv();
-        desc = { env, role: getEnvRole(env), pattern: ['dev', 'test', 'staging', 'prod'], app: '', dataRoot: '(config not found)', hostHint: 'unknown' };
+        desc = { env, role: getEnvRole(env), pattern: getPattern(), app: '', dataRoot: '(config not found)', hostHint: 'unknown' };
     }
     console.log(`\n${pc.bold('hazo-env current')}\n`);
     console.log(`  env:       ${pc.bold(desc.env)}`);
@@ -122,12 +122,22 @@ async function runMigrate() {
 }
 async function runVerify() {
     const targetEnv = args[0] ?? getEnv();
-    console.log(`\n${pc.bold('hazo-env verify')} ${pc.dim(targetEnv)}\n`);
+    // Parse --hash full|sample|none (default: sample) and --no-orphans
+    const hashIdx = args.indexOf('--hash');
+    const hashArg = hashIdx >= 0 ? args[hashIdx + 1] : 'sample';
+    const hash = (hashArg === 'full' || hashArg === 'none' || hashArg === 'sample') ? hashArg : 'sample';
+    const checkOrphans = !args.includes('--no-orphans');
+    console.log(`\n${pc.bold('hazo-env verify')} ${pc.dim(targetEnv)} ${pc.dim(`--hash ${hash}`)}\n`);
     const { verifyFiles } = await import('./migrate/verify.js');
     const { resolveFilesConfig } = await import('./resolve/files.js');
     const dataRoot = resolveFilesConfig().local.basePath;
-    const report = await verifyFiles(targetEnv, dataRoot, { hash: 'sample', checkOrphans: true });
-    console.log(`  Checked: ${report.checked} files`);
+    const report = await verifyFiles(targetEnv, dataRoot, { hash, checkOrphans });
+    if (report.skippedReason) {
+        console.log(`  ${pc.yellow('⚠')} ${report.skippedReason}`);
+    }
+    console.log(`  Checked: ${report.checked} files${report.hashed != null ? `, hashed: ${report.hashed}` : ''}`);
+    if (report.orphans.length)
+        console.log(`  ${pc.dim('ℹ')} Orphans (no DB row): ${report.orphans.join(', ')}`);
     if (report.ok) {
         console.log(`  ${pc.green('✓')} All files verified\n`);
     }
@@ -136,8 +146,10 @@ async function runVerify() {
             console.log(`  ${pc.red('✗')} Missing: ${report.missing.join(', ')}`);
         if (report.sizeMismatch.length)
             console.log(`  ${pc.yellow('⚠')} Size mismatch: ${report.sizeMismatch.join(', ')}`);
+        if (report.hashMismatch.length)
+            console.log(`  ${pc.yellow('⚠')} Hash mismatch: ${report.hashMismatch.join(', ')}`);
         console.log('');
-        process.exit(1);
+        process.exit(1); // S4: standalone verify exits 1 on failure (CI-friendly)
     }
 }
 async function runRestore() {
@@ -221,6 +233,8 @@ Usage:
     --no-db / --no-files                    Skip DB or file copy
     --allow-prod-target --confirm <token>   Override prod-target safety
   hazo-env verify <env>                     Verify files for an environment
+    --hash full|sample|none                Hash-check all / sampled / none (default: sample)
+    --no-orphans                           Skip orphan detection
   hazo-env restore <env> --snapshot <id>   Restore a snapshot
   hazo-env snapshot <env>                   Take a snapshot of an environment
   hazo-env mask sync                        Load masking ruleset from INI into DB

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA+I5E"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA8R5E"}

package/dist/doctor.js

@@ -4,9 +4,11 @@ import path from 'node:path';
 import { HazoConfig } from 'hazo_config/server';
 import { optional_import } from 'hazo_core';
 import { getEnv } from './index.client.js';
-import { listEnvs } from './env.server.js';
+import { listEnvs, getEnvRole, getRoleMap } from './env.server.js';
 import { resolveConnectConfig } from './resolve/connect.js';
 import { resolveFilesConfig } from './resolve/files.js';
+// Canonical env names that have built-in role defaults — no [env.roles] entry required
+const CANONICAL_ENV_NAMES = new Set(['dev', 'test', 'staging', 'prod']);
 function findConfigFile(pkg) {
     return path.resolve(process.cwd(), 'config', `${pkg}_config.ini`);
 }
@@ -110,8 +112,7 @@ export async function doctor(opts = {}) {
     if (opts.probe) {
         for (const env of envsToCheck) {
             // Get role for this env to guard against touching prod unattended
-            const role = env === 'dev' ? 'development' : env === 'test' ? 'test'
-                : env === 'staging' ? 'staging' : 'production';
+            const role = getEnvRole(env);
             if (role === 'production' && !opts.all) {
                 checks.push({
                     label: `DB probe [db.${env}]`,
@@ -153,6 +154,170 @@ export async function doctor(opts = {}) {
             }
         }
     }
+    // 6. Check that every env in the pattern has an explicit or canonical role mapping
+    const roleMap = getRoleMap();
+    const allEnvs = listEnvs();
+    for (const env of allEnvs) {
+        if (!CANONICAL_ENV_NAMES.has(env) && !(env in roleMap)) {
+            checks.push({
+                label: `Role for env '${env}'`,
+                status: 'error',
+                detail: `env '${env}' in pattern has no declared role in [env.roles]; defaulting to development`,
+            });
+        }
+    }
+    // 7. Migration readiness checks
+    // 7a. _migrations parity (probe mode, --all): open each SQLite env and compare name-sets
+    if (opts.probe && opts.all) {
+        const migSets = new Map();
+        for (const env of envsToCheck) {
+            let cfg;
+            try {
+                cfg = resolveConnectConfig({ env, allowOtherEnv: true });
+            }
+            catch {
+                continue;
+            }
+            if (cfg.type !== 'sqlite' || !cfg.sqlite)
+                continue;
+            try {
+                const Database = require('better-sqlite3');
+                const db = Database(cfg.sqlite.database_path);
+                let names;
+                try {
+                    names = db.prepare('SELECT name FROM _migrations').all().map((r) => r.name);
+                }
+                catch {
+                    names = [];
+                }
+                db.close();
+                migSets.set(env, new Set(names));
+            }
+            catch {
+                // DB not openable — skip (probe check already reported error)
+            }
+        }
+        if (migSets.size >= 2) {
+            const envList = [...migSets.keys()];
+            const referenceSet = migSets.get(envList[0]);
+            const referenceEnv = envList[0];
+            for (const env of envList.slice(1)) {
+                const s = migSets.get(env);
+                const onlyInRef = [...referenceSet].filter((n) => !s.has(n));
+                const onlyInEnv = [...s].filter((n) => !referenceSet.has(n));
+                if (onlyInRef.length === 0 && onlyInEnv.length === 0) {
+                    checks.push({ label: `Migration parity (${referenceEnv} ↔ ${env})`, status: 'ok', detail: `${s.size} applied` });
+                }
+                else {
+                    const detail = [
+                        onlyInRef.length ? `only in ${referenceEnv}: ${onlyInRef.join(', ')}` : '',
+                        onlyInEnv.length ? `only in ${env}: ${onlyInEnv.join(', ')}` : '',
+                    ].filter(Boolean).join('; ');
+                    checks.push({ label: `Migration parity (${referenceEnv} ↔ ${env})`, status: 'warn', detail });
+                }
+            }
+        }
+    }
+    // 7b. Masking ruleset column validation: every (table, column) in the masking INI must
+    //     exist in at least one SQLite env's schema. Skip silently for PostgREST envs.
+    const maskingConfigPath = path.resolve(process.cwd(), 'config', 'hazo_env_masking.ini');
+    if (fs.existsSync(maskingConfigPath)) {
+        try {
+            // Parse the masking INI directly — HazoConfig doesn't expose section enumeration.
+            // Format: each [section] is a table name; keys are column names.
+            const iniContent = fs.readFileSync(maskingConfigPath, 'utf-8');
+            const rules = [];
+            let currentTable = '';
+            for (const rawLine of iniContent.split('\n')) {
+                const line = rawLine.trim();
+                if (!line || line.startsWith(';') || line.startsWith('#'))
+                    continue;
+                const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+                if (sectionMatch) {
+                    currentTable = sectionMatch[1].trim();
+                    continue;
+                }
+                if (!currentTable)
+                    continue;
+                const eqIdx = line.indexOf('=');
+                if (eqIdx < 0)
+                    continue;
+                const column = line.slice(0, eqIdx).trim();
+                if (column)
+                    rules.push({ table: currentTable, column });
+            }
+            if (rules.length > 0) {
+                // Collect SQLite schemas for checked envs
+                const schemas = new Map(); // "table.column" → present
+                for (const env of envsToCheck) {
+                    let cfg;
+                    try {
+                        cfg = resolveConnectConfig({ env, allowOtherEnv: true });
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (cfg.type !== 'sqlite' || !cfg.sqlite)
+                        continue;
+                    try {
+                        const Database = require('better-sqlite3');
+                        const db = Database(cfg.sqlite.database_path);
+                        try {
+                            const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((r) => r.name);
+                            for (const tbl of tables) {
+                                const cols = db.prepare(`PRAGMA table_info(${tbl})`).all();
+                                for (const col of cols) {
+                                    schemas.set(`${tbl}.${col.name}`, new Set());
+                                }
+                            }
+                        }
+                        catch { /* DB empty or unreadable */ }
+                        db.close();
+                    }
+                    catch { /* DB not openable */ }
+                }
+                if (schemas.size > 0) {
+                    const badRules = [];
+                    for (const { table, column } of rules) {
+                        if (!schemas.has(`${table}.${column}`)) {
+                            badRules.push(`${table}.${column}`);
+                        }
+                    }
+                    if (badRules.length === 0) {
+                        checks.push({ label: 'Masking ruleset columns', status: 'ok', detail: `${rules.length} rule(s) validated` });
+                    }
+                    else {
+                        checks.push({
+                            label: 'Masking ruleset columns',
+                            status: 'warn',
+                            detail: `Column(s) not found in schema: ${badRules.join(', ')} (PostgREST envs skipped)`,
+                        });
+                    }
+                }
+                else {
+                    // No SQLite envs probed — can't validate columns; skip silently
+                    const hasPostgrest = envsToCheck.some((env) => {
+                        try {
+                            return resolveConnectConfig({ env, allowOtherEnv: true }).type === 'postgrest';
+                        }
+                        catch {
+                            return false;
+                        }
+                    });
+                    if (hasPostgrest) {
+                        checks.push({
+                            label: 'Masking ruleset columns',
+                            status: 'ok',
+                            detail: 'PostgREST env — column validation skipped',
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // Masking config parse failure — non-fatal, skip
+        }
+    }
     const passed = checks.every((c) => c.status !== 'error');
     return { env: targetEnv, checks, passed };
 }

package/dist/env.server.d.ts

@@ -1,4 +1,10 @@
-import type { EnvPattern, EnvDescription } from './types/index.js';
+import type { EnvPattern, EnvDescription, EnvRoleMap, HazoEnv, HazoEnvRole } from './types/index.js';
+/**
+ * Get the role map, merging client defaults with any [env.roles] section from hazo_env_config.ini.
+ */
+export declare function getRoleMap(): EnvRoleMap;
+/** Get the broad role for the current environment (server-aware, reads INI) */
+export declare function getEnvRole(env?: HazoEnv): HazoEnvRole;
 /**
  * Get the declared env pattern from [env] pattern in hazo_env_config.ini.
  * Falls back to ['dev','test','staging','prod'] if the config is absent.

package/dist/env.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.server.d.ts","sourceRoot":"","sources":["../src/env.server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAY,MAAM,kBAAkB,CAAC;AAc7E;;;GAGG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAKvC;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAW5C"}
+{"version":3,"file":"env.server.d.ts","sourceRoot":"","sources":["../src/env.server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAY,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAgB/G;;GAEG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAYvC;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,CAGrD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAKvC;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAY5C"}

package/dist/env.server.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import { HazoConfig } from 'hazo_config/server';
 import { HazoError } from 'hazo_core';
-import { getEnv, getEnvRole } from './index.client.js';
+import { getEnv, getRoleMap as clientGetRoleMap, normalize } from './index.client.js';
 function findConfigFile(pkg) {
     return path.resolve(process.cwd(), 'config', `${pkg}_config.ini`);
 }
@@ -14,6 +14,28 @@ function tryLoadConfig() {
         return null;
     }
 }
+const VALID_ROLES = new Set(['development', 'test', 'staging', 'production']);
+/**
+ * Get the role map, merging client defaults with any [env.roles] section from hazo_env_config.ini.
+ */
+export function getRoleMap() {
+    const config = tryLoadConfig();
+    const section = config?.getSection?.('env.roles') ?? {};
+    const out = { ...clientGetRoleMap() };
+    for (const [name, role] of Object.entries(section)) {
+        const r = String(role).trim();
+        if (VALID_ROLES.has(r)) {
+            out[name.trim()] = r;
+        }
+        // invalid values: skip silently (doctor will flag them)
+    }
+    return out;
+}
+/** Get the broad role for the current environment (server-aware, reads INI) */
+export function getEnvRole(env) {
+    const e = normalize(env ?? getEnv());
+    return getRoleMap()[e] ?? 'development';
+}
 /**
  * Get the declared env pattern from [env] pattern in hazo_env_config.ini.
  * Falls back to ['dev','test','staging','prod'] if the config is absent.
@@ -57,5 +79,6 @@ export function describeEnv() {
     const dataRoot = config?.getSection('data')?.['root'] ?? 'app_data';
     const locationRaw = config?.getSection(`host.${env}`)?.['location'] ?? 'unknown';
     const hostHint = locationRaw === 'local' ? 'local' : locationRaw === 'remote' ? 'remote' : 'unknown';
-    return { env, role, pattern, app, dataRoot, hostHint };
+    const roles = getRoleMap();
+    return { env, role, pattern, app, dataRoot, hostHint, roles };
 }

package/dist/index.client.d.ts

@@ -1,7 +1,11 @@
-import type { HazoEnv, HazoEnvRole, EnvPattern, EnvDescription } from './types/index.js';
-export type { HazoEnv, HazoEnvRole, EnvPattern, EnvDescription };
+import type { HazoEnv, HazoEnvRole, EnvPattern, EnvDescription, EnvRoleMap } from './types/index.js';
+export type { HazoEnv, HazoEnvRole, EnvPattern, EnvDescription, EnvRoleMap };
+/** Normalize raw env string to canonical form */
+export declare function normalize(raw: string): HazoEnv;
 /** Get the current environment name (normalized) */
 export declare function getEnv(): HazoEnv;
+/** Get the role map, merging any build-time injected overrides from __HAZO_ENV_ROLES__ */
+export declare function getRoleMap(): EnvRoleMap;
 /** Get the broad role for the current environment */
 export declare function getEnvRole(env?: HazoEnv): HazoEnvRole;
 export declare function isDev(env?: HazoEnv): boolean;

package/dist/index.client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.client.d.ts","sourceRoot":"","sources":["../src/index.client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzF,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC;AASjE,oDAAoD;AACpD,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,CAMrD;AAED,wBAAgB,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAA8C;AAC3F,wBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAuC;AACrF,wBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAA0C;AAC3F,wBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAA6C;AAE3F;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAMvC;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,IAAI,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,MAAM,CAAC,CAGlE"}
+{"version":3,"file":"index.client.d.ts","sourceRoot":"","sources":["../src/index.client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACrG,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC;AAE7E,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI9C;AAED,oDAAoD;AACpD,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AASD,0FAA0F;AAC1F,wBAAgB,UAAU,IAAI,UAAU,CAIvC;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,CAGrD;AAED,wBAAgB,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAA8C;AAC3F,wBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAuC;AACrF,wBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAA0C;AAC3F,wBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAA6C;AAE3F;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAMvC;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,IAAI,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,MAAM,CAAC,CAGlE"}