@agent-e/core 1.4.4 → 1.5.0

package/dist/index.d.mts

@@ -1,4 +1,63 @@
-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';
+/** 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;
+}
+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 (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)
+     */
+    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;
+    private scopeMatchScore;
+}
+
+type EconomicEventType = 'trade' | 'mint' | 'burn' | 'transfer' | 'produce' | 'consume' | 'role_change' | 'enter' | 'churn';
 interface EconomicEvent {
     type: EconomicEventType;
     timestamp: number;
@@ -10,6 +69,8 @@ interface EconomicEvent {
     price?: number;
     from?: string;
     to?: string;
+    system?: string;
+    sourceOrSink?: string;
     metadata?: Record<string, unknown>;
 }
 type PinchPointStatus = 'optimal' | 'oversupplied' | 'scarce';
@@ -82,10 +143,17 @@ interface EconomyMetrics {
     giftTradeRatio: number;
     disposalTradeRatioByCurrency: Record<string, number>;
     disposalTradeRatio: number;
+    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 +174,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 +247,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 +319,7 @@ interface AgentEConfig {
     mode?: AgentEMode;
     dominantRoles?: string[];
     idealDistribution?: Record<string, number>;
+    parameters?: RegisteredParameter[];
     tickConfig?: Partial<TickConfig>;
     gracePeriod?: number;
     checkInterval?: number;
@@ -257,7 +330,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 +420,7 @@ declare class AgentE {
     private simulator;
     private planner;
     private executor;
+    private registry;
     readonly log: DecisionLog;
     readonly store: MetricStore;
     private personaTracker;
@@ -375,6 +449,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 +481,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 +500,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;
 }
@@ -445,10 +525,12 @@ 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;
@@ -459,10 +541,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[];
 }
@@ -575,7 +659,7 @@ 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;
@@ -587,9 +671,9 @@ 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 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_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 };

package/dist/index.d.ts

@@ -1,4 +1,63 @@
-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';
+/** 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;
+}
+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 (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)
+     */
+    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;
+    private scopeMatchScore;
+}
+
+type EconomicEventType = 'trade' | 'mint' | 'burn' | 'transfer' | 'produce' | 'consume' | 'role_change' | 'enter' | 'churn';
 interface EconomicEvent {
     type: EconomicEventType;
     timestamp: number;
@@ -10,6 +69,8 @@ interface EconomicEvent {
     price?: number;
     from?: string;
     to?: string;
+    system?: string;
+    sourceOrSink?: string;
     metadata?: Record<string, unknown>;
 }
 type PinchPointStatus = 'optimal' | 'oversupplied' | 'scarce';
@@ -82,10 +143,17 @@ interface EconomyMetrics {
     giftTradeRatio: number;
     disposalTradeRatioByCurrency: Record<string, number>;
     disposalTradeRatio: number;
+    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 +174,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 +247,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 +319,7 @@ interface AgentEConfig {
     mode?: AgentEMode;
     dominantRoles?: string[];
     idealDistribution?: Record<string, number>;
+    parameters?: RegisteredParameter[];
     tickConfig?: Partial<TickConfig>;
     gracePeriod?: number;
     checkInterval?: number;
@@ -257,7 +330,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 +420,7 @@ declare class AgentE {
     private simulator;
     private planner;
     private executor;
+    private registry;
     readonly log: DecisionLog;
     readonly store: MetricStore;
     private personaTracker;
@@ -375,6 +449,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 +481,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 +500,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;
 }
@@ -445,10 +525,12 @@ 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;
@@ -459,10 +541,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[];
 }
@@ -575,7 +659,7 @@ 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;
@@ -587,9 +671,9 @@ 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 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_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 };