@agent-e/core 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,136 @@
+# @agent-e/core
+
+Autonomous economic balancer SDK. 60 built-in principles, 5-stage pipeline, zero dependencies.
+
+## Install
+
+```bash
+npm install @agent-e/core
+```
+
+## Quick Start
+
+```typescript
+import { AgentE } from '@agent-e/core';
+
+const agent = new AgentE({
+  adapter: {
+    getState: () => ({
+      tick: currentTick,
+      agentBalances: { /* id → gold */ },
+      agentRoles: { /* id → role */ },
+      agentInventories: { /* id → { resource → qty } */ },
+      marketPrices: { /* resource → price */ },
+      agentSatisfaction: { /* id → 0-100 */ },
+      poolSizes: { /* pool → amount */ },
+    }),
+    setParam: async (param, value) => {
+      // Apply parameter change to your economy
+    },
+  },
+  mode: 'advisor', // or 'autonomous'
+});
+
+agent.connect(agent.adapter).start();
+
+// Call once per tick in your loop:
+await agent.tick();
+```
+
+## The 5-Stage Pipeline
+
+1. **Observer** — Translates raw state into 40+ metrics at 3 resolutions (fine/medium/coarse)
+2. **Diagnoser** — Runs 60 principles, returns violations sorted by severity
+3. **Simulator** — Monte Carlo forward projection (≥100 iterations) before any action
+4. **Planner** — Lag-aware, cooldown-aware planning with rollback conditions
+5. **Executor** — Applies actions and monitors for rollback triggers
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `autonomous` | Full pipeline — executes parameter changes automatically |
+| `advisor` | Full pipeline but stops before execution — emits recommendations via `onDecision` |
+
+## 60 Principles
+
+Organized across 15 categories: supply chain, incentives, population, currency flow, bootstrap, feedback loops, regulator, market dynamics, measurement, statistical, system dynamics, resource management, player experience, open economy, and liveops.
+
+Each principle has a `check(metrics, thresholds)` function that returns either `{ violated: false }` or a violation with severity, evidence, suggested action, confidence, and estimated lag.
+
+## Developer API
+
+```typescript
+// Lock a parameter from automated adjustment
+agent.lock('craftingCost');
+agent.unlock('craftingCost');
+
+// Constrain a parameter to a range
+agent.constrain('auctionFee', { min: 0.01, max: 0.50 });
+
+// Add a custom principle
+agent.addPrinciple(myPrinciple);
+
+// Register a custom metric
+agent.registerCustomMetric('myMetric', (state) => compute(state));
+
+// Veto actions
+agent.on('beforeAction', (plan) => {
+  if (plan.targetValue > 2.0) return false;
+});
+
+// Query decision history
+const decisions = agent.getDecisions({ outcome: 'applied' });
+
+// Health score (0-100)
+const health = agent.getHealth();
+
+// Metric time-series
+const latest = agent.metrics.latest('fine');
+```
+
+## Custom Principles
+
+```typescript
+import type { Principle } from '@agent-e/core';
+
+const myRule: Principle = {
+  id: 'MY_01',
+  name: 'Healer Population Floor',
+  category: 'population',
+  description: 'Healer share below 5% is a crisis',
+  check(metrics, thresholds) {
+    const share = metrics.roleShares['Healer'] ?? 0;
+    if (share < 0.05) {
+      return {
+        violated: true,
+        severity: 8,
+        evidence: { share },
+        suggestedAction: {
+          parameter: 'healerReward',
+          direction: 'increase',
+          magnitude: 0.25,
+          reasoning: 'Healer population critically low.',
+        },
+        confidence: 0.90,
+        estimatedLag: 10,
+      };
+    }
+    return { violated: false };
+  },
+};
+
+agent.addPrinciple(myRule);
+```
+
+## Performance
+
+- **O(N) event classification** — single-pass instead of 6 separate filters
+- **Cached diagnosis** — no redundant principle checks within the same tick
+- **Numerical stability** — clamped inputs to prevent NaN edge cases
+
+Typical for 1,000 agents, 100 events/tick: ~60ms end-to-end.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -360,6 +360,7 @@ declare class Observer {
 
 declare class Simulator {
     private diagnoser;
+    private beforeViolationsCache;
     /**
      * Simulate the effect of applying `action` to the current economy forward `forwardTicks`.
      * Runs `iterations` Monte Carlo trials and returns the outcome distribution.

package/dist/index.d.ts

@@ -360,6 +360,7 @@ declare class Observer {
 
 declare class Simulator {
     private diagnoser;
+    private beforeViolationsCache;
     /**
      * Simulate the effect of applying `action` to the current economy forward `forwardTicks`.
      * Runs `iterations` Monte Carlo trials and returns the outcome distribution.

package/dist/index.js

@@ -203,14 +203,38 @@ var Observer = class {
     const balances = Object.values(state.agentBalances);
     const roles = Object.values(state.agentRoles);
     const totalAgents = balances.length;
+    let faucetVolume = 0;
+    let sinkVolume = 0;
+    const tradeEvents = [];
+    const roleChangeEvents = [];
+    let churnCount = 0;
+    for (const e of recentEvents) {
+      switch (e.type) {
+        case "mint":
+        case "spawn":
+          faucetVolume += e.amount ?? 0;
+          break;
+        case "burn":
+        case "consume":
+          sinkVolume += e.amount ?? 0;
+          break;
+        case "trade":
+          tradeEvents.push(e);
+          break;
+        case "churn":
+          churnCount++;
+          roleChangeEvents.push(e);
+          break;
+        case "role_change":
+          roleChangeEvents.push(e);
+          break;
+      }
+    }
     const totalSupply = balances.reduce((s, b) => s + b, 0);
-    const faucetVolume = recentEvents.filter((e) => e.type === "mint" || e.type === "spawn").reduce((s, e) => s + (e.amount ?? 0), 0);
-    const sinkVolume = recentEvents.filter((e) => e.type === "burn" || e.type === "consume").reduce((s, e) => s + (e.amount ?? 0), 0);
     const netFlow = faucetVolume - sinkVolume;
     const tapSinkRatio = sinkVolume > 0 ? faucetVolume / sinkVolume : faucetVolume > 0 ? Infinity : 1;
     const prevSupply = this.previousMetrics?.totalSupply ?? totalSupply;
     const inflationRate = prevSupply > 0 ? (totalSupply - prevSupply) / prevSupply : 0;
-    const tradeEvents = recentEvents.filter((e) => e.type === "trade");
     const velocity = totalSupply > 0 ? tradeEvents.length / totalSupply : 0;
     const sortedBalances = [...balances].sort((a, b) => a - b);
     const meanBalance = totalAgents > 0 ? totalSupply / totalAgents : 0;
@@ -229,12 +253,10 @@ var Observer = class {
       roleShares[role] = count / Math.max(1, totalAgents);
     }
     const churnByRole = {};
-    const roleChanges = recentEvents.filter((e) => e.type === "churn" || e.type === "role_change");
-    for (const e of roleChanges) {
+    for (const e of roleChangeEvents) {
       const role = e.role ?? "unknown";
       churnByRole[role] = (churnByRole[role] ?? 0) + 1;
     }
-    const churnCount = recentEvents.filter((e) => e.type === "churn").length;
     const churnRate = churnCount / Math.max(1, totalAgents);
     const prices = { ...state.marketPrices };
     const priceVolatility = {};
@@ -297,7 +319,8 @@ var Observer = class {
         for (let j = i + 1; j < priceKeys.length; j++) {
           const pA = prices[priceKeys[i]];
           const pB = prices[priceKeys[j]];
-          const ratio = pA / pB;
+          let ratio = pA / pB;
+          ratio = Math.max(1e-3, Math.min(1e3, ratio));
           totalDivergence += Math.abs(Math.log(ratio));
           pairCount++;
         }
@@ -1666,7 +1689,7 @@ var P57_CombinatorialPriceSpace = {
           magnitude: 0.1,
           reasoning: `Only ${(convergenceRate * 100).toFixed(0)}% of ${relativePriceCount} relative prices have converged (target: ${(thresholds.relativePriceConvergenceTarget * 100).toFixed(0)}%). Price space too complex for distributed discovery. Lower friction to help.`
         },
-        confidence: 0.6,
+        confidence: 0.55,
         estimatedLag: thresholds.priceDiscoveryWindowTicks
       };
     }
@@ -1752,7 +1775,7 @@ var P55_ArbitrageThermometer = {
           magnitude: 0.15,
           reasoning: `Arbitrage index ${arbitrageIndex.toFixed(2)} exceeds critical threshold (${thresholds.arbitrageIndexCritical}). Relative prices are diverging \u2014 economy destabilizing. Lower trading friction to accelerate price convergence.`
         },
-        confidence: 0.8,
+        confidence: 0.75,
         estimatedLag: 8
       };
     }
@@ -2499,7 +2522,7 @@ var P56_ContentDropShock = {
             magnitude: 0.1,
             reasoning: `Content drop ${contentDropAge} ticks ago \u2014 arbitrage at ${arbitrageIndex.toFixed(2)} exceeds post-drop max (${thresholds.postDropArbitrageMax}). Price discovery struggling. Lower trading friction temporarily.`
           },
-          confidence: 0.7,
+          confidence: 0.6,
           estimatedLag: 5
         };
       }
@@ -2553,6 +2576,7 @@ var ALL_PRINCIPLES = [
 var Simulator = class {
   constructor() {
     this.diagnoser = new Diagnoser(ALL_PRINCIPLES);
+    this.beforeViolationsCache = /* @__PURE__ */ new Map();
   }
   /**
    * Simulate the effect of applying `action` to the current economy forward `forwardTicks`.
@@ -2575,9 +2599,14 @@ var Simulator = class {
     const p90 = sorted[Math.floor(actualIterations * 0.9)] ?? emptyMetrics();
     const mean = this.averageMetrics(outcomes);
     const netImprovement = this.checkImprovement(currentMetrics, p50, action);
-    const beforeViolations = new Set(
-      this.diagnoser.diagnose(currentMetrics, thresholds).map((d) => d.principle.id)
-    );
+    const tick = currentMetrics.tick;
+    let beforeViolations = this.beforeViolationsCache.get(tick);
+    if (!beforeViolations) {
+      beforeViolations = new Set(
+        this.diagnoser.diagnose(currentMetrics, thresholds).map((d) => d.principle.id)
+      );
+      this.beforeViolationsCache.set(tick, beforeViolations);
+    }
     const afterViolations = new Set(
       this.diagnoser.diagnose(p50, thresholds).map((d) => d.principle.id)
     );