@agent-e/core 1.5.0 → 1.5.1

package/dist/index.js

@@ -36,7 +36,7 @@ __export(index_exports, {
   OPEN_ECONOMY_PRINCIPLES: () => OPEN_ECONOMY_PRINCIPLES,
   OPERATIONS_PRINCIPLES: () => OPERATIONS_PRINCIPLES,
   Observer: () => Observer,
-  P10_SpawnWeightingUsesInversePopulation: () => P10_SpawnWeightingUsesInversePopulation,
+  P10_EntryWeightingUsesInversePopulation: () => P10_EntryWeightingUsesInversePopulation,
   P11_TwoTierPressure: () => P11_TwoTierPressure,
   P12_OnePrimaryFaucet: () => P12_OnePrimaryFaucet,
   P13_PotsAreZeroSumAndSelfRegulate: () => P13_PotsAreZeroSumAndSelfRegulate,
@@ -56,9 +56,9 @@ __export(index_exports, {
   P26_ContinuousPressureBeatsThresholdCuts: () => P26_ContinuousPressureBeatsThresholdCuts,
   P27_AdjustmentsNeedCooldowns: () => P27_AdjustmentsNeedCooldowns,
   P28_StructuralDominanceIsNotPathological: () => P28_StructuralDominanceIsNotPathological,
-  P29_PinchPoint: () => P29_PinchPoint,
+  P29_BottleneckDetection: () => P29_BottleneckDetection,
   P2_ClosedLoopsNeedDirectHandoff: () => P2_ClosedLoopsNeedDirectHandoff,
-  P30_MovingPinchPoint: () => P30_MovingPinchPoint,
+  P30_DynamicBottleneckRotation: () => P30_DynamicBottleneckRotation,
   P31_AnchorValueTracking: () => P31_AnchorValueTracking,
   P32_VelocityAboveSupply: () => P32_VelocityAboveSupply,
   P33_FairNotEqual: () => P33_FairNotEqual,
@@ -81,12 +81,12 @@ __export(index_exports, {
   P49_IdleAssetTax: () => P49_IdleAssetTax,
   P4_MaterialsFlowFasterThanCooldown: () => P4_MaterialsFlowFasterThanCooldown,
   P50_PayPowerRatio: () => P50_PayPowerRatio,
-  P51_SharkTooth: () => P51_SharkTooth,
+  P51_CyclicalEngagement: () => P51_CyclicalEngagement,
   P52_EndowmentEffect: () => P52_EndowmentEffect,
   P53_EventCompletionRate: () => P53_EventCompletionRate,
-  P54_LiveOpsCadence: () => P54_LiveOpsCadence,
+  P54_OperationalCadence: () => P54_OperationalCadence,
   P55_ArbitrageThermometer: () => P55_ArbitrageThermometer,
-  P56_ContentDropShock: () => P56_ContentDropShock,
+  P56_SupplyShockAbsorption: () => P56_SupplyShockAbsorption,
   P57_CombinatorialPriceSpace: () => P57_CombinatorialPriceSpace,
   P58_NoNaturalNumeraire: () => P58_NoNaturalNumeraire,
   P59_GiftEconomyNoise: () => P59_GiftEconomyNoise,
@@ -109,6 +109,7 @@ __export(index_exports, {
   SYSTEM_DYNAMICS_PRINCIPLES: () => SYSTEM_DYNAMICS_PRINCIPLES,
   Simulator: () => Simulator,
   emptyMetrics: () => emptyMetrics,
+  findWorstSystem: () => findWorstSystem,
   validateEconomyState: () => validateEconomyState
 });
 module.exports = __toCommonJS(index_exports);
@@ -255,7 +256,7 @@ var Observer = class {
         if (!actorsBySystem[e.system]) actorsBySystem[e.system] = /* @__PURE__ */ new Set();
         actorsBySystem[e.system].add(e.actor);
         const amt = e.amount ?? 0;
-        if (e.type === "mint" || e.type === "enter") {
+        if (e.type === "mint") {
           flowBySystem[e.system] = (flowBySystem[e.system] ?? 0) + amt;
         } else if (e.type === "burn" || e.type === "consume") {
           flowBySystem[e.system] = (flowBySystem[e.system] ?? 0) - amt;
@@ -263,7 +264,7 @@ var Observer = class {
       }
       if (e.sourceOrSink) {
         const amt = e.amount ?? 0;
-        if (e.type === "mint" || e.type === "enter") {
+        if (e.type === "mint") {
           flowBySource[e.sourceOrSink] = (flowBySource[e.sourceOrSink] ?? 0) + amt;
         } else if (e.type === "burn" || e.type === "consume") {
           flowBySink[e.sourceOrSink] = (flowBySink[e.sourceOrSink] ?? 0) + amt;
@@ -571,6 +572,9 @@ var Observer = class {
       sharkToothValleys: this.previousMetrics?.sharkToothValleys ?? [],
       eventCompletionRate: NaN,
       contentDropAge,
+      systems: state.systems ?? [],
+      sources: state.sources ?? [],
+      sinks: state.sinks ?? [],
       flowBySystem,
       activityBySystem,
       participantsBySystem,
@@ -720,6 +724,9 @@ function emptyMetrics(tick = 0) {
     sharkToothValleys: [],
     eventCompletionRate: NaN,
     contentDropAge: 0,
+    systems: [],
+    sources: [],
+    sinks: [],
     flowBySystem: {},
     activityBySystem: {},
     participantsBySystem: {},
@@ -1058,7 +1065,7 @@ var P9_RoleSwitchingNeedsFriction = {
   id: "P9",
   name: "Role Switching Needs Friction",
   category: "population",
-  description: "If >5% of the population switches roles in a single evaluation period, it is a herd movement, not rational rebalancing. Without friction (satisfaction cost, cooldown), one good tick causes mass migration.",
+  description: "If >5% of the population switches roles in a single evaluation period, it is a herd movement, not rational rebalancing. Without friction (satisfaction cost, minimum interval), one good tick causes mass migration.",
   check(metrics, thresholds) {
     const { churnByRole, roleShares } = metrics;
     const totalChurn = Object.values(churnByRole).reduce((s, v) => s + v, 0);
@@ -1081,7 +1088,7 @@ var P9_RoleSwitchingNeedsFriction = {
     return { violated: false };
   }
 };
-var P10_SpawnWeightingUsesInversePopulation = {
+var P10_EntryWeightingUsesInversePopulation = {
   id: "P10",
   name: "Entry Weighting Uses Inverse Population",
   category: "population",
@@ -1187,7 +1194,7 @@ var P46_PersonaDiversity = {
 };
 var POPULATION_PRINCIPLES = [
   P9_RoleSwitchingNeedsFriction,
-  P10_SpawnWeightingUsesInversePopulation,
+  P10_EntryWeightingUsesInversePopulation,
   P11_TwoTierPressure,
   P46_PersonaDiversity
 ];
@@ -1278,7 +1285,7 @@ var P14_TrackActualInjection = {
   id: "P14",
   name: "Track Actual Currency Injection, Not Value Creation",
   category: "currency",
-  description: 'Counting resource gathering as "currency injected" is misleading. Currency enters through faucet mechanisms (entering, rewards). Fake metrics break every downstream decision.',
+  description: 'Counting resource extraction as "currency injected" is misleading. Currency enters through faucet mechanisms (entering, rewards). Fake metrics break every downstream decision.',
   check(metrics, _thresholds) {
     for (const curr of metrics.currencies) {
       const faucetVolume = metrics.faucetVolumeByCurrency[curr] ?? 0;
@@ -1866,7 +1873,7 @@ var REGULATOR_PRINCIPLES = [
 ];
 
 // src/principles/market-dynamics.ts
-var P29_PinchPoint = {
+var P29_BottleneckDetection = {
   id: "P29",
   name: "Bottleneck Detection",
   category: "market_dynamics",
@@ -1911,7 +1918,7 @@ var P29_PinchPoint = {
     return { violated: false };
   }
 };
-var P30_MovingPinchPoint = {
+var P30_DynamicBottleneckRotation = {
   id: "P30",
   name: "Dynamic Bottleneck Rotation",
   category: "market_dynamics",
@@ -1986,8 +1993,8 @@ var P57_CombinatorialPriceSpace = {
   }
 };
 var MARKET_DYNAMICS_PRINCIPLES = [
-  P29_PinchPoint,
-  P30_MovingPinchPoint,
+  P29_BottleneckDetection,
+  P30_DynamicBottleneckRotation,
   P57_CombinatorialPriceSpace
 ];
 
@@ -2295,7 +2302,7 @@ var P40_ReplacementRate = {
   id: "P40",
   name: "Replacement Rate \u2265 2\xD7 Consumption",
   category: "resource",
-  description: "Respawn/production rate must be at least 2\xD7 consumption rate for equilibrium. At 1\xD7 you drift toward depletion. At 2\xD7 you have a buffer for demand spikes.",
+  description: "Replacement/production rate must be at least 2\xD7 consumption rate for equilibrium. At 1\xD7 you drift toward depletion. At 2\xD7 you have a buffer for demand spikes.",
   check(metrics, thresholds) {
     const { productionIndex, sinkVolume } = metrics;
     if (sinkVolume > 0 && productionIndex > 0) {
@@ -2662,7 +2669,7 @@ var OPEN_ECONOMY_PRINCIPLES = [
 ];
 
 // src/principles/operations.ts
-var P51_SharkTooth = {
+var P51_CyclicalEngagement = {
   id: "P51",
   name: "Cyclical Engagement Pattern",
   category: "operations",
@@ -2718,7 +2725,7 @@ var P52_EndowmentEffect = {
   id: "P52",
   name: "Endowment Effect",
   category: "operations",
-  description: "Participants who never owned premium items do not value them. Free trial activities that let participants experience premium items drive conversions because ownership creates perceived value (endowment effect).",
+  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).",
   check(metrics, _thresholds) {
     const { avgSatisfaction, churnRate } = metrics;
     const { eventCompletionRate } = metrics;
@@ -2787,11 +2794,11 @@ var P53_EventCompletionRate = {
     return { violated: false };
   }
 };
-var P54_LiveOpsCadence = {
+var P54_OperationalCadence = {
   id: "P54",
   name: "Operational Cadence",
   category: "operations",
-  description: ">50% of activities that are re-wrapped existing content \u2192 staleness. The cadence must include genuinely new content at regular intervals. This is an advisory principle \u2014 AgentE can flag but cannot fix content.",
+  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.",
   check(metrics, _thresholds) {
     const { velocity, avgSatisfaction } = metrics;
     if (velocity < 2 && avgSatisfaction < 55 && metrics.tick > 100) {
@@ -2803,7 +2810,7 @@ var P54_LiveOpsCadence = {
           parameterType: "reward",
           direction: "increase",
           magnitude: 0.1,
-          reasoning: "Low velocity and satisfaction after long runtime. Possible content staleness. Increase rewards as bridge while new content is developed (developer action required)."
+          reasoning: "Low velocity and satisfaction after long runtime. Possible supply stagnation. Increase rewards as bridge while new supply is developed (developer action required)."
         },
         confidence: 0.4,
         estimatedLag: 30
@@ -2812,11 +2819,11 @@ var P54_LiveOpsCadence = {
     return { violated: false };
   }
 };
-var P56_ContentDropShock = {
+var P56_SupplyShockAbsorption = {
   id: "P56",
   name: "Supply Shock Absorption",
   category: "operations",
-  description: "Every new-item injection shatters existing price equilibria \u2014 arbitrage spikes as participants re-price. Build cooldown windows for price discovery before measuring post-drop economic health.",
+  description: "Every new-item injection shatters existing price equilibria \u2014 arbitrage spikes as participants re-price. Build stabilization windows for price discovery before measuring post-injection economic health.",
   check(metrics, thresholds) {
     const { contentDropAge, arbitrageIndex } = metrics;
     if (contentDropAge > 0 && contentDropAge <= thresholds.contentDropCooldownTicks) {
@@ -2835,7 +2842,7 @@ var P56_ContentDropShock = {
             scope: { tags: ["transaction"] },
             direction: "decrease",
             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.`
+            reasoning: `Supply injection ${contentDropAge} ticks ago \u2014 arbitrage at ${arbitrageIndex.toFixed(2)} exceeds post-injection max (${thresholds.postDropArbitrageMax}). Price discovery struggling. Lower trading friction temporarily.`
           },
           confidence: 0.6,
           estimatedLag: 5
@@ -2846,11 +2853,11 @@ var P56_ContentDropShock = {
   }
 };
 var OPERATIONS_PRINCIPLES = [
-  P51_SharkTooth,
+  P51_CyclicalEngagement,
   P52_EndowmentEffect,
   P53_EventCompletionRate,
-  P54_LiveOpsCadence,
-  P56_ContentDropShock
+  P54_OperationalCadence,
+  P56_SupplyShockAbsorption
 ];
 
 // src/principles/index.ts
@@ -3009,10 +3016,12 @@ var Simulator = class {
     const sign = direction === "increase" ? -1 : 1;
     const roleEntries = Object.entries(metrics.populationByRole).sort((a, b) => b[1] - a[1]);
     const dominantRoleCount = roleEntries[0]?.[1] ?? 0;
-    const resolvedKey = action.resolvedParameter;
     let impact;
-    if (resolvedKey && this.registry) {
-      impact = this.registry.getFlowImpact(resolvedKey);
+    if (this.registry) {
+      const resolved = this.registry.resolve(action.parameterType, action.scope);
+      if (resolved) {
+        impact = resolved.flowImpact;
+      }
     }
     if (!impact) {
       impact = this.inferFlowImpact(action.parameterType);
@@ -3026,6 +3035,10 @@ var Simulator = class {
         return sign * dominantRoleCount * 0.5;
       case "mixed":
         return sign * (metrics.faucetVolumeByCurrency[currency] ?? 0) * 0.15;
+      case "friction":
+        return sign * (metrics.netFlowByCurrency[currency] ?? 0) * 0.1;
+      case "redistribution":
+        return sign * dominantRoleCount * 0.05;
       default:
         return sign * (metrics.netFlowByCurrency[currency] ?? 0) * 0.1;
     }
@@ -3108,6 +3121,8 @@ var Planner = class {
     this.constraints = /* @__PURE__ */ new Map();
     this.cooldowns = /* @__PURE__ */ new Map();
     // param → last-applied-tick
+    this.typeCooldowns = /* @__PURE__ */ new Map();
+    // type+scope key → last-applied-tick
     this.activePlanCount = 0;
   }
   lock(param) {
@@ -3130,6 +3145,8 @@ var Planner = class {
    */
   plan(diagnosis, metrics, simulationResult, currentParams, thresholds, registry) {
     const action = diagnosis.violation.suggestedAction;
+    const typeKey = this.typeCooldownKey(action.parameterType, action.scope);
+    if (this.isTypeCooldown(typeKey, metrics.tick, thresholds.cooldownTicks)) return null;
     let param;
     let resolvedBaseline;
     let scope;
@@ -3187,6 +3204,9 @@ var Planner = class {
   }
   recordApplied(plan, tick) {
     this.cooldowns.set(plan.parameter, tick);
+    const action = plan.diagnosis.violation.suggestedAction;
+    const typeKey = this.typeCooldownKey(action.parameterType, action.scope);
+    this.typeCooldowns.set(typeKey, tick);
     this.activePlanCount++;
   }
   recordRolledBack(_plan) {
@@ -3203,6 +3223,19 @@ var Planner = class {
   /** Reset all cooldowns (useful for testing) */
   resetCooldowns() {
     this.cooldowns.clear();
+    this.typeCooldowns.clear();
+  }
+  typeCooldownKey(type, scope) {
+    const parts = [type];
+    if (scope?.system) parts.push(`sys:${scope.system}`);
+    if (scope?.currency) parts.push(`cur:${scope.currency}`);
+    if (scope?.tags?.length) parts.push(`tags:${scope.tags.sort().join(",")}`);
+    return parts.join("|");
+  }
+  isTypeCooldown(typeKey, currentTick, cooldownTicks) {
+    const lastApplied = this.typeCooldowns.get(typeKey);
+    if (lastApplied === void 0) return false;
+    return currentTick - lastApplied < cooldownTicks;
   }
 };
 
@@ -3640,25 +3673,30 @@ var ParameterRegistry = class {
    * 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, scope) {
     const candidates = this.findByType(type);
     if (candidates.length === 0) return void 0;
     if (candidates.length === 1) return candidates[0];
-    let bestScore = -1;
+    let bestScore = -Infinity;
+    let bestPriority = -Infinity;
     let best;
     for (const candidate of candidates) {
-      const score = this.scopeMatchScore(candidate.scope, scope);
-      if (score > bestScore) {
+      const score = this.scopeSpecificity(candidate.scope, scope);
+      const prio = candidate.priority ?? 0;
+      if (score > bestScore || score === bestScore && prio > bestPriority) {
         bestScore = score;
+        bestPriority = prio;
         best = candidate;
       }
     }
+    if (bestScore === -Infinity) return void 0;
     return best;
   }
   /** Find all parameters of a given type. */
@@ -3700,28 +3738,60 @@ var ParameterRegistry = class {
   get size() {
     return this.parameters.size;
   }
+  /**
+   * Validate the registry for common misconfigurations.
+   * Returns warnings (non-fatal) and errors (likely broken).
+   */
+  validate() {
+    const warnings = [];
+    const errors = [];
+    const typeMap = /* @__PURE__ */ new Map();
+    for (const param of this.parameters.values()) {
+      const list = typeMap.get(param.type) ?? [];
+      list.push(param);
+      typeMap.set(param.type, list);
+    }
+    for (const [type, params] of typeMap) {
+      if (params.length > 1) {
+        const unscopedCount = params.filter((p) => !p.scope).length;
+        if (unscopedCount > 1) {
+          errors.push(
+            `Type '${type}' has ${unscopedCount} unscoped parameters \u2014 resolve() cannot distinguish them`
+          );
+        }
+      }
+    }
+    for (const param of this.parameters.values()) {
+      if (!param.flowImpact) {
+        warnings.push(`Parameter '${param.key}' has no flowImpact \u2014 Simulator will use inference`);
+      }
+    }
+    return {
+      valid: errors.length === 0,
+      warnings,
+      errors
+    };
+  }
   // ── Private ─────────────────────────────────────────────────────────────
-  scopeMatchScore(paramScope, queryScope) {
+  scopeSpecificity(paramScope, queryScope) {
     if (!queryScope) return 0;
     if (!paramScope) return 0;
     let score = 0;
     if (queryScope.system && paramScope.system) {
       if (queryScope.system === paramScope.system) score += 10;
-      else return -1;
+      else return -Infinity;
     }
     if (queryScope.currency && paramScope.currency) {
       if (queryScope.currency === paramScope.currency) score += 5;
-      else return -1;
+      else return -Infinity;
     }
     if (queryScope.tags && queryScope.tags.length > 0 && paramScope.tags && paramScope.tags.length > 0) {
       const overlap = queryScope.tags.filter((t) => paramScope.tags.includes(t)).length;
       if (overlap > 0) {
         score += overlap * 3;
       } else {
-        return -1;
+        return -Infinity;
       }
-    } else if (queryScope.tags && queryScope.tags.length > 0 && paramScope.tags && paramScope.tags.length > 0) {
-      return -1;
     }
     return score;
   }
@@ -3753,6 +3823,7 @@ var AgentE = class {
       mode: this.mode,
       dominantRoles: config.dominantRoles ?? [],
       idealDistribution: config.idealDistribution ?? {},
+      validateRegistry: config.validateRegistry ?? true,
       tickConfig: config.tickConfig ?? { duration: 1, unit: "tick" },
       gracePeriod: config.gracePeriod ?? 50,
       checkInterval: config.checkInterval ?? 5,
@@ -3773,6 +3844,11 @@ var AgentE = class {
     if (config.parameters) {
       this.registry.registerAll(config.parameters);
     }
+    if (config.validateRegistry !== false && this.registry.size > 0) {
+      const validation = this.registry.validate();
+      for (const w of validation.warnings) console.warn(`[AgentE] Registry warning: ${w}`);
+      for (const e of validation.errors) console.error(`[AgentE] Registry error: ${e}`);
+    }
     this.simulator = new Simulator(this.registry);
     if (config.onDecision) this.on("decision", config.onDecision);
     if (config.onAlert) this.on("alert", config.onAlert);
@@ -3969,6 +4045,31 @@ var AgentE = class {
   }
 };
 
+// src/utils.ts
+function findWorstSystem(metrics, check, tolerancePercent = 0) {
+  const systems = metrics.systems;
+  if (systems.length === 0) return void 0;
+  let worstSystem;
+  let worstScore = -Infinity;
+  let totalScore = 0;
+  for (const sys of systems) {
+    const score = check(sys, metrics);
+    totalScore += score;
+    if (score > worstScore) {
+      worstScore = score;
+      worstSystem = sys;
+    }
+  }
+  if (!worstSystem) return void 0;
+  if (tolerancePercent > 0 && systems.length > 1) {
+    const avg = totalScore / systems.length;
+    if (avg === 0) return { system: worstSystem, score: worstScore };
+    const excessPercent = (worstScore - avg) / Math.abs(avg) * 100;
+    if (excessPercent < tolerancePercent) return void 0;
+  }
+  return { system: worstSystem, score: worstScore };
+}
+
 // src/StateValidator.ts
 function validateEconomyState(state) {
   const errors = [];
@@ -4320,7 +4421,7 @@ function describeValue(value) {
   OPEN_ECONOMY_PRINCIPLES,
   OPERATIONS_PRINCIPLES,
   Observer,
-  P10_SpawnWeightingUsesInversePopulation,
+  P10_EntryWeightingUsesInversePopulation,
   P11_TwoTierPressure,
   P12_OnePrimaryFaucet,
   P13_PotsAreZeroSumAndSelfRegulate,
@@ -4340,9 +4441,9 @@ function describeValue(value) {
   P26_ContinuousPressureBeatsThresholdCuts,
   P27_AdjustmentsNeedCooldowns,
   P28_StructuralDominanceIsNotPathological,
-  P29_PinchPoint,
+  P29_BottleneckDetection,
   P2_ClosedLoopsNeedDirectHandoff,
-  P30_MovingPinchPoint,
+  P30_DynamicBottleneckRotation,
   P31_AnchorValueTracking,
   P32_VelocityAboveSupply,
   P33_FairNotEqual,
@@ -4365,12 +4466,12 @@ function describeValue(value) {
   P49_IdleAssetTax,
   P4_MaterialsFlowFasterThanCooldown,
   P50_PayPowerRatio,
-  P51_SharkTooth,
+  P51_CyclicalEngagement,
   P52_EndowmentEffect,
   P53_EventCompletionRate,
-  P54_LiveOpsCadence,
+  P54_OperationalCadence,
   P55_ArbitrageThermometer,
-  P56_ContentDropShock,
+  P56_SupplyShockAbsorption,
   P57_CombinatorialPriceSpace,
   P58_NoNaturalNumeraire,
   P59_GiftEconomyNoise,
@@ -4393,6 +4494,7 @@ function describeValue(value) {
   SYSTEM_DYNAMICS_PRINCIPLES,
   Simulator,
   emptyMetrics,
+  findWorstSystem,
   validateEconomyState
 });
 //# sourceMappingURL=index.js.map