@hazeljs/organism 2.0.6

package/src/lifecycle/survival-engine.ts

@@ -0,0 +1,95 @@
+import type { RuntimeAgentRecord, SurvivalConfig, SurvivalState } from '../types/organism.types';
+import { DEFAULT_SURVIVAL_CONFIG } from '../types/organism.types';
+
+export interface SurvivalVerdict {
+  agentId: string;
+  state: SurvivalState;
+  reason: string;
+  shouldTerminate: boolean;
+}
+
+/**
+ * Survival engine — never kill on a single poor outcome.
+ */
+export class SurvivalEngine {
+  constructor(
+    private readonly config: SurvivalConfig = DEFAULT_SURVIVAL_CONFIG,
+    private readonly now: () => Date = () => new Date()
+  ) {}
+
+  evaluate(agent: RuntimeAgentRecord): SurvivalVerdict {
+    if (agent.status === 'terminated') {
+      return {
+        agentId: agent.id,
+        state: 'terminated',
+        reason: 'Already terminated',
+        shouldTerminate: false,
+      };
+    }
+
+    if (agent.criticalResponsibility) {
+      return {
+        agentId: agent.id,
+        state: 'healthy',
+        reason: 'Critical responsibility protected',
+        shouldTerminate: false,
+      };
+    }
+
+    const ageMs = this.now().getTime() - agent.createdAt.getTime();
+    if (ageMs < this.config.minimumEvaluationAgeMs) {
+      return {
+        agentId: agent.id,
+        state: 'healthy',
+        reason: `Too young to evaluate (${ageMs}ms < ${this.config.minimumEvaluationAgeMs}ms)`,
+        shouldTerminate: false,
+      };
+    }
+
+    if (agent.evaluationCount < this.config.minimumSampleSize) {
+      return {
+        agentId: agent.id,
+        state: 'watch',
+        reason: `Insufficient samples (${agent.evaluationCount} < ${this.config.minimumSampleSize})`,
+        shouldTerminate: false,
+      };
+    }
+
+    if (agent.lastEvaluatedAt) {
+      const since = this.now().getTime() - agent.lastEvaluatedAt.getTime();
+      if (since < this.config.cooldownMs && agent.utility.score >= this.config.minimumUtility) {
+        return {
+          agentId: agent.id,
+          state: 'healthy',
+          reason: 'Within cooldown',
+          shouldTerminate: false,
+        };
+      }
+    }
+
+    if (agent.utility.score < this.config.minimumUtility) {
+      return {
+        agentId: agent.id,
+        state: 'candidate-for-termination',
+        reason: `Utility ${agent.utility.score.toFixed(3)} below minimum ${this.config.minimumUtility}`,
+        shouldTerminate: true,
+      };
+    }
+
+    if (agent.utility.score < this.config.minimumUtility + 0.15) {
+      return {
+        agentId: agent.id,
+        state: 'watch',
+        reason: 'Utility near threshold',
+        shouldTerminate: false,
+      };
+    }
+
+    return {
+      agentId: agent.id,
+      state: 'healthy',
+      reason: 'Utility healthy',
+      shouldTerminate: false,
+    };
+  }
+}

package/src/observability/metrics.ts

