@feltdb/core 0.7.4 → 0.8.1

package/dist/cli/managed-project.js

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function readManagedProjectState(cwd = process.cwd()) {
+    const file = path.join(cwd, '.feltdb', 'managed.json');
+    return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+}

package/dist/cli/proposal-client.js

@@ -9,10 +9,11 @@ export function developmentProposalConnection(cwd = process.cwd()) {
         throw new Error('No running FeltDB proposal service. Start feltdb dev.');
     const config = fs.existsSync(path.join(cwd, 'feltdb.config.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, 'feltdb.config.json'), 'utf8')) : {};
     const published = fs.existsSync(path.join(cwd, '.feltdb', 'last-published.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, '.feltdb', 'last-published.json'), 'utf8')) : {};
+    const managed = fs.existsSync(path.join(cwd, '.feltdb', 'managed.json')) ? JSON.parse(fs.readFileSync(path.join(cwd, '.feltdb', 'managed.json'), 'utf8')) : {};
     const flowApplication = fs.existsSync(path.join(cwd, 'feltdb.flow')) ? parseFlowSpec(fs.readFileSync(path.join(cwd, 'feltdb.flow'), 'utf8')).app : undefined;
     return { endpoint: endpoint.replace(/\/$/, ''), proposalAuthorityToken: stored?.proposalAuthorityToken,
-        applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || published.applicationId || config.applicationId || flowApplication,
-        environment: process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || published.environment || 'local' };
+        applicationId: process.env.VITE_FELTDB_MANAGED_APPLICATION_ID || managed.applicationId || published.applicationId || config.applicationId || flowApplication,
+        environment: managed.environment || published.environment || 'local' };
 }
 export class ProposalServiceClient {
     constructor(connection, token = process.env.FELTDB_MANAGED_CONTROL_API_KEY || '') {
@@ -38,11 +39,23 @@ 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) }); }
-    list() { return this.request(this.scoped('/v1/proposals')); }
+    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)
+        query.set('limit', String(filters.limit)); if (filters.cursor)
+        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, 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

