@feltdb/core 0.4.4 → 0.4.6

package/dist/migrate/cli/index.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { analyze, classify, approve, domainModel, gate, plan, discoverStateContract, generateRepositories, proveStatic, requireProof, measure, report, scanPostgresDependencies, requirePostgresRuntimeFree, configurationMigrationPlan, verifyPostgresIsolation, hash, writeJson } from '../index.js';
+const argv = process.argv.slice(2), command = argv[0] ?? 'status';
+function arg(name, def) { const i = argv.indexOf(`--${name}`); return i >= 0 ? argv[i + 1] : def; }
+const cwd = process.cwd(), configFile = resolve(cwd, arg('config', 'felt-migrate.json'));
+const HELP = `FeltDB Migration Sherpa
+
+Usage: felt-migrate <command> [--config felt-migrate.json]
+
+Commands:
+  analyze          Discover schema and application persistence consumers
+  classify         Classify every persistence entity
+  review           Review classifications; add --approve to lock them
+  capabilities     Run the fail-closed FeltDB capability gate
+  plan             Generate the deterministic migration plan
+  generate         Generate FeltDB-native repositories
+  state-contract   Discover the canonical application state contract
+  ui-scan          Inventory legacy and canonical UI state consumers
+  ui-verify        Verify canonical UI state dependencies
+  postgres-scan    Inventory and classify PostgreSQL dependencies
+  runtime-scan     Scan application runtime connections and SQL
+  config-scan      Scan environment and configuration dependencies
+  deployment-scan  Scan containers, startup, health and deployment files
+  postgres-remove  Generate an approval-required configuration removal plan
+  postgres-verify  Prove startup and recovery with PostgreSQL blocked
+  prove            Run static semantic proof checks
+  measure          Capture measured before/after metrics
+  report           Generate the auditable migration report
+  status           Show migration readiness and provenance hashes
+  all              Run the safe pipeline, pausing at approval gates
+`;
+async function loadConfig() { return JSON.parse(await readFile(configFile, 'utf8')); }
+async function read(dir, file) { return JSON.parse(await readFile(join(dir, file), 'utf8')); }
+async function run() {
+    const cfg = await loadConfig(), root = resolve(cwd, cfg.sourceRoot), dir = resolve(cwd, cfg.artifactDir ?? '.feltdb');
+    await mkdir(dir, { recursive: true });
+    const runtimeCommands = ['postgres-scan', 'runtime-scan', 'config-scan', 'deployment-scan', 'postgres-remove', 'postgres-verify'];
+    if (runtimeCommands.includes(command)) {
+        if (!cfg.feltDbRuntime)
+            throw new Error('feltDbRuntime must define the deployment-mode-specific runtime contract');
+        let manifest;
+        if (command === 'postgres-verify')
+            manifest = await read(dir, 'postgres-dependencies.json');
+        else {
+            manifest = await scanPostgresDependencies(root, cfg.feltDbRuntime, cfg.runtimeDependencyOverrides);
+            await writeJson(join(dir, 'postgres-dependencies.json'), manifest);
+        }
+        if (command === 'config-scan' || command === 'postgres-remove')
+            await writeJson(join(dir, 'postgres-config-migration-plan.json'), configurationMigrationPlan(manifest));
+        if (command === 'postgres-verify') {
+            let harness;
+            if (cfg.runtimeVerificationModule) {
+                const loaded = await import(pathToFileURL(resolve(cwd, cfg.runtimeVerificationModule)).href);
+                harness = await (loaded.createHarness?.() ?? loaded.default?.());
+            }
+            const proof = await verifyPostgresIsolation(manifest, harness);
+            await writeJson(join(dir, 'runtime-dependency-proof.json'), proof);
+            if (!proof.verifiedWithoutPostgres)
+                throw new Error('Static runtime gate passed, but postgres-free startup/recovery/network isolation was not executed');
+        }
+        else
+            requirePostgresRuntimeFree(manifest);
+        console.log(JSON.stringify({ runtime: manifest.runtime.length, migrationSource: manifest.migrationSource.length, rollbackOnly: manifest.rollbackOnly.length, legacyFallback: manifest.legacyFallback.length, runtimeDependencyHash: manifest.runtimeDependencyHash }, null, 2));
+        return;
+    }
+    if (command === 'analyze' || command === 'all') {
+        const a = await analyze(root, resolve(cwd, cfg.schemaFile));
+        await writeJson(join(dir, 'analysis.json'), a);
+        await writeJson(join(dir, 'schema.json'), a.entities);
+        await writeJson(join(dir, 'dependency-graph.json'), a.dependencies);
+        await writeJson(join(dir, 'query-inventory.json'), a.findings.filter(x => x.kind === 'sql'));
+        await writeJson(join(dir, 'access-patterns.json'), a.findings);
+    }
+    if (command === 'classify' || command === 'all') {
+        const a = await read(dir, 'analysis.json');
+        let c = classify(a, cfg.confidenceThreshold ?? .8, cfg.classificationOverrides, cfg.blobThresholdBytes);
+        if (command === 'all') {
+            try {
+                const prior = await read(dir, 'classification.json');
+                if (prior.approved && prior.classificationHash === c.classificationHash)
+                    c = { ...c, approved: true };
+            }
+            catch { /* first run */ }
+        }
+        await writeJson(join(dir, 'classification.json'), c);
+        if (c.entities.some(x => x.requiresApproval)) {
+            console.log('Classification review required. Add explicit overrides, then run review --approve.');
+            if (command === 'all')
+                return;
+        }
+    }
+    if (command === 'review') {
+        const c = await read(dir, 'classification.json');
+        if (argv.includes('--state-contract')) {
+            const s = await read(dir, 'state-contract.json');
+            console.log(JSON.stringify({ domains: s.domains.length, legacyConsumers: s.legacyConsumers, unresolved: s.unresolved }, null, 2));
+            if (argv.includes('--approve') && s.unresolved.length)
+                throw new Error('Cannot approve an unresolved state contract');
+            return;
+        }
+        console.log(JSON.stringify(c.entities, null, 2));
+        if (argv.includes('--approve'))
+            await writeJson(join(dir, 'classification.json'), approve(c));
+        return;
+    }
+    if (command === 'all') {
+        const c = await read(dir, 'classification.json');
+        if (!c.approved) {
+            console.log('Pipeline paused at human classification approval gate. Run: felt-migrate review --approve');
+            return;
+        }
+    }
+    if (['capabilities', 'plan', 'generate', 'state-contract', 'ui-scan', 'ui-verify', 'prove', 'measure', 'benchmark', 'report', 'status', 'all'].includes(command)) {
+        const a = await read(dir, 'analysis.json'), c = await read(dir, 'classification.json');
+        if (!c.approved && command !== 'status')
+            throw new Error('Classification must be approved');
+        const model = domainModel(a, c);
+        if (command === 'capabilities' || command === 'all')
+            gate(cfg.capabilities ?? {}, cfg.requiredCapabilities);
+        if (command === 'plan' || command === 'all') {
+            const p = plan(a, c, cfg.tenantKeys);
+            await writeJson(join(dir, 'domain-model.json'), model);
+            await writeJson(join(dir, 'migration-plan.json'), p);
+            await writeJson(join(dir, 'migration-checkpoints.json'), p.steps.map(x => ({ stepId: x.id, status: 'pending', records: 0 })));
+        }
+        if (['state-contract', 'ui-scan', 'ui-verify', 'all'].includes(command)) {
+            const s = await discoverStateContract(a, cfg.stateDomains);
+            await writeJson(join(dir, 'state-contract.json'), s);
+            await writeJson(join(dir, 'state-consumption-graph.json'), s.consumers);
+            await writeJson(join(dir, 'ui-state-dependencies.json'), s.consumers);
+            if ((cfg.strictStateContract ?? true) && s.unresolved.length) {
+                console.log('Pipeline paused at state-contract review gate.');
+                if (command === 'all')
+                    return;
+            }
+        }
+        let runtimeManifest;
+        if (command === 'all') {
+            if (!cfg.feltDbRuntime)
+                throw new Error('feltDbRuntime must define the deployment-mode-specific runtime contract');
+            runtimeManifest = await scanPostgresDependencies(root, cfg.feltDbRuntime, cfg.runtimeDependencyOverrides);
+            await writeJson(join(dir, 'postgres-dependencies.json'), runtimeManifest);
+            await writeJson(join(dir, 'postgres-config-migration-plan.json'), configurationMigrationPlan(runtimeManifest));
+            requirePostgresRuntimeFree(runtimeManifest);
+        }
+        if (command === 'generate' || command === 'all') {
+            const repos = generateRepositories(model);
+            for (const [name, code] of Object.entries(repos)) {
+                const file = join(dir, 'generated', 'repositories', name);
+                await mkdir(resolve(file, '..'), { recursive: true });
+                await writeFile(file, code);
+            }
+            await writeJson(join(dir, 'generated-files.json'), Object.keys(repos));
+        }
+        if (command === 'prove' || command === 'all') {
+            const s = await read(dir, 'state-contract.json'), repos = generateRepositories(model), checks = proveStatic(model, repos, s, cfg.strictStateContract ?? true);
+            await writeJson(join(dir, 'proof.json'), checks);
+            requireProof(checks);
+        }
+        if (command === 'measure' || command === 'report' || command === 'all') {
+            const s = await read(dir, 'state-contract.json'), metrics = measure(a, model, s, generateRepositories(model));
+            await writeJson(join(dir, 'measurements.json'), metrics);
+            if (command === 'report' || command === 'all') {
+                const checks = await read(dir, 'proof.json');
+                let rm = runtimeManifest, ri;
+                if (!rm)
+                    try {
+                        rm = await read(dir, 'postgres-dependencies.json');
+                    }
+                    catch { /* runtime scan not run */ }
+                try {
+                    ri = await read(dir, 'runtime-dependency-proof.json');
+                }
+                catch { /* dynamic isolation not run */ }
+                await writeFile(join(dir, 'MIGRATION_REPORT.md'), report(metrics, checks, s, rm, ri));
+            }
+        }
+        if (command === 'benchmark')
+            throw new Error('Benchmark requires application workload adapters; use the exported benchmark() API');
+        if (command === 'status') {
+            const state = c.approved ? 'APPROVED' : 'CLASSIFIED';
+            console.log(JSON.stringify({ readiness: state, schemaHash: a.schemaHash, classificationHash: c.classificationHash }, null, 2));
+        }
+        if (command === 'all') {
+            const p = await read(dir, 'migration-plan.json'), s = await read(dir, 'state-contract.json'), r = runtimeManifest;
+            await writeJson(join(dir, 'migration-manifest.json'), { engineVersion: '1.0.0', source: { type: 'postgresql', schemaHash: a.schemaHash }, target: { type: 'feltdb' }, classificationHash: c.classificationHash, planHash: p.planHash, stateContractHash: s.contractHash, runtimeDependencyHash: r.runtimeDependencyHash, generatedAt: new Date().toISOString(), entities: model.entities.length, state: model.entities.filter(x => x.classification === 'STATE').length, history: model.entities.filter(x => x.classification === 'HISTORY').length, relationships: model.entities.filter(x => x.classification === 'RELATIONSHIP').length, blobs: model.entities.filter(x => x.classification === 'BLOB_REFERENCE').length, secrets: model.entities.filter(x => x.classification === 'SECRET_REFERENCE').length, uiConsumers: s.consumers.length, legacyUiConsumers: s.legacyConsumers, postgres: { migrationSource: r.migrationSource.length > 0, rollbackAvailable: r.rollbackOnly.length > 0, runtimeDependency: false }, manifestHash: hash([a.schemaHash, c.classificationHash, p.planHash, s.contractHash, r.runtimeDependencyHash]) });
+            console.log('Safe generation pipeline complete. Data migration requires runtime source and target adapters.');
+        }
+    }
+    else
+        throw new Error(`Unknown command: ${command}`);
+}
+if (argv.includes('--help') || argv.includes('-h') || command === 'help')
+    console.log(HELP);
+else if (argv.includes('--version') || argv.includes('-v'))
+    console.log('0.4.3');
+else
+    run().catch(e => { console.error(`felt-migrate: ${e instanceof Error ? e.message : String(e)}`); process.exitCode = 1; });

