@feltdb/core 0.4.3 → 0.4.5

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 }; }

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

@@ -0,0 +1,228 @@
+export declare const CLASSIFICATIONS: readonly ["STATE", "HISTORY", "RELATIONSHIP", "MATERIALIZED", "BLOB_REFERENCE", "SECRET_REFERENCE", "EXTERNAL_STATE", "OPERATIONAL", "REMOVE"];
+export type Classification = typeof CLASSIFICATIONS[number];
+export type Readiness = 'NEW' | 'ANALYZED' | 'CLASSIFIED' | 'APPROVED' | 'CAPABILITY_READY' | 'PLAN_READY' | 'GENERATED' | 'MIGRATED' | 'STATE_CONTRACT_READY' | 'UI_WIRING_READY' | 'POSTGRES_RUNTIME_FREE' | 'PROVEN' | 'BENCHMARKED' | 'CUTOVER_READY' | 'CUTOVER_COMPLETE';
+export interface Column {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    default?: string | null;
+    primaryKey?: boolean;
+    unique?: boolean;
+    sizeBytes?: number;
+}
+export interface ForeignKey {
+    columns: string[];
+    referencedTable: string;
+    referencedColumns: string[];
+}
+export interface Entity {
+    name: string;
+    columns: Column[];
+    primaryKey?: string[];
+    foreignKeys?: ForeignKey[];
+    indexes?: Array<{
+        name: string;
+        columns: string[];
+        unique?: boolean;
+    }>;
+    kind?: 'table' | 'view';
+}
+export interface SourceFinding {
+    file: string;
+    line: number;
+    kind: string;
+    value: string;
+    entities: string[];
+}
+export interface Analysis {
+    version: 1;
+    generatedAt: string;
+    sourceRoot: string;
+    entities: Entity[];
+    findings: SourceFinding[];
+    dependencies: Array<{
+        from: string;
+        to: string;
+    }>;
+    schemaHash: string;
+}
+export interface ClassifiedEntity {
+    entity: string;
+    classification: Classification;
+    confidence: number;
+    reasons: string[];
+    requiresApproval: boolean;
+}
+export interface ClassificationResult {
+    version: 1;
+    threshold: number;
+    entities: ClassifiedEntity[];
+    classificationHash: string;
+    approved: boolean;
+}
+export interface DomainEntity extends ClassifiedEntity {
+    authoritative: boolean;
+    target: string;
+    secretColumns: string[];
+    blobColumns: string[];
+}
+export interface DomainModel {
+    version: 1;
+    entities: DomainEntity[];
+    hash: string;
+}
+export interface PlanStep {
+    id: string;
+    entity: string;
+    classification: Classification;
+    dependsOn: string[];
+    order: number;
+    tenantKey?: string;
+}
+export interface MigrationPlan {
+    version: 1;
+    planHash: string;
+    steps: PlanStep[];
+}
+export interface StateConsumer {
+    id: string;
+    file: string;
+    line: number;
+    surface: string;
+    semantic: string;
+    source: 'legacy' | 'canonical' | 'unknown';
+    endpoint?: string;
+}
+export interface StateDomain {
+    name: string;
+    authoritativeState: string;
+    history?: string;
+    fields: Record<string, {
+        source: string;
+        canonical: string;
+    }>;
+    uiSurfaces: string[];
+    lifecycleStates: string[];
+    emptyWhen: string;
+    refresh: 'subscription' | 'poll' | 'request';
+    tenantKey?: string;
+}
+export interface StateContract {
+    contractVersion: '1.0';
+    contractHash: string;
+    generatedAt: string;
+    domains: StateDomain[];
+    consumers: StateConsumer[];
+    legacyConsumers: number;
+    canonicalConsumers: number;
+    unresolved: string[];
+}
+export interface Capabilities {
+    [name: string]: boolean;
+}
+export interface Checkpoint {
+    stepId: string;
+    status: 'pending' | 'running' | 'complete' | 'failed';
+    cursor?: string;
+    records: number;
+    error?: string;
+}
+export interface MigrationTelemetry {
+    timestamp: string;
+    stepId: string;
+    operation: string;
+    records: number;
+    durationMs: number;
+    tenant?: string;
+}
+export interface MigrationAdapter {
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    put(collection: string, id: string, value: unknown, options: {
+        idempotencyKey: string;
+        tenant?: string;
+    }): Promise<void>;
+    append(collection: string, id: string, value: unknown, options: {
+        idempotencyKey: string;
+        tenant?: string;
+    }): Promise<void>;
+    relate(collection: string, from: string, to: string, options: {
+        idempotencyKey: string;
+        tenant?: string;
+    }): Promise<void>;
+}
+export interface SourceAdapter {
+    read(entity: string, cursor?: string, tenant?: string): AsyncIterable<{
+        id: string;
+        value: Record<string, unknown>;
+        cursor?: string;
+    }>;
+}
+export interface FeltDBRuntimeContract {
+    mode: 'browser' | 'node' | 'self-hosted' | 'managed';
+    requiredEnvironment: string[];
+    healthCheck?: string;
+    persistence?: string;
+}
+export type DependencyClassification = 'RUNTIME' | 'MIGRATION_SOURCE' | 'LEGACY_FALLBACK' | 'TEST_ONLY' | 'BUILD_ONLY' | 'DEVELOPMENT_ONLY' | 'ROLLBACK_ONLY';
+export type RuntimeFindingCode = 'POSTGRES_RUNTIME_CONNECTION' | 'POSTGRES_RUNTIME_ENV' | 'POSTGRES_RUNTIME_URL' | 'POSTGRES_RUNTIME_CLIENT' | 'POSTGRES_RUNTIME_SQL' | 'POSTGRES_RUNTIME_STARTUP_DEPENDENCY' | 'POSTGRES_RUNTIME_HEALTHCHECK' | 'POSTGRES_RUNTIME_CONTAINER' | 'POSTGRES_RUNTIME_DEPLOYMENT_DEPENDENCY';
+export interface RuntimeDependencyFinding {
+    id: string;
+    code: RuntimeFindingCode;
+    file: string;
+    line: number;
+    classification: DependencyClassification;
+    runtime: boolean;
+    kind: 'environment' | 'connection' | 'sql' | 'startup' | 'healthcheck' | 'container' | 'deployment' | 'dependency';
+    evidence: string;
+    action: string;
+}
+export interface PostgresDependencyManifest {
+    version: 1;
+    generatedAt: string;
+    sourceRoot: string;
+    findings: RuntimeDependencyFinding[];
+    runtime: RuntimeDependencyFinding[];
+    migrationSource: RuntimeDependencyFinding[];
+    legacyFallback: RuntimeDependencyFinding[];
+    testOnly: RuntimeDependencyFinding[];
+    developmentOnly: RuntimeDependencyFinding[];
+    buildOnly: RuntimeDependencyFinding[];
+    rollbackOnly: RuntimeDependencyFinding[];
+    runtimeDependencyHash: string;
+    feltDbRuntime: FeltDBRuntimeContract;
+}
+export interface RuntimeDependencyProof {
+    postgresRuntimeDependency: boolean;
+    postgresConnections: number;
+    postgresSqlExecutions: number;
+    postgresEnvironmentVariables: number;
+    postgresStartupDependencies: number;
+    postgresHealthChecks: number;
+    postgresRuntimeContainers: number;
+    postgresRuntimeDeploymentReferences: number;
+    feltDbRuntime: boolean;
+    verifiedWithoutPostgres: boolean;
+    startupVerified: boolean;
+    recoveryVerified: boolean;
+    networkIsolationVerified: boolean;
+    runtimeDependencyHash: string;
+}
+export interface SherpaConfig {
+    sourceRoot: string;
+    artifactDir?: string;
+    schemaFile: string;
+    confidenceThreshold?: number;
+    classificationOverrides?: Record<string, Classification>;
+    tenantKeys?: Record<string, string>;
+    capabilities?: Capabilities;
+    requiredCapabilities?: string[];
+    stateDomains?: Array<Partial<StateDomain> & {
+        name: string;
+        authoritativeState: string;
+    }>;
+    strictStateContract?: boolean;
+    blobThresholdBytes?: number;
+    feltDbRuntime?: FeltDBRuntimeContract;
+    runtimeDependencyOverrides?: Record<string, DependencyClassification>;
+    runtimeVerificationModule?: string;
+}

