1 // Package organ manages WASM modules that the organism can compile,
2 // load, evaluate, share, and hot-swap at runtime.
3 //
4 // Each organ is a TinyGo-compiled WASM module loaded via wazero.
5 // Organs specialize in a task: digestion (enzyme), emission (emitter),
6 // evaluation (evaluator), self-governance (governor), or compilation
7 // (compiler). The host process loads organs into a Registry, calls them
8 // through a uniform byte-oriented interface, and destroys them when
9 // they are superseded or fail fitness.
10 //
11 // Organs supplement but never replace host-side Go code. The host
12 // implementation is always available as a fallback.
13 package organ
14 15 import (
16 "crypto/sha256"
17 "encoding/hex"
18 "sync/atomic"
19 "time"
20 21 "git.mleku.dev/mleku/dendrite/pkg/ratio"
22 )
23 24 // OrganType classifies what role an organ fills.
25 type OrganType string
26 27 const (
28 TypeEnzyme OrganType = "enzyme"
29 TypeEmitter OrganType = "emitter"
30 TypeEvaluator OrganType = "evaluator"
31 TypeGovernor OrganType = "governor"
32 TypeCompiler OrganType = "compiler"
33 )
34 35 // OrganID is a content-addressable identifier: sha256 of the .wasm bytes.
36 type OrganID [32]byte
37 38 // ComputeID returns the OrganID for the given WASM bytes.
39 func ComputeID(wasmBytes []byte) OrganID {
40 return sha256.Sum256(wasmBytes)
41 }
42 43 // String returns the hex-encoded ID (first 16 chars for readability).
44 func (id OrganID) String() string {
45 return hex.EncodeToString(id[:8])
46 }
47 48 // Manifest describes a compiled organ for exchange and evaluation.
49 // It is serializable and can travel between instances.
50 type Manifest struct {
51 ID OrganID `json:"id"`
52 Type OrganType `json:"type"`
53 Version uint64 `json:"version"`
54 Size int `json:"size"` // .wasm byte count
55 Hash uint64 `json:"hash"` // organ_hash() from the module
56 SourceGen int `json:"source_gen"` // generation that produced this organ
57 SourceID uint32 `json:"source_id"` // instance ID that compiled it
58 Fitness ratio.Ratio `json:"fitness"` // evaluated fitness at source
59 }
60 61 // OrganStatus tracks the lifecycle of a loaded organ.
62 type OrganStatus int
63 64 const (
65 StatusPending OrganStatus = iota // received, not yet evaluated
66 StatusLoaded // instantiated and callable
67 StatusFailed // failed fitness or runtime error
68 StatusEvicted // dissolved — module closed
69 )
70 71 // Organ is a loaded WASM module with its runtime state.
72 type Organ struct {
73 Manifest Manifest
74 WasmBytes []byte // raw module bytes for sharing
75 Status OrganStatus
76 Loaded time.Time
77 CallCount atomic.Uint64
78 LastCall time.Time
79 }
80 81 // Opcodes are the operation codes prepended to input bytes when
82 // calling an organ's process function.
83 const (
84 // Enzyme opcodes.
85 OpCanDigest byte = 0x01
86 OpDigest byte = 0x02
87 88 // Emitter opcodes.
89 OpEmit byte = 0x01
90 91 // Evaluator opcodes.
92 OpEvaluate byte = 0x01
93 94 // Governor opcodes.
95 OpDerive byte = 0x01
96 OpTable byte = 0x02
97 98 // Compiler opcodes.
99 OpCompile byte = 0x01
100 )
101