@feltdb/core 0.8.0 → 0.8.1

package/dist/cli/commands.js

@@ -9,7 +9,9 @@ import { createRequire } from 'module';
 import { spawn, spawnSync } from 'child_process';
 import { randomBytes } from 'crypto';
 import { createInterface } from 'node:readline/promises';
-import { createFeltDB, createModuleImplementationProposal, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, listFeltDBModules, parseFlowSpec, planFlowSpecMigration, renderProposalDiagnostic, resolveFeltDBModule, resolveModuleIntent, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
+import { createFeltDB, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, listFeltDBModules, parseFlowSpec, planFlowSpecMigration, renderConvergenceDiagnostic, renderProposalDiagnostic, resolveFeltDBModule, resolveModuleIntent, startLocalDevelopmentAuthority, validateFlowSpec, verifyProposalConvergence } from '@feltdb/core';
+import { collectApplicationUnderstanding } from '@feltdb/core';
+import { collectRepositoryEvidence } from './repository-evidence.js';
 import { discoverWorkspace, ensureWorkspaceGitIgnored, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
 import { applicationUrlCandidate, detectApplication, discoverApplicationUrl } from './application.js';
 import { resolveApplicationLifecycle, startManagedApplication, waitForManagedApplication } from './application-lifecycle.js';
@@ -111,7 +113,8 @@ function handleModules(args) {
         const flowPath = path.resolve('feltdb.flow');
         const spec = args.includes('--application') && fs.existsSync(flowPath) ? parseFlowSpec(fs.readFileSync(flowPath, 'utf8')) : undefined;
         const declaration = spec?.modules?.find(value => value.name === args[1]);
-        const module = resolveFeltDBModule(declaration ?? { name: args[1], provider: args.find((value, index) => index > 1 && !value.startsWith('--')) || 'stripe-compatible' });
+        const registered = listFeltDBModules().find(value => value.id === args[1]);
+        const module = resolveFeltDBModule(declaration ?? { name: args[1], provider: args.find((value, index) => index > 1 && !value.startsWith('--')) || registered?.provider || '' });
         const usage = spec?.collections.flatMap(collection => collection.fields.filter(field => field.type.startsWith(`ref ${module.id}.`)).map(field => `${collection.name}.${field.name} -> ${field.type.slice(4)}`)) ?? [];
         console.log(JSON.stringify({ ...module, application_usage: usage }, null, 2));
         return;
@@ -140,6 +143,30 @@ function validateRepositoryBuild(args) {
         console.log(`✓ ${name} passed`);
     }
 }
+function verificationChecks(run = true) {
+    const packagePath = path.resolve('package.json');
+    const projectPackage = fs.existsSync(packagePath) ? JSON.parse(fs.readFileSync(packagePath, 'utf8')) : {};
+    const results = [];
+    for (const name of ['typecheck', 'test', 'build'].filter(value => projectPackage.scripts?.[value])) {
+        if (!run) {
+            results.push({ surface: name === 'test' ? 'test' : 'build', claim: `repository.${name}`, status: 'satisfied', evidence: [`npm run ${name}`] });
+            continue;
+        }
+        const checked = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', name], { cwd: process.cwd(), stdio: 'inherit' });
+        results.push({ surface: name === 'test' ? 'test' : 'build', claim: `repository.${name}`, status: checked.status === 0 ? 'satisfied' : 'missing', evidence: [`npm run ${name} exited ${checked.status ?? 'without status'}`] });
+    }
+    if (!results.length)
+        results.push({ surface: 'test', claim: 'repository.validation', status: 'unverified', evidence: ['No typecheck, test, or build script is declared.'] });
+    return results;
+}
+async function verifyAndRecord(proposal, runChecks = true) {
+    const current = await loadLocalDevelopmentContract();
+    const source = proposal.source_plan.files.map(file => ({ path: file.path, status: (fs.existsSync(path.resolve(file.path)) ? 'implemented' : 'missing'), evidence: [fs.existsSync(path.resolve(file.path)) ? `repository path ${file.path}` : `missing repository path ${file.path}`] }));
+    const result = await verifyProposalConvergence({ proposal, currentFlow: current.source, snapshot: current.snapshot, source, verification: verificationChecks(runChecks), observations: collectRepositoryEvidence() });
+    const stored = await proposalService().recordConvergence(proposal.id, result);
+    console.log(renderConvergenceDiagnostic(stored).join('\n'));
+    return stored;
+}
 async function handleAi(args) {
     loadProjectEnvironment();
     if (args[0] === 'model') {
@@ -171,6 +198,16 @@ async function handleAi(args) {
         return handleStudio(args, studioUrl => console.log(`Ask FeltDB: ${studioUrl}`));
     }
     const action = args[0];
+    if (action === 'verify' || action === 'converge') {
+        const id = args[1];
+        if (!id)
+            throw new Error(`Usage: feltdb ai ${action} <proposal-id>`);
+        const proposal = await proposalService().get(id);
+        if (proposal.status !== 'applied')
+            throw new Error(`Cannot verify Proposal ${id}. Current status: ${proposal.status}. Verification follows application.`);
+        await verifyAndRecord(proposal, !args.includes('--no-build'));
+        return;
+    }
     if (action === 'proposals')
         return handleProposals(['list', ...args.slice(1)]);
     if (action === 'proposal') {
@@ -185,7 +222,7 @@ async function handleAi(args) {
             throw new Error('Usage: feltdb ai approve <id> [--yes]');
         const client = proposalService();
         const proposal = await client.get(id);
-        const readiness = await client.status(id);
+        const readiness = await currentProposalReadiness(client, proposal);
         if (proposal.status !== 'previewed')
             throw new Error(`Cannot approve Proposal ${id}. Current status: ${proposal.status}. A current preview is required.`);
         if (readiness.blockers.length)
@@ -231,7 +268,7 @@ async function handleAi(args) {
             throw new Error('A proposal id or JSON file is required');
         const stored = target.startsWith('p_') ? await proposalService().get(target) : undefined;
         const proposal = stored ? { baseContractHash: stored.base_contract_hash, baseFlowHash: stored.base_flow_hash,
-            proposedFlow: stored.proposed_flow, summary: stored.summary, changes: stored.contract_diff, warnings: stored.warnings }
+            proposedFlow: stored.proposed_flow, summary: stored.summary, changes: stored.contract_diff, warnings: stored.warnings, source_plan: stored.source_plan }
             : JSON.parse(fs.readFileSync(path.resolve(target), 'utf8'));
         if (stored && stored.status !== 'approved')
             throw new Error(`Cannot apply Proposal ${stored.id}. Current status: ${stored.status}. Approval is required. Run: feltdb ai approve ${stored.id}`);
@@ -250,6 +287,7 @@ async function handleAi(args) {
             });
             await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
             console.log(`✓ Reconciled and marked ${stored.id} applied`);
+            await verifyAndRecord({ ...stored, status: 'applied' }, false);
             return;
         }
         if (stored) {
@@ -291,50 +329,43 @@ async function handleAi(args) {
         console.log(`✓ Applied validated flow proposal (${review.proposedContract.hashes.application})`);
         for (const file of review.written)
             console.log(`  ${file}`);
-        if (stored)
-            await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
+        if (stored) {
+            const applied = await proposalService().transition(stored.id, 'applied', 'cli-repository-applier', true);
+            await verifyAndRecord(applied, false);
+        }
         return;
     }
     const developerIntent = args.filter(value => !value.startsWith('--')).join(' ').trim();
     if (developerIntent) {
         const resolved = resolveModuleIntent(developerIntent);
         if (resolved) {
-            console.log('Understanding application...');
-            const current = await loadLocalDevelopmentContract();
-            console.log('✓ Application contract loaded');
-            const proposal = await createModuleImplementationProposal({ intent: developerIntent, snapshot: current.snapshot, currentFlow: current.source });
-            console.log(`✓ ${proposal.implementation?.module.name} ${proposal.implementation?.module.version} resolved`);
-            console.log(`✓ Billing owner: ${proposal.implementation?.owner}`);
-            const review = await reviewFlowProposal(proposal);
-            if (proposal.implementation?.alreadyInstalled) {
-                console.log(`${proposal.implementation.module.name} is already installed.`);
-                const missing = [...review.diff.added, ...review.diff.changed];
-                if (!missing.length) {
-                    console.log('Current implementation is complete. No proposal created.');
-                    return;
-                }
-                console.log('Missing:');
-                for (const value of missing)
-                    console.log(`  ${value}`);
-                console.log('Creating a completion proposal.');
-            }
-            console.log('Generating implementation proposal...');
             const client = proposalService();
-            const parent = (await client.list({ status: 'applied', limit: 100 })).proposals.find(value => value.metadata?.module === resolved.module);
-            let stored = await client.create({ application_id: current.snapshot.application.application_id, environment: current.snapshot.application.environment,
-                base_contract_hash: proposal.baseContractHash, base_flow_hash: proposal.baseFlowHash, proposed_flow: proposal.proposedFlow,
-                proposal_version: 1, contract_diff: [], source_plan: { files: [] },
-                summary: proposal.summary, warnings: proposal.warnings, actor: 'cli-developer', parent_proposal_id: parent?.id, metadata: { created_from: 'module-intent', module: resolved.module, module_version: resolved.version } });
-            await client.validate(stored.id, 'feltdb-validator', review.proposedContract.manifest);
-            const preview = await client.preview(stored.id, 'cli-developer');
-            stored = preview.proposal;
-            const readiness = await client.status(stored.id);
-            console.log(renderProposalDiagnostic(stored, { readiness, preview: preview }).join('\n'));
+            console.log('Executing intent through the FeltDB Intent Service...');
+            const execution = await client.executeIntent(developerIntent);
+            if (execution.blockers.length)
+                throw new Error(`INTENT_BLOCKED: ${execution.blockers.join(', ')}`);
+            const ownerClaim = execution.plan?.module.placement.owner_claim;
+            const ownerInference = execution.understanding?.inferences.find(value => value.claim === ownerClaim);
+            console.log(`✓ Intent ${execution.intent.id}: ${execution.intent.action} ${execution.intent.module}`);
+            console.log(`✓ Evidence collected (${execution.understanding?.evidence.length ?? 0} normalized facts)`);
+            if (execution.understanding?.completeness)
+                console.log(`✓ Understanding completeness: ${execution.understanding.completeness.score}%`);
+            if (ownerInference)
+                console.log(`✓ Integration owner: ${String(ownerInference.value)} · ${Math.round(ownerInference.confidence * 100)}% · ${ownerInference.authority}`);
+            if (!execution.proposal) {
+                console.log(`✓ ${execution.intent.module} is already installed and converged. No proposal created.`);
+                return;
+            }
+            const stored = execution.proposal;
+            if (execution.plan?.already_installed)
+                console.log('Creating a completion proposal for the existing module implementation.');
+            const readiness = await client.status(stored.id, stored.evidence_hash);
+            console.log(renderProposalDiagnostic(stored, { readiness, preview: execution.preview }).join('\n'));
             console.log(`Use:\n  feltdb ai proposal ${stored.id}`);
             return;
         }
     }
-    throw new Error('Usage: feltdb ai ["implement <module>"|context|proposals|proposal <id>|approve <id>|review <proposal.json>|apply <id>]');
+    throw new Error('Usage: feltdb ai ["implement <module>"|context|proposals|proposal <id>|approve <id>|review <proposal.json>|apply <id>|verify <id>|converge <id>]');
 }
 async function handleProposals(args) {
     loadProjectEnvironment();
@@ -362,7 +393,7 @@ async function handleProposals(args) {
         throw new Error(`feltdb proposals ${action} requires a proposal id`);
     if (action === 'get') {
         const proposal = await client.get(id);
-        const [readiness, history] = await Promise.all([client.status(id), client.history(id)]);
+        const [readiness, history] = await Promise.all([currentProposalReadiness(client, proposal), client.history(id)]);
         const preview = proposal.preview_id ? await client.getPreview(proposal.preview_id).catch(() => undefined) : undefined;
         const result = { proposal, readiness, preview, history: history.events };
         if (args.includes('--json'))
@@ -384,6 +415,18 @@ async function handleProposals(args) {
     }
     throw new Error('Usage: feltdb proposals [list|get|diff|approve|reject] [id]');
 }
+async function currentProposalReadiness(client, proposal) {
+    if (!proposal.understanding)
+        return client.status(proposal.id);
+    const current = await loadLocalDevelopmentContract();
+    let moduleIntent;
+    try {
+        moduleIntent = resolveModuleIntent(proposal.understanding.intent);
+    }
+    catch { }
+    const understanding = await collectApplicationUnderstanding({ intent: proposal.understanding.intent, snapshot: current.snapshot, currentFlow: current.source, moduleIntent, observations: collectRepositoryEvidence(), now: proposal.understanding.created_at });
+    return client.status(proposal.id, understanding.evidence_hash);
+}
 async function handleSourceSync(args) {
     loadProjectEnvironment();
     const context = await loadLocalDevelopmentContract();
@@ -1080,6 +1123,7 @@ async function handleDev(args) {
             dataDir: path.join(projectDir, '.feltdb-data', 'authority'),
             port: authorityPort,
             proposalContext: () => loadLocalDevelopmentContract(projectDir),
+            intentObservations: () => collectRepositoryEvidence(projectDir),
         });
         process.env.VITE_FELTDB_URL = localAuthority.endpoint;
         const connectionsPath = path.join(projectDir, '.feltdb', 'connections.json');
@@ -1699,6 +1743,55 @@ async function handleStudio(args, onReady) {
             }
             return;
         }
+        if (pathname === '/_feltdb/intents' && request.method === 'POST') {
+            response.setHeader('Content-Type', 'application/json; charset=utf-8');
+            response.setHeader('Cache-Control', 'no-store');
+            if (request.headers['x-feltdb-studio-token'] !== studioMutationToken) {
+                response.statusCode = 403;
+                response.end(JSON.stringify({ error: 'Invalid Studio token' }));
+                return;
+            }
+            try {
+                const chunks = [];
+                for await (const chunk of request)
+                    chunks.push(Buffer.from(chunk));
+                const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                if (!input.intent?.trim())
+                    throw new Error('An intent is required');
+                const execution = await proposalClient.executeIntent(input.intent, 'studio-developer');
+                if (!execution.proposal) {
+                    response.statusCode = execution.blockers.length ? 409 : 200;
+                    response.end(JSON.stringify(execution));
+                    return;
+                }
+                const flowProposal = {
+                    baseContractHash: execution.proposal.base_contract_hash,
+                    baseFlowHash: execution.proposal.base_flow_hash,
+                    proposedFlow: execution.proposal.proposed_flow,
+                    summary: execution.proposal.summary,
+                    changes: execution.proposal.contract_diff,
+                    warnings: execution.proposal.warnings,
+                    source_plan: execution.proposal.source_plan,
+                    implementation: execution.plan ? {
+                        intent: { action: execution.intent.action === 'extend' ? 'extend' : 'implement', module: execution.plan.module.id, provider: execution.plan.module.provider, version: execution.plan.module.version, original: execution.intent.raw_request },
+                        module: execution.plan.module, alreadyInstalled: execution.plan.already_installed, owner: Object.values(execution.plan.ownership)[0], ownerClaim: execution.plan.module.placement.owner_claim, primaryApplicationModel: execution.plan.module.placement.primary_application_model,
+                        applicationModels: execution.plan.state_changes, relationships: execution.plan.relationships, events: execution.plan.events,
+                        workflows: execution.plan.workflows, capabilities: execution.plan.capabilities, authorization: execution.plan.authorization,
+                        configuration: execution.plan.configuration, secrets: execution.plan.secrets, dependencies: execution.plan.dependencies, stateFlow: [], warnings: execution.plan.warnings,
+                    } : undefined,
+                    understanding: execution.understanding,
+                };
+                const review = await reviewFlowProposal(flowProposal);
+                response.end(JSON.stringify({ execution, proposal: flowProposal, proposalId: execution.proposal.id,
+                    changes: describeProposal(review), sourcePlan: execution.proposal.source_plan.files.map(value => value.path),
+                    authorizationChanges: review.authorizationChanges, migration: review.migration, contractHash: review.proposedContract.hashes.application }));
+            }
+            catch (error) {
+                response.statusCode = 400;
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         const proposalDetail = pathname.match(/^\/_feltdb\/proposals\/(p_[A-Za-z0-9]+)$/);
         if (proposalDetail && request.method === 'GET') {
             response.setHeader('Content-Type', 'application/json; charset=utf-8');

package/dist/cli/proposal-client.js

@@ -39,6 +39,8 @@ export class ProposalServiceClient {
     }
     actor(input = {}) { return { application_id: this.connection.applicationId, environment: this.connection.environment, ...input }; }
     create(input) { return this.request('/v1/proposals', { method: 'POST', body: JSON.stringify(input) }); }
+    executeIntent(rawRequest, actor = 'cli-developer') { return this.request('/v1/intents', { method: 'POST', body: JSON.stringify(this.actor({ raw_request: rawRequest, actor })) }); }
+    intents() { return this.request(this.scoped('/v1/intents')); }
     list(filters = {}) { const query = new URLSearchParams(); if (this.connection.applicationId)
         query.set('application_id', this.connection.applicationId); query.set('environment', filters.environment || this.connection.environment || 'local'); if (filters.status)
         query.set('status', filters.status); if (filters.limit)
@@ -46,12 +48,14 @@ export class ProposalServiceClient {
         query.set('cursor', filters.cursor); return this.request(`/v1/proposals?${query}`); }
     get(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}`)); }
     history(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}/history`)); }
-    status(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}/status`)); }
+    status(id, currentEvidenceHash) { const path = this.scoped(`/v1/proposals/${encodeURIComponent(id)}/status`); return this.request(currentEvidenceHash ? `${path}&current_evidence_hash=${encodeURIComponent(currentEvidenceHash)}` : path); }
     validate(id, actor = 'local-developer', proposedManifest) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/validate`, { method: 'POST', body: JSON.stringify(this.actor({ actor, proposed_manifest: proposedManifest })) }); }
     preview(id, actor = 'local-developer') { return this.request(`/v1/proposals/${encodeURIComponent(id)}/preview`, { method: 'POST', body: JSON.stringify(this.actor({ actor })) }); }
     getPreview(id) { return this.request(this.scoped(`/v1/previews/${encodeURIComponent(id)}`)); }
     approve(id, actor = 'local-developer', approveAuthorization = false) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/approve`, { method: 'POST', body: JSON.stringify(this.actor({ actor, approve_authorization: approveAuthorization })) }); }
     reject(id, actor = 'local-developer', reason) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/reject`, { method: 'POST', body: JSON.stringify(this.actor({ actor, reason })) }); }
+    convergence(id) { return this.request(this.scoped(`/v1/proposals/${encodeURIComponent(id)}/convergence`)); }
+    recordConvergence(id, result) { return this.request(`/v1/proposals/${encodeURIComponent(id)}/convergence`, { method: 'POST', body: JSON.stringify(this.actor(result)) }); }
     transition(id, status, actor = 'local-developer', repositoryAuthority = false, approveAuthorization = false) {
         return this.request(`/v1/proposals/${encodeURIComponent(id)}/status`, { method: 'PATCH', headers: repositoryAuthority && this.connection.proposalAuthorityToken
                 ? { 'FeltDB-Proposal-Authority': this.connection.proposalAuthorityToken, 'FeltDB-Repository-Apply': '1' } : {}, body: JSON.stringify(this.actor({ status, actor, approve_authorization: approveAuthorization })) });

package/dist/cli/publish-engine.js

@@ -81,7 +81,7 @@ export function buildPublishBundle(cwd, configuration) {
         'feltdb.artifact_hash': artifactHash,
         'feltdb.namespace': configuration.namespace,
     };
-    manifest.artifacts = artifacts.map(value => ({ name: value.path, uri: `data:${value.mediaType};base64,${value.content}`, media_type: value.mediaType }));
+    manifest.artifacts = artifacts.map(value => ({ name: value.path, uri: `artifact://${value.hash}`, media_type: value.mediaType, ...(value.path === 'feltdb.flow' ? { content: value.content } : {}) }));
     const git = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
     const sourceRevision = git.status === 0 ? git.stdout.trim() : undefined;
     if (sourceRevision)

package/dist/cli/repository-evidence.js

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+const sourceExtensions = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.rs']);
+function sourceFiles(root) {
+    const found = [];
+    const visit = (directory) => {
+        if (found.length >= 300 || !fs.existsSync(directory))
+            return;
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (found.length >= 300)
+                break;
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory() && !['node_modules', 'dist', 'build', '.git', '.feltdb-data'].includes(entry.name))
+                visit(absolute);
+            else if (entry.isFile() && sourceExtensions.has(path.extname(entry.name)) && fs.statSync(absolute).size <= 64 * 1024)
+                found.push(absolute);
+        }
+    };
+    visit(path.join(root, 'src'));
+    return found;
+}
+/** Produces bounded claims and file references; source text never leaves this function. */
+export function collectRepositoryEvidence(cwd = process.cwd()) {
+    const observations = [];
+    try {
+        const status = execFileSync('git', ['status', '--porcelain=v1'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        observations.push({ source: 'git', claim: 'git.working_tree', value: status.trim() ? 'dirty' : 'clean', source_ref: '.git' });
+    }
+    catch { }
+    for (const absolute of sourceFiles(cwd)) {
+        if (observations.length >= 50)
+            break;
+        const relative = path.relative(cwd, absolute).split(path.sep).join('/');
+        let source = '';
+        try {
+            source = fs.readFileSync(absolute, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const add = (claim, value) => observations.push({ source: 'repository', claim, value, source_ref: relative });
+        if (/\b(authenticated|useSession|session|signIn|signOut)\b/i.test(source))
+            add('repository.authentication', 'authenticated session implementation observed');
+        if (/\borganization(?:Id|_id)?\b/i.test(source) && /\b(project|settings|billing)\b/i.test(source))
+            add('repository.organization_boundary', 'organization-scoped implementation observed');
+        if (/\buser(?:Id|_id|\.id)?\b/i.test(source) && /\b(project|settings|billing)\b/i.test(source))
+            add('repository.user_boundary', 'user-scoped implementation observed');
+        if (/\b(checkout|subscription|billing|stripe)\b/i.test(source))
+            add('repository.billing_surface', 'billing implementation surface observed');
+        if (/\b(github|repository|installation|webhook)\b/i.test(source))
+            add('repository.integration_surface', 'external collaboration implementation surface observed');
+    }
+    return observations.slice(0, 50);
+}