@hazeljs/organism 2.0.6

package/src/decorators/index.ts

@@ -0,0 +1,180 @@
+/**
+ * Organism decorators — follow @Agent (reflect-metadata + global registries).
+ */
+
+import 'reflect-metadata';
+import type {
+  AgentGeneDefinition,
+  ConstitutionDefinition,
+  EnvironmentDefinition,
+  MissionDefinition,
+  ResourceDefinition,
+} from '../types/organism.types';
+
+type Newable = new (...args: unknown[]) => unknown;
+
+const MISSION_KEY = Symbol('organism:mission');
+const ORGANISM_KEY = Symbol('organism:organism');
+const GENE_KEY = Symbol('organism:gene');
+const ENVIRONMENT_KEY = Symbol('organism:environment');
+const CONSTITUTION_KEY = Symbol('organism:constitution');
+const RESOURCE_KEY = Symbol('organism:resource');
+
+const MISSION_REGISTRY = new Set<Newable>();
+const ORGANISM_REGISTRY = new Set<Newable>();
+const GENE_REGISTRY = new Set<Newable>();
+const ENVIRONMENT_REGISTRY = new Set<Newable>();
+const CONSTITUTION_REGISTRY = new Set<Newable>();
+const RESOURCE_REGISTRY = new Set<Newable>();
+
+export interface OrganismDecoratorOptions {
+  mission?: Newable | MissionDefinition;
+  environment?: Newable | EnvironmentDefinition;
+  constitution?: Newable | ConstitutionDefinition;
+  genes?: Array<Newable | AgentGeneDefinition>;
+  resources?: Newable | ResourceDefinition;
+  id?: string;
+}
+
+export function Mission(config: MissionDefinition): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return ((target: Function) => {
+    Reflect.defineMetadata(MISSION_KEY, config, target);
+    MISSION_REGISTRY.add(target as Newable);
+  }) as ClassDecorator;
+}
+
+export function Organism(config: OrganismDecoratorOptions = {}): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return ((target: Function) => {
+    Reflect.defineMetadata(ORGANISM_KEY, config, target);
+    ORGANISM_REGISTRY.add(target as Newable);
+  }) as ClassDecorator;
+}
+
+export function AgentGene(config: AgentGeneDefinition): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return ((target: Function) => {
+    Reflect.defineMetadata(GENE_KEY, config, target);
+    GENE_REGISTRY.add(target as Newable);
+  }) as ClassDecorator;
+}
+
+export function Environment(config: EnvironmentDefinition): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return ((target: Function) => {
+    Reflect.defineMetadata(ENVIRONMENT_KEY, config, target);
+    ENVIRONMENT_REGISTRY.add(target as Newable);
+  }) as ClassDecorator;
+}
+
+export function Constitution(config: ConstitutionDefinition): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return ((target: Function) => {
+    Reflect.defineMetadata(CONSTITUTION_KEY, config, target);
+    CONSTITUTION_REGISTRY.add(target as Newable);
+  }) as ClassDecorator;
+}
+
+export function Resource(config: ResourceDefinition): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return ((target: Function) => {
+    Reflect.defineMetadata(RESOURCE_KEY, config, target);
+    RESOURCE_REGISTRY.add(target as Newable);
+  }) as ClassDecorator;
+}
+
+export function getMissionMetadata(target: Newable): MissionDefinition | undefined {
+  return Reflect.getMetadata(MISSION_KEY, target);
+}
+
+export function getOrganismMetadata(target: Newable): OrganismDecoratorOptions | undefined {
+  return Reflect.getMetadata(ORGANISM_KEY, target);
+}
+
+export function getAgentGeneMetadata(target: Newable): AgentGeneDefinition | undefined {
+  return Reflect.getMetadata(GENE_KEY, target);
+}
+
+export function getEnvironmentMetadata(target: Newable): EnvironmentDefinition | undefined {
+  return Reflect.getMetadata(ENVIRONMENT_KEY, target);
+}
+
+export function getConstitutionMetadata(target: Newable): ConstitutionDefinition | undefined {
+  return Reflect.getMetadata(CONSTITUTION_KEY, target);
+}
+
+export function getResourceMetadata(target: Newable): ResourceDefinition | undefined {
+  return Reflect.getMetadata(RESOURCE_KEY, target);
+}
+
+export function getRegisteredMissions(): Newable[] {
+  return Array.from(MISSION_REGISTRY);
+}
+
+export function getRegisteredOrganisms(): Newable[] {
+  return Array.from(ORGANISM_REGISTRY);
+}
+
+export function getRegisteredGenes(): Newable[] {
+  return Array.from(GENE_REGISTRY);
+}
+
+export function getRegisteredEnvironments(): Newable[] {
+  return Array.from(ENVIRONMENT_REGISTRY);
+}
+
+export function getRegisteredConstitutions(): Newable[] {
+  return Array.from(CONSTITUTION_REGISTRY);
+}
+
+export function getRegisteredResources(): Newable[] {
+  return Array.from(RESOURCE_REGISTRY);
+}
+
+export function resolveMission(input: Newable | MissionDefinition): MissionDefinition {
+  if (typeof input === 'function') {
+    const meta = getMissionMetadata(input);
+    if (!meta) throw new Error(`Class ${input.name} is not decorated with @Mission`);
+    return meta;
+  }
+  return input;
+}
+
+export function resolveGene(input: Newable | AgentGeneDefinition): AgentGeneDefinition {
+  if (typeof input === 'function') {
+    const meta = getAgentGeneMetadata(input);
+    if (!meta) throw new Error(`Class ${input.name} is not decorated with @AgentGene`);
+    return meta;
+  }
+  return input;
+}
+
+export function resolveEnvironment(input: Newable | EnvironmentDefinition): EnvironmentDefinition {
+  if (typeof input === 'function') {
+    const meta = getEnvironmentMetadata(input);
+    if (!meta) throw new Error(`Class ${input.name} is not decorated with @Environment`);
+    return meta;
+  }
+  return input;
+}
+
+export function resolveConstitution(
+  input: Newable | ConstitutionDefinition
+): ConstitutionDefinition {
+  if (typeof input === 'function') {
+    const meta = getConstitutionMetadata(input);
+    if (!meta) throw new Error(`Class ${input.name} is not decorated with @Constitution`);
+    return meta;
+  }
+  return input;
+}
+
+export function resolveResource(input: Newable | ResourceDefinition): ResourceDefinition {
+  if (typeof input === 'function') {
+    const meta = getResourceMetadata(input);
+    if (!meta) throw new Error(`Class ${input.name} is not decorated with @Resource`);
+    return meta;
+  }
+  return input;
+}

