@feltdb/core 0.8.0 → 0.8.1

package/dist/cli/source-sync.js

@@ -1,58 +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 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 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 };
+    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) {
-    const allowed = new Set([FLOW_FILE, GENERATED_FILE]);
     if (!sourcePlan?.files?.length)
-        throw new Error('SOURCE_PLAN_BLOCKED: Proposal has no source operations');
+        throw new Error("SOURCE_PLAN_BLOCKED: Proposal has no source operations");
     for (const operation of sourcePlan.files) {
-        if (!allowed.has(operation.path) || !['add', 'modify'].includes(operation.operation))
+        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))
+    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 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 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,
@@ -65,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);
@@ -120,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) {
@@ -137,20 +233,37 @@ 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 files = [FLOW_FILE, GENERATED_FILE, SYNC_STATE].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 }));
+    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?.();
@@ -170,14 +283,16 @@ export async function applyFlowProposalAtomic(proposal, cwd = process.cwd(), opt
 }
 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)})` : ''}`)]; }

package/dist/create/managed-account.js

@@ -68,6 +68,7 @@ export async function configureManagedAccount(options) {
                 'application:read', 'application:write', 'application:revision:create',
                 'application:revision:read', 'application:revision:promote',
                 'application:environment:read', 'application:environment:write',
+                'connections:read',
             ],
         }),
     }), 'Could not create the managed control-plane key');

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.8.0';
+export const FELTDB_PACKAGE_VERSION = '0.8.1';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;

package/dist/create/server-source/crates/feltdb/src/application.rs

@@ -211,6 +211,10 @@ pub struct ArtifactReference {
     pub name: String,
     pub uri: String,
     pub media_type: String,
+    /// Immutable source bytes used by trusted control-plane services. The URI
+    /// remains the content identity; values are base64 and never interpreted by Rust.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub content: Option<String>,
 }
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
 pub struct DeploymentIntent {

package/dist/create/server-source/crates/feltdb-server/src/connections.rs

@@ -590,6 +590,20 @@ impl ConnectionStore {
             .cloned()
             .collect())
     }
+
+    /// Internal inventory lookup used after the caller has already passed an
+    /// application-scoped runtime or promotion authorization check.
+    pub fn application_connections(&self, application_id: &str) -> Result<Vec<Connection>, String> {
+        Ok(self
+            .records
+            .read()
+            .map_err(|_| "connection store lock poisoned")?
+            .connections
+            .iter()
+            .filter(|connection| connection.application_id == application_id)
+            .cloned()
+            .collect())
+    }
     pub fn disable(
         &self,
         actor: &str,