@agent-e/core 1.5.0 → 1.5.2

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** 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';
+type FlowImpact = 'sink' | 'faucet' | 'neutral' | 'mixed' | 'friction' | 'redistribution';
 /** Scope narrows which concrete parameter a type resolves to */
 interface ParameterScope {
     system?: string;
@@ -22,6 +22,16 @@ interface RegisteredParameter {
     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;
@@ -33,11 +43,12 @@ declare class ParameterRegistry {
      * Resolve a parameterType + scope to a concrete RegisteredParameter.
      * Returns the best match, or undefined if no match.
      *
-     * Matching rules (in priority order):
-     * 1. Exact type match + all scope fields match
-     * 2. Exact type match + partial scope match (tags overlap)
-     * 3. Exact type match + no scope constraints
-     * 4. undefined (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. */
@@ -54,7 +65,12 @@ declare class ParameterRegistry {
     getAll(): RegisteredParameter[];
     /** Number of registered parameters. */
     get size(): number;
-    private scopeMatchScore;
+    /**
+     * 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';
@@ -143,6 +159,9 @@ 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>;
@@ -284,7 +303,7 @@ interface Thresholds {
     maxAdjustmentPercent: number;
     cooldownTicks: number;
     poolWinRate: number;
-    poolHouseCut: number;
+    poolOperatorShare: number;
     roleSwitchFrictionMax: number;
     poolCapPercent: number;
     poolDecayRate: number;
@@ -313,6 +332,16 @@ interface TickConfig {
     /** Coarse-resolution metric window in ticks. Default: 100 */
     coarseWindow?: number;
 }
+interface SimulationConfig {
+    sinkMultiplier?: number;
+    faucetMultiplier?: number;
+    frictionMultiplier?: number;
+    frictionVelocityScale?: number;
+    redistributionMultiplier?: number;
+    neutralMultiplier?: number;
+    minIterations?: number;
+    maxProjectionTicks?: number;
+}
 type AgentEMode = 'autonomous' | 'advisor';
 interface AgentEConfig {
     adapter: EconomyAdapter;
@@ -320,11 +349,15 @@ interface AgentEConfig {
     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;
     maxAdjustmentPercent?: number;
     cooldownTicks?: number;
+    simulation?: SimulationConfig;
+    settlementWindowTicks?: number;
     thresholds?: Partial<Thresholds>;
     onDecision?: (entry: DecisionEntry) => void;
     onAlert?: (diagnosis: Diagnosis) => void;
@@ -482,8 +515,10 @@ declare class Observer {
 declare class Simulator {
     private diagnoser;
     private registry;
-    constructor(registry?: ParameterRegistry);
-    private beforeViolationsCache;
+    private simConfig;
+    constructor(registry?: ParameterRegistry, simConfig?: SimulationConfig);
+    private cachedViolationsTick;
+    private cachedViolations;
     /**
      * Simulate the effect of applying `action` to the current economy forward `forwardTicks`.
      * Runs `iterations` Monte Carlo trials and returns the outcome distribution.
@@ -514,6 +549,7 @@ declare class Planner {
     private lockedParams;
     private constraints;
     private cooldowns;
+    private typeCooldowns;
     private activePlanCount;
     lock(param: string): void;
     unlock(param: string): void;
@@ -534,10 +570,19 @@ declare class Planner {
     isOnCooldown(param: string, currentTick: number, cooldownTicks: number): boolean;
     /** Reset all cooldowns (useful for testing) */
     resetCooldowns(): void;
+    /** V1.5.2: Reset active plan count (e.g., on system restart) */
+    resetActivePlans(): void;
+    /** V1.5.2: Current active plan count (for diagnostics) */
+    getActivePlanCount(): number;
+    private typeCooldownKey;
+    private isTypeCooldown;
 }
 
+type ExecutionResult = 'applied' | 'rolled_back' | 'rollback_skipped';
 declare class Executor {
     private activePlans;
+    private maxActiveTicks;
+    constructor(settlementWindowTicks?: number);
     apply(plan: ActionPlan, adapter: EconomyAdapter, currentParams: Record<string, number>): Promise<void>;
     /**
      * Check all active plans for rollback conditions.
@@ -553,6 +598,7 @@ declare class Executor {
 
 declare class PersonaTracker {
     private agentHistory;
+    private lastSeen;
     /** Ingest a state snapshot and update agent signal history */
     update(state: EconomyState): void;
     /** Classify all agents and return persona distribution */
@@ -560,6 +606,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;
@@ -590,14 +650,14 @@ declare const P4_MaterialsFlowFasterThanCooldown: Principle;
 declare const P60_SurplusDisposalAsymmetry: Principle;
 declare const SUPPLY_CHAIN_PRINCIPLES: Principle[];
 
-declare const P5_ProfitabilityIsCompetitive: Principle;
+declare const P5_ProfitabilityIsRelative: Principle;
 declare const P6_CrowdingMultiplierOnAllRoles: Principle;
 declare const P7_NonSpecialistsSubsidiseSpecialists: Principle;
 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[];
@@ -630,8 +690,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[];
 
@@ -666,14 +726,14 @@ 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 P54_OperationalCadence: Principle;
+declare const P56_SupplyShockAbsorption: Principle;
 declare const OPERATIONS_PRINCIPLES: Principle[];
 
 /** 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, type FlowImpact, INCENTIVE_PRINCIPLES, MARKET_DYNAMICS_PRINCIPLES, MEASUREMENT_PRINCIPLES, type MetricQuery, type MetricQueryResult, type MetricResolution, MetricStore, OPEN_ECONOMY_PRINCIPLES, OPERATIONS_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, 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 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, type ExecutionResult, 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_ProfitabilityIsRelative, 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 SimulationConfig, type SimulationOutcome, type SimulationResult, Simulator, type SuggestedAction, type Thresholds, type TickConfig, type ValidationError, type ValidationResult, type ValidationWarning, emptyMetrics, findWorstSystem, validateEconomyState };