package/dist/migrate/domain-model/index.d.ts

@@ -0,0 +1,2 @@
+import type { Analysis, ClassificationResult, DomainModel } from '../types/index.js';
+export declare function domainModel(a: Analysis, c: ClassificationResult): DomainModel;

package/dist/migrate/domain-model/index.js

@@ -0,0 +1,4 @@
+import { hash } from '../util.js';
+const secret = /(password|secret|token|credential|private_key|certificate|api_key)/i, blob = /(bytea|blob|binary|image|wasm|archive)/i;
+export function domainModel(a, c) { if (!c.approved)
+    throw new Error('Classification is not approved'); const by = new Map(a.entities.map(e => [e.name, e])); const entities = c.entities.map(x => { const e = by.get(x.entity); return { ...x, authoritative: x.classification === 'STATE', target: x.entity.replace(/_([a-z])/g, (_, v) => v.toUpperCase()), secretColumns: e.columns.filter(v => secret.test(v.name)).map(v => v.name), blobColumns: e.columns.filter(v => blob.test(v.type) || blob.test(v.name)).map(v => v.name) }; }); return { version: 1, entities, hash: hash(entities) }; }

package/dist/migrate/generator/index.d.ts

@@ -0,0 +1,2 @@
+import type { DomainModel } from '../types/index.js';
+export declare function generateRepositories(model: DomainModel): Record<string, string>;