@@ -0,0 +1,120 @@
+/**
+ * Optional OpenTelemetry-compatible metrics for organism runtime.
+ */
+
+export interface OrganismMetricsSnapshot {
+  activeAgents: number;
+  agentsSpawnedTotal: number;
+  agentsTerminatedTotal: number;
+  reproductionsTotal: number;
+  mutationsTotal: number;
+  tokenUsage: number;
+  cost: number;
+  missionProgress: number;
+  constitutionViolations: number;
+}
+
+export class OrganismMetrics {
+  private spawned = 0;
+  private terminated = 0;
+  private reproductions = 0;
+  private mutations = 0;
+  private tokens = 0;
+  private cost = 0;
+  private violations = 0;
+  private active = 0;
+  private missionProgress = 0;
+
+  recordSpawn(): void {
+    this.spawned += 1;
+    this.active += 1;
+  }
+
+  recordReproduction(): void {
+    this.reproductions += 1;
+    this.spawned += 1;
+    this.active += 1;
+  }
+
+  recordMutation(): void {
+    this.mutations += 1;
+  }
+
+  recordTermination(): void {
+    this.terminated += 1;
+    this.active = Math.max(0, this.active - 1);
+  }
+
+  recordTokens(n: number): void {
+    this.tokens += n;
+  }
+
+  recordCost(n: number): void {
+    this.cost += n;
+  }
+
+  recordViolation(): void {
+    this.violations += 1;
+  }
+
+  setMissionProgress(ratio: number): void {
+    this.missionProgress = ratio;
+  }
+
+  snapshot(): OrganismMetricsSnapshot {
+    return {
+      activeAgents: this.active,
+      agentsSpawnedTotal: this.spawned,
+      agentsTerminatedTotal: this.terminated,
+      reproductionsTotal: this.reproductions,
+      mutationsTotal: this.mutations,
+      tokenUsage: this.tokens,
+      cost: this.cost,
+      missionProgress: this.missionProgress,
+      constitutionViolations: this.violations,
+    };
+  }
+
+  /** Soft-bind to OpenTelemetry if available. */
+  exportToOtel(meterName = 'hazel.organism'): void {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const otel = require('@opentelemetry/api') as {
+        metrics?: {
+          getMeter: (name: string) => {
+            createObservableGauge: (
+              name: string,
+              opts: { description: string },
+              cb: (obs: { observe: (v: number) => void }) => void
+            ) => void;
+          };
+        };
+      };
+      const meter = otel.metrics?.getMeter(meterName);
+      if (!meter) return;
+      const snap = (): OrganismMetricsSnapshot => this.snapshot();
+      meter.createObservableGauge(
+        'hazel.organism.active_agents',
+        { description: 'Active organism agents' },
+        (obs) => obs.observe(snap().activeAgents)
+      );
+      meter.createObservableGauge(
+        'hazel.organism.agents_spawned_total',
+        { description: 'Total agents spawned' },
+        (obs) => obs.observe(snap().agentsSpawnedTotal)
+      );
+      meter.createObservableGauge(
+        'hazel.organism.token_usage',
+        { description: 'Organism token usage' },
+        (obs) => obs.observe(snap().tokenUsage)
+      );
+      meter.createObservableGauge(
+        'hazel.organism.mission_progress',
+        { description: 'Mission progress ratio' },
+        (obs) => obs.observe(snap().missionProgress)
+      );
+    } catch {
+      // optional peer
+    }
+  }
+}

package/src/perception/perception-engine.ts