package/dist/migrate/types/index.js

@@ -0,0 +1 @@
+export const CLASSIFICATIONS = ['STATE', 'HISTORY', 'RELATIONSHIP', 'MATERIALIZED', 'BLOB_REFERENCE', 'SECRET_REFERENCE', 'EXTERNAL_STATE', 'OPERATIONAL', 'REMOVE'];

package/dist/migrate/ui-wiring/index.d.ts

@@ -0,0 +1,18 @@
+import type { StateContract } from '../types/index.js';
+export interface CanonicalStateReader {
+    state(domain: string, id: string): Promise<Record<string, unknown> | undefined>;
+    history(domain: string, id: string): Promise<unknown[]>;
+    relationships?(domain: string, id: string): Promise<unknown[]>;
+}
+export declare function createCanonicalAdapter(contract: StateContract, reader: CanonicalStateReader): {
+    read(domainName: string, id: string): Promise<{
+        status: unknown;
+        currentAction: unknown;
+        plan: unknown;
+        activity: unknown[];
+        history: unknown[];
+        result: unknown;
+        relationships: unknown[];
+        empty: boolean;
+    }>;
+};

package/dist/migrate/ui-wiring/index.js

@@ -0,0 +1,2 @@
+export function createCanonicalAdapter(contract, reader) { return { async read(domainName, id) { const domain = contract.domains.find(d => d.name === domainName); if (!domain)
+        throw new Error(`Unknown canonical domain: ${domainName}`); const [state, history, relationships] = await Promise.all([reader.state(domain.authoritativeState, id), domain.history ? reader.history(domain.history, id) : Promise.resolve([]), reader.relationships?.(domainName, id) ?? Promise.resolve([])]); return { status: state?.status, currentAction: state?.currentAction, plan: state?.plan, activity: history, history, result: state?.result, relationships, empty: !state && history.length === 0 }; } }; }