package/dist/migrate/generator/index.js

@@ -0,0 +1,21 @@
+const forbidden = /\b(SQL|JOIN|SELECT\s+.+\s+FROM|INSERT\s+INTO|UPDATE\s+\w+\s+SET|DELETE\s+FROM|ORM|query\s*builder)\b/i;
+export function generateRepositories(model) {
+    const output = {};
+    for (const e of model.entities) {
+        if (['REMOVE', 'OPERATIONAL', 'SECRET_REFERENCE', 'BLOB_REFERENCE'].includes(e.classification))
+            continue;
+        let methods = '';
+        if (e.classification === 'HISTORY')
+            methods = `  append(event) { return this.history.append('${e.target}', event); }\n  list(query) { return this.history.list('${e.target}', query); }\n  reconstruct(id) { return this.history.reconstruct('${e.target}', id); }`;
+        else if (e.classification === 'RELATIONSHIP')
+            methods = `  add(from, to) { return this.relationship.add('${e.target}', from, to); }\n  remove(from, to) { return this.relationship.remove('${e.target}', from, to); }\n  list(id) { return this.relationship.list('${e.target}', id); }`;
+        else
+            methods = `  get(id) { return this.state.get('${e.target}', id); }\n  put(id, value) { return this.state.put('${e.target}', id, value); }\n  update(id, patch) { return this.state.update('${e.target}', id, patch); }\n  delete(id) { return this.state.delete('${e.target}', id); }\n  find(query) { return this.state.find('${e.target}', query); }`;
+        const name = e.target[0].toUpperCase() + e.target.slice(1);
+        output[`${e.target}.repository.js`] = `// Generated by FeltDB Migration Sherpa\nexport class ${name}Repository {\n  constructor(primitives) { Object.assign(this, primitives); }\n${methods}\n}\n`;
+    }
+    for (const [file, code] of Object.entries(output))
+        if (forbidden.test(code.replace(/^\/\/.*$/gm, '')))
+            throw new Error(`Generated repository ${file} contains a prohibited compatibility primitive`);
+    return output;
+}

package/dist/migrate/index.d.ts

@@ -0,0 +1,16 @@
+export * from './types/index.js';
+export * from './analyzer/index.js';
+export * from './classifier/index.js';
+export * from './domain-model/index.js';
+export * from './capability-gate/index.js';
+export * from './planner/index.js';
+export * from './state-contract/index.js';
+export * from './ui-wiring/index.js';
+export * from './runtime-dependencies/index.js';
+export * from './generator/index.js';
+export * from './migrator/index.js';
+export * from './prover/index.js';
+export * from './measurement/index.js';
+export * from './benchmark/index.js';
+export * from './reporter/index.js';
+export * from './util.js';

package/dist/migrate/index.js

@@ -0,0 +1,16 @@
+export * from './types/index.js';
+export * from './analyzer/index.js';
+export * from './classifier/index.js';
+export * from './domain-model/index.js';
+export * from './capability-gate/index.js';
+export * from './planner/index.js';
+export * from './state-contract/index.js';
+export * from './ui-wiring/index.js';
+export * from './runtime-dependencies/index.js';
+export * from './generator/index.js';
+export * from './migrator/index.js';
+export * from './prover/index.js';
+export * from './measurement/index.js';
+export * from './benchmark/index.js';
+export * from './reporter/index.js';
+export * from './util.js';

