@feltdb/core 0.8.0 → 0.8.1

package/dist/module.js

@@ -1,46 +1,535 @@
+const model = (name, ownership = "external-authoritative") => ({
+    name,
+    authority: "external",
+    ownership,
+    fields: [
+        {
+            name: "id",
+            type: "text",
+            immutable: true,
+            externally_owned: true,
+            application_readable: true,
+        },
+        {
+            name: "status",
+            type: "text",
+            optional: true,
+            externally_owned: true,
+            application_readable: true,
+        },
+        {
+            name: "created_at",
+            type: "datetime",
+            externally_owned: true,
+            application_readable: true,
+        },
+        {
+            name: "metadata",
+            type: "json",
+            optional: true,
+            externally_owned: true,
+            application_readable: true,
+        },
+    ],
+});
 const stripe = {
-    id: 'stripe', name: 'Stripe-compatible billing', version: '1.0.0', provider: 'stripe-compatible',
-    compatibility: ['stripe', 'stripe-compatible'],
-    models: ['Customer', 'Product', 'Price', 'Subscription', 'SubscriptionItem', 'Invoice', 'PaymentIntent', 'CheckoutSession', 'PaymentMethod', 'Refund', 'WebhookEvent']
-        .map(name => ({ name, authority: 'external', ownership: 'external-authoritative', fields: [
-            { name: 'id', type: 'text', immutable: true, externally_owned: true, application_readable: true },
-            { name: 'status', type: 'text', optional: true, externally_owned: true, application_readable: true },
-            { name: 'created_at', type: 'datetime', externally_owned: true, application_readable: true },
-            { name: 'metadata', type: 'json', optional: true, externally_owned: true, application_readable: true },
-        ] })),
+    id: "stripe",
+    name: "Stripe-compatible billing",
+    version: "1.0.0",
+    provider: "stripe-compatible",
+    compatibility: ["stripe", "stripe-compatible"],
+    intent_keywords: ["stripe", "billing", "plan", "subscription"],
+    models: [
+        "Customer",
+        "Product",
+        "Price",
+        "Subscription",
+        "SubscriptionItem",
+        "Invoice",
+        "PaymentIntent",
+        "CheckoutSession",
+        "PaymentMethod",
+        "Refund",
+        "WebhookEvent",
+    ].map((name) => model(name)),
     relationships: [
-        { from: 'Customer', to: 'Subscription', kind: 'many' }, { from: 'Subscription', to: 'SubscriptionItem', kind: 'many' },
-        { from: 'SubscriptionItem', to: 'Price', kind: 'one' }, { from: 'Price', to: 'Product', kind: 'one' },
-        { from: 'Customer', to: 'Invoice', kind: 'many' }, { from: 'Invoice', to: 'PaymentIntent', kind: 'one' },
-    ],
-    events: ['stripe.customer.created', 'stripe.customer.updated', 'stripe.subscription.created', 'stripe.subscription.updated', 'stripe.subscription.deleted', 'stripe.invoice.paid', 'stripe.invoice.payment_failed', 'stripe.checkout.session.completed'],
-    capabilities: ['stripe.customer.read', 'stripe.customer.create', 'stripe.checkout.create', 'stripe.subscription.read', 'stripe.subscription.create', 'stripe.subscription.cancel', 'stripe.invoice.read', 'stripe.webhooks.receive'],
-    workflows: ['ReconcileSubscription', 'ReconcileFailedPayment'],
-    configuration: [{ name: 'STRIPE_PUBLISHABLE_KEY', required: false, description: 'Browser-safe publishable provider key' }],
-    secrets: [{ name: 'STRIPE_SECRET_KEY', required: true, description: 'Server-side provider credential' }, { name: 'STRIPE_WEBHOOK_SECRET', required: true, environments: ['production'], description: 'Webhook signature verification secret' }],
-    validation: ['Webhook receivers must verify signatures', 'Checkout creation requires authenticated authorization'],
-    dependencies: [],
+        { from: "Customer", to: "Subscription", kind: "many" },
+        { from: "Subscription", to: "SubscriptionItem", kind: "many" },
+        { from: "SubscriptionItem", to: "Price", kind: "one" },
+        { from: "Price", to: "Product", kind: "one" },
+        { from: "Customer", to: "Invoice", kind: "many" },
+        { from: "Invoice", to: "PaymentIntent", kind: "one" },
+    ],
+    events: [
+        "stripe.customer.created",
+        "stripe.customer.updated",
+        "stripe.subscription.created",
+        "stripe.subscription.updated",
+        "stripe.subscription.deleted",
+        "stripe.invoice.paid",
+        "stripe.invoice.payment_failed",
+        "stripe.checkout.session.completed",
+    ],
+    capabilities: [
+        "stripe.customer.read",
+        "stripe.customer.create",
+        "stripe.checkout.create",
+        "stripe.subscription.read",
+        "stripe.subscription.create",
+        "stripe.subscription.cancel",
+        "stripe.invoice.read",
+        "stripe.webhooks.receive",
+    ],
+    workflows: ["ReconcileSubscription", "ReconcileFailedPayment"],
+    configuration: [
+        {
+            name: "STRIPE_PUBLISHABLE_KEY",
+            required: false,
+            description: "Browser-safe publishable provider key",
+            visibility: "browser",
+        },
+    ],
+    secrets: [
+        {
+            name: "STRIPE_SECRET_KEY",
+            required: true,
+            description: "Server-side provider credential",
+            visibility: "server",
+        },
+        {
+            name: "STRIPE_WEBHOOK_SECRET",
+            required: true,
+            environments: ["production"],
+            description: "Webhook signature verification secret",
+            visibility: "server",
+        },
+    ],
+    validation: [
+        "Webhook receivers must verify signatures",
+        "Checkout creation requires authenticated authorization",
+    ],
+    dependencies: [
+        {
+            name: "authentication",
+            description: "Checkout requires an authenticated application identity",
+            any_collections: ["User", "Account"],
+            any_capabilities: ["auth.session.read", "authentication"],
+        },
+    ],
     authorization: [
-        { capability: 'stripe.checkout.create', subject: 'authenticated', implication: 'A signed-in billing owner may create a hosted checkout session' },
-        { capability: 'stripe.subscription.cancel', subject: 'owner', implication: 'Only the billing owner may cancel a subscription' },
+        {
+            capability: "stripe.checkout.create",
+            subject: "authenticated",
+            implication: "A signed-in billing owner may create a hosted checkout session",
+        },
+        {
+            capability: "stripe.subscription.cancel",
+            subject: "owner",
+            implication: "Only the billing owner may cancel a subscription",
+        },
+    ],
+    extension_application_models: [
+        {
+            name: "BillingPlan",
+            ownership: "application-authoritative",
+            purpose: "Application pricing and entitlement plan",
+            fields: [
+                { name: "code", type: "text" },
+                { name: "interval", type: "enum(monthly,annual)" },
+                { name: "price", type: "ref $module.Price" },
+                { name: "active", type: "boolean" },
+            ],
+        },
     ],
     patterns: [
-        { name: 'organization billing', when: 'The application contains Organization or Workspace state', owner_candidates: ['Organization', 'Workspace'], application_models: [
-                { name: 'BillingAccount', ownership: 'application-authoritative', purpose: 'Connect the application billing owner to provider state' },
-                { name: 'Entitlement', ownership: 'derived', purpose: 'Materialize product access from reconciled subscription state' },
-            ] },
-        { name: 'user billing', when: 'The application is user-centric and has no organizational owner', owner_candidates: ['User', 'Account'], application_models: [
-                { name: 'BillingAccount', ownership: 'application-authoritative', purpose: 'Connect the user to provider state' },
-                { name: 'Entitlement', ownership: 'derived', purpose: 'Materialize product access from reconciled subscription state' },
-            ] },
+        {
+            name: "organization billing",
+            when: "The application contains an organizational owner",
+            owner_candidates: ["Organization", "Workspace"],
+            application_models: [
+                {
+                    name: "BillingAccount",
+                    ownership: "application-authoritative",
+                    purpose: "Connect the application billing owner to provider state",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "customer", type: "ref $module.Customer" },
+                        {
+                            name: "subscription",
+                            type: "ref $module.Subscription",
+                            optional: true,
+                        },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "Entitlement",
+                    ownership: "derived",
+                    purpose: "Materialize product access from reconciled subscription state",
+                    fields: [
+                        { name: "billing_account", type: "ref BillingAccount" },
+                        { name: "key", type: "text" },
+                        { name: "active", type: "boolean" },
+                    ],
+                },
+            ],
+        },
+        {
+            name: "user billing",
+            when: "The application is user-centric",
+            owner_candidates: ["User", "Account"],
+            application_models: [
+                {
+                    name: "BillingAccount",
+                    ownership: "application-authoritative",
+                    purpose: "Connect the user to provider state",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "customer", type: "ref $module.Customer" },
+                        {
+                            name: "subscription",
+                            type: "ref $module.Subscription",
+                            optional: true,
+                        },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "Entitlement",
+                    ownership: "derived",
+                    purpose: "Materialize product access from reconciled subscription state",
+                    fields: [
+                        { name: "billing_account", type: "ref BillingAccount" },
+                        { name: "key", type: "text" },
+                        { name: "active", type: "boolean" },
+                    ],
+                },
+            ],
+        },
     ],
     reconciliation: [
-        { event: 'stripe.subscription.updated', workflow: 'ReconcileSubscription', reads: ['stripe.Subscription', 'BillingAccount'], writes: ['BillingAccount', 'Entitlement'], outcome: 'Subscription changes become application entitlements' },
-        { event: 'stripe.invoice.payment_failed', workflow: 'ReconcileFailedPayment', reads: ['stripe.Invoice', 'BillingAccount'], writes: ['BillingAccount', 'Entitlement'], outcome: 'Failed payment state restricts derived entitlements' },
+        {
+            event: "stripe.subscription.updated",
+            workflow: "ReconcileSubscription",
+            reads: ["stripe.Subscription", "BillingAccount"],
+            writes: ["BillingAccount", "Entitlement"],
+            outcome: "Subscription changes become application entitlements",
+        },
+        {
+            event: "stripe.invoice.payment_failed",
+            workflow: "ReconcileFailedPayment",
+            reads: ["stripe.Invoice", "BillingAccount"],
+            writes: ["BillingAccount", "Entitlement"],
+            outcome: "Failed payment state restricts derived entitlements",
+        },
+    ],
+    placement: {
+        owner_claim: "billing.owner",
+        primary_application_model: "BillingAccount",
+        owner_field: "owner",
+    },
+    source_artifacts: [
+        {
+            path: "src/integrations/stripe/domain.ts",
+            role: "module-domain",
+            purpose: "Application billing state",
+        },
+        {
+            path: "src/integrations/stripe/provider-boundary.ts",
+            role: "module-provider-boundary",
+            purpose: "Stripe operations and verified event boundary",
+        },
+        {
+            path: "src/integrations/stripe/reconcile.ts",
+            role: "module-reconciliation",
+            purpose: "Subscription to entitlement reconciliation",
+        },
+        {
+            path: "src/integrations/stripe/IntegrationView.tsx",
+            role: "module-ui",
+            purpose: "Billing application experience",
+        },
+        {
+            path: "src/integrations/stripe/module.test.ts",
+            role: "module-contract-test",
+            purpose: "Module contract test",
+        },
     ],
 };
