@agent-e/core 1.4.4 → 1.5.1

package/dist/index.d.mts

@@ -1,4 +1,79 @@
-type EconomicEventType = 'trade' | 'mint' | 'burn' | 'transfer' | 'produce' | 'consume' | 'role_change' | 'spawn' | 'churn';
+/** High-level parameter categories (what it IS, not what it's called) */
+type ParameterType = 'cost' | 'fee' | 'reward' | 'yield' | 'rate' | 'cap' | 'penalty' | 'multiplier' | string;
+/** How a parameter change affects net currency flow */
+type FlowImpact = 'sink' | 'faucet' | 'neutral' | 'mixed' | 'friction' | 'redistribution';
+/** Scope narrows which concrete parameter a type resolves to */
+interface ParameterScope {
+    system?: string;
+    currency?: string;
+    tags?: string[];
+}
+/** A registered parameter in the economy */
+interface RegisteredParameter {
+    /** Concrete key used by the adapter (e.g. 'craftingCost', 'stakingYield') */
+    key: string;
+    /** What type of parameter this is */
+    type: ParameterType;
+    /** How changing this affects net flow */
+    flowImpact: FlowImpact;
+    /** Scope constraints — narrows resolution */
+    scope?: Partial<ParameterScope>;
+    /** Current value (updated after each apply) */
+    currentValue?: number;
+    /** Human-readable description */
+    description?: string;
+    /** Priority tiebreaker — higher wins when specificity scores are equal */
+    priority?: number;
+    /** Human-readable label for UIs and logs */
+    label?: string;
+}
+/** Result of registry.validate() */
+interface RegistryValidationResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+}
+declare class ParameterRegistry {
+    private parameters;
+    /** Register a parameter. Overwrites if key already exists. */
+    register(param: RegisteredParameter): void;
+    /** Register multiple parameters at once. */
+    registerAll(params: RegisteredParameter[]): void;
+    /**
+     * Resolve a parameterType + scope to a concrete RegisteredParameter.
+     * Returns the best match, or undefined if no match.
+     *
+     * Matching rules:
+     * 1. Filter candidates by type
+     * 2. Score each by scope specificity (system +10, currency +5, tags +3 each)
+     * 3. Mismatched scope fields disqualify (score = -Infinity)
+     * 4. Ties broken by `priority` (higher wins), then registration order
+     * 5. All disqualified → undefined
+     */
+    resolve(type: ParameterType, scope?: Partial<ParameterScope>): RegisteredParameter | undefined;
+    /** Find all parameters of a given type. */
+    findByType(type: ParameterType): RegisteredParameter[];
+    /** Find all parameters belonging to a given system. */
+    findBySystem(system: string): RegisteredParameter[];
+    /** Get a parameter by its concrete key. */
+    get(key: string): RegisteredParameter | undefined;
+    /** Get the flow impact of a parameter by its concrete key. */
+    getFlowImpact(key: string): FlowImpact | undefined;
+    /** Update the current value of a registered parameter. */
+    updateValue(key: string, value: number): void;
+    /** Get all registered parameters. */
+    getAll(): RegisteredParameter[];
+    /** Number of registered parameters. */
+    get size(): number;
+    /**
+     * Validate the registry for common misconfigurations.
+     * Returns warnings (non-fatal) and errors (likely broken).
+     */
+    validate(): RegistryValidationResult;
+    private scopeSpecificity;
+}
+
+type EconomicEventType = 'trade' | 'mint' | 'burn' | 'transfer' | 'produce' | 'consume' | 'role_change' | 'enter' | 'churn';
 interface EconomicEvent {
     type: EconomicEventType;
     timestamp: number;
@@ -10,6 +85,8 @@ interface EconomicEvent {
     price?: number;
     from?: string;
     to?: string;
+    system?: string;
+    sourceOrSink?: string;
     metadata?: Record<string, unknown>;
 }
 type PinchPointStatus = 'optimal' | 'oversupplied' | 'scarce';
@@ -82,10 +159,20 @@ interface EconomyMetrics {
     giftTradeRatio: number;
     disposalTradeRatioByCurrency: Record<string, number>;
     disposalTradeRatio: number;
+    systems: string[];
+    sources: string[];
+    sinks: string[];
+    flowBySystem: Record<string, number>;
+    activityBySystem: Record<string, number>;
+    participantsBySystem: Record<string, number>;
+    flowBySource: Record<string, number>;
+    flowBySink: Record<string, number>;
+    sourceShare: Record<string, number>;
+    sinkShare: Record<string, number>;
     custom: Record<string, number>;
 }
 declare function emptyMetrics(tick?: number): EconomyMetrics;
-type PrincipleCategory = 'supply_chain' | 'incentive' | 'population' | 'currency' | 'bootstrap' | 'feedback' | 'regulator' | 'market_dynamics' | 'measurement' | 'wealth_distribution' | 'resource' | 'system_design' | 'player_experience' | 'statistical' | 'system_dynamics' | 'open_economy' | 'liveops';
+type PrincipleCategory = 'supply_chain' | 'incentive' | 'population' | 'currency' | 'bootstrap' | 'feedback' | 'regulator' | 'market_dynamics' | 'measurement' | 'wealth_distribution' | 'resource' | 'system_design' | 'participant_experience' | 'statistical' | 'system_dynamics' | 'open_economy' | 'operations';
 interface PrincipleViolation {
     violated: true;
     severity: number;
@@ -106,18 +193,19 @@ interface Principle {
     check: (metrics: EconomyMetrics, thresholds: Thresholds) => PrincipleResult;
 }
 interface SuggestedAction {
-    parameter: string;
+    parameterType: ParameterType;
     direction: 'increase' | 'decrease' | 'set';
     magnitude?: number;
     absoluteValue?: number;
-    currency?: string;
+    scope?: Partial<ParameterScope>;
+    resolvedParameter?: string;
     reasoning: string;
 }
 interface ActionPlan {
     id: string;
     diagnosis: Diagnosis;
     parameter: string;
-    currency?: string;
+    scope?: ParameterScope;
     currentValue: number;
     targetValue: number;
     maxChangePercent: number;
@@ -178,13 +266,16 @@ interface EconomyState {
     marketPrices: Record<string, Record<string, number>>;
     recentTransactions: EconomicEvent[];
     poolSizes?: Record<string, Record<string, number>>;
+    systems?: string[];
+    sources?: string[];
+    sinks?: string[];
     customData?: Record<string, unknown>;
 }
 interface EconomyAdapter {
     /** Return current full state snapshot */
     getState(): EconomyState | Promise<EconomyState>;
     /** Apply a parameter change to the host system */
-    setParam(key: string, value: number, currency?: string): void | Promise<void>;
+    setParam(key: string, value: number, scope?: ParameterScope): void | Promise<void>;
     /** Optional: adapter pushes events as they happen */
     onEvent?: (handler: (event: EconomicEvent) => void) => void;
 }
@@ -247,6 +338,9 @@ interface AgentEConfig {
     mode?: AgentEMode;
     dominantRoles?: string[];
     idealDistribution?: Record<string, number>;
+    parameters?: RegisteredParameter[];
+    /** Run registry.validate() on startup and log warnings/errors (default: true) */
+    validateRegistry?: boolean;
     tickConfig?: Partial<TickConfig>;
     gracePeriod?: number;
     checkInterval?: number;
@@ -257,7 +351,7 @@ interface AgentEConfig {
     onAlert?: (diagnosis: Diagnosis) => void;
     onRollback?: (plan: ActionPlan, reason: string) => void;
 }
-type PersonaType = 'Active' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'Whale' | 'Influencer';
+type PersonaType = 'Active' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'HighValue' | 'Influencer' | string;
 interface PersonaProfile {
     type: PersonaType;
     share: number;
@@ -347,6 +441,7 @@ declare class AgentE {
     private simulator;
     private planner;
     private executor;
+    private registry;
     readonly log: DecisionLog;
     readonly store: MetricStore;
     private personaTracker;
@@ -375,6 +470,8 @@ declare class AgentE {
     setMode(mode: AgentEMode): void;
     getMode(): AgentEMode;
     removePrinciple(id: string): void;
+    registerParameter(param: RegisteredParameter): void;
+    getRegistry(): ParameterRegistry;
     registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
     getDecisions(filter?: Parameters<DecisionLog['query']>[0]): DecisionEntry[];
     getPrinciples(): Principle[];
@@ -405,6 +502,8 @@ declare class Observer {
 
 declare class Simulator {
     private diagnoser;
+    private registry;
+    constructor(registry?: ParameterRegistry);
     private beforeViolationsCache;
     /**
      * Simulate the effect of applying `action` to the current economy forward `forwardTicks`.
@@ -422,6 +521,8 @@ declare class Simulator {
     private runForward;
     private actionMultiplier;
     private flowEffect;
+    /** Infer flow impact from parameter type when registry is unavailable */
+    private inferFlowImpact;
     private checkImprovement;
     private averageMetrics;
 }
@@ -434,6 +535,7 @@ declare class Planner {
     private lockedParams;
     private constraints;
     private cooldowns;
+    private typeCooldowns;
     private activePlanCount;
     lock(param: string): void;
     unlock(param: string): void;
@@ -445,13 +547,17 @@ declare class Planner {
      * - parameter is still in cooldown
      * - simulation result failed
      * - complexity budget exceeded
+     * - no matching parameter in registry
      */
-    plan(diagnosis: Diagnosis, metrics: EconomyMetrics, simulationResult: SimulationResult, currentParams: Record<string, number>, thresholds: Thresholds): ActionPlan | null;
+    plan(diagnosis: Diagnosis, metrics: EconomyMetrics, simulationResult: SimulationResult, currentParams: Record<string, number>, thresholds: Thresholds, registry?: ParameterRegistry): ActionPlan | null;
     recordApplied(plan: ActionPlan, tick: number): void;
     recordRolledBack(_plan: ActionPlan): void;
+    recordSettled(_plan: ActionPlan): void;
     isOnCooldown(param: string, currentTick: number, cooldownTicks: number): boolean;
     /** Reset all cooldowns (useful for testing) */
     resetCooldowns(): void;
+    private typeCooldownKey;
+    private isTypeCooldown;
 }
 
 declare class Executor {
@@ -459,10 +565,12 @@ declare class Executor {
     apply(plan: ActionPlan, adapter: EconomyAdapter, currentParams: Record<string, number>): Promise<void>;
     /**
      * Check all active plans for rollback conditions.
-     * Called every tick after metrics are computed.
-     * Returns list of plans that were rolled back.
+     * Returns { rolledBack, settled } — plans that were undone and plans that passed their window.
      */
-    checkRollbacks(metrics: EconomyMetrics, adapter: EconomyAdapter): Promise<ActionPlan[]>;
+    checkRollbacks(metrics: EconomyMetrics, adapter: EconomyAdapter): Promise<{
+        rolledBack: ActionPlan[];
+        settled: ActionPlan[];
+    }>;
     private getMetricValue;
     getActivePlans(): ActionPlan[];
 }
@@ -476,6 +584,20 @@ declare class PersonaTracker {
     private classify;
 }
 
+/**
+ * Find the system with the worst metric value.
+ * Works with flat Record<string, number> maps like flowBySystem.
+ *
+ * @param metrics - Current economy metrics snapshot
+ * @param check - Function that returns a numeric "badness" score per system (higher = worse)
+ * @param tolerancePercent - Only flag if the worst system exceeds the average by this % (default 0)
+ * @returns The system name and its score, or undefined if no systems or none exceeds tolerance
+ */
+declare function findWorstSystem(metrics: EconomyMetrics, check: (systemName: string, metrics: EconomyMetrics) => number, tolerancePercent?: number): {
+    system: string;
+    score: number;
+} | undefined;
+
 interface ValidationError {
     path: string;
     expected: string;
@@ -513,7 +635,7 @@ declare const P8_RegulatorCannotFightDesign: Principle;
 declare const INCENTIVE_PRINCIPLES: Principle[];
 
 declare const P9_RoleSwitchingNeedsFriction: Principle;
-declare const P10_SpawnWeightingUsesInversePopulation: Principle;
+declare const P10_EntryWeightingUsesInversePopulation: Principle;
 declare const P11_TwoTierPressure: Principle;
 declare const P46_PersonaDiversity: Principle;
 declare const POPULATION_PRINCIPLES: Principle[];
@@ -546,8 +668,8 @@ declare const P28_StructuralDominanceIsNotPathological: Principle;
 declare const P38_CommunicationPreventsRevolt: Principle;
 declare const REGULATOR_PRINCIPLES: Principle[];
 
-declare const P29_PinchPoint: Principle;
-declare const P30_MovingPinchPoint: Principle;
+declare const P29_BottleneckDetection: Principle;
+declare const P30_DynamicBottleneckRotation: Principle;
 declare const P57_CombinatorialPriceSpace: Principle;
 declare const MARKET_DYNAMICS_PRINCIPLES: Principle[];
 
@@ -575,21 +697,21 @@ declare const P36_MechanicFrictionDetector: Principle;
 declare const P37_LatecommerProblem: Principle;
 declare const P45_TimeBudget: Principle;
 declare const P50_PayPowerRatio: Principle;
-declare const PLAYER_EXPERIENCE_PRINCIPLES: Principle[];
+declare const PARTICIPANT_EXPERIENCE_PRINCIPLES: Principle[];
 
 declare const P34_ExtractionRatio: Principle;
 declare const P47_SmokeTest: Principle;
 declare const P48_CurrencyInsulation: Principle;
 declare const OPEN_ECONOMY_PRINCIPLES: Principle[];
 
-declare const P51_SharkTooth: Principle;
+declare const P51_CyclicalEngagement: Principle;
 declare const P52_EndowmentEffect: Principle;
 declare const P53_EventCompletionRate: Principle;
-declare const P54_LiveOpsCadence: Principle;
-declare const P56_ContentDropShock: Principle;
-declare const LIVEOPS_PRINCIPLES: Principle[];
+declare const P54_OperationalCadence: Principle;
+declare const P56_SupplyShockAbsorption: Principle;
+declare const OPERATIONS_PRINCIPLES: Principle[];
 
-/** All 60 built-in principles in priority order (supply chain → liveops) */
+/** All 60 built-in principles in priority order (supply chain → operations) */
 declare const ALL_PRINCIPLES: Principle[];
 
-export { ALL_PRINCIPLES, type ActionPlan, AgentE, type AgentEConfig, type AgentEMode, BOOTSTRAP_PRINCIPLES, CURRENCY_FLOW_PRINCIPLES, DEFAULT_THRESHOLDS, type DecisionEntry, DecisionLog, type DecisionResult, Diagnoser, type Diagnosis, type EconomicEvent, type EconomicEventType, type EconomyAdapter, type EconomyMetrics, type EconomyState, Executor, FEEDBACK_LOOP_PRINCIPLES, INCENTIVE_PRINCIPLES, LIVEOPS_PRINCIPLES, MARKET_DYNAMICS_PRINCIPLES, MEASUREMENT_PRINCIPLES, type MetricQuery, type MetricQueryResult, type MetricResolution, MetricStore, OPEN_ECONOMY_PRINCIPLES, Observer, P10_SpawnWeightingUsesInversePopulation, P11_TwoTierPressure, P12_OnePrimaryFaucet, P13_PotsAreZeroSumAndSelfRegulate, P14_TrackActualInjection, P15_PoolsNeedCapAndDecay, P16_WithdrawalPenaltyScales, P17_GracePeriodBeforeIntervention, P18_FirstProducerNeedsStartingInventory, P19_StartingSupplyExceedsDemand, P1_ProductionMatchesConsumption, P20_DecayPreventsAccumulation, P21_PriceFromGlobalSupply, P22_MarketAwarenessPreventsSurplus, P23_ProfitabilityFactorsFeasibility, P24_BlockedAgentsDecayFaster, P25_CorrectLeversForCorrectProblems, P26_ContinuousPressureBeatsThresholdCuts, P27_AdjustmentsNeedCooldowns, P28_StructuralDominanceIsNotPathological, P29_PinchPoint, P2_ClosedLoopsNeedDirectHandoff, P30_MovingPinchPoint, P31_AnchorValueTracking, P32_VelocityAboveSupply, P33_FairNotEqual, P34_ExtractionRatio, P35_DestructionCreatesValue, P36_MechanicFrictionDetector, P37_LatecommerProblem, P38_CommunicationPreventsRevolt, P39_TheLagPrinciple, P3_BootstrapCapitalCoversFirstTransaction, P40_ReplacementRate, P41_MultiResolutionMonitoring, P42_TheMedianPrinciple, P43_SimulationMinimum, P44_ComplexityBudget, P45_TimeBudget, P46_PersonaDiversity, P47_SmokeTest, P48_CurrencyInsulation, P49_IdleAssetTax, P4_MaterialsFlowFasterThanCooldown, P50_PayPowerRatio, P51_SharkTooth, P52_EndowmentEffect, P53_EventCompletionRate, P54_LiveOpsCadence, P55_ArbitrageThermometer, P56_ContentDropShock, P57_CombinatorialPriceSpace, P58_NoNaturalNumeraire, P59_GiftEconomyNoise, P5_ProfitabilityIsCompetitive, P60_SurplusDisposalAsymmetry, P6_CrowdingMultiplierOnAllRoles, P7_NonSpecialistsSubsidiseSpecialists, P8_RegulatorCannotFightDesign, P9_RoleSwitchingNeedsFriction, PERSONA_HEALTHY_RANGES, PLAYER_EXPERIENCE_PRINCIPLES, POPULATION_PRINCIPLES, type PersonaProfile, PersonaTracker, type PersonaType, type PinchPointStatus, Planner, type Principle, type PrincipleCategory, type PrincipleOk, type PrincipleResult, type PrincipleViolation, REGULATOR_PRINCIPLES, RESOURCE_MGMT_PRINCIPLES, type RollbackCondition, STATISTICAL_PRINCIPLES, SUPPLY_CHAIN_PRINCIPLES, SYSTEM_DYNAMICS_PRINCIPLES, type SimulationOutcome, type SimulationResult, Simulator, type SuggestedAction, type Thresholds, type TickConfig, type ValidationError, type ValidationResult, type ValidationWarning, emptyMetrics, validateEconomyState };
+export { ALL_PRINCIPLES, type ActionPlan, AgentE, type AgentEConfig, type AgentEMode, BOOTSTRAP_PRINCIPLES, CURRENCY_FLOW_PRINCIPLES, DEFAULT_THRESHOLDS, type DecisionEntry, DecisionLog, type DecisionResult, Diagnoser, type Diagnosis, type EconomicEvent, type EconomicEventType, type EconomyAdapter, type EconomyMetrics, type EconomyState, Executor, FEEDBACK_LOOP_PRINCIPLES, type FlowImpact, INCENTIVE_PRINCIPLES, MARKET_DYNAMICS_PRINCIPLES, MEASUREMENT_PRINCIPLES, type MetricQuery, type MetricQueryResult, type MetricResolution, MetricStore, OPEN_ECONOMY_PRINCIPLES, OPERATIONS_PRINCIPLES, Observer, P10_EntryWeightingUsesInversePopulation, P11_TwoTierPressure, P12_OnePrimaryFaucet, P13_PotsAreZeroSumAndSelfRegulate, P14_TrackActualInjection, P15_PoolsNeedCapAndDecay, P16_WithdrawalPenaltyScales, P17_GracePeriodBeforeIntervention, P18_FirstProducerNeedsStartingInventory, P19_StartingSupplyExceedsDemand, P1_ProductionMatchesConsumption, P20_DecayPreventsAccumulation, P21_PriceFromGlobalSupply, P22_MarketAwarenessPreventsSurplus, P23_ProfitabilityFactorsFeasibility, P24_BlockedAgentsDecayFaster, P25_CorrectLeversForCorrectProblems, P26_ContinuousPressureBeatsThresholdCuts, P27_AdjustmentsNeedCooldowns, P28_StructuralDominanceIsNotPathological, P29_BottleneckDetection, P2_ClosedLoopsNeedDirectHandoff, P30_DynamicBottleneckRotation, P31_AnchorValueTracking, P32_VelocityAboveSupply, P33_FairNotEqual, P34_ExtractionRatio, P35_DestructionCreatesValue, P36_MechanicFrictionDetector, P37_LatecommerProblem, P38_CommunicationPreventsRevolt, P39_TheLagPrinciple, P3_BootstrapCapitalCoversFirstTransaction, P40_ReplacementRate, P41_MultiResolutionMonitoring, P42_TheMedianPrinciple, P43_SimulationMinimum, P44_ComplexityBudget, P45_TimeBudget, P46_PersonaDiversity, P47_SmokeTest, P48_CurrencyInsulation, P49_IdleAssetTax, P4_MaterialsFlowFasterThanCooldown, P50_PayPowerRatio, P51_CyclicalEngagement, P52_EndowmentEffect, P53_EventCompletionRate, P54_OperationalCadence, P55_ArbitrageThermometer, P56_SupplyShockAbsorption, P57_CombinatorialPriceSpace, P58_NoNaturalNumeraire, P59_GiftEconomyNoise, P5_ProfitabilityIsCompetitive, P60_SurplusDisposalAsymmetry, P6_CrowdingMultiplierOnAllRoles, P7_NonSpecialistsSubsidiseSpecialists, P8_RegulatorCannotFightDesign, P9_RoleSwitchingNeedsFriction, PARTICIPANT_EXPERIENCE_PRINCIPLES, PERSONA_HEALTHY_RANGES, POPULATION_PRINCIPLES, ParameterRegistry, type ParameterScope, type ParameterType, type PersonaProfile, PersonaTracker, type PersonaType, type PinchPointStatus, Planner, type Principle, type PrincipleCategory, type PrincipleOk, type PrincipleResult, type PrincipleViolation, REGULATOR_PRINCIPLES, RESOURCE_MGMT_PRINCIPLES, type RegisteredParameter, type RegistryValidationResult, type RollbackCondition, STATISTICAL_PRINCIPLES, SUPPLY_CHAIN_PRINCIPLES, SYSTEM_DYNAMICS_PRINCIPLES, type SimulationOutcome, type SimulationResult, Simulator, type SuggestedAction, type Thresholds, type TickConfig, type ValidationError, type ValidationResult, type ValidationWarning, emptyMetrics, findWorstSystem, validateEconomyState };

package/dist/index.d.ts

@@ -1,4 +1,79 @@
-type EconomicEventType = 'trade' | 'mint' | 'burn' | 'transfer' | 'produce' | 'consume' | 'role_change' | 'spawn' | 'churn';
+/** High-level parameter categories (what it IS, not what it's called) */
+type ParameterType = 'cost' | 'fee' | 'reward' | 'yield' | 'rate' | 'cap' | 'penalty' | 'multiplier' | string;
+/** How a parameter change affects net currency flow */
+type FlowImpact = 'sink' | 'faucet' | 'neutral' | 'mixed' | 'friction' | 'redistribution';
+/** Scope narrows which concrete parameter a type resolves to */
+interface ParameterScope {
+    system?: string;
+    currency?: string;
+    tags?: string[];
+}
+/** A registered parameter in the economy */
+interface RegisteredParameter {
+    /** Concrete key used by the adapter (e.g. 'craftingCost', 'stakingYield') */
+    key: string;
+    /** What type of parameter this is */
+    type: ParameterType;
+    /** How changing this affects net flow */
+    flowImpact: FlowImpact;
+    /** Scope constraints — narrows resolution */
+    scope?: Partial<ParameterScope>;
+    /** Current value (updated after each apply) */
+    currentValue?: number;
+    /** Human-readable description */
+    description?: string;
+    /** Priority tiebreaker — higher wins when specificity scores are equal */
+    priority?: number;
+    /** Human-readable label for UIs and logs */
+    label?: string;
+}
+/** Result of registry.validate() */
+interface RegistryValidationResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+}
+declare class ParameterRegistry {
+    private parameters;
+    /** Register a parameter. Overwrites if key already exists. */
+    register(param: RegisteredParameter): void;
+    /** Register multiple parameters at once. */
+    registerAll(params: RegisteredParameter[]): void;
+    /**
+     * Resolve a parameterType + scope to a concrete RegisteredParameter.
+     * Returns the best match, or undefined if no match.
+     *
+     * Matching rules:
+     * 1. Filter candidates by type
+     * 2. Score each by scope specificity (system +10, currency +5, tags +3 each)
+     * 3. Mismatched scope fields disqualify (score = -Infinity)
+     * 4. Ties broken by `priority` (higher wins), then registration order
+     * 5. All disqualified → undefined
+     */
+    resolve(type: ParameterType, scope?: Partial<ParameterScope>): RegisteredParameter | undefined;
+    /** Find all parameters of a given type. */
+    findByType(type: ParameterType): RegisteredParameter[];
+    /** Find all parameters belonging to a given system. */
+    findBySystem(system: string): RegisteredParameter[];
+    /** Get a parameter by its concrete key. */
+    get(key: string): RegisteredParameter | undefined;
+    /** Get the flow impact of a parameter by its concrete key. */
+    getFlowImpact(key: string): FlowImpact | undefined;
+    /** Update the current value of a registered parameter. */
+    updateValue(key: string, value: number): void;
+    /** Get all registered parameters. */
+    getAll(): RegisteredParameter[];
+    /** Number of registered parameters. */
+    get size(): number;
+    /**
+     * Validate the registry for common misconfigurations.
+     * Returns warnings (non-fatal) and errors (likely broken).
+     */
+    validate(): RegistryValidationResult;
+    private scopeSpecificity;
+}
+
+type EconomicEventType = 'trade' | 'mint' | 'burn' | 'transfer' | 'produce' | 'consume' | 'role_change' | 'enter' | 'churn';
 interface EconomicEvent {
     type: EconomicEventType;
     timestamp: number;
@@ -10,6 +85,8 @@ interface EconomicEvent {
     price?: number;
     from?: string;
     to?: string;
+    system?: string;
+    sourceOrSink?: string;
     metadata?: Record<string, unknown>;
 }
 type PinchPointStatus = 'optimal' | 'oversupplied' | 'scarce';
@@ -82,10 +159,20 @@ interface EconomyMetrics {
     giftTradeRatio: number;
     disposalTradeRatioByCurrency: Record<string, number>;
     disposalTradeRatio: number;
+    systems: string[];
+    sources: string[];
+    sinks: string[];
+    flowBySystem: Record<string, number>;
+    activityBySystem: Record<string, number>;
+    participantsBySystem: Record<string, number>;
+    flowBySource: Record<string, number>;
+    flowBySink: Record<string, number>;
+    sourceShare: Record<string, number>;
+    sinkShare: Record<string, number>;
     custom: Record<string, number>;
 }
 declare function emptyMetrics(tick?: number): EconomyMetrics;
-type PrincipleCategory = 'supply_chain' | 'incentive' | 'population' | 'currency' | 'bootstrap' | 'feedback' | 'regulator' | 'market_dynamics' | 'measurement' | 'wealth_distribution' | 'resource' | 'system_design' | 'player_experience' | 'statistical' | 'system_dynamics' | 'open_economy' | 'liveops';
+type PrincipleCategory = 'supply_chain' | 'incentive' | 'population' | 'currency' | 'bootstrap' | 'feedback' | 'regulator' | 'market_dynamics' | 'measurement' | 'wealth_distribution' | 'resource' | 'system_design' | 'participant_experience' | 'statistical' | 'system_dynamics' | 'open_economy' | 'operations';
 interface PrincipleViolation {
     violated: true;
     severity: number;
@@ -106,18 +193,19 @@ interface Principle {
     check: (metrics: EconomyMetrics, thresholds: Thresholds) => PrincipleResult;
 }
 interface SuggestedAction {
-    parameter: string;
+    parameterType: ParameterType;
     direction: 'increase' | 'decrease' | 'set';
     magnitude?: number;
     absoluteValue?: number;
-    currency?: string;
+    scope?: Partial<ParameterScope>;
+    resolvedParameter?: string;
     reasoning: string;
 }
 interface ActionPlan {
     id: string;
     diagnosis: Diagnosis;
     parameter: string;
-    currency?: string;
+    scope?: ParameterScope;
     currentValue: number;
     targetValue: number;
     maxChangePercent: number;
@@ -178,13 +266,16 @@ interface EconomyState {
     marketPrices: Record<string, Record<string, number>>;
     recentTransactions: EconomicEvent[];
     poolSizes?: Record<string, Record<string, number>>;
+    systems?: string[];
+    sources?: string[];
+    sinks?: string[];
     customData?: Record<string, unknown>;
 }
 interface EconomyAdapter {
     /** Return current full state snapshot */
     getState(): EconomyState | Promise<EconomyState>;
     /** Apply a parameter change to the host system */
-    setParam(key: string, value: number, currency?: string): void | Promise<void>;
+    setParam(key: string, value: number, scope?: ParameterScope): void | Promise<void>;
     /** Optional: adapter pushes events as they happen */
     onEvent?: (handler: (event: EconomicEvent) => void) => void;
 }
@@ -247,6 +338,9 @@ interface AgentEConfig {
     mode?: AgentEMode;
     dominantRoles?: string[];
     idealDistribution?: Record<string, number>;
+    parameters?: RegisteredParameter[];
+    /** Run registry.validate() on startup and log warnings/errors (default: true) */
+    validateRegistry?: boolean;
     tickConfig?: Partial<TickConfig>;
     gracePeriod?: number;
     checkInterval?: number;
@@ -257,7 +351,7 @@ interface AgentEConfig {
     onAlert?: (diagnosis: Diagnosis) => void;
     onRollback?: (plan: ActionPlan, reason: string) => void;
 }
-type PersonaType = 'Active' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'Whale' | 'Influencer';
+type PersonaType = 'Active' | 'Trader' | 'Collector' | 'Speculator' | 'Earner' | 'Builder' | 'Social' | 'HighValue' | 'Influencer' | string;
 interface PersonaProfile {
     type: PersonaType;
     share: number;
@@ -347,6 +441,7 @@ declare class AgentE {
     private simulator;
     private planner;
     private executor;
+    private registry;
     readonly log: DecisionLog;
     readonly store: MetricStore;
     private personaTracker;
@@ -375,6 +470,8 @@ declare class AgentE {
     setMode(mode: AgentEMode): void;
     getMode(): AgentEMode;
     removePrinciple(id: string): void;
+    registerParameter(param: RegisteredParameter): void;
+    getRegistry(): ParameterRegistry;
     registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
     getDecisions(filter?: Parameters<DecisionLog['query']>[0]): DecisionEntry[];
     getPrinciples(): Principle[];
@@ -405,6 +502,8 @@ declare class Observer {
 
 declare class Simulator {
     private diagnoser;
+    private registry;
+    constructor(registry?: ParameterRegistry);
     private beforeViolationsCache;
     /**
      * Simulate the effect of applying `action` to the current economy forward `forwardTicks`.
@@ -422,6 +521,8 @@ declare class Simulator {
     private runForward;
     private actionMultiplier;
     private flowEffect;
+    /** Infer flow impact from parameter type when registry is unavailable */
+    private inferFlowImpact;
     private checkImprovement;
     private averageMetrics;
 }
@@ -434,6 +535,7 @@ declare class Planner {
     private lockedParams;
     private constraints;
     private cooldowns;
+    private typeCooldowns;
     private activePlanCount;
     lock(param: string): void;
     unlock(param: string): void;
@@ -445,13 +547,17 @@ declare class Planner {
      * - parameter is still in cooldown
      * - simulation result failed
      * - complexity budget exceeded
+     * - no matching parameter in registry
      */
-    plan(diagnosis: Diagnosis, metrics: EconomyMetrics, simulationResult: SimulationResult, currentParams: Record<string, number>, thresholds: Thresholds): ActionPlan | null;
+    plan(diagnosis: Diagnosis, metrics: EconomyMetrics, simulationResult: SimulationResult, currentParams: Record<string, number>, thresholds: Thresholds, registry?: ParameterRegistry): ActionPlan | null;
     recordApplied(plan: ActionPlan, tick: number): void;
     recordRolledBack(_plan: ActionPlan): void;
+    recordSettled(_plan: ActionPlan): void;
     isOnCooldown(param: string, currentTick: number, cooldownTicks: number): boolean;
     /** Reset all cooldowns (useful for testing) */
     resetCooldowns(): void;
+    private typeCooldownKey;
+    private isTypeCooldown;
 }
 
 declare class Executor {
@@ -459,10 +565,12 @@ declare class Executor {
     apply(plan: ActionPlan, adapter: EconomyAdapter, currentParams: Record<string, number>): Promise<void>;
     /**
      * Check all active plans for rollback conditions.
-     * Called every tick after metrics are computed.
-     * Returns list of plans that were rolled back.
+     * Returns { rolledBack, settled } — plans that were undone and plans that passed their window.
      */
-    checkRollbacks(metrics: EconomyMetrics, adapter: EconomyAdapter): Promise<ActionPlan[]>;
+    checkRollbacks(metrics: EconomyMetrics, adapter: EconomyAdapter): Promise<{
+        rolledBack: ActionPlan[];
+        settled: ActionPlan[];
+    }>;
     private getMetricValue;
     getActivePlans(): ActionPlan[];
 }
@@ -476,6 +584,20 @@ declare class PersonaTracker {
     private classify;
 }
 
+/**
+ * Find the system with the worst metric value.
+ * Works with flat Record<string, number> maps like flowBySystem.
+ *
+ * @param metrics - Current economy metrics snapshot
+ * @param check - Function that returns a numeric "badness" score per system (higher = worse)
+ * @param tolerancePercent - Only flag if the worst system exceeds the average by this % (default 0)
+ * @returns The system name and its score, or undefined if no systems or none exceeds tolerance
+ */
+declare function findWorstSystem(metrics: EconomyMetrics, check: (systemName: string, metrics: EconomyMetrics) => number, tolerancePercent?: number): {
+    system: string;
+    score: number;
+} | undefined;
+
 interface ValidationError {
     path: string;
     expected: string;
@@ -513,7 +635,7 @@ declare const P8_RegulatorCannotFightDesign: Principle;
 declare const INCENTIVE_PRINCIPLES: Principle[];
 
 declare const P9_RoleSwitchingNeedsFriction: Principle;
-declare const P10_SpawnWeightingUsesInversePopulation: Principle;
+declare const P10_EntryWeightingUsesInversePopulation: Principle;
 declare const P11_TwoTierPressure: Principle;
 declare const P46_PersonaDiversity: Principle;
 declare const POPULATION_PRINCIPLES: Principle[];
@@ -546,8 +668,8 @@ declare const P28_StructuralDominanceIsNotPathological: Principle;
 declare const P38_CommunicationPreventsRevolt: Principle;
 declare const REGULATOR_PRINCIPLES: Principle[];
 
-declare const P29_PinchPoint: Principle;
-declare const P30_MovingPinchPoint: Principle;
+declare const P29_BottleneckDetection: Principle;
+declare const P30_DynamicBottleneckRotation: Principle;
 declare const P57_CombinatorialPriceSpace: Principle;
 declare const MARKET_DYNAMICS_PRINCIPLES: Principle[];
 
@@ -575,21 +697,21 @@ declare const P36_MechanicFrictionDetector: Principle;
 declare const P37_LatecommerProblem: Principle;
 declare const P45_TimeBudget: Principle;
 declare const P50_PayPowerRatio: Principle;
-declare const PLAYER_EXPERIENCE_PRINCIPLES: Principle[];
+declare const PARTICIPANT_EXPERIENCE_PRINCIPLES: Principle[];
 
 declare const P34_ExtractionRatio: Principle;
 declare const P47_SmokeTest: Principle;
 declare const P48_CurrencyInsulation: Principle;
 declare const OPEN_ECONOMY_PRINCIPLES: Principle[];
 
-declare const P51_SharkTooth: Principle;
+declare const P51_CyclicalEngagement: Principle;
 declare const P52_EndowmentEffect: Principle;
 declare const P53_EventCompletionRate: Principle;
-declare const P54_LiveOpsCadence: Principle;
-declare const P56_ContentDropShock: Principle;
-declare const LIVEOPS_PRINCIPLES: Principle[];
+declare const P54_OperationalCadence: Principle;
+declare const P56_SupplyShockAbsorption: Principle;
+declare const OPERATIONS_PRINCIPLES: Principle[];
 
-/** All 60 built-in principles in priority order (supply chain → liveops) */
+/** All 60 built-in principles in priority order (supply chain → operations) */
 declare const ALL_PRINCIPLES: Principle[];
 
-export { ALL_PRINCIPLES, type ActionPlan, AgentE, type AgentEConfig, type AgentEMode, BOOTSTRAP_PRINCIPLES, CURRENCY_FLOW_PRINCIPLES, DEFAULT_THRESHOLDS, type DecisionEntry, DecisionLog, type DecisionResult, Diagnoser, type Diagnosis, type EconomicEvent, type EconomicEventType, type EconomyAdapter, type EconomyMetrics, type EconomyState, Executor, FEEDBACK_LOOP_PRINCIPLES, INCENTIVE_PRINCIPLES, LIVEOPS_PRINCIPLES, MARKET_DYNAMICS_PRINCIPLES, MEASUREMENT_PRINCIPLES, type MetricQuery, type MetricQueryResult, type MetricResolution, MetricStore, OPEN_ECONOMY_PRINCIPLES, Observer, P10_SpawnWeightingUsesInversePopulation, P11_TwoTierPressure, P12_OnePrimaryFaucet, P13_PotsAreZeroSumAndSelfRegulate, P14_TrackActualInjection, P15_PoolsNeedCapAndDecay, P16_WithdrawalPenaltyScales, P17_GracePeriodBeforeIntervention, P18_FirstProducerNeedsStartingInventory, P19_StartingSupplyExceedsDemand, P1_ProductionMatchesConsumption, P20_DecayPreventsAccumulation, P21_PriceFromGlobalSupply, P22_MarketAwarenessPreventsSurplus, P23_ProfitabilityFactorsFeasibility, P24_BlockedAgentsDecayFaster, P25_CorrectLeversForCorrectProblems, P26_ContinuousPressureBeatsThresholdCuts, P27_AdjustmentsNeedCooldowns, P28_StructuralDominanceIsNotPathological, P29_PinchPoint, P2_ClosedLoopsNeedDirectHandoff, P30_MovingPinchPoint, P31_AnchorValueTracking, P32_VelocityAboveSupply, P33_FairNotEqual, P34_ExtractionRatio, P35_DestructionCreatesValue, P36_MechanicFrictionDetector, P37_LatecommerProblem, P38_CommunicationPreventsRevolt, P39_TheLagPrinciple, P3_BootstrapCapitalCoversFirstTransaction, P40_ReplacementRate, P41_MultiResolutionMonitoring, P42_TheMedianPrinciple, P43_SimulationMinimum, P44_ComplexityBudget, P45_TimeBudget, P46_PersonaDiversity, P47_SmokeTest, P48_CurrencyInsulation, P49_IdleAssetTax, P4_MaterialsFlowFasterThanCooldown, P50_PayPowerRatio, P51_SharkTooth, P52_EndowmentEffect, P53_EventCompletionRate, P54_LiveOpsCadence, P55_ArbitrageThermometer, P56_ContentDropShock, P57_CombinatorialPriceSpace, P58_NoNaturalNumeraire, P59_GiftEconomyNoise, P5_ProfitabilityIsCompetitive, P60_SurplusDisposalAsymmetry, P6_CrowdingMultiplierOnAllRoles, P7_NonSpecialistsSubsidiseSpecialists, P8_RegulatorCannotFightDesign, P9_RoleSwitchingNeedsFriction, PERSONA_HEALTHY_RANGES, PLAYER_EXPERIENCE_PRINCIPLES, POPULATION_PRINCIPLES, type PersonaProfile, PersonaTracker, type PersonaType, type PinchPointStatus, Planner, type Principle, type PrincipleCategory, type PrincipleOk, type PrincipleResult, type PrincipleViolation, REGULATOR_PRINCIPLES, RESOURCE_MGMT_PRINCIPLES, type RollbackCondition, STATISTICAL_PRINCIPLES, SUPPLY_CHAIN_PRINCIPLES, SYSTEM_DYNAMICS_PRINCIPLES, type SimulationOutcome, type SimulationResult, Simulator, type SuggestedAction, type Thresholds, type TickConfig, type ValidationError, type ValidationResult, type ValidationWarning, emptyMetrics, validateEconomyState };
+export { ALL_PRINCIPLES, type ActionPlan, AgentE, type AgentEConfig, type AgentEMode, BOOTSTRAP_PRINCIPLES, CURRENCY_FLOW_PRINCIPLES, DEFAULT_THRESHOLDS, type DecisionEntry, DecisionLog, type DecisionResult, Diagnoser, type Diagnosis, type EconomicEvent, type EconomicEventType, type EconomyAdapter, type EconomyMetrics, type EconomyState, Executor, FEEDBACK_LOOP_PRINCIPLES, type FlowImpact, INCENTIVE_PRINCIPLES, MARKET_DYNAMICS_PRINCIPLES, MEASUREMENT_PRINCIPLES, type MetricQuery, type MetricQueryResult, type MetricResolution, MetricStore, OPEN_ECONOMY_PRINCIPLES, OPERATIONS_PRINCIPLES, Observer, P10_EntryWeightingUsesInversePopulation, P11_TwoTierPressure, P12_OnePrimaryFaucet, P13_PotsAreZeroSumAndSelfRegulate, P14_TrackActualInjection, P15_PoolsNeedCapAndDecay, P16_WithdrawalPenaltyScales, P17_GracePeriodBeforeIntervention, P18_FirstProducerNeedsStartingInventory, P19_StartingSupplyExceedsDemand, P1_ProductionMatchesConsumption, P20_DecayPreventsAccumulation, P21_PriceFromGlobalSupply, P22_MarketAwarenessPreventsSurplus, P23_ProfitabilityFactorsFeasibility, P24_BlockedAgentsDecayFaster, P25_CorrectLeversForCorrectProblems, P26_ContinuousPressureBeatsThresholdCuts, P27_AdjustmentsNeedCooldowns, P28_StructuralDominanceIsNotPathological, P29_BottleneckDetection, P2_ClosedLoopsNeedDirectHandoff, P30_DynamicBottleneckRotation, P31_AnchorValueTracking, P32_VelocityAboveSupply, P33_FairNotEqual, P34_ExtractionRatio, P35_DestructionCreatesValue, P36_MechanicFrictionDetector, P37_LatecommerProblem, P38_CommunicationPreventsRevolt, P39_TheLagPrinciple, P3_BootstrapCapitalCoversFirstTransaction, P40_ReplacementRate, P41_MultiResolutionMonitoring, P42_TheMedianPrinciple, P43_SimulationMinimum, P44_ComplexityBudget, P45_TimeBudget, P46_PersonaDiversity, P47_SmokeTest, P48_CurrencyInsulation, P49_IdleAssetTax, P4_MaterialsFlowFasterThanCooldown, P50_PayPowerRatio, P51_CyclicalEngagement, P52_EndowmentEffect, P53_EventCompletionRate, P54_OperationalCadence, P55_ArbitrageThermometer, P56_SupplyShockAbsorption, P57_CombinatorialPriceSpace, P58_NoNaturalNumeraire, P59_GiftEconomyNoise, P5_ProfitabilityIsCompetitive, P60_SurplusDisposalAsymmetry, P6_CrowdingMultiplierOnAllRoles, P7_NonSpecialistsSubsidiseSpecialists, P8_RegulatorCannotFightDesign, P9_RoleSwitchingNeedsFriction, PARTICIPANT_EXPERIENCE_PRINCIPLES, PERSONA_HEALTHY_RANGES, POPULATION_PRINCIPLES, ParameterRegistry, type ParameterScope, type ParameterType, type PersonaProfile, PersonaTracker, type PersonaType, type PinchPointStatus, Planner, type Principle, type PrincipleCategory, type PrincipleOk, type PrincipleResult, type PrincipleViolation, REGULATOR_PRINCIPLES, RESOURCE_MGMT_PRINCIPLES, type RegisteredParameter, type RegistryValidationResult, type RollbackCondition, STATISTICAL_PRINCIPLES, SUPPLY_CHAIN_PRINCIPLES, SYSTEM_DYNAMICS_PRINCIPLES, type SimulationOutcome, type SimulationResult, Simulator, type SuggestedAction, type Thresholds, type TickConfig, type ValidationError, type ValidationResult, type ValidationWarning, emptyMetrics, findWorstSystem, validateEconomyState };