package/dist/migrate/measurement/index.d.ts

@@ -0,0 +1,7 @@
+import type { Analysis, DomainModel, StateContract } from '../types/index.js';
+export interface Measurements {
+    before: Record<string, number>;
+    after: Record<string, number>;
+    reductions: Record<string, number>;
+}
+export declare function measure(a: Analysis, model: DomainModel, contract: StateContract, repositories: Record<string, string>): Measurements;

package/dist/migrate/measurement/index.js

@@ -0,0 +1 @@
+export function measure(a, model, contract, repositories) { const before = { postgresTables: a.entities.length, foreignKeys: a.entities.reduce((n, e) => n + (e.foreignKeys?.length ?? 0), 0), indexes: a.entities.reduce((n, e) => n + (e.indexes?.length ?? 0), 0), sqlConsumers: a.findings.filter(x => x.kind === 'sql').length, uiDatabaseConsumers: contract.consumers.length }; const after = { feltCollections: model.entities.filter(e => !['REMOVE', 'SECRET_REFERENCE', 'BLOB_REFERENCE'].includes(e.classification)).length, stateCollections: model.entities.filter(e => e.classification === 'STATE').length, historyCollections: model.entities.filter(e => e.classification === 'HISTORY').length, relationships: model.entities.filter(e => e.classification === 'RELATIONSHIP').length, blobReferences: model.entities.filter(e => e.classification === 'BLOB_REFERENCE').length, repositoryLOC: Object.values(repositories).reduce((n, x) => n + x.split('\n').length, 0), canonicalUiConsumers: contract.canonicalConsumers, legacyUiConsumers: contract.legacyConsumers }; const reductions = { postgresTables: before.postgresTables, foreignKeys: before.foreignKeys, sqlConsumers: before.sqlConsumers, legacyUiConsumers: before.uiDatabaseConsumers - after.legacyUiConsumers }; return { before, after, reductions }; }

package/dist/migrate/migrator/index.d.ts

@@ -0,0 +1,2 @@
+import type { Checkpoint, DomainModel, MigrationAdapter, MigrationPlan, MigrationTelemetry, SourceAdapter } from '../types/index.js';
+export declare function migrate(plan: MigrationPlan, model: DomainModel, source: SourceAdapter, target: MigrationAdapter, previous?: Checkpoint[], tenant?: string, onTelemetry?: (x: MigrationTelemetry) => void): Promise<Checkpoint[]>;

package/dist/migrate/migrator/index.js

@@ -0,0 +1,35 @@
+export async function migrate(plan, model, source, target, previous = [], tenant, onTelemetry) { const checkpoints = new Map(previous.map(x => [x.stepId, x])); const by = new Map(model.entities.map(x => [x.entity, x])); for (const step of plan.steps) {
+    const old = checkpoints.get(step.id);
+    if (old?.status === 'complete')
+        continue;
+    const cp = { stepId: step.id, status: 'running', cursor: old?.cursor, records: old?.records ?? 0 };
+    checkpoints.set(step.id, cp);
+    const started = Date.now();
+    try {
+        await target.transaction(async () => { for await (const record of source.read(step.entity, cp.cursor, tenant)) {
+            const d = by.get(step.entity);
+            const clean = { ...record.value };
+            for (const key of [...d.secretColumns, ...d.blobColumns])
+                delete clean[key];
+            const options = { idempotencyKey: `${plan.planHash}:${step.id}:${record.id}`, tenant };
+            if (step.classification === 'HISTORY')
+                await target.append(d.target, record.id, clean, options);
+            else if (step.classification === 'RELATIONSHIP') {
+                const values = Object.values(clean).filter(v => typeof v === 'string');
+                if (values.length >= 2)
+                    await target.relate(d.target, values[0], values[1], options);
+            }
+            else if (!['REMOVE', 'SECRET_REFERENCE', 'BLOB_REFERENCE'].includes(step.classification))
+                await target.put(d.target, record.id, clean, options);
+            cp.cursor = record.cursor;
+            cp.records++;
+        } });
+        cp.status = 'complete';
+        onTelemetry?.({ timestamp: new Date().toISOString(), stepId: step.id, operation: 'migrate', records: cp.records, durationMs: Date.now() - started, tenant });
+    }
+    catch (e) {
+        cp.status = 'failed';
+        cp.error = e instanceof Error ? e.message : String(e);
+        throw e;
+    }
+} return plan.steps.map(s => checkpoints.get(s.id) ?? { stepId: s.id, status: 'pending', records: 0 }); }

package/dist/migrate/planner/index.d.ts

@@ -0,0 +1,2 @@
+import type { Analysis, ClassificationResult, MigrationPlan } from '../types/index.js';
+export declare function plan(a: Analysis, c: ClassificationResult, tenantKeys?: Record<string, string>): MigrationPlan;

package/dist/migrate/planner/index.js

@@ -0,0 +1,12 @@
+import { hash } from '../util.js';
+export function plan(a, c, tenantKeys = {}) { if (!c.approved)
+    throw new Error('Classification is not approved'); const deps = new Map(a.entities.map(e => [e.name, new Set((e.foreignKeys ?? []).map(f => f.referencedTable))])); const done = new Set(), steps = []; while (done.size < a.entities.length) {
+    const ready = [...deps].filter(([n, d]) => !done.has(n) && [...d].every(x => done.has(x) || !deps.has(x))).map(([n]) => n).sort();
+    if (!ready.length)
+        throw new Error(`Dependency cycle: ${[...deps.keys()].filter(x => !done.has(x)).join(', ')}`);
+    for (const n of ready) {
+        done.add(n);
+        const ce = c.entities.find(x => x.entity === n);
+        steps.push({ id: `${String(steps.length + 1).padStart(4, '0')}-${n}`, entity: n, classification: ce.classification, dependsOn: [...deps.get(n)].sort(), order: steps.length, tenantKey: tenantKeys[n] });
+    }
+} const core = { version: 1, steps }; return { ...core, planHash: hash(core) }; }