package/src/economy/market-engine.ts

@@ -0,0 +1,324 @@
+/**
+ * Phase 4 — internal resource market: bids, clearing, peer negotiation.
+ */
+
+import type {
+  AgentResourceWallet,
+  MarketClearingResult,
+  MarketConfig,
+  NegotiationOffer,
+  NegotiationResult,
+  OrganismRecord,
+  ResourceBid,
+  ResourceRequest,
+  RuntimeAgentRecord,
+} from '../types/organism.types';
+import { DEFAULT_MARKET_CONFIG } from '../types/organism.types';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+import { ResourceAllocator } from './resource-allocator';
+import { UtilityForecaster } from './utility-forecaster';
+
+let bidSeq = 0;
+
+export function resetBidSeqForTests(): void {
+  bidSeq = 0;
+}
+
+/**
+ * Deterministic sealed-bid style clearing:
+ * rank by forecast net value + price + urgency − opportunity cost.
+ */
+export class MarketEngine {
+  private openBids = new Map<string, ResourceBid>();
+  private history: MarketClearingResult[] = [];
+  private readonly config: MarketConfig;
+
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly allocator: ResourceAllocator,
+    private readonly forecaster: UtilityForecaster,
+    private readonly organismId: string,
+    private readonly now: () => Date = () => new Date(),
+    config: Partial<MarketConfig> = {}
+  ) {
+    this.config = { ...DEFAULT_MARKET_CONFIG, ...config };
+  }
+
+  placeBid(input: {
+    agentId: string;
+    reason: string;
+    requested: ResourceRequest;
+    expectedValue: number;
+    confidence: number;
+    urgency?: number;
+    bidPrice?: number;
+    ttlMs?: number;
+  }): ResourceBid {
+    bidSeq += 1;
+    const createdAt = this.now();
+    const ttl = input.ttlMs ?? this.config.defaultBidTtlMs;
+    const bid: ResourceBid = {
+      id: `bid_${bidSeq}`,
+      agentId: input.agentId,
+      reason: input.reason,
+      requested: { ...input.requested },
+      expectedValue: input.expectedValue,
+      confidence: input.confidence,
+      urgency: input.urgency ?? 0.5,
+      bidPrice: input.bidPrice,
+      createdAt,
+      expiresAt: new Date(createdAt.getTime() + ttl),
+      status: 'open',
+    };
+    this.openBids.set(bid.id, bid);
+    void this.events.emit(OrganismEventType.ORGANISM_RESOURCE_BID, this.organismId, bid);
+    return bid;
+  }
+
+  listOpenBids(): ResourceBid[] {
+    this.expireBids();
+    return Array.from(this.openBids.values()).filter((b) => b.status === 'open');
+  }
+
+  cancelBid(bidId: string): boolean {
+    const bid = this.openBids.get(bidId);
+    if (!bid || bid.status !== 'open') return false;
+    bid.status = 'cancelled';
+    return true;
+  }
+
+  /**
+   * Clear all open (non-expired) bids against the organism pool.
+   * Higher clearing score wins until pool is exhausted.
+   */
+  clearMarket(input: {
+    record: OrganismRecord;
+    agents: Map<string, RuntimeAgentRecord>;
+  }): MarketClearingResult {
+    this.expireBids();
+    const roundId = `mkt_${Date.now().toString(36)}_${bidSeq}`;
+    const open = this.listOpenBids();
+
+    type Ranked = {
+      bid: ResourceBid;
+      agent: RuntimeAgentRecord;
+      forecast: ReturnType<UtilityForecaster['forecast']>;
+      clearingScore: number;
+    };
+
+    const ranked: Ranked[] = [];
+    for (const bid of open) {
+      const agent = input.agents.get(bid.agentId);
+      if (!agent || agent.status === 'terminated') {
+        bid.status = 'lost';
+        continue;
+      }
+      const forecast = this.forecaster.forecast({
+        agent,
+        record: input.record,
+        requested: bid.requested,
+        expectedValue: bid.expectedValue,
+        confidence: bid.confidence,
+        urgency: bid.urgency,
+      });
+      const priceScore = (bid.bidPrice ?? 0) / Math.max(1, bid.expectedValue);
+      const clearingScore =
+        forecast.netExpectedValue * (1 - this.config.priceWeight) +
+        priceScore * bid.expectedValue * this.config.priceWeight +
+        bid.urgency * 10 +
+        agent.reputation.score * 5;
+      ranked.push({ bid, agent, forecast, clearingScore });
+    }
+
+    ranked.sort((a, b) => b.clearingScore - a.clearingScore);
+
+    const awarded: MarketClearingResult['awarded'] = [];
+    const denied: MarketClearingResult['denied'] = [];
+    let opportunityCostTotal = 0;
+
+    for (const item of ranked) {
+      if (item.forecast.netExpectedValue < this.config.minNetExpectedValue) {
+        item.bid.status = 'lost';
+        denied.push({
+          bidId: item.bid.id,
+          agentId: item.bid.agentId,
+          reason: `Net expected value ${item.forecast.netExpectedValue.toFixed(2)} below minimum`,
+          forecast: item.forecast,
+        });
+        continue;
+      }
+
+      const allocation = this.allocator.allocate(input.record, {
+        agentId: item.bid.agentId,
+        requestedResources: item.bid.requested,
+        expectedUtility: item.forecast.expectedUtility,
+        confidence: item.bid.confidence,
+        urgency: item.bid.urgency,
+        reputationScore: item.agent.reputation.score,
+      });
+
+      if (!allocation.approved) {
+        item.bid.status = 'lost';
+        denied.push({
+          bidId: item.bid.id,
+          agentId: item.bid.agentId,
+          reason: allocation.reason,
+          forecast: item.forecast,
+        });
+        continue;
+      }
+
+      // Charge bid price from agent wallet if present
+      if (item.bid.bidPrice && item.bid.bidPrice > 0) {
+        const money = item.agent.wallet.moneyRemaining?.amount ?? 0;
+        if (money >= item.bid.bidPrice) {
+          item.agent.wallet = {
+            ...item.agent.wallet,
+            moneyRemaining: {
+              amount: money - item.bid.bidPrice,
+              currency:
+                item.agent.wallet.moneyRemaining?.currency ??
+                input.record.pool.moneyRemaining.currency,
+            },
+          };
+          input.record.pool.moneyRemaining.amount += item.bid.bidPrice;
+        }
+      }
+
+      item.bid.status = 'won';
+      opportunityCostTotal += item.forecast.opportunityCost;
+      awarded.push({
+        bidId: item.bid.id,
+        agentId: item.bid.agentId,
+        wallet: allocation.wallet,
+        forecast: item.forecast,
+      });
+    }
+
+    // Mark any remaining open as lost
+    for (const bid of this.openBids.values()) {
+      if (bid.status === 'open') {
+        bid.status = 'lost';
+        denied.push({
+          bidId: bid.id,
+          agentId: bid.agentId,
+          reason: 'Not selected in clearing round',
+        });
+      }
+    }
+
+    const result: MarketClearingResult = {
+      roundId,
+      awarded,
+      denied,
+      opportunityCostTotal,
+    };
+    this.history.push(result);
+    if (this.history.length > 100) this.history.splice(0, this.history.length - 100);
+
+    void this.events.emit(OrganismEventType.ORGANISM_MARKET_CLEARED, this.organismId, result);
+    return result;
+  }
+
+  /**
+   * Peer negotiation: transfer resources from one agent wallet to another
+   * when forecast justifies it and donor has balance.
+   */
+  negotiate(input: {
+    offer: NegotiationOffer;
+    from: RuntimeAgentRecord;
+    to: RuntimeAgentRecord;
+    record: OrganismRecord;
+  }): NegotiationResult {
+    const { offer, from, to, record } = input;
+    if (from.id === to.id) {
+      return { approved: false, reason: 'Cannot negotiate with self' };
+    }
+    if (from.status === 'terminated' || to.status === 'terminated') {
+      return { approved: false, reason: 'Agent not active' };
+    }
+
+    const tokens = offer.transfer.tokens ?? 0;
+    const money = offer.transfer.money ?? 0;
+    const fromTokens = from.wallet.tokensRemaining ?? 0;
+    const fromMoney = from.wallet.moneyRemaining?.amount ?? 0;
+
+    if (tokens > fromTokens || money > fromMoney) {
+      const result: NegotiationResult = {
+        approved: false,
+        reason: 'Donor insufficient resources',
+      };
+      void this.events.emit(OrganismEventType.ORGANISM_NEGOTIATION, this.organismId, {
+        ...offer,
+        ...result,
+      });
+      return result;
+    }
+
+    const forecast = this.forecaster.forecast({
+      agent: to,
+      record,
+      requested: offer.transfer,
+      expectedValue: offer.expectedValue ?? tokens * 0.001 + money * 2,
+      confidence: offer.confidence ?? 0.6,
+    });
+
+    if (forecast.netExpectedValue < this.config.minNetExpectedValue) {
+      const result: NegotiationResult = {
+        approved: false,
+        reason: `Forecast net value too low (${forecast.netExpectedValue.toFixed(2)})`,
+      };
+      void this.events.emit(OrganismEventType.ORGANISM_NEGOTIATION, this.organismId, {
+        ...offer,
+        ...result,
+        forecast,
+      });
+      return result;
+    }
+
+    const currency = from.wallet.moneyRemaining?.currency ?? record.pool.moneyRemaining.currency;
+
+    from.wallet = {
+      ...from.wallet,
+      tokensRemaining: fromTokens - tokens,
+      moneyRemaining: { amount: fromMoney - money, currency },
+    };
+    to.wallet = {
+      ...to.wallet,
+      tokensRemaining: (to.wallet.tokensRemaining ?? 0) + tokens,
+      moneyRemaining: {
+        amount: (to.wallet.moneyRemaining?.amount ?? 0) + money,
+        currency: to.wallet.moneyRemaining?.currency ?? currency,
+      },
+    };
+
+    const result: NegotiationResult = {
+      approved: true,
+      reason: 'Transfer approved',
+      transfer: offer.transfer,
+      fromWallet: from.wallet,
+      toWallet: to.wallet,
+    };
+    void this.events.emit(OrganismEventType.ORGANISM_NEGOTIATION, this.organismId, {
+      ...offer,
+      ...result,
+      forecast,
+    });
+    return result;
+  }
+
+  getHistory(limit = 20): MarketClearingResult[] {
+    return this.history.slice(-limit);
+  }
+
+  private expireBids(): void {
+    const now = this.now().getTime();
+    for (const bid of this.openBids.values()) {
+      if (bid.status === 'open' && bid.expiresAt && bid.expiresAt.getTime() < now) {
+        bid.status = 'expired';
+      }
+    }
+  }
+}
+
+export type { ResourceRequest, AgentResourceWallet };