package/dist/migrate/util.d.ts

@@ -0,0 +1,5 @@
+export declare function stable(value: unknown): string;
+export declare function hash(value: unknown): string;
+export declare function json<T>(file: string): Promise<T>;
+export declare function writeJson(file: string, value: unknown): Promise<void>;
+export declare const artifact: (dir: string, name: string) => string;

package/dist/migrate/util.js

@@ -0,0 +1,10 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export function stable(value) { if (Array.isArray(value))
+    return `[${value.map(stable).join(',')}]`; if (value && typeof value === 'object')
+    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${stable(v)}`).join(',')}}`; return JSON.stringify(value); }
+export function hash(value) { return createHash('sha256').update(stable(value)).digest('hex'); }
+export async function json(file) { return JSON.parse(await readFile(file, 'utf8')); }
+export async function writeJson(file, value) { await mkdir(dirname(file), { recursive: true }); await writeFile(file, JSON.stringify(value, null, 2) + '\n'); }
+export const artifact = (dir, name) => join(dir, name);

package/dist/react/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @feltdb/react - React Hooks for FeltDB
+ */
+export * from './useFeltDB.js';
+export * from './useCollection.js';
+export * from './useCapability.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,6 @@
+/**
+ * @feltdb/react - React Hooks for FeltDB
+ */
+export * from './useFeltDB.js';
+export * from './useCollection.js';
+export * from './useCapability.js';

package/dist/react/useCapability.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hook for executing FeltDB capabilities
+ */
+import type { Capability } from '@feltdb/core';
+export declare function useCapability<TArgs extends any[] = any[], TResult = any>(capability: Capability | undefined): {
+    execute: (...args: TArgs) => Promise<any>;
+    loading: boolean;
+    error: Error | null;
+    result: TResult | null;
+};
+//# sourceMappingURL=useCapability.d.ts.map

