118 lines
2.8 KiB
TypeScript
118 lines
2.8 KiB
TypeScript
/**
|
|
* Flow Funding V2 - Continuous Flow Dynamics
|
|
*
|
|
* Core types for the flow-oriented funding mechanism
|
|
*/
|
|
|
|
/**
|
|
* Flow Node - A participant in the flow network
|
|
*
|
|
* Each node has:
|
|
* - External inflow ($/month) - what funders contribute
|
|
* - Min threshold ($/month) - needs level
|
|
* - Max threshold ($/month) - capacity level
|
|
* - Allocations - where overflow flows to
|
|
*/
|
|
export interface FlowNode {
|
|
id: string
|
|
name: string
|
|
|
|
// Flow rates ($/month for UI, converted to $/second for simulation)
|
|
externalInflow: number // From funders/sliders
|
|
minThreshold: number // Needs level
|
|
maxThreshold: number // Capacity level
|
|
|
|
// Where overflow flows to (percentages sum to ≤100)
|
|
allocations: Map<string, number>
|
|
|
|
// Computed during steady-state calculation
|
|
totalInflow?: number // External + incoming from other nodes
|
|
totalOutflow?: number // Sent to other nodes
|
|
balance?: number // Accumulated balance (for visualization only)
|
|
}
|
|
|
|
/**
|
|
* Progressive Outflow Zones
|
|
*
|
|
* Deficit Zone (totalInflow < min): Keep everything, outflow = 0
|
|
* Building Zone (min ≤ totalInflow ≤ max): Progressive sharing
|
|
* Capacity Zone (totalInflow > max): Redirect all excess
|
|
*/
|
|
export type FlowZone = 'deficit' | 'building' | 'capacity'
|
|
|
|
/**
|
|
* Flow between two nodes
|
|
*/
|
|
export interface FlowEdge {
|
|
source: string
|
|
target: string
|
|
flowRate: number // $/month
|
|
percentage: number // Allocation percentage
|
|
}
|
|
|
|
/**
|
|
* Network Overflow Node
|
|
*
|
|
* Pure sink that absorbs unallocatable overflow
|
|
* Created when total external inflow > total network capacity
|
|
*/
|
|
export interface OverflowNode {
|
|
id: 'overflow'
|
|
totalInflow: number // $/month
|
|
}
|
|
|
|
/**
|
|
* Complete network state
|
|
*/
|
|
export interface FlowNetwork {
|
|
nodes: Map<string, FlowNode>
|
|
edges: FlowEdge[]
|
|
overflowNode: OverflowNode | null
|
|
|
|
// Network-level metrics
|
|
totalExternalInflow: number // Sum of all external inflows
|
|
totalNetworkCapacity: number // Sum of all max thresholds
|
|
totalNetworkNeeds: number // Sum of all min thresholds
|
|
|
|
// Convergence info
|
|
converged: boolean
|
|
iterations: number
|
|
}
|
|
|
|
/**
|
|
* Simulation state (per-frame)
|
|
*/
|
|
export interface SimulationState {
|
|
timestamp: number // Simulation time in seconds
|
|
network: FlowNetwork
|
|
|
|
// Per-node state
|
|
nodeStates: Map<string, {
|
|
zone: FlowZone
|
|
inflows: Map<string, number> // From specific sources
|
|
outflows: Map<string, number> // To specific targets
|
|
balance: number
|
|
}>
|
|
}
|
|
|
|
/**
|
|
* Scenario preset
|
|
*/
|
|
export interface ScenarioV2 {
|
|
id: string
|
|
name: string
|
|
description: string
|
|
nodes: FlowNode[]
|
|
layout: Map<string, { x: number; y: number }>
|
|
suggestedTotalInflow: number // $/month
|
|
}
|
|
|
|
/**
|
|
* Validation result
|
|
*/
|
|
export interface ValidationResult {
|
|
valid: boolean
|
|
errors: string[]
|
|
warnings: string[]
|
|
}
|