@agent-e/core 1.6.6 → 1.6.7

package/dist/index.d.mts

@@ -321,6 +321,7 @@ interface Thresholds {
     priceDiscoveryWindowTicks: number;
     giftTradeFilterRatio: number;
     disposalTradeWeightDiscount: number;
+    dominantRoles: string[];
 }
 interface TickConfig {
     /** How many real-world units one tick represents. Default: 1 */
@@ -525,7 +526,7 @@ declare class Observer {
     private tickConfig;
     constructor(tickConfig?: Partial<TickConfig>);
     registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
-    compute(state: EconomyState, recentEvents: EconomicEvent[]): EconomyMetrics;
+    compute(state: EconomyState, recentEvents: EconomicEvent[], personaDistribution?: Record<string, number>): EconomyMetrics;
 }
 
 declare class Simulator {
@@ -627,10 +628,14 @@ interface PersonaConfig {
     powerUserMinSystems: number;
     /** Rolling history window size (ticks). Default: 50 */
     historyWindow: number;
+    /** Ticks between full reclassification. Default: 10 */
+    reclassifyInterval: number;
 }
 declare class PersonaTracker {
     private agents;
     private config;
+    private cachedDistribution;
+    private lastClassifiedTick;
     constructor(config?: Partial<PersonaConfig>);
     /**
      * Ingest a state snapshot + events and update per-agent signals.
@@ -640,8 +645,10 @@ declare class PersonaTracker {
     /**
      * Classify all tracked agents and return the population distribution.
      * Returns { Whale: 0.05, ActiveTrader: 0.18, Passive: 0.42, ... }
+     * Caches results and only reclassifies at `reclassifyInterval` boundaries.
      */
-    getDistribution(): Record<string, number>;
+    getDistribution(currentTick?: number): Record<string, number>;
+    private _classify;
 }
 
 /**

package/dist/index.d.ts

@@ -321,6 +321,7 @@ interface Thresholds {
     priceDiscoveryWindowTicks: number;
     giftTradeFilterRatio: number;
     disposalTradeWeightDiscount: number;
+    dominantRoles: string[];
 }
 interface TickConfig {
     /** How many real-world units one tick represents. Default: 1 */
@@ -525,7 +526,7 @@ declare class Observer {
     private tickConfig;
     constructor(tickConfig?: Partial<TickConfig>);
     registerCustomMetric(name: string, fn: (state: EconomyState) => number): void;
-    compute(state: EconomyState, recentEvents: EconomicEvent[]): EconomyMetrics;
+    compute(state: EconomyState, recentEvents: EconomicEvent[], personaDistribution?: Record<string, number>): EconomyMetrics;
 }
 
 declare class Simulator {
@@ -627,10 +628,14 @@ interface PersonaConfig {
     powerUserMinSystems: number;
     /** Rolling history window size (ticks). Default: 50 */
     historyWindow: number;
+    /** Ticks between full reclassification. Default: 10 */
+    reclassifyInterval: number;
 }
 declare class PersonaTracker {
     private agents;
     private config;
+    private cachedDistribution;
+    private lastClassifiedTick;
     constructor(config?: Partial<PersonaConfig>);
     /**
      * Ingest a state snapshot + events and update per-agent signals.
@@ -640,8 +645,10 @@ declare class PersonaTracker {
     /**
      * Classify all tracked agents and return the population distribution.
      * Returns { Whale: 0.05, ActiveTrader: 0.18, Passive: 0.42, ... }
+     * Caches results and only reclassifies at `reclassifyInterval` boundaries.
      */
-    getDistribution(): Record<string, number>;
+    getDistribution(currentTick?: number): Record<string, number>;
+    private _classify;
 }
 
 /**

package/dist/index.js

@@ -176,7 +176,9 @@ var DEFAULT_THRESHOLDS = {
   relativePriceConvergenceTarget: 0.85,
   priceDiscoveryWindowTicks: 20,
   giftTradeFilterRatio: 0.15,
-  disposalTradeWeightDiscount: 0.5
+  disposalTradeWeightDiscount: 0.5,
+  // Structural dominance (P8)
+  dominantRoles: []
 };
 var PERSONA_HEALTHY_RANGES = {
   Active: { min: 0.2, max: 0.4 },
@@ -208,7 +210,7 @@ var Observer = class {
   registerCustomMetric(name, fn) {
     this.customMetricFns[name] = fn;
   }
-  compute(state, recentEvents) {
+  compute(state, recentEvents, personaDistribution) {
     if (!state.currencies || state.currencies.length === 0) {
       console.warn("[AgentE] Warning: state.currencies is empty. Metrics will be zeroed.");
     }
@@ -361,6 +363,16 @@ var Observer = class {
     for (const [role, count] of Object.entries(populationByRole)) {
       roleShares[role] = count / Math.max(1, totalAgents);
     }
+    const uniqueRoles = new Set(Object.values(state.agentRoles));
+    const rolesEmpty = uniqueRoles.size <= 1;
+    if (rolesEmpty && personaDistribution && Object.keys(personaDistribution).length > 0) {
+      for (const [persona, fraction] of Object.entries(personaDistribution)) {
+        populationByRole[persona] = Math.round(fraction * totalAgents);
+      }
+      for (const [role, count] of Object.entries(populationByRole)) {
+        roleShares[role] = count / Math.max(1, totalAgents);
+      }
+    }
     const churnByRole = {};
     for (const e of roleChangeEvents) {
       const role = e.role ?? "unknown";
@@ -850,25 +862,45 @@ var P4_MaterialsFlowFasterThanCooldown = {
   category: "supply_chain",
   description: "Input delivery rate must exceed or match production cooldown rate. If producers produce every 5 ticks but only receive raw materials every 10 ticks, they starve regardless of supply levels.",
   check(metrics, _thresholds) {
-    const { supplyByResource, populationByRole, velocity, totalAgents } = metrics;
+    const { supplyByResource, populationByRole, velocity, velocityByCurrency, totalAgents } = metrics;
     const totalSupply = Object.values(supplyByResource).reduce((s, v) => s + v, 0);
     const avgSupplyPerAgent = totalAgents > 0 ? totalSupply / totalAgents : 0;
     const roleEntries = Object.entries(populationByRole);
     const totalRoles = roleEntries.length;
-    if (totalRoles >= 2 && velocity < 5 && avgSupplyPerAgent < 0.5) {
-      return {
-        violated: true,
-        severity: 5,
-        evidence: { avgSupplyPerAgent, velocity, totalRoles },
-        suggestedAction: {
-          parameterType: "yield",
-          direction: "increase",
-          magnitude: 0.15,
-          reasoning: "Low supply per agent with stagnant velocity. Increase yield to compensate."
-        },
-        confidence: 0.65,
-        estimatedLag: 8
-      };
+    if (totalRoles >= 2 && avgSupplyPerAgent < 0.5) {
+      for (const [currency, currVelocity] of Object.entries(velocityByCurrency)) {
+        if (currVelocity < 5) {
+          return {
+            violated: true,
+            severity: 5,
+            evidence: { currency, currVelocity, avgSupplyPerAgent, totalRoles },
+            suggestedAction: {
+              parameterType: "yield",
+              scope: { currency },
+              direction: "increase",
+              magnitude: 0.15,
+              reasoning: `${currency} velocity is ${currVelocity.toFixed(1)} \u2014 materials not flowing. Increase yield to compensate.`
+            },
+            confidence: 0.7,
+            estimatedLag: 8
+          };
+        }
+      }
+      if (Object.keys(velocityByCurrency).length === 0 && velocity < 5) {
+        return {
+          violated: true,
+          severity: 5,
+          evidence: { avgSupplyPerAgent, velocity, totalRoles },
+          suggestedAction: {
+            parameterType: "yield",
+            direction: "increase",
+            magnitude: 0.15,
+            reasoning: "Low supply per agent with stagnant velocity. Increase yield to compensate."
+          },
+          confidence: 0.65,
+          estimatedLag: 8
+        };
+      }
     }
     if (avgSupplyPerAgent > 2) {
       return {
@@ -1027,28 +1059,42 @@ var P8_RegulatorCannotFightDesign = {
   id: "P8",
   name: "Regulator Cannot Fight the Design",
   category: "incentive",
-  description: "If the economy is designed to have a majority role (e.g. dominant role exceeds 55%), the regulator must know this and exempt that role from population suppression. AgentE at tick 1 seeing dominant role exceeds 55% and slashing pool rewards is overreach.",
-  check(metrics, _thresholds) {
+  description: "If a role dominates above 30%, classify as structural (in dominantRoles config) or pathological. Structural dominance gets no intervention. Pathological dominance gets crowding pressure.",
+  check(metrics, thresholds) {
     const { roleShares, avgSatisfaction } = metrics;
-    if (avgSatisfaction < 45) {
-      const dominantRole = Object.entries(roleShares).sort((a, b) => b[1] - a[1])[0];
-      if (dominantRole && dominantRole[1] > 0.3) {
-        return {
-          violated: true,
-          severity: 4,
-          evidence: { dominantRole: dominantRole[0], share: dominantRole[1], avgSatisfaction },
-          suggestedAction: {
-            parameterType: "reward",
-            direction: "increase",
-            magnitude: 0.1,
-            reasoning: `Low satisfaction with ${dominantRole[0]} dominant. Regulator may be suppressing a structurally necessary role. Ease pressure on dominant role rewards.`
-          },
-          confidence: 0.55,
-          estimatedLag: 8
-        };
-      }
+    const dominant = Object.entries(roleShares).sort((a, b) => b[1] - a[1])[0];
+    if (!dominant) return { violated: false };
+    const [dominantRole, dominantShare] = dominant;
+    if (dominantShare <= 0.3) return { violated: false };
+    const isStructural = thresholds.dominantRoles?.includes(dominantRole) ?? false;
+    if (isStructural) {
+      return {
+        violated: true,
+        severity: 3,
+        evidence: { role: dominantRole, share: dominantShare, classification: "structural" },
+        suggestedAction: {
+          parameterType: "rate",
+          direction: "set",
+          magnitude: 0,
+          reasoning: `${dominantRole} dominance (${(dominantShare * 100).toFixed(0)}%) is by design. No intervention.`
+        },
+        confidence: 0.85
+      };
     }
-    return { violated: false };
+    return {
+      violated: true,
+      severity: 7,
+      evidence: { role: dominantRole, share: dominantShare, classification: "pathological", avgSatisfaction },
+      suggestedAction: {
+        parameterType: "reward",
+        scope: { tags: [dominantRole] },
+        direction: "decrease",
+        magnitude: 0.1,
+        reasoning: `${dominantRole} at ${(dominantShare * 100).toFixed(0)}% is not a designed majority \u2014 apply crowding pressure.`
+      },
+      confidence: 0.7,
+      estimatedLag: 12
+    };
   }
 };
 var INCENTIVE_PRINCIPLES = [
@@ -1314,7 +1360,7 @@ var P15_PoolsNeedCapAndDecay = {
   id: "P15",
   name: "Pools Need Cap + Decay",
   category: "currency",
-  description: "Any pool (bank, reward pool) without a cap accumulates infinitely. A pool at 42% of total supply means 42% of the economy is frozen. Cap at 5%, decay at 2%/tick.",
+  description: "Any pool (bank, reward pool) without a cap accumulates infinitely. A pool at 42% of total supply means 42% of the economy is frozen. Cap configurable (default 10%). Violation fires at 2\xD7 cap share of total supply.",
   check(metrics, thresholds) {
     const { poolCapPercent } = thresholds;
     for (const [pool, currencyAmounts] of Object.entries(metrics.poolSizesByCurrency)) {
@@ -1347,7 +1393,7 @@ var P16_WithdrawalPenaltyScales = {
   id: "P16",
   name: "Withdrawal Penalty Scales with Lock Duration",
   category: "currency",
-  description: "A 50-tick lock period with a penalty calculated as /100 means agents can exit after 1 tick and keep 99% of accrued yield. Penalty must scale linearly: (1 - ticksStaked/lockDuration) \xD7 yield.",
+  description: "Depleted pool with estimated high staking signals early-withdrawal abuse. Symptom detector \u2014 penalty formula is developer responsibility.",
   check(metrics, _thresholds) {
     for (const [poolName, currencyAmounts] of Object.entries(metrics.poolSizesByCurrency)) {
       for (const curr of metrics.currencies) {
@@ -1463,7 +1509,7 @@ var P17_GracePeriodBeforeIntervention = {
   id: "P17",
   name: "Grace Period Before Intervention",
   category: "bootstrap",
-  description: "Any intervention before tick 50 is premature. The economy needs time to bootstrap with designed distributions. AgentE intervening at tick 1 against dominant role exceeds 55% (designed) killed the economy instantly.",
+  description: "Any intervention before tick 30 is premature. The economy needs time to bootstrap with designed distributions. Early intervention against designed dominance can kill the economy instantly.",
   check(metrics, _thresholds) {
     if (metrics.tick < 30 && metrics.avgSatisfaction < 40) {
       return {
@@ -1784,7 +1830,7 @@ var P27_AdjustmentsNeedCooldowns = {
   id: "P27",
   name: "Adjustments Need Cooldowns",
   category: "regulator",
-  description: "Adjusting the same parameter twice in a window causes oscillation. Minimum 15 ticks between same-parameter adjustments. This is enforced in the Planner but checked here as a diagnostic.",
+  description: "High churn + low satisfaction may indicate oscillation from rapid adjustments. Cooldown enforcement is structural (Planner). This is a symptom detector.",
   check(metrics, _thresholds) {
     const { churnRate, avgSatisfaction } = metrics;
     if (churnRate > 0.08 && avgSatisfaction < 50) {
@@ -1841,7 +1887,7 @@ var P38_CommunicationPreventsRevolt = {
   id: "P38",
   name: "Communication Prevents Revolt",
   category: "regulator",
-  description: "Every adjustment must be logged with reasoning. An adjustment made without explanation to participants causes revolt. AgentE logs every decision \u2014 this principle checks that logging is active.",
+  description: "High churn may indicate unexplained changes. Logging enforcement is structural (DecisionLog). Flags high churn as signal to review recent decisions.",
   check(metrics, _thresholds) {
     const { churnRate } = metrics;
     if (churnRate > 0.1) {
@@ -1866,7 +1912,7 @@ var REGULATOR_PRINCIPLES = [
   P25_CorrectLeversForCorrectProblems,
   P26_ContinuousPressureBeatsThresholdCuts,
   P27_AdjustmentsNeedCooldowns,
-  P28_StructuralDominanceIsNotPathological,
+  // P28 merged into P8 (v1.6.7)
   P38_CommunicationPreventsRevolt
 ];
 
@@ -2175,7 +2221,7 @@ var P43_SimulationMinimum = {
   id: "P43",
   name: "Simulation Minimum (100 Iterations)",
   category: "statistical",
-  description: "Fewer than 100 Monte Carlo iterations produces unreliable predictions. The variance of a 10-iteration simulation is so high that you might as well be guessing. This principle enforces the minimum in the Simulator.",
+  description: "Wild inflation swings (>30%) may indicate insufficient simulation data. Minimum iteration enforcement is structural (Simulator config). Symptom detector.",
   check(metrics, thresholds) {
     const { inflationRate } = metrics;
     if (Math.abs(inflationRate) > 0.3) {
@@ -2342,7 +2388,7 @@ var P49_IdleAssetTax = {
   id: "P49",
   name: "Idle Asset Tax",
   category: "resource",
-  description: 'Appreciating assets without holding cost \u2192 wealth concentration. If hoarding an asset makes you richer just by holding it, everyone hoards. Decay rates, storage costs, or expiry are "idle asset taxes" that force circulation.',
+  description: "Concentrated idle wealth (Gini >0.55, top 10% >60%, velocity <5). Raises transaction fees as proxy holding tax. Decay/storage/expiry requires developer implementation.",
   check(metrics, _thresholds) {
     const { giniCoefficient, top10PctShare, velocity } = metrics;
     if (giniCoefficient > 0.55 && top10PctShare > 0.6 && velocity < 5) {
@@ -2375,7 +2421,7 @@ var P33_FairNotEqual = {
   id: "P33",
   name: "Fair \u2260 Equal",
   category: "participant_experience",
-  description: "Gini = 0 is boring \u2014 everyone has the same and there is nothing to strive for. Healthy inequality from skill/effort is fine. Inequality from money (pay-to-win) is toxic. Target Gini 0.3-0.45: meaningful spread, not oligarchy.",
+  description: "Gini = 0 is boring \u2014 everyone has the same and there is nothing to strive for. Healthy inequality from skill/effort is fine. Inequality from money (pay-to-win) is toxic. Below 0.10 Gini = too flat; above configurable thresholds = oligarchy.",
   check(metrics, thresholds) {
     for (const curr of metrics.currencies) {
       const giniCoefficient = metrics.giniCoefficientByCurrency[curr] ?? 0;
@@ -2485,7 +2531,7 @@ var P45_TimeBudget = {
   id: "P45",
   name: "Time Budget",
   category: "participant_experience",
-  description: "required_time \u2264 available_time \xD7 0.8. If the economy requires more engagement than participants can realistically give, it is a disguised paywall. The 0.8 buffer accounts for real life.",
+  description: "timeToValue > 30 with satisfaction < 55 suggests excessive time demand. Proxy metric \u2014 does not measure individual available time.",
   check(metrics, thresholds) {
     const { timeToValue, avgSatisfaction } = metrics;
     const timePressure = timeToValue > 30;
@@ -2723,7 +2769,7 @@ var P52_EndowmentEffect = {
   id: "P52",
   name: "Endowment Effect",
   category: "operations",
-  description: "Participants who never owned premium assets do not value them. Free trial activities that let participants experience premium assets drive conversions because ownership creates perceived value (endowment effect).",
+  description: "High completion (>90%) + low satisfaction (<60) suggests activities not creating perceived value. May indicate missing endowment effect.",
   check(metrics, _thresholds) {
     const { avgSatisfaction, churnRate } = metrics;
     const { eventCompletionRate } = metrics;
@@ -2796,7 +2842,7 @@ var P54_OperationalCadence = {
   id: "P54",
   name: "Operational Cadence",
   category: "operations",
-  description: ">50% of activities that are re-wrapped existing supply \u2192 stagnation. The cadence must include genuinely new supply at regular intervals. This is an advisory principle \u2014 AgentE can flag but cannot fix supply.",
+  description: "Low velocity (<2) + low satisfaction after tick 100 = supply stagnation. Advisory signal for developer to audit content freshness.",
   check(metrics, _thresholds) {
     const { velocity, avgSatisfaction } = metrics;
     if (velocity < 2 && avgSatisfaction < 55 && metrics.tick > 100) {
@@ -3646,11 +3692,14 @@ var DEFAULT_PERSONA_CONFIG = {
   dormantWindow: 20,
   atRiskDropThreshold: 0.5,
   powerUserMinSystems: 3,
-  historyWindow: 50
+  historyWindow: 50,
+  reclassifyInterval: 10
 };
 var PersonaTracker = class {
   constructor(config) {
     this.agents = /* @__PURE__ */ new Map();
+    this.cachedDistribution = {};
+    this.lastClassifiedTick = -Infinity;
     this.config = { ...DEFAULT_PERSONA_CONFIG, ...config };
   }
   /**
@@ -3658,6 +3707,7 @@ var PersonaTracker = class {
    * Call this once per tick BEFORE getDistribution().
    */
   update(state, events) {
+    if (!state.agentBalances) return;
     const tick = state.tick;
     const txByAgent = /* @__PURE__ */ new Map();
     if (events) {
@@ -3713,8 +3763,18 @@ var PersonaTracker = class {
   /**
    * Classify all tracked agents and return the population distribution.
    * Returns { Whale: 0.05, ActiveTrader: 0.18, Passive: 0.42, ... }
+   * Caches results and only reclassifies at `reclassifyInterval` boundaries.
    */
-  getDistribution() {
+  getDistribution(currentTick) {
+    const tick = currentTick ?? 0;
+    if (tick - this.lastClassifiedTick < this.config.reclassifyInterval && Object.keys(this.cachedDistribution).length > 0) {
+      return this.cachedDistribution;
+    }
+    this.lastClassifiedTick = tick;
+    this.cachedDistribution = this._classify();
+    return this.cachedDistribution;
+  }
+  _classify() {
     const agentIds = [...this.agents.keys()];
     const total = agentIds.length;
     if (total === 0) return {};
@@ -4020,16 +4080,17 @@ var AgentE = class {
     this.currentTick = currentState.tick;
     const events = this.eventBuffer;
     this.eventBuffer = [];
+    this.personaTracker.update(currentState, events);
+    const personaDist = this.personaTracker.getDistribution(currentState.tick);
     let metrics;
     try {
-      metrics = this.observer.compute(currentState, events);
+      metrics = this.observer.compute(currentState, events, personaDist);
     } catch (err) {
       console.error(`[AgentE] Observer.compute() failed at tick ${currentState.tick}:`, err);
       return;
     }
     this.store.record(metrics);
-    this.personaTracker.update(currentState, events);
-    metrics.personaDistribution = this.personaTracker.getDistribution();
+    metrics.personaDistribution = personaDist;
     const { rolledBack, settled } = await this.executor.checkRollbacks(metrics, this.adapter);
     for (const plan2 of rolledBack) {
       this.planner.recordRolledBack(plan2);