package/dist/migrate/prover/index.d.ts

@@ -0,0 +1,9 @@
+import type { DomainModel, StateContract } from '../types/index.js';
+export interface ProofCheck {
+    name: string;
+    status: 'pass' | 'fail';
+    measured: number;
+    details?: string;
+}
+export declare function proveStatic(model: DomainModel, repositories: Record<string, string>, contract: StateContract, strict?: boolean): ProofCheck[];
+export declare function requireProof(checks: ProofCheck[]): void;

package/dist/migrate/prover/index.js

@@ -0,0 +1,3 @@
+export function proveStatic(model, repositories, contract, strict = true) { const code = Object.values(repositories).join('\n'); const checks = [{ name: 'generated_sql', status: /\b(SELECT|INSERT|JOIN|query builder)\b/i.test(code) ? 'fail' : 'pass', measured: (code.match(/\b(SELECT|INSERT|JOIN)\b/gi) ?? []).length }, { name: 'secret_payload_fields', status: model.entities.every(e => e.classification === 'SECRET_REFERENCE' || e.secretColumns.every(c => !code.includes(c))) ? 'pass' : 'fail', measured: model.entities.reduce((n, e) => n + e.secretColumns.length, 0) }, { name: 'blob_payload_fields', status: model.entities.every(e => e.classification === 'BLOB_REFERENCE' || e.blobColumns.every(c => !code.includes(c))) ? 'pass' : 'fail', measured: model.entities.reduce((n, e) => n + e.blobColumns.length, 0) }, { name: 'state_contract', status: (!strict || contract.unresolved.length === 0) ? 'pass' : 'fail', measured: contract.unresolved.length, details: contract.unresolved.join(', ') }]; return checks; }
+export function requireProof(checks) { const failed = checks.filter(x => x.status === 'fail'); if (failed.length)
+    throw new Error(`Semantic proof failed: ${failed.map(x => x.name).join(', ')}`); }

package/dist/migrate/reporter/index.d.ts

@@ -0,0 +1,4 @@
+import type { Measurements } from '../measurement/index.js';
+import type { ProofCheck } from '../prover/index.js';
+import type { PostgresDependencyManifest, RuntimeDependencyProof, StateContract } from '../types/index.js';
+export declare function report(measurements: Measurements, proof: ProofCheck[], contract: StateContract, runtime?: PostgresDependencyManifest, isolation?: RuntimeDependencyProof): string;

package/dist/migrate/reporter/index.js

@@ -0,0 +1 @@
+export function report(measurements, proof, contract, runtime, isolation) { const passed = proof.filter(x => x.status === 'pass').length, runtimeLines = runtime ? `\n## PostgreSQL runtime cutover\n\n- Runtime dependencies: ${runtime.runtime.length}\n- Migration-source dependencies: ${runtime.migrationSource.length}\n- Rollback-only dependencies: ${runtime.rollbackOnly.length}\n- Legacy fallbacks: ${runtime.legacyFallback.length}\n- FeltDB runtime mode: ${runtime.feltDbRuntime.mode}\n- Postgres-free startup: ${isolation?.startupVerified ? 'PASS' : 'NOT MEASURED'}\n- Postgres-free recovery: ${isolation?.recoveryVerified ? 'PASS' : 'NOT MEASURED'}\n- Network isolation: ${isolation?.networkIsolationVerified ? 'PASS' : 'NOT MEASURED'}\n` : ''; return `# FeltDB Migration Sherpa Report\n\nGenerated: ${new Date().toISOString()}\n\n## Measured result\n\n- PostgreSQL entities discovered: ${measurements.before.postgresTables}\n- FeltDB-native collections generated: ${measurements.after.feltCollections}\n- Foreign keys eliminated from generated model: ${measurements.reductions.foreignKeys}\n- Canonical state domains: ${contract.domains.length}\n- Canonical UI consumers: ${contract.canonicalConsumers}\n- Remaining legacy UI consumers: ${contract.legacyConsumers}\n- Semantic proof checks: ${passed}/${proof.length} PASS\n${runtimeLines}\nNo unmeasured performance or reduction claims are included.\n`; }

package/dist/migrate/runtime-dependencies/index.d.ts

@@ -0,0 +1,13 @@
+import type { DependencyClassification, FeltDBRuntimeContract, PostgresDependencyManifest, RuntimeDependencyProof } from '../types/index.js';
+export declare function scanPostgresDependencies(sourceRoot: string, feltDbRuntime: FeltDBRuntimeContract, overrides?: Record<string, DependencyClassification>): Promise<PostgresDependencyManifest>;
+export declare function requirePostgresRuntimeFree(manifest: PostgresDependencyManifest): void;
+export declare function configurationMigrationPlan(manifest: PostgresDependencyManifest): Array<Record<string, unknown>>;
+export interface PostgresIsolationHarness {
+    startWithPostgresBlocked(): Promise<void>;
+    executeWorkflow(): Promise<void>;
+    restart(): Promise<void>;
+    verifyRecovery(): Promise<void>;
+    postgresConnectionAttempts(): Promise<number>;
+    cleanup?(): Promise<void>;
+}
+export declare function verifyPostgresIsolation(manifest: PostgresDependencyManifest, harness?: PostgresIsolationHarness): Promise<RuntimeDependencyProof>;