package/src/economy/resource-allocator.ts

@@ -0,0 +1,188 @@
+import type {
+  AgentResourceWallet,
+  OrganismLimits,
+  OrganismRecord,
+  ResourceRequest,
+  RuntimeAgentRecord,
+} from '../types/organism.types';
+import { OrganismResourceDeniedError } from '../errors/organism.errors';
+import { OrganismEventEmitter, OrganismEventType } from '../events/organism-events';
+
+export interface AllocationRequest {
+  agentId: string;
+  requestedResources: ResourceRequest;
+  expectedUtility: number;
+  confidence: number;
+  urgency: number;
+  reputationScore?: number;
+  missionPriority?: number;
+}
+
+export interface AllocationResult {
+  approved: boolean;
+  wallet: AgentResourceWallet;
+  score: number;
+  reason: string;
+}
+
+/**
+ * Deterministic weighted resource allocator.
+ */
+export class ResourceAllocator {
+  private spawnTimestamps: number[] = [];
+
+  constructor(
+    private readonly events: OrganismEventEmitter,
+    private readonly organismId: string,
+    private readonly now: () => Date = () => new Date()
+  ) {}
+
+  score(request: AllocationRequest): number {
+    const utility = clamp(request.expectedUtility, 0, 1);
+    const confidence = clamp(request.confidence, 0, 1);
+    const urgency = clamp(request.urgency, 0, 1);
+    const reputation = clamp(request.reputationScore ?? 0.5, 0, 1);
+    const priority = clamp(request.missionPriority ?? 0.5, 0, 1);
+    return utility * 0.3 + confidence * 0.2 + urgency * 0.2 + reputation * 0.2 + priority * 0.1;
+  }
+
+  canSpawn(record: OrganismRecord, liveAgentCount: number): { ok: boolean; reason: string } {
+    if (record.emergencyStopped) {
+      return { ok: false, reason: 'Emergency stop active' };
+    }
+    if (record.status === 'paused' || record.status === 'terminated') {
+      return { ok: false, reason: `Organism is ${record.status}` };
+    }
+    if (liveAgentCount >= record.limits.maxAgents) {
+      return { ok: false, reason: `maxAgents (${record.limits.maxAgents}) reached` };
+    }
+    const now = this.now().getTime();
+    this.spawnTimestamps = this.spawnTimestamps.filter((t) => now - t < 60_000);
+    if (this.spawnTimestamps.length >= record.limits.maxSpawnRatePerMinute) {
+      return {
+        ok: false,
+        reason: `maxSpawnRatePerMinute (${record.limits.maxSpawnRatePerMinute}) exceeded`,
+      };
+    }
+    if (record.pool.costSpentThisHour >= record.limits.maxTotalCostPerHour) {
+      return {
+        ok: false,
+        reason: `maxTotalCostPerHour ($${record.limits.maxTotalCostPerHour}) exceeded`,
+      };
+    }
+    return { ok: true, reason: 'ok' };
+  }
+
+  recordSpawn(): void {
+    this.spawnTimestamps.push(this.now().getTime());
+  }
+
+  allocate(record: OrganismRecord, request: AllocationRequest): AllocationResult {
+    const score = this.score(request);
+    const tokens = request.requestedResources.tokens ?? 0;
+    const money = request.requestedResources.money ?? 0;
+
+    if (tokens > record.pool.tokensRemaining) {
+      const result: AllocationResult = {
+        approved: false,
+        wallet: {},
+        score,
+        reason: `Insufficient tokens (need ${tokens}, have ${record.pool.tokensRemaining})`,
+      };
+      void this.events.emit(OrganismEventType.ORGANISM_RESOURCE_DENIED, this.organismId, {
+        agentId: request.agentId,
+        ...result,
+      });
+      return result;
+    }
+
+    if (money > record.pool.moneyRemaining.amount) {
+      const result: AllocationResult = {
+        approved: false,
+        wallet: {},
+        score,
+        reason: `Insufficient money (need ${money}, have ${record.pool.moneyRemaining.amount})`,
+      };
+      void this.events.emit(OrganismEventType.ORGANISM_RESOURCE_DENIED, this.organismId, {
+        agentId: request.agentId,
+        ...result,
+      });
+      return result;
+    }
+
+    if (score < 0.15 && (tokens > 0 || money > 0)) {
+      const result: AllocationResult = {
+        approved: false,
+        wallet: {},
+        score,
+        reason: `Allocation score too low (${score.toFixed(3)})`,
+      };
+      void this.events.emit(OrganismEventType.ORGANISM_RESOURCE_DENIED, this.organismId, {
+        agentId: request.agentId,
+        ...result,
+      });
+      return result;
+    }
+
+    record.pool.tokensRemaining -= tokens;
+    record.pool.moneyRemaining.amount -= money;
+
+    const wallet: AgentResourceWallet = {
+      tokensRemaining: tokens || undefined,
+      moneyRemaining:
+        money > 0 ? { amount: money, currency: record.pool.moneyRemaining.currency } : undefined,
+      computeUnitsRemaining: request.requestedResources.computeUnits,
+      toolCallsRemaining: request.requestedResources.toolCalls,
+    };
+
+    const result: AllocationResult = {
+      approved: true,
+      wallet,
+      score,
+      reason: 'Allocated',
+    };
+    void this.events.emit(OrganismEventType.ORGANISM_RESOURCE_ALLOCATED, this.organismId, {
+      agentId: request.agentId,
+      wallet,
+      score,
+    });
+    return result;
+  }
+
+  release(record: OrganismRecord, agent: RuntimeAgentRecord): void {
+    const tokens = agent.wallet.tokensRemaining ?? 0;
+    const money = agent.wallet.moneyRemaining?.amount ?? 0;
+    record.pool.tokensRemaining += tokens;
+    record.pool.moneyRemaining.amount += money;
+    agent.wallet = {
+      tokensRemaining: 0,
+      moneyRemaining: {
+        amount: 0,
+        currency: record.pool.moneyRemaining.currency,
+      },
+    };
+  }
+
+  assertWithinLimits(_limits: OrganismLimits): void {
+    // reserved for future hard asserts
+  }
+}
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, n));
+}
+
+export function createEmptyWallet(): AgentResourceWallet {
+  return {
+    tokensRemaining: 0,
+    moneyRemaining: { amount: 0, currency: 'USD' },
+    computeUnitsRemaining: 0,
+    toolCallsRemaining: 0,
+  };
+}
+
+export function throwIfDenied(result: AllocationResult): void {
+  if (!result.approved) {
+    throw new OrganismResourceDeniedError(result.reason);
+  }
+}