-const definitions = new Map([[stripe.id, stripe]]);
-export function listFeltDBModules() { return [...definitions.values()].map(value => structuredClone(value)); }
+const github = {
+    id: "github",
+    name: "GitHub App collaboration",
+    version: "1.0.0",
+    provider: "github-app",
+    compatibility: ["github", "github-app"],
+    intent_keywords: ["github", "repository", "repositories", "issues"],
+    models: [
+        model("Organization"),
+        model("Repository"),
+        model("Installation", "synchronized"),
+        model("Issue"),
+        model("Membership"),
+    ],
+    relationships: [
+        { from: "Organization", to: "Repository", kind: "many" },
+        { from: "Installation", to: "Repository", kind: "many" },
+        { from: "Repository", to: "Issue", kind: "many" },
+    ],
+    events: [
+        "github.repository.created",
+        "github.repository.updated",
+        "github.repository.deleted",
+        "github.installation.created",
+        "github.installation.deleted",
+        "github.membership.added",
+        "github.membership.removed",
+    ],
+    capabilities: [
+        "github.repository.read",
+        "github.repository.create",
+        "github.issue.read",
+        "github.issue.write",
+        "github.webhooks.receive",
+    ],
+    workflows: ["SynchronizeRepository", "SynchronizeInstallation"],
+    configuration: [
+        {
+            name: "GITHUB_APP_ID",
+            required: true,
+            description: "GitHub App identifier",
+            visibility: "server",
+        },
+    ],
+    secrets: [
+        {
+            name: "GITHUB_PRIVATE_KEY",
+            required: true,
+            description: "GitHub App signing key",
+            visibility: "server",
+        },
+        {
+            name: "GITHUB_WEBHOOK_SECRET",
+            required: true,
+            description: "GitHub webhook verification secret",
+            visibility: "server",
+        },
+    ],
+    validation: [
+        "Webhook receivers must verify signatures",
+        "Repository writes require explicit application authorization",
+    ],
+    dependencies: [
+        {
+            name: "authentication",
+            description: "GitHub installation management requires authenticated identity",
+            any_collections: ["User", "Account"],
+            any_capabilities: ["auth.session.read", "authentication"],
+        },
+    ],
+    authorization: [
+        {
+            capability: "github.repository.read",
+            subject: "authenticated",
+            implication: "Authenticated members may read connected repositories",
+        },
+        {
+            capability: "github.repository.create",
+            subject: "owner",
+            implication: "The integration owner controls repository creation",
+        },
+    ],
+    patterns: [
+        {
+            name: "organizational collaboration",
+            when: "Projects belong to an organization or workspace",
+            owner_candidates: ["Organization", "Workspace"],
+            application_models: [
+                {
+                    name: "GitHubConnection",
+                    ownership: "application-authoritative",
+                    purpose: "Bind an application owner to a GitHub App installation",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "installation", type: "ref $module.Installation" },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "RepositoryConnection",
+                    ownership: "synchronized",
+                    purpose: "Map provider repositories into application projects",
+                    fields: [
+                        { name: "connection", type: "ref GitHubConnection" },
+                        { name: "repository", type: "ref $module.Repository" },
+                        { name: "project", type: "ref $project", optional: true },
+                        { name: "synchronized_at", type: "datetime" },
+                    ],
+                },
+            ],
+        },
+        {
+            name: "personal collaboration",
+            when: "Projects belong directly to a user",
+            owner_candidates: ["User", "Account"],
+            application_models: [
+                {
+                    name: "GitHubConnection",
+                    ownership: "application-authoritative",
+                    purpose: "Bind a user to a GitHub App installation",
+                    fields: [
+                        { name: "owner", type: "ref $owner" },
+                        { name: "installation", type: "ref $module.Installation" },
+                        { name: "status", type: "text" },
+                    ],
+                },
+                {
+                    name: "RepositoryConnection",
+                    ownership: "synchronized",
+                    purpose: "Map provider repositories into application projects",
+                    fields: [
+                        { name: "connection", type: "ref GitHubConnection" },
+                        { name: "repository", type: "ref $module.Repository" },
+                        { name: "project", type: "ref $project", optional: true },
+                        { name: "synchronized_at", type: "datetime" },
+                    ],
+                },
+            ],
+        },
+    ],
+    reconciliation: [
+        {
+            event: "github.repository.updated",
+            workflow: "SynchronizeRepository",
+            reads: ["github.Repository", "RepositoryConnection"],
+            writes: ["RepositoryConnection"],
+            outcome: "Repository changes synchronize into application project state",
+        },
+        {
+            event: "github.installation.created",
+            workflow: "SynchronizeInstallation",
+            reads: ["github.Installation"],
+            writes: ["GitHubConnection"],
+            outcome: "GitHub App installations become application connections",
+        },
+    ],
+    placement: {
+        owner_claim: "repository.owner",
+        primary_application_model: "GitHubConnection",
+        owner_field: "owner",
+    },
+    source_artifacts: [
+        {
+            path: "src/integrations/github/domain.ts",
+            role: "module-domain",
+            purpose: "GitHub connection state",
+        },
+        {
+            path: "src/integrations/github/provider-boundary.ts",
+            role: "module-provider-boundary",
+            purpose: "GitHub App operations and webhook verification",
+        },
+        {
+            path: "src/integrations/github/reconcile.ts",
+            role: "module-reconciliation",
+            purpose: "Repository synchronization",
+        },
+        {
+            path: "src/integrations/github/IntegrationView.tsx",
+            role: "module-ui",
+            purpose: "Repository connection experience",
+        },
+        {
+            path: "src/integrations/github/module.test.ts",
+            role: "module-contract-test",
+            purpose: "Module contract test",
+        },
+    ],
+};
+const definitions = new Map();
+export function validateFeltDBModule(module) {
+    const errors = [];
+    for (const key of ["id", "name", "version", "provider"])
+        if (!module[key])
+            errors.push(`missing:${key}`);
+    for (const name of [
+        "compatibility",
+        "models",
+        "relationships",
+        "events",
+        "workflows",
+        "capabilities",
+        "configuration",
+        "secrets",
+        "authorization",
+        "dependencies",
+        "patterns",
+        "reconciliation",
+        "source_artifacts",
+    ])
+        if (!Array.isArray(module[name]))
+            errors.push(`missing:${name}`);
+    for (const item of module.models ?? [])
+        if (![
+            "external-authoritative",
+            "application-authoritative",
+            "derived",
+            "synchronized",
+        ].includes(item.ownership))
+            errors.push(`invalid_ownership:${item.name}`);
+    if (!module.placement?.owner_claim ||
+        !module.placement?.primary_application_model ||
+        !module.placement?.owner_field)
+        errors.push("missing:placement");
+    for (const pattern of module.patterns ?? [])
+        for (const applicationModel of pattern.application_models)
+            if (!applicationModel.fields?.length)
+                errors.push(`missing_fields:${applicationModel.name}`);
+    const modelNames = new Set((module.models ?? []).map(value => value.name));
+    for (const relationship of module.relationships ?? []) {
+        if (!modelNames.has(relationship.from))
+            errors.push(`unknown_relationship_model:${relationship.from}`);
+        if (!modelNames.has(relationship.to))
+            errors.push(`unknown_relationship_model:${relationship.to}`);
+    }
+    const events = new Set(module.events ?? []);
+    const workflows = new Set(module.workflows ?? []);
+    const capabilities = new Set(module.capabilities ?? []);
+    for (const reconciliation of module.reconciliation ?? []) {
+        if (!events.has(reconciliation.event))
+            errors.push(`undeclared_reconciliation_event:${reconciliation.event}`);
+        if (!workflows.has(reconciliation.workflow))
+            errors.push(`undeclared_reconciliation_workflow:${reconciliation.workflow}`);
+    }
+    for (const authorization of module.authorization ?? [])
+        if (!capabilities.has(authorization.capability))
+            errors.push(`undeclared_authorization_capability:${authorization.capability}`);
+    for (const secret of module.secrets ?? [])
+        if (secret.visibility === 'browser' || secret.name.startsWith('VITE_'))
+            errors.push(`browser_secret:${secret.name}`);
+    const sourceRoles = new Set(['module-domain', 'module-provider-boundary', 'module-reconciliation', 'module-ui', 'module-contract-test']);
+    for (const artifact of module.source_artifacts ?? [])
+        if (!artifact.path.startsWith(`src/integrations/${module.id}/`) || !sourceRoles.has(artifact.role))
+            errors.push(`invalid_source_artifact:${artifact.path}`);
+    return [...new Set(errors)];
+}
+export function registerFeltDBModule(module) {
+    const errors = validateFeltDBModule(module);
+    if (errors.length)
+        throw new Error(`MODULE_CONFORMANCE_FAILED: ${errors.join(", ")}`);
+    if (definitions.has(module.id))
+        throw new Error(`MODULE_ALREADY_REGISTERED: ${module.id}`);
+    definitions.set(module.id, structuredClone(module));
+    return () => {
+        definitions.delete(module.id);
+    };
+}
+registerFeltDBModule(stripe);
+registerFeltDBModule(github);
+export function listFeltDBModules() {
+    return [...definitions.values()]
+        .map((value) => structuredClone(value))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
 export function resolveFeltDBModule(declaration) {
     const definition = definitions.get(declaration.name);
     if (!definition)
@@ -53,9 +542,25 @@ export function resolveFeltDBModule(declaration) {
 }
 export function findFeltDBModules(query) {
     const normalized = query.trim().toLowerCase();
-    return listFeltDBModules().filter(module => module.id === normalized || module.name.toLowerCase().includes(normalized) || module.compatibility.some(value => value.includes(normalized)));
+    return listFeltDBModules().filter((module) => module.id === normalized ||
+        module.name.toLowerCase().includes(normalized) ||
+        module.compatibility.some((value) => value.includes(normalized)) ||
+        module.intent_keywords.includes(normalized));
+}
+export function resolveFeltDBModules(declarations = []) {
+    return declarations
+        .map(resolveFeltDBModule)
+        .sort((a, b) => a.id.localeCompare(b.id));
 }
-export function resolveFeltDBModules(declarations = []) { return declarations.map(resolveFeltDBModule).sort((a, b) => a.id.localeCompare(b.id)); }
-export function validateResolvedModules(modules, environment = 'development') {
-    return modules.flatMap(module => [...module.secrets.filter(value => value.required && (!value.environments || value.environments.includes(environment))).map(value => `${value.name} is required in ${environment} runtime configuration`), ...module.capabilities.filter(value => value.endsWith('.create')).map(value => `${value} requires an explicit authorization policy`)]);
+export function validateResolvedModules(modules, environment = "development") {
+    return modules.flatMap((module) => [
+        ...validateFeltDBModule(module).map((value) => `${module.id}: ${value}`),
+        ...module.secrets
+            .filter((value) => value.required &&
+            (!value.environments || value.environments.includes(environment)))
+            .map((value) => `${value.name} is required in ${environment} runtime configuration`),
+        ...module.capabilities
+            .filter((value) => value.endsWith(".create"))
+            .map((value) => `${value} requires an explicit authorization policy`),
+    ]);
 }

package/dist/proposal.d.ts

@@ -1,12 +1,15 @@
 import { type FeltDBContractSnapshot } from './application-development.js';
+import { type ApplicationUnderstanding, type ObservedEvidenceInput } from './application-understanding.js';
 export declare const FELTDB_PROPOSAL_COLLECTION = "_feltdb.Proposal";
 export declare const FELTDB_PROPOSAL_EVENT_COLLECTION = "_feltdb.ProposalEvent";
 export declare const FELTDB_PROPOSAL_PREVIEW_COLLECTION = "_feltdb.ProposalPreview";
+export declare const FELTDB_CONVERGENCE_COLLECTION = "_feltdb.Convergence";
 export declare const FELTDB_PROPOSAL_VERSION = 1;
 export type ProposalStatus = 'proposed' | 'validated' | 'previewed' | 'approved' | 'applied' | 'rejected' | 'expired';
 export interface ProposalSourceOperation {
     path: string;
     operation: 'add' | 'modify' | 'delete';
+    role?: string;
 }
 export interface FeltDBProposalRecord {
     id: string;
@@ -43,6 +46,9 @@ export interface FeltDBProposalRecord {
         provider: string;
         version: string;
     }[];
+    evidence_hash?: string;
+    understanding_hash?: string;
+    understanding?: ApplicationUnderstanding;
     module_impact: {
         modules: string[];
         models: string[];
@@ -69,7 +75,7 @@ export interface FeltDBProposalEvent {
 export interface ProposalReadiness {
     status: ProposalStatus;
     readiness: 'ready' | 'blocked';
-    blockers: ('contract_changed' | 'flow_changed' | 'module_versions_changed' | 'expired')[];
+    blockers: ('contract_changed' | 'flow_changed' | 'module_versions_changed' | 'evidence_changed' | 'expired')[];
     notes: string[];
     current_contract_hash: string;
     proposal_contract_hash: string;
@@ -127,6 +133,7 @@ export interface ProposalStore {
 export interface ProposalContext {
     source: string;
     snapshot: FeltDBContractSnapshot;
+    observations?: ObservedEvidenceInput[];
 }
 export declare class FeltDBProposalService {
     private store;
@@ -145,6 +152,11 @@ export declare class FeltDBProposalService {
         metadata?: Record<string, string>;
         parent_proposal_id?: string;
         expires_at?: string | number;
+        understanding?: ApplicationUnderstanding;
+        contract_diff?: string[];
+        source_plan?: {
+            files: ProposalSourceOperation[];
+        };
     }): Promise<FeltDBProposalRecord>;
     list(): Promise<FeltDBProposalRecord[]>;
     get(id: string): Promise<FeltDBProposalRecord>;