package/dist/migrate/runtime-dependencies/index.js

@@ -0,0 +1,112 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+import { hash } from '../util.js';
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'target', '.feltdb', 'coverage']);
+const ENV = /^(?:export\s+)?(POSTGRES_(?:HOST|PORT|DB|USER|PASSWORD)|PG(?:HOST|PORT|DATABASE|USER|PASSWORD)|DATABASE_(?:URL|HOST|PORT|NAME|USER|PASSWORD))\s*[:=]/i;
+const CLIENT = /\b(?:@neondatabase\/serverless|node-postgres|tokio-postgres|postgres\.js|pglite|@electric-sql\/pglite|sqlx|diesel|knex|typeorm|prisma|drizzle-orm|require\(['"]pg['"]\)|from\s+['"]pg['"])/i;
+const CONNECTION = /\b(?:new\s+(?:Pool|Client)\s*\(|createPool\s*\(|postgres\s*\(|connect\s*\(.*postgres)/i;
+const SQL = /\b(?:SELECT\s+.+\s+FROM|INSERT\s+INTO|UPDATE\s+\w+\s+SET|DELETE\s+FROM|JOIN\s+\w+|CREATE\s+(?:TABLE|INDEX)|ALTER\s+TABLE)\b/i;
+const STARTUP = /(?:wait-for-postgres|dockerize\s+-wait\s+tcp:\/\/(?:postgres|[^\s:]+):5432|pg_isready|psql\s)/i;
+const HEALTH = /(?:pg_isready|postgres(?:ql)?[^\n]{0,30}health|health[^\n]{0,30}(?:postgres|5432))/i;
+const IMAGE = /(?:image\s*:\s*postgres(?:ql)?(?::|\s|$)|container.*postgres|services?\s*:\s*postgres)/i;
+const DEPLOY = /(?:depends_on[^\n]*postgres|postgres\s*:\s*(?:condition|required)|(?:host|hostname)\s*:\s*postgres|tcp:\/\/postgres:5432)/i;
+const TEXT = /(?:^|\/)(?:Dockerfile[^/]*|[^/]*\.(?:[cm]?[jt]sx?|py|rb|go|rs|sql|ya?ml|toml|json|env|example|md|sh)|\.env[^/]*)$/i;
+async function walk(root, dir = root, out = []) { for (const n of await readdir(dir)) {
+    if (SKIP.has(n))
+        continue;
+    const p = join(dir, n), s = await stat(p);
+    if (s.isDirectory())
+        await walk(root, p, out);
+    else if (TEXT.test(p))
+        out.push(p);
+} return out.sort(); }
+function context(file, line) { const p = file.toLowerCase(); if (/(?:^|\/)(?:migrations?|migration-sherpa|feltdb-migration)(?:\/|\.|$)/.test(p))
+    return 'MIGRATION_SOURCE'; if (/(?:^|\/)(?:rollback|backout)(?:\/|\.|$)/.test(p) || /rollback[-_ ]only/i.test(line))
+    return 'ROLLBACK_ONLY'; if (/(?:^|\/)(?:legacy|fallback)(?:\/|\.|$)/.test(p) || /legacy[-_ ]fallback/i.test(line))
+    return 'LEGACY_FALLBACK'; if (/(?:^|\/)(?:test|tests|e2e|fixtures?|__tests__)(?:\/|\.|$)|(?:\.|_)(?:test|tests|spec|acceptance_tests)\./.test(p))
+    return 'TEST_ONLY'; if (/(?:^|\/)(?:dev|development|examples?)(?:\/|\.|$)|compose\.dev/.test(p))
+    return 'DEVELOPMENT_ONLY'; if (/(?:^|\/)(?:docs?|ops)(?:\/|$)|readme|\.md$|\.github\/workflows\/build|(?:baseline|results|report|metrics)[^/]*\.json$|(?:^|\/)persistence_[^/]*\.json$/.test(p))
+    return 'BUILD_ONLY'; return 'RUNTIME'; }
+function redact(line) { return line.replace(/^((?:export\s+)?(?:POSTGRES_|PG|DATABASE_)[A-Z_]+\s*[:=]\s*).*/i, '$1<redacted>').trim().slice(0, 300); }
+function action(code) { return code === 'POSTGRES_RUNTIME_ENV' ? 'Remove or replace with the configured FeltDB runtime contract.' : code === 'POSTGRES_RUNTIME_HEALTHCHECK' ? 'Replace with a FeltDB health/readiness check.' : 'Remove from the application runtime or explicitly classify it as migration, rollback, test, development, build, or fallback infrastructure.'; }
+export async function scanPostgresDependencies(sourceRoot, feltDbRuntime, overrides = {}) {
+    const findings = [];
+    for (const absolute of await walk(sourceRoot)) {
+        const file = relative(sourceRoot, absolute), content = await readFile(absolute, 'utf8');
+        const isManifest = basename(file) === 'package.json', isDeployment = /(?:docker|compose|kubernetes|k8s|helm|deploy|\.github\/workflows|fly\.toml)/i.test(file);
+        let packageJson = {};
+        if (isManifest)
+            try {
+                packageJson = JSON.parse(content);
+            }
+            catch { /* scan malformed JSON as text */ }
+        for (const [i, line] of content.split(/\r?\n/).entries()) {
+            const matches = [];
+            const env = line.match(ENV), comment = /^\s*(?:\/\/|#(?!\!)|\/\*|\*)/.test(line);
+            if (env) {
+                const generic = env[1].toUpperCase().startsWith('DATABASE_');
+                const postgresValue = /(?:postgres(?:ql)?:\/\/|\bpostgres\b|\b5432\b)/i.test(line);
+                if (!generic || postgresValue || CLIENT.test(content))
+                    matches.push([postgresValue ? 'POSTGRES_RUNTIME_URL' : 'POSTGRES_RUNTIME_ENV', 'environment']);
+            }
+            if (CLIENT.test(line) && !comment)
+                matches.push(['POSTGRES_RUNTIME_CLIENT', 'connection']);
+            if (CONNECTION.test(line) && !comment && CLIENT.test(content))
+                matches.push(['POSTGRES_RUNTIME_CONNECTION', 'connection']);
+            if (SQL.test(line) && !comment && (/\.sql$/i.test(file) || CLIENT.test(content) || /(?:query|execute|raw)\s*\(/i.test(line)))
+                matches.push(['POSTGRES_RUNTIME_SQL', 'sql']);
+            if (STARTUP.test(line) && !comment)
+                matches.push(['POSTGRES_RUNTIME_STARTUP_DEPENDENCY', 'startup']);
+            if (HEALTH.test(line) && !comment)
+                matches.push(['POSTGRES_RUNTIME_HEALTHCHECK', 'healthcheck']);
+            if ((IMAGE.test(line) || (isDeployment && /^\s+postgres\s*:\s*$/.test(line))) && !comment)
+                matches.push(['POSTGRES_RUNTIME_CONTAINER', 'container']);
+            if ((DEPLOY.test(line) || (isDeployment && /^\s*-\s*postgres\s*$/.test(line))) && !comment)
+                matches.push(['POSTGRES_RUNTIME_DEPLOYMENT_DEPENDENCY', 'deployment']);
+            for (const [code, kind] of matches) {
+                const key = `${file}:${i + 1}`, base = context(file, line);
+                let classification = overrides[key] ?? overrides[file] ?? base;
+                if (/pglite/i.test(line) && classification === 'RUNTIME' && /(legacy|fallback)/i.test(content))
+                    classification = 'LEGACY_FALLBACK';
+                const runtime = classification === 'RUNTIME';
+                findings.push({ id: hash([file, i + 1, code, line]).slice(0, 16), code, file, line: i + 1, classification, runtime, kind, evidence: redact(line), action: action(code) });
+            }
+        }
+        if (isManifest)
+            for (const section of ['dependencies', 'devDependencies'])
+                for (const [name] of Object.entries(packageJson[section] ?? {})) {
+                    if (!CLIENT.test(name))
+                        continue;
+                    const key = `${file}:${section}:${name}`, classification = overrides[key] ?? overrides[file] ?? (section === 'devDependencies' ? 'BUILD_ONLY' : context(file, name));
+                    findings.push({ id: hash(key).slice(0, 16), code: 'POSTGRES_RUNTIME_CLIENT', file, line: 1, classification, runtime: classification === 'RUNTIME', kind: 'dependency', evidence: `${section}.${name}`, action: action('POSTGRES_RUNTIME_CLIENT') });
+                }
+    }
+    const unique = [...new Map(findings.map(f => [`${f.file}:${f.line}:${f.code}:${f.evidence}`, f])).values()].sort((a, b) => `${a.file}:${a.line}:${a.code}`.localeCompare(`${b.file}:${b.line}:${b.code}`));
+    const group = (c) => unique.filter(f => f.classification === c);
+    const core = { version: 1, generatedAt: new Date().toISOString(), sourceRoot, findings: unique, runtime: group('RUNTIME'), migrationSource: group('MIGRATION_SOURCE'), legacyFallback: group('LEGACY_FALLBACK'), testOnly: group('TEST_ONLY'), developmentOnly: group('DEVELOPMENT_ONLY'), buildOnly: group('BUILD_ONLY'), rollbackOnly: group('ROLLBACK_ONLY'), feltDbRuntime };
+    return { ...core, runtimeDependencyHash: hash({ ...core, generatedAt: undefined }) };
+}
+export function requirePostgresRuntimeFree(manifest) { if (manifest.runtime.length) {
+    const f = manifest.runtime[0];
+    throw new Error(`FELTDB CUTOVER BLOCKED: ${f.code} at ${f.file}:${f.line} (${manifest.runtime.length} runtime finding${manifest.runtime.length === 1 ? '' : 's'})`);
+} }
+export function configurationMigrationPlan(manifest) {
+    const removals = manifest.findings.filter(f => f.kind === 'environment' && f.runtime).map(f => ({ change: 'REMOVE_RUNTIME_CONFIG', file: f.file, line: f.line, reason: 'FeltDB-native runtime', findingId: f.id, requiresApproval: true }));
+    const additions = manifest.feltDbRuntime.requiredEnvironment.map(key => ({ change: 'ADD_FELTDB_CONFIG', file: '.env.example', key, reason: `FeltDB ${manifest.feltDbRuntime.mode} runtime`, requiresApproval: true }));
+    return [...removals, ...additions];
+}
+export async function verifyPostgresIsolation(manifest, harness) { requirePostgresRuntimeFree(manifest); let startup = false, recovery = false, network = false; if (harness)
+    try {
+        await harness.startWithPostgresBlocked();
+        startup = true;
+        await harness.executeWorkflow();
+        await harness.restart();
+        await harness.verifyRecovery();
+        recovery = true;
+        network = (await harness.postgresConnectionAttempts()) === 0;
+        if (!network)
+            throw new Error('PostgreSQL connection attempted during network isolation');
+    }
+    finally {
+        await harness.cleanup?.();
+    } const count = (code) => manifest.runtime.filter(f => f.code === code).length; return { postgresRuntimeDependency: false, postgresConnections: count('POSTGRES_RUNTIME_CONNECTION') + count('POSTGRES_RUNTIME_CLIENT'), postgresSqlExecutions: count('POSTGRES_RUNTIME_SQL'), postgresEnvironmentVariables: count('POSTGRES_RUNTIME_ENV') + count('POSTGRES_RUNTIME_URL'), postgresStartupDependencies: count('POSTGRES_RUNTIME_STARTUP_DEPENDENCY'), postgresHealthChecks: count('POSTGRES_RUNTIME_HEALTHCHECK'), postgresRuntimeContainers: count('POSTGRES_RUNTIME_CONTAINER'), postgresRuntimeDeploymentReferences: count('POSTGRES_RUNTIME_DEPLOYMENT_DEPENDENCY'), feltDbRuntime: manifest.feltDbRuntime.requiredEnvironment.length > 0 || manifest.feltDbRuntime.mode === 'browser', verifiedWithoutPostgres: startup && recovery && network, startupVerified: startup, recoveryVerified: recovery, networkIsolationVerified: network, runtimeDependencyHash: manifest.runtimeDependencyHash }; }

package/dist/migrate/state-contract/index.d.ts

@@ -0,0 +1,13 @@
+import type { Analysis, StateContract, StateDomain } from '../types/index.js';
+export declare function discoverStateContract(a: Analysis, configured?: Array<Partial<StateDomain> & {
+    name: string;
+    authoritativeState: string;
+}>): Promise<StateContract>;
+export declare function verifyObservableState(contract: StateContract, domain: string, input: {
+    status?: string;
+    currentAction?: string;
+    history?: unknown[];
+}): {
+    active: boolean;
+    empty: boolean;
+};

package/dist/migrate/state-contract/index.js

@@ -0,0 +1,49 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { hash } from '../util.js';
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'target', '.feltdb']);
+async function walk(root, dir = root, out = []) { for (const n of await readdir(dir)) {
+    if (SKIP.has(n))
+        continue;
+    const p = join(dir, n), s = await stat(p);
+    if (s.isDirectory())
+        await walk(root, p, out);
+    else if (/\.[cm]?[jt]sx?$/.test(n))
+        out.push(p);
+} return out.sort(); }
+function semantic(line) { if (/current.?action/i.test(line))
+    return 'currentAction'; if (/status/i.test(line))
+    return 'status'; if (/plans?/i.test(line))
+    return 'plan'; if (/results?/i.test(line))
+    return 'result'; if (/activit|events?|history/i.test(line))
+    return 'activity'; return 'state'; }
+export async function discoverStateContract(a, configured = []) {
+    const consumers = [];
+    for (const file of await walk(a.sourceRoot)) {
+        const text = await readFile(file, 'utf8');
+        for (const [i, line] of text.split(/\r?\n/).entries()) {
+            if (!/(fetch\(|axios|useQuery|useSWR|poll|subscribe|\.sql\b|SELECT\s|postgres|pg\.)/i.test(line))
+                continue;
+            const canonical = /feltdb|canonical|stateContract/i.test(line);
+            const endpoint = line.match(/['"`]([^'"`]*\/api\/[^'"`]*)['"`]/)?.[1];
+            consumers.push({ id: hash([relative(a.sourceRoot, file), i + 1, line]).slice(0, 16), file: relative(a.sourceRoot, file), line: i + 1, surface: file.split('/').pop(), semantic: semantic(line), source: canonical ? 'canonical' : /sql|select|postgres|pg\.|\/api\//i.test(line) ? 'legacy' : 'unknown', endpoint });
+        }
+    }
+    const domains = configured.map(d => ({ name: d.name, authoritativeState: d.authoritativeState, history: d.history, fields: d.fields ?? {}, uiSurfaces: d.uiSurfaces ?? consumers.map(c => c.surface), lifecycleStates: d.lifecycleStates ?? ['NEW', 'ACTIVE', 'PAUSED', 'COMPLETED', 'FAILED'], emptyWhen: d.emptyWhen ?? 'authoritative state is absent and history is empty', refresh: d.refresh ?? 'subscription', tenantKey: d.tenantKey }));
+    const unresolved = [];
+    for (const d of domains) {
+        for (const sem of ['status', 'currentAction', 'plan', 'activity']) {
+            const matching = consumers.filter(c => c.semantic === sem);
+            if (new Set(matching.map(c => c.source)).size > 1)
+                unresolved.push(`STATE_CONTRACT_MISMATCH:${d.name}:${sem}`);
+        }
+    }
+    if (!domains.length)
+        unresolved.push('No canonical state domains configured');
+    consumers.filter(c => c.source !== 'canonical').forEach(c => unresolved.push(`LEGACY_CONSUMER:${c.file}:${c.line}`));
+    const core = { contractVersion: '1.0', generatedAt: new Date().toISOString(), domains, consumers, legacyConsumers: consumers.filter(c => c.source === 'legacy').length, canonicalConsumers: consumers.filter(c => c.source === 'canonical').length, unresolved };
+    return { ...core, contractHash: hash({ ...core, generatedAt: undefined }) };
+}
+export function verifyObservableState(contract, domain, input) { const d = contract.domains.find(x => x.name === domain); if (!d)
+    throw new Error(`Unknown state domain: ${domain}`); const active = !!input.status && !['NEW', 'EMPTY', 'COMPLETED', 'FAILED'].includes(input.status); const empty = !input.status && !(input.history?.length); if (active && empty)
+    throw new Error(`STATE_CONTRACT_MISMATCH:${domain}: active state rendered empty`); return { active, empty }; }