@holoscript/std 2.1.0 → 6.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +7 -0
- package/LICENSE +21 -0
- package/README.md +197 -0
- package/dist/__tests__/EconomicPrimitives.test.d.ts +2 -0
- package/dist/__tests__/EconomicPrimitives.test.d.ts.map +1 -0
- package/dist/__tests__/EconomicTraits.test.d.ts +2 -0
- package/dist/__tests__/EconomicTraits.test.d.ts.map +1 -0
- package/dist/__tests__/SimulationLabPrimitives.test.d.ts +2 -0
- package/dist/__tests__/SimulationLabPrimitives.test.d.ts.map +1 -0
- package/dist/__tests__/collections.test.d.ts +2 -0
- package/dist/__tests__/collections.test.d.ts.map +1 -0
- package/dist/__tests__/events.test.d.ts +2 -0
- package/dist/__tests__/events.test.d.ts.map +1 -0
- package/dist/__tests__/index.test.d.ts +2 -0
- package/dist/__tests__/index.test.d.ts.map +1 -0
- package/dist/__tests__/materials.test.d.ts +2 -0
- package/dist/__tests__/materials.test.d.ts.map +1 -0
- package/dist/__tests__/math.test.d.ts +2 -0
- package/dist/__tests__/math.test.d.ts.map +1 -0
- package/dist/__tests__/physics.test.d.ts +2 -0
- package/dist/__tests__/physics.test.d.ts.map +1 -0
- package/dist/__tests__/spatial.test.d.ts +2 -0
- package/dist/__tests__/spatial.test.d.ts.map +1 -0
- package/dist/__tests__/standard-library-fundamentals.test.d.ts +2 -0
- package/dist/__tests__/standard-library-fundamentals.test.d.ts.map +1 -0
- package/dist/__tests__/string-and-time-utilities.test.d.ts +2 -0
- package/dist/__tests__/string-and-time-utilities.test.d.ts.map +1 -0
- package/dist/__tests__/string-decoupled.test.d.ts +2 -0
- package/dist/__tests__/string-decoupled.test.d.ts.map +1 -0
- package/dist/__tests__/string.test.d.ts +2 -0
- package/dist/__tests__/string.test.d.ts.map +1 -0
- package/dist/__tests__/time.test.d.ts +2 -0
- package/dist/__tests__/time.test.d.ts.map +1 -0
- package/dist/chunk-7HVUYGPS.js +679 -0
- package/dist/chunk-7HVUYGPS.js.map +1 -0
- package/dist/chunk-P4O3WNG2.js +287 -0
- package/dist/chunk-P4O3WNG2.js.map +1 -0
- package/dist/chunk-PFX2JM4X.js +683 -0
- package/dist/chunk-PFX2JM4X.js.map +1 -0
- package/dist/chunk-W2Q3LUCM.js +348 -0
- package/dist/chunk-W2Q3LUCM.js.map +1 -0
- package/dist/chunk-WS6W35YC.js +443 -0
- package/dist/chunk-WS6W35YC.js.map +1 -0
- package/dist/chunk-ZXVZAQCZ.js +470 -0
- package/dist/chunk-ZXVZAQCZ.js.map +1 -0
- package/dist/collections.cjs +715 -0
- package/dist/collections.cjs.map +1 -0
- package/dist/collections.d.ts.map +1 -1
- package/dist/collections.js +16 -719
- package/dist/collections.js.map +1 -1
- package/dist/events.d.ts +32 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/index.cjs +4101 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +21 -9
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1270 -157
- package/dist/index.js.map +1 -1
- package/dist/materials.d.ts +50 -0
- package/dist/materials.d.ts.map +1 -0
- package/dist/math.cjs +591 -0
- package/dist/math.cjs.map +1 -0
- package/dist/math.d.ts.map +1 -1
- package/dist/math.js +51 -537
- package/dist/math.js.map +1 -1
- package/dist/physics.d.ts +59 -0
- package/dist/physics.d.ts.map +1 -0
- package/dist/spatial.d.ts +82 -0
- package/dist/spatial.d.ts.map +1 -0
- package/dist/string.basic.test.d.ts +5 -0
- package/dist/string.basic.test.d.ts.map +1 -0
- package/dist/string.cjs +422 -0
- package/dist/string.cjs.map +1 -0
- package/dist/string.d.ts +5 -1
- package/dist/string.d.ts.map +1 -1
- package/dist/string.js +106 -442
- package/dist/string.js.map +1 -1
- package/dist/string.test.d.ts +5 -0
- package/dist/string.test.d.ts.map +1 -0
- package/dist/time.cjs +512 -0
- package/dist/time.cjs.map +1 -0
- package/dist/time.d.ts.map +1 -1
- package/dist/time.js +41 -528
- package/dist/time.js.map +1 -1
- package/dist/traits/ARTraits.d.ts +14 -0
- package/dist/traits/ARTraits.d.ts.map +1 -0
- package/dist/traits/EconomicPrimitives.cjs +335 -0
- package/dist/traits/EconomicPrimitives.cjs.map +1 -0
- package/dist/traits/EconomicPrimitives.d.ts +345 -0
- package/dist/traits/EconomicPrimitives.d.ts.map +1 -0
- package/dist/traits/EconomicPrimitives.js +55 -0
- package/dist/traits/EconomicPrimitives.js.map +1 -0
- package/dist/traits/EconomicTraits.cjs +471 -0
- package/dist/traits/EconomicTraits.cjs.map +1 -0
- package/dist/traits/EconomicTraits.d.ts +71 -0
- package/dist/traits/EconomicTraits.d.ts.map +1 -0
- package/dist/traits/EconomicTraits.js +17 -0
- package/dist/traits/EconomicTraits.js.map +1 -0
- package/dist/traits/IoTTraits.d.ts +14 -0
- package/dist/traits/IoTTraits.d.ts.map +1 -0
- package/dist/traits/SimulationLabPrimitives.d.ts +187 -0
- package/dist/traits/SimulationLabPrimitives.d.ts.map +1 -0
- package/dist/traits/SimulationLabTraits.d.ts +42 -0
- package/dist/traits/SimulationLabTraits.d.ts.map +1 -0
- package/dist/traits/VRRTraits.d.ts +150 -0
- package/dist/traits/VRRTraits.d.ts.map +1 -0
- package/dist/traits/__tests__/ARTraits.test.d.ts +2 -0
- package/dist/traits/__tests__/ARTraits.test.d.ts.map +1 -0
- package/dist/traits/__tests__/EconomicPrimitives.test.d.ts +2 -0
- package/dist/traits/__tests__/EconomicPrimitives.test.d.ts.map +1 -0
- package/dist/traits/__tests__/EconomicTraits.test.d.ts +2 -0
- package/dist/traits/__tests__/EconomicTraits.test.d.ts.map +1 -0
- package/dist/types.d.ts +9 -0
- package/dist/types.d.ts.map +1 -1
- package/error-utf8.log +6 -0
- package/error.log +0 -0
- package/package.json +42 -19
- package/src/__tests__/EconomicPrimitives.test.ts +690 -0
- package/src/__tests__/EconomicTraits.test.ts +425 -0
- package/src/__tests__/SimulationLabPrimitives.test.ts +415 -0
- package/src/__tests__/collections.test.ts +182 -0
- package/src/__tests__/events.test.ts +135 -0
- package/src/__tests__/index.test.ts +14 -0
- package/src/__tests__/materials.test.ts +84 -0
- package/src/__tests__/math.test.ts +246 -0
- package/src/__tests__/physics.test.ts +83 -0
- package/src/__tests__/spatial.test.ts +333 -0
- package/src/__tests__/standard-library-fundamentals.test.ts +1301 -0
- package/src/__tests__/string-and-time-utilities.test.ts +1070 -0
- package/src/__tests__/string-decoupled.test.ts +14 -0
- package/src/__tests__/string.test.ts +164 -0
- package/src/__tests__/time.test.ts +110 -0
- package/src/collections.ts +8 -2
- package/src/events.ts +88 -0
- package/src/index.ts +161 -11
- package/src/materials.ts +109 -0
- package/src/math.ts +30 -14
- package/src/physics.ts +141 -0
- package/src/spatial.ts +320 -0
- package/src/string.basic.test.ts +14 -0
- package/src/string.test.ts +335 -0
- package/src/string.ts +45 -13
- package/src/time.ts +10 -11
- package/src/traits/ARTraits.ts +103 -0
- package/src/traits/EconomicPrimitives.ts +755 -0
- package/src/traits/EconomicTraits.ts +552 -0
- package/src/traits/IoTTraits.ts +102 -0
- package/src/traits/SimulationLabPrimitives.ts +650 -0
- package/src/traits/SimulationLabTraits.ts +191 -0
- package/src/traits/VRRTraits.ts +326 -0
- package/src/traits/__tests__/ARTraits.test.ts +14 -0
- package/src/traits/__tests__/EconomicPrimitives.test.ts +14 -0
- package/src/traits/__tests__/EconomicTraits.test.ts +14 -0
- package/src/types.ts +47 -12
- package/std_error.log +5 -0
- package/tsup.config.ts +17 -0
- package/vitest.config.ts +10 -0
- package/dist/types.js +0 -198
- package/dist/types.js.map +0 -1
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Economic Primitives - Runtime math and types for virtual economy self-regulation
|
|
3
|
+
* @module @holoscript/std/economic
|
|
4
|
+
*
|
|
5
|
+
* Provides the mathematical building blocks for composable economic behaviors in HoloScript.
|
|
6
|
+
* These primitives implement research-proven mechanisms from control theory, DeFi AMMs,
|
|
7
|
+
* and progressive taxation -- adapted for spatial computing economies.
|
|
8
|
+
*
|
|
9
|
+
* References:
|
|
10
|
+
* - P.030.01: Dual-Loop PID Economy Controller (Alter Aeon model)
|
|
11
|
+
* - P.030.02: Bonding Curve Marketplace (DeFi AMM adaptation)
|
|
12
|
+
* - P.030.03: Progressive Wealth Recycling (logarithmic tax + UBI)
|
|
13
|
+
* - W.031: Faucet-Sink Ratio Is the Master Variable
|
|
14
|
+
* - W.032: Dual-Loop Feedback Control Solves Long-Term Stability
|
|
15
|
+
* - W.034: Wealth Tax > Income Tax for Virtual Gini Reduction
|
|
16
|
+
* - W.035: Bonding Curves Provide Intrinsic Price Discovery
|
|
17
|
+
*
|
|
18
|
+
* @version 1.0.0
|
|
19
|
+
* @category economic
|
|
20
|
+
*/
|
|
21
|
+
/**
|
|
22
|
+
* Represents an in-world currency amount. Always positive.
|
|
23
|
+
* Uses number to stay compatible with HoloScript's numeric system.
|
|
24
|
+
*/
|
|
25
|
+
export type Currency = number;
|
|
26
|
+
/**
|
|
27
|
+
* An agent identifier (player, NPC, or system account).
|
|
28
|
+
*/
|
|
29
|
+
export type AgentID = string;
|
|
30
|
+
/**
|
|
31
|
+
* Result type for economic operations that can fail.
|
|
32
|
+
*/
|
|
33
|
+
export type EconomicResult<T> = {
|
|
34
|
+
ok: true;
|
|
35
|
+
value: T;
|
|
36
|
+
} | {
|
|
37
|
+
ok: false;
|
|
38
|
+
error: EconomicError;
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* Economic error codes.
|
|
42
|
+
*/
|
|
43
|
+
export type EconomicError = 'INSUFFICIENT_FUNDS' | 'UNAUTHORIZED' | 'INVALID_AMOUNT' | 'BELOW_MINIMUM' | 'ABOVE_MAXIMUM' | 'ITEM_DESTROYED' | 'TRANSFER_BLOCKED' | 'CURVE_EXHAUSTED' | 'PID_DIVERGED' | 'TAX_EXEMPT' | 'INVALID_PARAMETER';
|
|
44
|
+
/**
|
|
45
|
+
* RBAC permission categories needed for economic operations.
|
|
46
|
+
* These map to the existing HoloScript RBAC system (RBACTrait.ts).
|
|
47
|
+
*/
|
|
48
|
+
export type EconomicPermission = 'economy.trade' | 'economy.mint' | 'economy.burn' | 'economy.set_price' | 'economy.tax' | 'economy.redistribute' | 'economy.tune_pid' | 'economy.audit' | 'economy.*';
|
|
49
|
+
/**
|
|
50
|
+
* Ownership record for a tradeable entity.
|
|
51
|
+
*/
|
|
52
|
+
export interface OwnershipRecord {
|
|
53
|
+
/** Current owner */
|
|
54
|
+
owner: AgentID;
|
|
55
|
+
/** Transfer history (most recent first, capped at last 50) */
|
|
56
|
+
history: TransferRecord[];
|
|
57
|
+
/** Whether transfers are currently locked */
|
|
58
|
+
locked: boolean;
|
|
59
|
+
/** Optional lock reason */
|
|
60
|
+
lockReason?: string;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* A single transfer event in the ownership history.
|
|
64
|
+
*/
|
|
65
|
+
export interface TransferRecord {
|
|
66
|
+
from: AgentID;
|
|
67
|
+
to: AgentID;
|
|
68
|
+
price: Currency;
|
|
69
|
+
timestamp: number;
|
|
70
|
+
/** Transaction hash for integrity verification (P.030.04) */
|
|
71
|
+
txHash: string;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Generate a transaction hash from transfer details.
|
|
75
|
+
* Uses a simple deterministic hash for in-engine verification.
|
|
76
|
+
* NOT cryptographically secure -- server authority provides integrity (W.037).
|
|
77
|
+
*/
|
|
78
|
+
export declare function generateTxHash(from: AgentID, to: AgentID, price: Currency, timestamp: number): string;
|
|
79
|
+
/**
|
|
80
|
+
* Execute a trade (transfer ownership for a price).
|
|
81
|
+
* Returns a new OwnershipRecord if successful.
|
|
82
|
+
*/
|
|
83
|
+
export declare function executeTrade(record: OwnershipRecord, buyer: AgentID, price: Currency, timestamp: number): EconomicResult<OwnershipRecord>;
|
|
84
|
+
/**
|
|
85
|
+
* Configuration for asset depreciation (hard sink mechanic).
|
|
86
|
+
*/
|
|
87
|
+
export interface DepreciationConfig {
|
|
88
|
+
/** Per-second decay rate (0.0 - 1.0). E.g., 0.001 = 0.1% per second */
|
|
89
|
+
decayRate: number;
|
|
90
|
+
/** Current condition (0.0 = destroyed, 1.0 = mint condition) */
|
|
91
|
+
condition: number;
|
|
92
|
+
/** Minimum condition before the item is considered destroyed */
|
|
93
|
+
destroyThreshold: number;
|
|
94
|
+
/** Whether repairs are allowed */
|
|
95
|
+
repairable: boolean;
|
|
96
|
+
/** Cost multiplier for repairs (relative to original value) */
|
|
97
|
+
repairCostMultiplier: number;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Default depreciation configuration.
|
|
101
|
+
*/
|
|
102
|
+
export declare const DEFAULT_DEPRECIATION: DepreciationConfig;
|
|
103
|
+
/**
|
|
104
|
+
* Calculate the current condition of an asset after elapsed time.
|
|
105
|
+
* Uses exponential decay: condition(t) = condition(0) * e^(-rate * elapsed)
|
|
106
|
+
*/
|
|
107
|
+
export declare function calculateDepreciation(initialCondition: number, decayRate: number, elapsedSeconds: number): number;
|
|
108
|
+
/**
|
|
109
|
+
* Calculate the effective value of an asset based on condition.
|
|
110
|
+
* Value scales linearly with condition.
|
|
111
|
+
*/
|
|
112
|
+
export declare function depreciatedValue(baseValue: Currency, condition: number): Currency;
|
|
113
|
+
/**
|
|
114
|
+
* Check if an asset has been destroyed by depreciation.
|
|
115
|
+
*/
|
|
116
|
+
export declare function isDestroyed(condition: number, threshold: number): boolean;
|
|
117
|
+
/**
|
|
118
|
+
* Calculate repair cost to restore an asset to full condition.
|
|
119
|
+
*/
|
|
120
|
+
export declare function calculateRepairCost(baseValue: Currency, currentCondition: number, repairCostMultiplier: number): Currency;
|
|
121
|
+
/**
|
|
122
|
+
* Bonding curve types with different economic properties.
|
|
123
|
+
*
|
|
124
|
+
* - linear: P = R * S (gentle, predictable)
|
|
125
|
+
* - exponential: P = R * S^n (early-adopter reward)
|
|
126
|
+
* - logarithmic: P = R * ln(S + 1) (stability-favoring)
|
|
127
|
+
* - sigmoid: P = R * S^n / (K^n + S^n) (bounded with plateau)
|
|
128
|
+
*/
|
|
129
|
+
export type BondingCurveType = 'linear' | 'exponential' | 'logarithmic' | 'sigmoid';
|
|
130
|
+
/**
|
|
131
|
+
* Configuration for a bonding curve marketplace.
|
|
132
|
+
*/
|
|
133
|
+
export interface BondingCurveConfig {
|
|
134
|
+
/** Curve type */
|
|
135
|
+
curveType: BondingCurveType;
|
|
136
|
+
/** Reserve ratio (base price multiplier) */
|
|
137
|
+
reserveRatio: number;
|
|
138
|
+
/** Curve steepness (n in P = R * S^(1/n)) */
|
|
139
|
+
curveSteepness: number;
|
|
140
|
+
/** Current supply */
|
|
141
|
+
currentSupply: number;
|
|
142
|
+
/** Reserve pool balance (collateral backing the curve) */
|
|
143
|
+
reserveBalance: Currency;
|
|
144
|
+
/** Transaction fee percentage (hard sink, 0-1) */
|
|
145
|
+
transactionFee: number;
|
|
146
|
+
/** Half-saturation constant for sigmoid curves */
|
|
147
|
+
sigmoidK: number;
|
|
148
|
+
/** Optional spatial distance factor for VR marketplaces */
|
|
149
|
+
spatialDistanceFactor: number;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Default bonding curve configuration.
|
|
153
|
+
*/
|
|
154
|
+
export declare const DEFAULT_BONDING_CURVE: BondingCurveConfig;
|
|
155
|
+
/**
|
|
156
|
+
* Calculate the spot price on a bonding curve given current supply.
|
|
157
|
+
*
|
|
158
|
+
* P = R * S^(1/n) for exponential
|
|
159
|
+
* P = R * S for linear
|
|
160
|
+
* P = R * ln(S+1) for logarithmic
|
|
161
|
+
* P = R * S^n / (K^n + S^n) for sigmoid
|
|
162
|
+
*/
|
|
163
|
+
export declare function bondingCurvePrice(supply: number, reserveRatio: number, curveSteepness: number, curveType?: BondingCurveType, sigmoidK?: number): Currency;
|
|
164
|
+
/**
|
|
165
|
+
* Calculate the cost to buy `amount` tokens on the bonding curve.
|
|
166
|
+
* Integrates the price function from currentSupply to currentSupply + amount.
|
|
167
|
+
*/
|
|
168
|
+
export declare function bondingCurveBuyCost(config: BondingCurveConfig, amount: number): Currency;
|
|
169
|
+
/**
|
|
170
|
+
* Calculate the refund for selling `amount` tokens on the bonding curve.
|
|
171
|
+
*/
|
|
172
|
+
export declare function bondingCurveSellRefund(config: BondingCurveConfig, amount: number): Currency;
|
|
173
|
+
/**
|
|
174
|
+
* Apply spatial distance factor to a bonding curve price.
|
|
175
|
+
* P_spatial = P_bonding * (1 + distance_factor * distance)
|
|
176
|
+
* Creates emergent trade routes in VR economies (P.030.02 ENRICHED).
|
|
177
|
+
*/
|
|
178
|
+
export declare function spatialPrice(basePrice: Currency, distanceToHub: number, distanceFactor: number): Currency;
|
|
179
|
+
/**
|
|
180
|
+
* Configuration for progressive wealth taxation.
|
|
181
|
+
*/
|
|
182
|
+
export interface WealthTaxConfig {
|
|
183
|
+
/** Wealth threshold below which no tax is levied */
|
|
184
|
+
threshold: Currency;
|
|
185
|
+
/** Base tax rate (multiplied by log of excess wealth) */
|
|
186
|
+
baseRate: number;
|
|
187
|
+
/** Maximum effective tax rate cap (prevents punishing engagement) */
|
|
188
|
+
maxEffectiveRate: number;
|
|
189
|
+
/** Tax collection interval description */
|
|
190
|
+
collectionInterval: 'hourly' | 'daily' | 'weekly';
|
|
191
|
+
/** Whether to redistribute to lowest quintile */
|
|
192
|
+
enableRedistribution: boolean;
|
|
193
|
+
/** Fraction of collected tax that goes to redistribution (remainder is burned as hard sink) */
|
|
194
|
+
redistributionFraction: number;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Default wealth tax configuration.
|
|
198
|
+
*/
|
|
199
|
+
export declare const DEFAULT_WEALTH_TAX: WealthTaxConfig;
|
|
200
|
+
/**
|
|
201
|
+
* Calculate the effective tax rate for a given wealth level.
|
|
202
|
+
* Uses logarithmic scaling: rate = min(maxRate, log(wealth/threshold) * baseRate)
|
|
203
|
+
* Returns 0 if wealth is below threshold (W.034).
|
|
204
|
+
*/
|
|
205
|
+
export declare function calculateTaxRate(wealth: Currency, threshold: Currency, baseRate: number, maxEffectiveRate: number): number;
|
|
206
|
+
/**
|
|
207
|
+
* Calculate the tax amount owed for a given wealth level.
|
|
208
|
+
*/
|
|
209
|
+
export declare function calculateTaxAmount(wealth: Currency, config: WealthTaxConfig): Currency;
|
|
210
|
+
/**
|
|
211
|
+
* Calculate redistribution amounts from a tax pool.
|
|
212
|
+
* Returns the per-recipient amount and the amount burned as a hard sink.
|
|
213
|
+
*/
|
|
214
|
+
export declare function calculateRedistribution(totalTaxCollected: Currency, recipientCount: number, redistributionFraction: number): {
|
|
215
|
+
perRecipient: Currency;
|
|
216
|
+
burned: Currency;
|
|
217
|
+
};
|
|
218
|
+
/**
|
|
219
|
+
* Configuration for a PID controller (P.030.01).
|
|
220
|
+
*/
|
|
221
|
+
export interface PIDConfig {
|
|
222
|
+
/** Proportional gain */
|
|
223
|
+
kp: number;
|
|
224
|
+
/** Integral gain */
|
|
225
|
+
ki: number;
|
|
226
|
+
/** Derivative gain */
|
|
227
|
+
kd: number;
|
|
228
|
+
/** Target setpoint (e.g., target money supply) */
|
|
229
|
+
setpoint: number;
|
|
230
|
+
/** Output limits [min, max] */
|
|
231
|
+
outputMin: number;
|
|
232
|
+
outputMax: number;
|
|
233
|
+
/** Anti-windup integral limit */
|
|
234
|
+
integralLimit: number;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Internal state of a PID controller.
|
|
238
|
+
*/
|
|
239
|
+
export interface PIDState {
|
|
240
|
+
/** Previous error (for derivative term) */
|
|
241
|
+
previousError: number;
|
|
242
|
+
/** Accumulated integral */
|
|
243
|
+
integral: number;
|
|
244
|
+
/** Last output value */
|
|
245
|
+
lastOutput: number;
|
|
246
|
+
/** Whether the controller has ever been updated */
|
|
247
|
+
initialized: boolean;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Default PID configuration for economy flow control.
|
|
251
|
+
*/
|
|
252
|
+
export declare const DEFAULT_PID: PIDConfig;
|
|
253
|
+
/**
|
|
254
|
+
* Create initial PID state.
|
|
255
|
+
*/
|
|
256
|
+
export declare function createPIDState(): PIDState;
|
|
257
|
+
/**
|
|
258
|
+
* Update the PID controller with a new measurement.
|
|
259
|
+
*
|
|
260
|
+
* Returns the control output (e.g., faucet rate multiplier).
|
|
261
|
+
* Positive output means increase faucet rate, negative means decrease.
|
|
262
|
+
*
|
|
263
|
+
* @param config PID configuration
|
|
264
|
+
* @param state Current PID state (mutated in place for performance)
|
|
265
|
+
* @param measurement Current measured value (e.g., total money supply)
|
|
266
|
+
* @param dt Time delta in seconds
|
|
267
|
+
* @returns The control output value
|
|
268
|
+
*/
|
|
269
|
+
export declare function updatePID(config: PIDConfig, state: PIDState, measurement: number, dt: number): number;
|
|
270
|
+
/**
|
|
271
|
+
* Dual-loop PID controller configuration (P.030.01).
|
|
272
|
+
*
|
|
273
|
+
* Inner loop: Per-source faucet adjustment (fast response)
|
|
274
|
+
* Outer loop: Global money supply targeting (slow response, adjusts inner setpoint)
|
|
275
|
+
*/
|
|
276
|
+
export interface DualLoopPIDConfig {
|
|
277
|
+
/** Inner loop PID (fast: adjusts faucet rates) */
|
|
278
|
+
innerLoop: PIDConfig;
|
|
279
|
+
/** Outer loop PID (slow: adjusts inner loop setpoint based on total supply) */
|
|
280
|
+
outerLoop: PIDConfig;
|
|
281
|
+
/** Target total money supply */
|
|
282
|
+
targetMoneySupply: number;
|
|
283
|
+
/** Active player count (for per-capita targeting) */
|
|
284
|
+
activePlayerCount: number;
|
|
285
|
+
/** Per-capita money supply target */
|
|
286
|
+
perCapitaTarget: number;
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* State for the dual-loop PID controller.
|
|
290
|
+
*/
|
|
291
|
+
export interface DualLoopPIDState {
|
|
292
|
+
innerState: PIDState;
|
|
293
|
+
outerState: PIDState;
|
|
294
|
+
/** Current effective faucet rate multiplier (0.0 - 2.0, where 1.0 = normal) */
|
|
295
|
+
faucetMultiplier: number;
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Create initial dual-loop PID state.
|
|
299
|
+
*/
|
|
300
|
+
export declare function createDualLoopPIDState(): DualLoopPIDState;
|
|
301
|
+
/**
|
|
302
|
+
* Update the dual-loop PID controller.
|
|
303
|
+
*
|
|
304
|
+
* @param config Dual-loop configuration
|
|
305
|
+
* @param state Current state (mutated in place)
|
|
306
|
+
* @param totalMoneySupply Current total money supply
|
|
307
|
+
* @param currentFaucetRate Current inflow rate
|
|
308
|
+
* @param dt Time delta in seconds
|
|
309
|
+
* @returns The new faucet rate multiplier
|
|
310
|
+
*/
|
|
311
|
+
export declare function updateDualLoopPID(config: DualLoopPIDConfig, state: DualLoopPIDState, totalMoneySupply: number, currentFaucetRate: number, dt: number): number;
|
|
312
|
+
/**
|
|
313
|
+
* Tracks the faucet/sink ratio -- the master variable for economy health (W.031).
|
|
314
|
+
*/
|
|
315
|
+
export interface FaucetSinkMetrics {
|
|
316
|
+
/** Total currency created in the current period */
|
|
317
|
+
totalFaucet: Currency;
|
|
318
|
+
/** Total currency destroyed in the current period */
|
|
319
|
+
totalSink: Currency;
|
|
320
|
+
/** Current faucet/sink ratio (target: ~1.0) */
|
|
321
|
+
ratio: number;
|
|
322
|
+
/** Velocity of money (transactions per unit per period) */
|
|
323
|
+
velocity: number;
|
|
324
|
+
/** Period start timestamp */
|
|
325
|
+
periodStart: number;
|
|
326
|
+
/** Historical ratio samples */
|
|
327
|
+
ratioHistory: number[];
|
|
328
|
+
}
|
|
329
|
+
/**
|
|
330
|
+
* Create initial faucet-sink metrics.
|
|
331
|
+
*/
|
|
332
|
+
export declare function createFaucetSinkMetrics(timestamp: number): FaucetSinkMetrics;
|
|
333
|
+
/**
|
|
334
|
+
* Record a faucet event (currency creation).
|
|
335
|
+
*/
|
|
336
|
+
export declare function recordFaucet(metrics: FaucetSinkMetrics, amount: Currency): void;
|
|
337
|
+
/**
|
|
338
|
+
* Record a sink event (currency destruction).
|
|
339
|
+
*/
|
|
340
|
+
export declare function recordSink(metrics: FaucetSinkMetrics, amount: Currency): void;
|
|
341
|
+
/**
|
|
342
|
+
* Reset metrics for a new period, archiving the current ratio.
|
|
343
|
+
*/
|
|
344
|
+
export declare function resetMetricsPeriod(metrics: FaucetSinkMetrics, timestamp: number): void;
|
|
345
|
+
//# sourceMappingURL=EconomicPrimitives.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"EconomicPrimitives.d.ts","sourceRoot":"","sources":["../../src/traits/EconomicPrimitives.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import {
|
|
2
|
+
DEFAULT_BONDING_CURVE,
|
|
3
|
+
DEFAULT_DEPRECIATION,
|
|
4
|
+
DEFAULT_PID,
|
|
5
|
+
DEFAULT_WEALTH_TAX,
|
|
6
|
+
bondingCurveBuyCost,
|
|
7
|
+
bondingCurvePrice,
|
|
8
|
+
bondingCurveSellRefund,
|
|
9
|
+
calculateDepreciation,
|
|
10
|
+
calculateRedistribution,
|
|
11
|
+
calculateRepairCost,
|
|
12
|
+
calculateTaxAmount,
|
|
13
|
+
calculateTaxRate,
|
|
14
|
+
createDualLoopPIDState,
|
|
15
|
+
createFaucetSinkMetrics,
|
|
16
|
+
createPIDState,
|
|
17
|
+
depreciatedValue,
|
|
18
|
+
executeTrade,
|
|
19
|
+
generateTxHash,
|
|
20
|
+
isDestroyed,
|
|
21
|
+
recordFaucet,
|
|
22
|
+
recordSink,
|
|
23
|
+
resetMetricsPeriod,
|
|
24
|
+
spatialPrice,
|
|
25
|
+
updateDualLoopPID,
|
|
26
|
+
updatePID
|
|
27
|
+
} from "../chunk-P4O3WNG2.js";
|
|
28
|
+
export {
|
|
29
|
+
DEFAULT_BONDING_CURVE,
|
|
30
|
+
DEFAULT_DEPRECIATION,
|
|
31
|
+
DEFAULT_PID,
|
|
32
|
+
DEFAULT_WEALTH_TAX,
|
|
33
|
+
bondingCurveBuyCost,
|
|
34
|
+
bondingCurvePrice,
|
|
35
|
+
bondingCurveSellRefund,
|
|
36
|
+
calculateDepreciation,
|
|
37
|
+
calculateRedistribution,
|
|
38
|
+
calculateRepairCost,
|
|
39
|
+
calculateTaxAmount,
|
|
40
|
+
calculateTaxRate,
|
|
41
|
+
createDualLoopPIDState,
|
|
42
|
+
createFaucetSinkMetrics,
|
|
43
|
+
createPIDState,
|
|
44
|
+
depreciatedValue,
|
|
45
|
+
executeTrade,
|
|
46
|
+
generateTxHash,
|
|
47
|
+
isDestroyed,
|
|
48
|
+
recordFaucet,
|
|
49
|
+
recordSink,
|
|
50
|
+
resetMetricsPeriod,
|
|
51
|
+
spatialPrice,
|
|
52
|
+
updateDualLoopPID,
|
|
53
|
+
updatePID
|
|
54
|
+
};
|
|
55
|
+
//# sourceMappingURL=EconomicPrimitives.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
|