@@ -0,0 +1,140 @@
+import type {
+  DetectedNeed,
+  EnvironmentSignal,
+  MissionDefinition,
+  SignalNeedMapping,
+} from '../types/organism.types';
+
+export interface PerceptionResult {
+  accepted: boolean;
+  signal: EnvironmentSignal;
+  reason: string;
+}
+
+/**
+ * Normalize + relevance-filter environment signals.
+ */
+export class PerceptionEngine {
+  constructor(
+    private readonly relevanceThreshold = 0.3,
+    private readonly severityThreshold = 0.2
+  ) {}
+
+  normalize(
+    raw: Partial<EnvironmentSignal> & Pick<EnvironmentSignal, 'type' | 'source'>
+  ): EnvironmentSignal {
+    return {
+      id: raw.id ?? `sig_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      type: raw.type,
+      source: raw.source,
+      timestamp: raw.timestamp ?? new Date(),
+      data: raw.data ?? {},
+      severity: raw.severity,
+      relevance: raw.relevance,
+    };
+  }
+
+  filter(signal: EnvironmentSignal, mission: MissionDefinition): PerceptionResult {
+    const relevance = signal.relevance ?? this.inferRelevance(signal, mission);
+    const severity = signal.severity ?? 0.5;
+    const accepted = relevance >= this.relevanceThreshold || severity >= this.severityThreshold;
+    return {
+      accepted,
+      signal: { ...signal, relevance, severity },
+      reason: accepted
+        ? `Accepted (relevance=${relevance.toFixed(2)}, severity=${severity.toFixed(2)})`
+        : `Ignored (relevance=${relevance.toFixed(2)}, severity=${severity.toFixed(2)})`,
+    };
+  }
+
+  private inferRelevance(signal: EnvironmentSignal, mission: MissionDefinition): number {
+    const text = `${mission.objective} ${(mission.constraints ?? []).join(' ')}`.toLowerCase();
+    const typeParts = signal.type.toLowerCase().split(/[._-]/);
+    let hits = 0;
+    for (const part of typeParts) {
+      if (part.length > 2 && text.includes(part)) hits += 1;
+    }
+    if (hits === 0) return 0.4;
+    return Math.min(1, 0.5 + hits * 0.15);
+  }
+}
+
+/**
+ * Deterministic need detector using configurable signal→need mappings.
+ *
+ * Domain-specific capability routing belongs in `signalNeedMappings`
+ * (e.g. ecommerce refund → analytics). The unmapped fallback only
+ * treats generic anomaly suffixes as needs and derives capability
+ * hints from the signal type subject tokens — never from a fixed
+ * industry vocabulary.
+ */
+export class NeedDetector {
+  /** Tokens that describe change/anomaly, not a capability subject. */
+  private static readonly ANOMALY_TOKENS = new Set([
+    'increased',
+    'decreased',
+    'spike',
+    'drop',
+    'failure',
+    'failed',
+    'shortage',
+    'delay',
+    'delayed',
+    'rate',
+    'volume',
+    'high',
+    'low',
+  ]);
+
+  constructor(private readonly mappings: SignalNeedMapping[] = []) {}
+
+  detect(signal: EnvironmentSignal, _mission: MissionDefinition): DetectedNeed | undefined {
+    const mapping = this.mappings.find((m) => m.signalType === signal.type);
+    if (!mapping) {
+      if (!this.looksLikeAnomaly(signal.type)) {
+        return undefined;
+      }
+      const need = signal.type.replace(/\./g, '-');
+      return {
+        need,
+        reason: `Signal ${signal.type} indicates intervention may be required`,
+        requiredCapabilities: this.capabilitiesFromSignalType(signal.type),
+        urgency: signal.severity ?? 0.7,
+        confidence: 0.6,
+        signalId: signal.id,
+      };
+    }
+
+    const data = signal.data as { baseline?: number; current?: number } | undefined;
+    let reason = `Signal ${signal.type} mapped to need ${mapping.need}`;
+    if (data?.baseline != null && data?.current != null) {
+      reason = `${mapping.need}: ${signal.type} from ${data.baseline} to ${data.current}`;
+    }
+
+    return {
+      need: mapping.need,
+      reason,
+      requiredCapabilities: [...mapping.requiredCapabilities],
+      urgency: mapping.urgency ?? signal.severity ?? 0.7,
+      confidence: mapping.confidence ?? 0.9,
+      signalId: signal.id,
+    };
+  }
+
+  private looksLikeAnomaly(signalType: string): boolean {
+    return /(increased|decreased|spike|drop|failure|shortage|delay)/i.test(signalType);
+  }
+
+  /**
+   * Derive capability hints from signal type subjects.
+   * e.g. `orders.fulfillment.delay` → `['orders', 'fulfillment']`
+   */
+  private capabilitiesFromSignalType(signalType: string): string[] {
+    const parts = signalType
+      .toLowerCase()
+      .split(/[._-]/)
+      .filter((p) => p.length > 1 && !NeedDetector.ANOMALY_TOKENS.has(p));
+    if (parts.length === 0) return ['general'];
+    return Array.from(new Set(parts));
+  }
+}

package/src/persistence/in-memory-organism-repository.ts

@@ -0,0 +1 @@
+export * from './organism-repository';

package/src/persistence/organism-repository.ts

@@ -0,0 +1,134 @@
+/**
+ * Persistence abstractions for organism state.
+ */
+
+import type {
+  AgentGenealogy,
+  EnvironmentSignal,
+  OrganismDecision,
+  OrganismRecord,
+  RuntimeAgentRecord,
+} from '../types/organism.types';
+
+export interface OrganismRepository {
+  saveOrganism(record: OrganismRecord): Promise<void>;
+  getOrganism(id: string): Promise<OrganismRecord | undefined>;
+  listOrganisms(): Promise<OrganismRecord[]>;
+  deleteOrganism(id: string): Promise<boolean>;
+
+  saveAgent(organismId: string, agent: RuntimeAgentRecord): Promise<void>;
+  getAgent(organismId: string, agentId: string): Promise<RuntimeAgentRecord | undefined>;
+  listAgents(organismId: string): Promise<RuntimeAgentRecord[]>;
+  deleteAgent(organismId: string, agentId: string): Promise<boolean>;
+
+  saveGenealogy(organismId: string, genealogy: AgentGenealogy): Promise<void>;
+  listGenealogy(organismId: string): Promise<AgentGenealogy[]>;
+
+  appendSignal(organismId: string, signal: EnvironmentSignal): Promise<void>;
+  listSignals(organismId: string, limit?: number): Promise<EnvironmentSignal[]>;
+
+  appendDecision(organismId: string, decision: OrganismDecision): Promise<void>;
+  listDecisions(organismId: string, limit?: number): Promise<OrganismDecision[]>;
+}
+
+export class InMemoryOrganismRepository implements OrganismRepository {
+  private organisms = new Map<string, OrganismRecord>();
+  private agents = new Map<string, Map<string, RuntimeAgentRecord>>();
+  private genealogy = new Map<string, Map<string, AgentGenealogy>>();
+  private signals = new Map<string, EnvironmentSignal[]>();
+  private decisions = new Map<string, OrganismDecision[]>();
+
+  async saveOrganism(record: OrganismRecord): Promise<void> {
+    this.organisms.set(record.id, { ...record, updatedAt: new Date() });
+    if (!this.agents.has(record.id)) this.agents.set(record.id, new Map());
+    if (!this.genealogy.has(record.id)) this.genealogy.set(record.id, new Map());
+    if (!this.signals.has(record.id)) this.signals.set(record.id, []);
+    if (!this.decisions.has(record.id)) this.decisions.set(record.id, []);
+  }
+
+  async getOrganism(id: string): Promise<OrganismRecord | undefined> {
+    const record = this.organisms.get(id);
+    return record ? { ...record } : undefined;
+  }
+
+  async listOrganisms(): Promise<OrganismRecord[]> {
+    return Array.from(this.organisms.values()).map((r) => ({ ...r }));
+  }
+
+  async deleteOrganism(id: string): Promise<boolean> {
+    this.agents.delete(id);
+    this.genealogy.delete(id);
+    this.signals.delete(id);
+    this.decisions.delete(id);
+    return this.organisms.delete(id);
+  }
+
+  async saveAgent(organismId: string, agent: RuntimeAgentRecord): Promise<void> {
+    let map = this.agents.get(organismId);
+    if (!map) {
+      map = new Map();
+      this.agents.set(organismId, map);
+    }
+    map.set(agent.id, { ...agent });
+  }
+
+  async getAgent(organismId: string, agentId: string): Promise<RuntimeAgentRecord | undefined> {
+    const agent = this.agents.get(organismId)?.get(agentId);
+    return agent ? { ...agent } : undefined;
+  }
+
+  async listAgents(organismId: string): Promise<RuntimeAgentRecord[]> {
+    const map = this.agents.get(organismId);
+    if (!map) return [];
+    return Array.from(map.values()).map((a) => ({ ...a }));
+  }
+
+  async deleteAgent(organismId: string, agentId: string): Promise<boolean> {
+    return this.agents.get(organismId)?.delete(agentId) ?? false;
+  }
+
+  async saveGenealogy(organismId: string, genealogy: AgentGenealogy): Promise<void> {
+    let map = this.genealogy.get(organismId);
+    if (!map) {
+      map = new Map();
+      this.genealogy.set(organismId, map);
+    }
+    map.set(genealogy.agentId, {
+      ...genealogy,
+      children: [...genealogy.children],
+    });
+  }
+
+  async listGenealogy(organismId: string): Promise<AgentGenealogy[]> {
+    const map = this.genealogy.get(organismId);
+    if (!map) return [];
+    return Array.from(map.values()).map((g) => ({
+      ...g,
+      children: [...g.children],
+    }));
+  }
+
+  async appendSignal(organismId: string, signal: EnvironmentSignal): Promise<void> {
+    const list = this.signals.get(organismId) ?? [];
+    list.push({ ...signal });
+    if (list.length > 200) list.splice(0, list.length - 200);
+    this.signals.set(organismId, list);
+  }
+
+  async listSignals(organismId: string, limit = 50): Promise<EnvironmentSignal[]> {
+    const list = this.signals.get(organismId) ?? [];
+    return list.slice(-limit).map((s) => ({ ...s }));
+  }
+
+  async appendDecision(organismId: string, decision: OrganismDecision): Promise<void> {
+    const list = this.decisions.get(organismId) ?? [];
+    list.push({ ...decision });
+    if (list.length > 200) list.splice(0, list.length - 200);
+    this.decisions.set(organismId, list);
+  }
+
+  async listDecisions(organismId: string, limit = 50): Promise<OrganismDecision[]> {
+    const list = this.decisions.get(organismId) ?? [];
+    return list.slice(-limit).map((d) => ({ ...d }));
+  }
+}