@@ -25,12 +25,14 @@ export function discoverPublishConfiguration(cwd = process.cwd(), environmentOve
         throw new Error('feltdb.config.json is required for publish');
     const project = JSON.parse(fs.readFileSync(configFile, 'utf8'));
     const file = loadEnv(path.join(cwd, '.env.local'));
+    const managedFile = path.join(cwd, '.feltdb', 'managed.json');
+    const managed = fs.existsSync(managedFile) ? JSON.parse(fs.readFileSync(managedFile, 'utf8')) : {};
     const value = (name) => process.env[name] || file[name];
     const configuration = {
-        url: value('VITE_FELTDB_MANAGED_URL'), token: value('FELTDB_MANAGED_CONTROL_API_KEY'),
-        tenantId: value('VITE_FELTDB_MANAGED_TENANT_ID'), applicationId: value('VITE_FELTDB_MANAGED_APPLICATION_ID'),
-        namespace: value('VITE_FELTDB_MANAGED_NAMESPACE') || project.namespace,
-        environment: environmentOverride || value('VITE_FELTDB_MANAGED_ENVIRONMENT') || 'production',
+        url: value('VITE_FELTDB_MANAGED_URL') || managed.url, token: value('FELTDB_MANAGED_CONTROL_API_KEY'),
+        tenantId: managed.tenantId || value('VITE_FELTDB_MANAGED_TENANT_ID'), applicationId: value('VITE_FELTDB_MANAGED_APPLICATION_ID') || managed.applicationId,
+        namespace: managed.namespace || value('VITE_FELTDB_MANAGED_NAMESPACE') || project.namespace,
+        environment: environmentOverride || managed.environment || value('VITE_FELTDB_MANAGED_ENVIRONMENT') || 'production',
     };
     const missing = Object.entries(configuration).filter(([, value]) => !value).map(([name]) => name);
     if (missing.length)
@@ -75,10 +77,11 @@ export function buildPublishBundle(cwd, configuration) {
         'feltdb.agent_hash': contractHash(manifest.agents),
         'feltdb.capability_hash': contractHash(manifest.capabilities),
         'feltdb.contract_hash': contractHash({ dsl_version: spec.version, manifest }),
+        'feltdb.flow_hash': `sha256:${sha256(flowSource.replace(/\r\n/g, '\n'))}`,
         '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);
+}

package/dist/cli/source-sync.js

@@ -1,35 +1,139 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { createHash } from 'node:crypto';
-import { spawnSync } from 'node:child_process';
-import { compileApplicationContract, createContractSnapshot, flowSourceHash, validateFlowProposal, } from '@feltdb/core';
-import { parseFlowSpec } from '@feltdb/core';
-const FLOW_FILE = 'feltdb.flow';
-const GENERATED_FILE = 'src/feltdb/generated-contract.ts';
-const SYNC_STATE = '.feltdb/source-sync.json';
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { compileApplicationContract, createContractSnapshot, flowSourceHash, validateFlowProposal, resolveFeltDBModule, } from "@feltdb/core";
+import { parseFlowSpec } from "@feltdb/core";
+const FLOW_FILE = "feltdb.flow";
+const GENERATED_FILE = "src/feltdb/generated-contract.ts";
+const SYNC_STATE = ".feltdb/source-sync.json";
 function digest(value) {
-    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }
 function readJson(file) {
-    return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : undefined;
+    return fs.existsSync(file)
+        ? JSON.parse(fs.readFileSync(file, "utf8"))
+        : undefined;
 }
 function gitDirty(cwd, files) {
-    const result = spawnSync('git', ['status', '--porcelain', '--', ...files], { cwd, encoding: 'utf8' });
+    const result = spawnSync("git", ["status", "--porcelain", "--", ...files], {
+        cwd,
+        encoding: "utf8",
+    });
     if (result.status !== 0)
         return [];
-    return result.stdout.split(/\r?\n/).filter(Boolean).map(line => line.slice(3));
+    return result.stdout
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => line.slice(3));
+}
+export async function repositoryContext(cwd = process.cwd(), plannedFiles = [FLOW_FILE, GENERATED_FILE]) {
+    const git = (args) => spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const rootResult = git(["rev-parse", "--show-toplevel"]);
+    const root = rootResult.status === 0 ? rootResult.stdout.trim() : path.resolve(cwd);
+    const branchResult = git(["branch", "--show-current"]);
+    const commitResult = git(["rev-parse", "HEAD"]);
+    const context = await loadLocalDevelopmentContract(root);
+    return {
+        root,
+        branch: branchResult.status === 0
+            ? branchResult.stdout.trim() || undefined
+            : undefined,
+        commit: commitResult.status === 0 ? commitResult.stdout.trim() : undefined,
+        dirty: gitDirty(root, plannedFiles),
+        flowPath: path.join(root, FLOW_FILE),
+        flowHash: context.flowHash,
+    };
+}
+export function assertProposalSourcePlan(sourcePlan) {
+    if (!sourcePlan?.files?.length)
+        throw new Error("SOURCE_PLAN_BLOCKED: Proposal has no source operations");
+    for (const operation of sourcePlan.files) {
+        const allowed = operation.path === FLOW_FILE ||
+            operation.path === GENERATED_FILE ||
+            /^src\/integrations\/[a-z0-9-]+\/[A-Za-z0-9._-]+\.(?:ts|tsx)$/.test(operation.path);
+        if (!allowed || !["add", "modify"].includes(operation.operation))
+            throw new Error(`SOURCE_PLAN_BLOCKED: unsupported ${operation.operation} operation for ${operation.path}`);
+    }
+    if (!sourcePlan.files.some((value) => value.path === FLOW_FILE))
+        throw new Error(`SOURCE_PLAN_BLOCKED: ${FLOW_FILE} synchronization is required`);
+}
+function moduleSource(role, module, owner) {
+    const header = `/* Generated from an approved FeltDB ${module.id} module Proposal. Configuration references only; no credential values. */\n`;
+    if (role === "module-domain")
+        return (header +
+            `export type IntegrationOwner=${JSON.stringify(owner)};\nexport const MODULE_MODELS=${JSON.stringify(module.models.map((value) => ({ name: value.name, ownership: value.ownership })))} as const;\nexport interface IntegrationConnection { id:string; ownerType:IntegrationOwner; ownerId:string; externalId:string; status:string; synchronizedAt?:string }\n`);
+    if (role === "module-provider-boundary")
+        return (header +
+            `export const MODULE_ID=${JSON.stringify(module.id)};\nexport const SERVER_CONFIGURATION=${JSON.stringify(module.configuration.filter((value) => value.visibility !== "browser").map((value) => value.name))} as const;\nexport const SERVER_SECRETS=${JSON.stringify(module.secrets.map((value) => value.name))} as const;\nexport const BROWSER_CONFIGURATION=${JSON.stringify(module.configuration.filter((value) => value.visibility === "browser").map((value) => value.name))} as const;\nexport const CAPABILITIES=${JSON.stringify(module.capabilities)} as const;\nexport const EVENTS=${JSON.stringify(module.events)} as const;\nexport interface ModuleTransport { invoke<T>(capability:string,input:unknown):Promise<T>; verifyEvent(payload:string,signature:string,secret:string):Promise<{type:string;data:unknown}> }\nexport function requireServerConfiguration(value:Record<string,string|undefined>){for(const name of [...SERVER_CONFIGURATION,...SERVER_SECRETS]){if(name.startsWith('VITE_'))throw new Error('Server module configuration cannot use VITE_ names');if(!value[name])throw new Error(\`Missing required server configuration: \${name}\`)}return value}\nexport const invokeCapability=<T>(transport:ModuleTransport,capability:typeof CAPABILITIES[number],input:unknown)=>transport.invoke<T>(capability,input);\n`);
+    if (role === "module-reconciliation")
+        return (header +
+            `export const RECONCILIATION=${JSON.stringify(module.reconciliation)} as const;\nexport function reconciliationTrace(event:string){const flow=RECONCILIATION.find(value=>value.event===event);if(!flow)throw new Error(\`Unsupported ${module.id} event: \${event}\`);return [flow.event,flow.workflow,...flow.writes] as const}\n`);
+    if (role === "module-ui")
+        return (header +
+            `export interface IntegrationViewModel { module:${JSON.stringify(module.id)};ownerType:${JSON.stringify(owner)};title:string;connections:Array<{id:string;status:string}>;capabilities:string[] }\nexport function integrationViewModel(connections:Array<{id:string;status:string}>):IntegrationViewModel{return{module:${JSON.stringify(module.id)},ownerType:${JSON.stringify(owner)},title:${JSON.stringify(module.name)},connections,capabilities:${JSON.stringify(module.capabilities)}}}\n`);
+    if (role === "module-contract-test")
+        return (header +
+            `import { reconciliationTrace } from './reconcile.js';\nexport function verifyModuleContract(){const trace=reconciliationTrace(${JSON.stringify(module.reconciliation[0]?.event ?? "")});if(trace[1]!==${JSON.stringify(module.reconciliation[0]?.workflow ?? "")})throw new Error('Module reconciliation contract failed');return true}\n`);
+    throw new Error(`SOURCE_PLAN_BLOCKED: unsupported generated role ${role ?? "<missing>"}`);
+}
+function syncProposalSource(proposal, cwd, replace = false) {
+    const operations = proposal.source_plan?.files.filter((value) => value.role?.startsWith("module-")) ?? [];
+    if (!operations.length)
+        return [];
+    const spec = parseFlowSpec(proposal.proposedFlow);
+    const operationPath = operations[0]?.path;
+    const declaration = spec.modules
+        ?.map((value) => resolveFeltDBModule(value))
+        .find((value) => value.source_artifacts.some((artifact) => artifact.path === operationPath));
+    if (!declaration)
+        throw new Error("SOURCE_PLAN_BLOCKED: source artifacts do not belong to a resolved module");
+    const primary = spec.collections.find((value) => value.name === declaration.placement.primary_application_model);
+    const owner = primary?.fields
+        .find((value) => value.name === declaration.placement.owner_field)
+        ?.type.replace(/^ref /, "") ?? "User";
+    const statePath = path.join(cwd, SYNC_STATE);
+    const state = readJson(statePath) ?? { version: 1, files: {} };
+    const written = [];
+    for (const operation of operations) {
+        const target = path.join(cwd, operation.path);
+        if (fs.existsSync(target)) {
+            const actual = digest(fs.readFileSync(target));
+            const recorded = state.files?.[operation.path];
+            if ((!recorded || recorded !== actual) && !replace)
+                throw new Error(`SOURCE_SYNC_CONFLICT: ${operation.path} has developer changes; review it or rerun with --replace-generated`);
+        }
+        const source = moduleSource(operation.role, declaration, owner);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, source);
+        state.files[operation.path] = digest(source);
+        written.push(operation.path);
+    }
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    return written;
 }
 export async function loadLocalDevelopmentContract(cwd = process.cwd()) {
     const flowPath = path.join(cwd, FLOW_FILE);
     if (!fs.existsSync(flowPath))
         throw new Error(`${FLOW_FILE} is required`);
-    const source = fs.readFileSync(flowPath, 'utf8');
-    const project = readJson(path.join(cwd, 'feltdb.config.json')) ?? {};
-    const published = readJson(path.join(cwd, '.feltdb', 'last-published.json'));
-    const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID
-        || published?.applicationId || project.applicationId || parseFlowSpec(source).app;
-    const tenantId = process.env.VITE_FELTDB_MANAGED_TENANT_ID || published?.tenantId || 'local';
-    const environment = process.env.VITE_FELTDB_MANAGED_ENVIRONMENT || published?.environment || 'local';
+    const source = fs.readFileSync(flowPath, "utf8");
+    const project = readJson(path.join(cwd, "feltdb.config.json")) ?? {};
+    const managed = readJson(path.join(cwd, ".feltdb", "managed.json")) ?? {};
+    const published = readJson(path.join(cwd, ".feltdb", "last-published.json"));
+    const applicationId = process.env.VITE_FELTDB_MANAGED_APPLICATION_ID ||
+        managed.applicationId ||
+        published?.applicationId ||
+        project.applicationId ||
+        parseFlowSpec(source).app;
+    const tenantId = managed.tenantId || published?.tenantId || "local";
+    const environment = managed.environment || published?.environment || "local";
     const contract = await compileApplicationContract(parseFlowSpec(source), tenantId, applicationId);
     return {
         source,
@@ -42,45 +146,60 @@ export async function loadLocalDevelopmentContract(cwd = process.cwd()) {
 }
 export async function reviewFlowProposal(proposal, cwd = process.cwd()) {
     const current = await loadLocalDevelopmentContract(cwd);
-    return validateFlowProposal({ proposal, currentFlow: current.source, snapshot: current.snapshot });
+    return validateFlowProposal({
+        proposal,
+        currentFlow: current.source,
+        snapshot: current.snapshot,
+    });
 }
 function generatedContractSource(review) {
     const snapshot = createContractSnapshot(review.proposedContract, {
-        environment: 'local',
-        contractVersion: review.proposal.baseContractHash === review.proposedContract.hashes.application ? 1 : 2,
+        environment: "local",
+        contractVersion: review.proposal.baseContractHash ===
+            review.proposedContract.hashes.application
+            ? 1
+            : 2,
     });
-    const collections = review.proposedSpec.collections.map(collection => ({
+    const collections = review.proposedSpec.collections.map((collection) => ({
         name: collection.name,
-        fields: collection.fields.map(field => ({ name: field.name, type: field.type, optional: field.optional })),
+        fields: collection.fields.map((field) => ({
+            name: field.name,
+            type: field.type,
+            optional: field.optional,
+        })),
     }));
     const typeName = (value) => {
-        const cleaned = value.replace(/[^A-Za-z0-9_$]/g, '_');
+        const cleaned = value.replace(/[^A-Za-z0-9_$]/g, "_");
         return /^[A-Za-z_$]/.test(cleaned) ? cleaned : `_${cleaned}`;
     };
     const valueType = (value) => {
-        const normalized = value.toLowerCase().replace(/\?$/, '');
-        if (['int', 'integer', 'float', 'number'].includes(normalized))
-            return 'number';
-        if (['bool', 'boolean'].includes(normalized))
-            return 'boolean';
-        if (['json', 'object'].includes(normalized))
-            return 'unknown';
-        if (normalized.endsWith('[]'))
+        const normalized = value.toLowerCase().replace(/\?$/, "");
+        if (["int", "integer", "float", "number"].includes(normalized))
+            return "number";
+        if (["bool", "boolean"].includes(normalized))
+            return "boolean";
+        if (["json", "object"].includes(normalized))
+            return "unknown";
+        if (normalized.endsWith("[]"))
             return `${valueType(normalized.slice(0, -2))}[]`;
-        return 'string';
+        return "string";
     };
-    const types = review.proposedSpec.collections.map(collection => {
-        const fields = collection.fields.map(field => `  ${JSON.stringify(field.name)}${field.optional ? '?' : ''}: ${valueType(field.type)};`);
-        return `export interface ${typeName(collection.name)}Record {\n  id: string;\n${fields.join('\n')}\n}`;
-    }).join('\n\n');
-    const bindings = review.proposedSpec.collections.map(collection => `  ${JSON.stringify(collection.name)}: database.collection<${typeName(collection.name)}Record>(${JSON.stringify(collection.name)}),`).join('\n');
-    return `/* Generated by feltdb sync from feltdb.flow. Do not edit this file directly. */\n`
-        + `export const FELTDB_CONTRACT = ${JSON.stringify(snapshot, null, 2)} as const;\n\n`
-        + `export const FELTDB_COLLECTIONS = ${JSON.stringify(collections, null, 2)} as const;\n\n`
-        + `${types}\n\n`
-        + `export interface FeltDBCollectionBinder {\n  collection<T>(name: string): unknown;\n}\n\n`
-        + `/** Bind the generated, typed collection map to the project's FeltDB instance. */\n`
-        + `export function bindGeneratedCollections(database: FeltDBCollectionBinder) {\n  return {\n${bindings}\n  };\n}\n`;
+    const types = review.proposedSpec.collections
+        .map((collection) => {
+        const fields = collection.fields.map((field) => `  ${JSON.stringify(field.name)}${field.optional ? "?" : ""}: ${valueType(field.type)};`);
+        return `export interface ${typeName(collection.name)}Record {\n  id: string;\n${fields.join("\n")}\n}`;
+    })
+        .join("\n\n");
+    const bindings = review.proposedSpec.collections
+        .map((collection) => `  ${JSON.stringify(collection.name)}: database.collection<${typeName(collection.name)}Record>(${JSON.stringify(collection.name)}),`)
+        .join("\n");
+    return (`/* Generated by feltdb sync from feltdb.flow. Do not edit this file directly. */\n` +
+        `export const FELTDB_CONTRACT = ${JSON.stringify(snapshot, null, 2)} as const;\n\n` +
+        `export const FELTDB_COLLECTIONS = ${JSON.stringify(collections, null, 2)} as const;\n\n` +
+        `${types}\n\n` +
+        `export interface FeltDBCollectionBinder {\n  collection<T>(name: string): unknown;\n}\n\n` +
+        `/** Bind the generated, typed collection map to the project's FeltDB instance. */\n` +
+        `export function bindGeneratedCollections(database: FeltDBCollectionBinder) {\n  return {\n${bindings}\n  };\n}\n`);
 }
 export function syncGeneratedSource(review, cwd = process.cwd(), options = {}) {
     const target = path.join(cwd, GENERATED_FILE);
@@ -97,7 +216,7 @@ export function syncGeneratedSource(review, cwd = process.cwd(), options = {}) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, source);
     fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    fs.writeFileSync(statePath, `${JSON.stringify({ version: 1, contractHash: review.proposedContract.hashes.application, files: { [GENERATED_FILE]: digest(source) } }, null, 2)}\n`, { mode: 0o600 });
+    fs.writeFileSync(statePath, `${JSON.stringify({ version: 1, contractHash: review.proposedContract.hashes.application, files: { ...(state.files ?? {}), [GENERATED_FILE]: digest(source) } }, null, 2)}\n`, { mode: 0o600 });
     return { written: [GENERATED_FILE] };
 }
 function assertGeneratedSourceSafe(cwd, replace = false) {
@@ -114,26 +233,66 @@ export async function applyFlowProposal(proposal, cwd = process.cwd(), options =
     const review = await reviewFlowProposal(proposal, cwd);
     const dirty = gitDirty(cwd, [FLOW_FILE, GENERATED_FILE]);
     if (dirty.length && !options.allowDirty)
-        throw new Error(`DIRTY_SOURCE: uncommitted changes affect ${dirty.join(', ')}`);
+        throw new Error(`DIRTY_SOURCE: uncommitted changes affect ${dirty.join(", ")}`);
     if (review.authorizationChanges.length && !options.approveAuthorization) {
-        throw new Error(`AUTHORIZATION_APPROVAL_REQUIRED: ${review.authorizationChanges.map(change => change.policy).join(', ')}`);
+        throw new Error(`AUTHORIZATION_APPROVAL_REQUIRED: ${review.authorizationChanges.map((change) => change.policy).join(", ")}`);
     }
     if (options.syncSource !== false)
         assertGeneratedSourceSafe(cwd, options.replaceGenerated);
-    fs.writeFileSync(path.join(cwd, FLOW_FILE), proposal.proposedFlow.replace(/\r\n/g, '\n'));
-    const synchronized = options.syncSource === false ? { written: [] } : syncGeneratedSource(review, cwd, { replace: options.replaceGenerated });
-    return { ...review, written: [FLOW_FILE, ...synchronized.written] };
+    fs.writeFileSync(path.join(cwd, FLOW_FILE), proposal.proposedFlow.replace(/\r\n/g, "\n"));
+    const synchronized = options.syncSource === false
+        ? { written: [] }
+        : syncGeneratedSource(review, cwd, { replace: options.replaceGenerated });
+    const moduleWritten = options.syncSource === false
+        ? []
+        : syncProposalSource(proposal, cwd, Boolean(options.replaceGenerated));
+    return {
+        ...review,
+        written: [FLOW_FILE, ...synchronized.written, ...moduleWritten],
+    };
+}
+/** Apply and verify as one developer-visible transaction, restoring exact prior bytes on failure. */
+export async function applyFlowProposalAtomic(proposal, cwd = process.cwd(), options = {}) {
+    const planned = proposal.source_plan?.files.map((value) => value.path) ?? [];
+    const files = [
+        ...new Set([FLOW_FILE, GENERATED_FILE, SYNC_STATE, ...planned]),
+    ].map((relative) => ({ relative, absolute: path.join(cwd, relative) }));
+    const before = files.map((file) => ({
+        ...file,
+        existed: fs.existsSync(file.absolute),
+        bytes: fs.existsSync(file.absolute)
+            ? fs.readFileSync(file.absolute)
+            : undefined,
+    }));
+    try {
+        const result = await applyFlowProposal(proposal, cwd, options);
+        options.verify?.();
+        return result;
+    }
+    catch (error) {
+        for (const file of before) {
+            if (file.existed && file.bytes) {
+                fs.mkdirSync(path.dirname(file.absolute), { recursive: true });
+                fs.writeFileSync(file.absolute, file.bytes);
+            }
+            else if (fs.existsSync(file.absolute))
+                fs.rmSync(file.absolute, { force: true });
+        }
+        throw error;
+    }
 }
 export function describeProposal(review) {
     return [
-        ...review.diff.added.map(value => `+ ${value}`),
-        ...review.diff.changed.map(value => `~ ${value}`),
-        ...review.diff.removed.map(value => `- ${value}`),
-        ...review.authorizationChanges.flatMap(value => [
-            `AUTHORIZATION CHANGE${value.widening ? ' (possible widening)' : ''}: ${value.policy}`,
-            `  before: ${(value.before ?? ['<absent>']).join(' | ')}`,
-            `  after:  ${(value.after ?? ['<removed>']).join(' | ')}`,
+        ...review.diff.added.map((value) => `+ ${value}`),
+        ...review.diff.changed.map((value) => `~ ${value}`),
+        ...review.diff.removed.map((value) => `- ${value}`),
+        ...review.authorizationChanges.flatMap((value) => [
+            `AUTHORIZATION CHANGE${value.widening ? " (possible widening)" : ""}: ${value.policy}`,
+            `  before: ${(value.before ?? ["<absent>"]).join(" | ")}`,
+            `  after:  ${(value.after ?? ["<removed>"]).join(" | ")}`,
         ]),
-        ...review.migration.filter(value => value.safety !== 'safe').map(value => `${value.safety.toUpperCase()}: ${value.target} — ${value.detail}`),
+        ...review.migration
+            .filter((value) => value.safety !== "safe")
+            .map((value) => `${value.safety.toUpperCase()}: ${value.target} — ${value.detail}`),
     ];
 }

package/dist/convergence.d.ts

@@ -0,0 +1,55 @@
+import { type ApplicationUnderstanding, type ObservedEvidenceInput } from './application-understanding.js';
+import type { FeltDBContractSnapshot } from './application-development.js';
+import type { FeltDBProposalRecord } from './proposal.js';
+export type ConvergenceFindingStatus = 'satisfied' | 'missing' | 'partial' | 'contradictory' | 'stale' | 'unverified' | 'unexpected';
+export type ConvergenceStatus = 'pending' | 'checking' | 'converged' | 'partially_converged' | 'diverged' | 'blocked' | 'unverified';
+export type ConvergenceSurface = 'contract' | 'flow' | 'schema' | 'relationship' | 'policy' | 'workflow' | 'capability' | 'module' | 'source' | 'test' | 'build' | 'runtime';
+export interface ConvergenceFinding {
+    claim: string;
+    surface: ConvergenceSurface;
+    status: ConvergenceFindingStatus;
+    expected?: unknown;
+    observed?: unknown;
+    confidence: number;
+    evidence: string[];
+    missing?: string[];
+    reason: string;
+}
+export interface SourcePlanObservation {
+    path: string;
+    status: 'implemented' | 'modified' | 'missing' | 'conflicted' | 'unexpected';
+    evidence?: string[];
+}
+export interface VerificationObservation {
+    surface: 'test' | 'build' | 'runtime';
+    claim: string;
+    status: 'satisfied' | 'partial' | 'missing' | 'unverified';
+    evidence?: string[];
+}
+export interface ConvergenceResult {
+    id?: string;
+    proposal_id: string;
+    application_id: string;
+    environment: string;
+    contract_hash: string;
+    flow_hash: string;
+    evidence_hash: string;
+    status: ConvergenceStatus;
+    findings: ConvergenceFinding[];
+    confidence: number;
+    created_at: string;
+    verifier_version: 1;
+    updated_understanding: ApplicationUnderstanding;
+}
+/** Verifies semantic satisfaction. Source layout is supporting evidence, never the primary convergence boundary. */
+export declare function verifyProposalConvergence(input: {
+    proposal: FeltDBProposalRecord;
+    currentFlow: string;
+    snapshot: FeltDBContractSnapshot;
+    source?: SourcePlanObservation[];
+    verification?: VerificationObservation[];
+    observations?: ObservedEvidenceInput[];
+    now?: string;
+}): Promise<ConvergenceResult>;
+export declare function renderConvergenceDiagnostic(result: ConvergenceResult): string[];
+//# sourceMappingURL=convergence.d.ts.map

package/dist/convergence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convergence.d.ts","sourceRoot":"","sources":["../src/convergence.ts"],"names":[],"mappings":"AACA,OAAO,EAA6D,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACtK,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAE3E,OAAO,KAAK,EAAE,oBAAoB,EAA2B,MAAM,eAAe,CAAC;AAEnF,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,eAAe,GAAG,OAAO,GAAG,YAAY,GAAG,YAAY,CAAC;AACrI,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,qBAAqB,GAAG,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;AACrI,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAC7K,MAAM,WAAW,kBAAkB;IAAG,KAAK,EAAC,MAAM,CAAC;IAAC,OAAO,EAAC,kBAAkB,CAAC;IAAC,MAAM,EAAC,wBAAwB,CAAC;IAAC,QAAQ,CAAC,EAAC,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAC,OAAO,CAAC;IAAC,UAAU,EAAC,MAAM,CAAC;IAAC,QAAQ,EAAC,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAC,MAAM,EAAE,CAAC;IAAC,MAAM,EAAC,MAAM,CAAA;CAAE;AAC/N,MAAM,WAAW,qBAAqB;IAAG,IAAI,EAAC,MAAM,CAAC;IAAC,MAAM,EAAC,aAAa,GAAC,UAAU,GAAC,SAAS,GAAC,YAAY,GAAC,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAC,MAAM,EAAE,CAAA;CAAE;AAC/I,MAAM,WAAW,uBAAuB;IAAG,OAAO,EAAC,MAAM,GAAC,OAAO,GAAC,SAAS,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,MAAM,EAAC,WAAW,GAAC,SAAS,GAAC,SAAS,GAAC,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAC,MAAM,EAAE,CAAA;CAAE;AACpK,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAC,MAAM,CAAC;IAAC,WAAW,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,WAAW,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,CAAC;IAAC,SAAS,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,CAAC;IACxI,MAAM,EAAC,iBAAiB,CAAC;IAAC,QAAQ,EAAC,kBAAkB,EAAE,CAAC;IAAC,UAAU,EAAC,MAAM,CAAC;IAAC,UAAU,EAAC,MAAM,CAAC;IAAC,gBAAgB,EAAC,CAAC,CAAC;IAAC,qBAAqB,EAAC,wBAAwB,CAAC;CACnK;AAKD,oHAAoH;AACpH,wBAAsB,yBAAyB,CAAC,KAAK,EAAC;IAAE,QAAQ,EAAC,oBAAoB,CAAC;IAAC,WAAW,EAAC,MAAM,CAAC;IAAC,QAAQ,EAAC,sBAAsB,CAAC;IAAC,MAAM,CAAC,EAAC,qBAAqB,EAAE,CAAC;IAAC,YAAY,CAAC,EAAC,uBAAuB,EAAE,CAAC;IAAC,YAAY,CAAC,EAAC,qBAAqB,EAAE,CAAC;IAAC,GAAG,CAAC,EAAC,MAAM,CAAA;CAAE,GAAE,OAAO,CAAC,iBAAiB,CAAC,CAqBrS;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAC,iBAAiB,GAAE,MAAM,EAAE,CAA8e"}

package/dist/convergence.js

@@ -0,0 +1,63 @@
+import { canonicalApplicationBytes } from './canonical-application.js';
+import { collectApplicationUnderstanding } from './application-understanding.js';
+import { parseFlowSpec } from './flowspec.js';
+async function digest(value) { const bytes = canonicalApplicationBytes(value); const result = await crypto.subtle.digest('SHA-256', bytes.slice().buffer); return `sha256:${Array.from(new Uint8Array(result), byte => byte.toString(16).padStart(2, '0')).join('')}`; }
+const ev = (items, claim) => items.filter(value => value.claim === claim).map(value => value.id);
+/** Verifies semantic satisfaction. Source layout is supporting evidence, never the primary convergence boundary. */
+export async function verifyProposalConvergence(input) {
+    const expected = parseFlowSpec(input.proposal.proposed_flow);
+    const actual = parseFlowSpec(input.currentFlow);
+    const findings = [];
+    const understanding = await collectApplicationUnderstanding({ intent: `verify ${input.proposal.id}`, snapshot: input.snapshot, currentFlow: input.currentFlow, observations: input.observations, now: input.now });
+    const push = (finding) => findings.push(finding);
+    const actualCollections = new Map(actual.collections.map(value => [value.name, value]));
+    for (const collection of expected.collections) {
+        const observed = actualCollections.get(collection.name);
+        push({ claim: `schema.collection.${collection.name}`, surface: 'schema', status: observed ? 'satisfied' : 'missing', expected: collection.name, observed: observed?.name, confidence: 1, evidence: ev(understanding.evidence, `schema.collection.${collection.name}`), reason: observed ? 'Collection exists in the canonical contract.' : 'Required collection is absent from the canonical contract.' });
+        if (!observed)
+            continue;
+        for (const field of collection.fields.filter(value => value.type.startsWith('ref '))) {
+            const current = observed.fields.find(value => value.name === field.name);
+            const status = !current ? 'missing' : current.type === field.type ? 'satisfied' : 'contradictory';
+            push({ claim: `schema.relationship.${collection.name}.${field.name}`, surface: 'relationship', status, expected: field.type, observed: current?.type, confidence: 1, evidence: ev(understanding.evidence, `schema.relationship.${collection.name}.${field.name}`), reason: status === 'satisfied' ? 'Relationship matches the Proposal.' : status === 'contradictory' ? 'The canonical relationship points to a different target.' : 'Required relationship is absent.' });
+        }
+    }
+    const compareNamed = (surface, expectedValues, actualValues) => { const names = new Set(actualValues.map(value => value.name)); for (const value of expectedValues)
+        push({ claim: `${surface}.${value.name}`, surface, status: names.has(value.name) ? 'satisfied' : 'missing', expected: value.name, observed: names.has(value.name) ? value.name : undefined, confidence: 1, evidence: ev(understanding.evidence, `${surface}.${value.name}`), reason: names.has(value.name) ? `${surface} exists in the canonical contract.` : `Required ${surface} is absent from the canonical contract.` }); };
+    compareNamed('policy', expected.policies, actual.policies);
+    compareNamed('workflow', expected.workflows, actual.workflows);
+    compareNamed('capability', expected.capabilities, actual.capabilities);
+    compareNamed('module', expected.modules ?? [], actual.modules ?? []);
+    const unexpectedNamed = (surface, expectedValues, actualValues) => { const names = new Set(expectedValues.map(value => value.name)); for (const value of actualValues.filter(value => !names.has(value.name)))
+        push({ claim: `${surface}.${value.name}`, surface, status: 'unexpected', observed: value.name, confidence: 1, evidence: ev(understanding.evidence, `${surface}.${surface === 'schema' ? 'collection.' : ''}${value.name}`), reason: `${surface} exists outside the Proposal semantics and does not automatically block convergence.` }); };
+    unexpectedNamed('schema', expected.collections, actual.collections);
+    unexpectedNamed('policy', expected.policies, actual.policies);
+    unexpectedNamed('workflow', expected.workflows, actual.workflows);
+    unexpectedNamed('capability', expected.capabilities, actual.capabilities);
+    unexpectedNamed('module', expected.modules ?? [], actual.modules ?? []);
+    const sourceByPath = new Map((input.source ?? []).map(value => [value.path, value]));
+    for (const planned of input.proposal.source_plan.files) {
+        const observed = sourceByPath.get(planned.path);
+        const status = observed?.status === 'implemented' ? 'satisfied' : observed?.status === 'modified' ? 'partial' : observed?.status === 'conflicted' ? 'contradictory' : observed?.status === 'unexpected' ? 'unexpected' : 'missing';
+        push({ claim: `source.${planned.path}`, surface: 'source', status, expected: planned.operation, observed: observed?.status, confidence: observed ? 1 : .2, evidence: observed?.evidence ?? [], reason: observed ? `Planned source is ${observed.status}.` : 'Planned source path was not verified.' });
+    }
+    for (const observed of input.source ?? [])
+        if (!input.proposal.source_plan.files.some(value => value.path === observed.path) && observed.status === 'unexpected')
+            push({ claim: `source.${observed.path}`, surface: 'source', status: 'unexpected', observed: observed.status, confidence: 1, evidence: observed.evidence ?? [], reason: 'Repository change was outside the Proposal source plan.' });
+    for (const observed of input.verification ?? [])
+        push({ claim: observed.claim, surface: observed.surface, status: observed.status, confidence: observed.status === 'unverified' ? .4 : 1, evidence: observed.evidence ?? [], reason: observed.status === 'satisfied' ? `${observed.surface} verification passed.` : `${observed.surface} verification is ${observed.status}.` });
+    const semantic = findings.filter(value => ['schema', 'relationship', 'policy', 'workflow', 'capability', 'module'].includes(value.surface));
+    const contradictions = semantic.some(value => value.status === 'contradictory');
+    const missing = semantic.some(value => value.status === 'missing');
+    const partial = findings.some(value => value.status === 'partial' || value.status === 'unverified');
+    const status = contradictions || missing ? 'diverged' : partial ? 'partially_converged' : semantic.length ? 'converged' : 'unverified';
+    const assessed = findings.filter(value => value.status !== 'unexpected');
+    const verified = assessed.filter(value => value.status === 'satisfied').length;
+    const confidence = assessed.length ? Math.round((verified / assessed.length) * 100) / 100 : 0;
+    const convergenceObservations = findings.slice(0, 50).map(value => ({ source: 'proposal_history', claim: `convergence.${value.claim}`, value: { status: value.status, confidence: value.confidence }, source_ref: `proposal:${input.proposal.id}` }));
+    const updatedUnderstanding = await collectApplicationUnderstanding({ intent: `verify ${input.proposal.id}`, snapshot: input.snapshot, currentFlow: input.currentFlow, observations: [...(input.observations ?? []).slice(0, 25), ...convergenceObservations.slice(0, 25)], now: input.now });
+    const flowHash = await digest(input.currentFlow.replace(/\r\n/g, '\n'));
+    const evidenceHash = await digest({ proposal_id: input.proposal.id, contract_hash: input.snapshot.contract_hash, flow_hash: flowHash, findings });
+    return { proposal_id: input.proposal.id, application_id: input.proposal.application_id, environment: input.proposal.environment, contract_hash: input.snapshot.contract_hash, flow_hash: flowHash, evidence_hash: evidenceHash, status, findings, confidence, created_at: input.now ?? new Date().toISOString(), verifier_version: 1, updated_understanding: updatedUnderstanding };
+}
+export function renderConvergenceDiagnostic(result) { const icon = (status) => status === 'satisfied' ? '✓' : status === 'unverified' || status === 'partial' ? '⚠' : status === 'unexpected' ? '+' : '✗'; return [`Verification: ${result.status.toUpperCase().replace('_', ' ')}`, `Confidence: ${Math.round(result.confidence * 100)}%`, ...result.findings.map(value => `${icon(value.status)} ${value.surface.toUpperCase()} ${value.claim} — ${value.status}${value.observed !== undefined && value.status !== 'satisfied' ? ` (observed: ${String(value.observed)})` : ''}`)]; }