FeltDB Migration Sherpa

Configuration-driven PostgreSQL → FeltDB-native application-state migration. Extracted from the Synapse reference migration and designed to fail closed at classification, capability, canonical-state, and semantic-proof gates.

Install

npm install --save-dev @feltdb/migration-sherpa

The package provides both the felt-migrate CLI and a typed ESM API.

Configure

Create felt-migrate.json:

{
  "sourceRoot": ".",
  "schemaFile": "postgres-schema.json",
  "artifactDir": ".feltdb",
  "confidenceThreshold": 0.9,
  "strictStateContract": true,
  "feltDbRuntime": {
    "mode": "node",
    "requiredEnvironment": ["FELTDB_STORAGE_PATH"],
    "healthCheck": "FeltDB checkpoint storage is writable",
    "persistence": "atomic checkpoint"
  },
  "classificationOverrides": {
    "release_events": "HISTORY"
  },
  "stateDomains": [
    {
      "name": "release",
      "authoritativeState": "releases",
      "history": "release_events",
      "tenantKey": "tenant_id"
    }
  ],
  "capabilities": {
    "atomicTransactions": true,
    "immutableHistory": true,
    "deterministicOrdering": true,
    "durablePersistence": true,
    "indexedQueries": true,
    "tenantIsolation": true,
    "idempotentWrites": true,
    "concurrencySafety": true,
    "reconstruction": true,
    "versionConflicts": true,
    "canonicalStateRefresh": true,
    "stateHistorySeparation": true,
    "uiStateContract": true
  }
}

The schema inventory has the shape { "entities": [...] }. Its TypeScript definitions are exported as Entity, Column, and ForeignKey.

Run

npx felt-migrate analyze
npx felt-migrate classify
npx felt-migrate review --approve
npx felt-migrate postgres-scan
npx felt-migrate all

all never crosses a human approval gate automatically. Machine-readable analysis, plans, checkpoints, state contracts, proofs, measurements, reports, and the migration manifest are written beneath .feltdb/.

Programmatic migration

import { migrate } from '@feltdb/migration-sherpa';

const checkpoints = await migrate(
  migrationPlan,
  domainModel,
  postgresSourceAdapter,
  feltDBPrimitiveAdapter,
  previousCheckpoints,
  tenantId,
  telemetry => observability.emit(telemetry),
);

The source and target adapters keep database credentials and runtime choices outside the engine. Migration is deterministic and resumable through checkpoints and idempotency keys. Secret and blob payload columns are removed before target writes; FeltDB receives references, not sensitive or oversized payloads.

Product-specific classifications and state semantics belong in configuration and adapters, never in the package itself.

PostgreSQL-free cutover

The runtime scanner distinguishes application dependencies from permitted migration sources, rollback infrastructure, legacy fallback code, tests, development, and build tooling:

npx felt-migrate postgres-scan
npx felt-migrate config-scan
npx felt-migrate deployment-scan
npx felt-migrate postgres-remove
npx felt-migrate postgres-verify

postgres-remove generates an approval-required configuration plan; it does not silently edit configuration. Classification exceptions are explicit and auditable through runtimeDependencyOverrides, keyed by file, file:line, or dependency identity.

Dynamic verification uses an application-owned module so deployment startup is not hard-coded into the Sherpa:

{
  "runtimeVerificationModule": "./migration/postgres-isolation.js"
}

The module exports createHarness() (or a default factory) returning startWithPostgresBlocked, executeWorkflow, restart, verifyRecovery, postgresConnectionAttempts, and optional cleanup functions. A passing proof requires successful startup, workflow persistence, restart recovery, and zero PostgreSQL connection attempts.