package/dist/react/useCapability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCapability.d.ts","sourceRoot":"","sources":["../src/useCapability.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,wBAAgB,aAAa,CAAC,KAAK,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,OAAO,GAAG,GAAG,EACtE,UAAU,EAAE,UAAU,GAAG,SAAS;uBAOhB,KAAK;;;;EAsBxB"}

package/dist/react/useCapability.js

@@ -0,0 +1,30 @@
+/**
+ * Hook for executing FeltDB capabilities
+ */
+import { useCallback, useState } from 'react';
+export function useCapability(capability) {
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [result, setResult] = useState(null);
+    const execute = useCallback(async (...args) => {
+        if (!capability) {
+            throw new Error('Capability not available');
+        }
+        setLoading(true);
+        setError(null);
+        try {
+            const output = await capability.execute(...args);
+            setResult(output);
+            return output;
+        }
+        catch (err) {
+            const error = err;
+            setError(error);
+            throw error;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [capability]);
+    return { execute, loading, error, result };
+}

package/dist/react/useCollection.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hook for interacting with FeltDB collections
+ */
+import type { Collection } from '@feltdb/core';
+export interface UseCollectionOptions {
+    query?: any;
+    subscribe?: boolean;
+}
+export declare function useCollection<T = any>(collection: Collection<T>, options?: UseCollectionOptions): {
+    data: T[];
+    loading: boolean;
+    error: Error | null;
+    insert: (item: T) => Promise<void>;
+    update: (id: string, item: Partial<T>) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+};
+//# sourceMappingURL=useCollection.d.ts.map

package/dist/react/useCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCollection.d.ts","sourceRoot":"","sources":["../src/useCollection.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,aAAa,CAAC,CAAC,GAAG,GAAG,EACnC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE,oBAAoB;;;;mBA0Bf,CAAC;iBAaH,MAAM,QAAQ,OAAO,CAAC,CAAC,CAAC;iBAaxB,MAAM;EAapB"}

package/dist/react/useCollection.js

@@ -0,0 +1,69 @@
+/**
+ * Hook for interacting with FeltDB collections
+ */
+import { useCallback, useState, useEffect } from 'react';
+export function useCollection(collection, options) {
+    const [data, setData] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let active = true;
+        setLoading(true);
+        collection
+            .find(options?.query || {})
+            .then((results) => {
+            if (active) {
+                setData(results);
+                setLoading(false);
+            }
+        })
+            .catch((err) => {
+            if (active) {
+                setError(err);
+                setLoading(false);
+            }
+        });
+        const unsubscribe = options?.subscribe === false ? undefined : collection.subscribe(() => {
+            void collection.find(options?.query || {}).then(results => {
+                if (active) {
+                    setData(results);
+                    setError(null);
+                    setLoading(false);
+                }
+            }).catch(err => { if (active)
+                setError(err); });
+        });
+        return () => { active = false; unsubscribe?.(); };
+    }, [collection, options?.query, options?.subscribe]);
+    const insert = useCallback(async (item) => {
+        try {
+            await collection.insert(item);
+            const updated = await collection.find(options?.query || {});
+            setData(updated);
+        }
+        catch (err) {
+            setError(err);
+        }
+    }, [collection, options?.query]);
+    const update = useCallback(async (id, item) => {
+        try {
+            await collection.update(id, item);
+            const updated = await collection.find(options?.query || {});
+            setData(updated);
+        }
+        catch (err) {
+            setError(err);
+        }
+    }, [collection, options?.query]);
+    const remove = useCallback(async (id) => {
+        try {
+            await collection.delete(id);
+            const updated = await collection.find(options?.query || {});
+            setData(updated);
+        }
+        catch (err) {
+            setError(err);
+        }
+    }, [collection, options?.query]);
+    return { data, loading, error, insert, update, remove };
+}