1. Scopo e confini

Un neurone è la materializzazione di una capacità che myclaw non aveva e che ha sintetizzato al bisogno. Questo documento definisce la sua anatomia: come è fatto, come vive, come è firmato. La pipeline di sintesi è in synthesizer.html; il grafo dei rapporti fra neuroni è in synapse.html.

Cosa copre

• Layout filesystem di un neurone.
• Schema del manifest YAML (campi obbligatori, vincoli).
• Firma HMAC: chiave, algoritmo, cosa è coperto.
• Il journal locale (counter d'uso, esiti, errori).
• Stati di vita: neonato, attivo, dormiente, quarantena, estinto.

Cosa non copre

• Il processo che sceglie quando creare un neurone → synthesizer.
• Il calcolo della fitness darwiniana → synapse.
• La sandbox che esegue corpo & test → sandbox.
• Il policy check sulle capability → policy.

2. Anatomia su disco

Ogni neurone vive in una directory dedicata sotto workspace/neurons/<nome>/. La directory è self-contained: corpo, manifest, test, firma e journal stanno insieme. Per spostare o archiviare un neurone basta spostare la sua directory.

workspace/neurons/log-parser/
├── manifest.yaml           # schema dichiarativo (capability, quote, sinapsi)
├── body.py                 # il codice Python: funzione run(...)
├── test_birth.py           # test di nascita (deve passare in sandbox)
├── signature.hmac          # HMAC-SHA256 su manifest+body
├── journal.sqlite          # counter, esiti, sinapsi osservate
└── README.md               # opzionale: dettagli generati dal synthesizer

3. Schema del manifest

# workspace/neurons/log-parser/manifest.yaml
name: log-parser                    # ^[a-z][a-z0-9_-]{2,31}$, univoco
version: 1.4.0                      # semver
created_at: 2026-04-22T21:11:00+02:00
created_by: synthesizer@myclaw      # o "manual" se scritto a mano
parent_trace: 7c3f...d21            # trace_id che ha innescato la sintesi

purpose: |
  Estrae errori e warning da log strutturati in JSONL,
  raggruppa per servizio e ritorna un riassunto.

# --- contratto di invocazione ---
entry: body:run                     # modulo:funzione
input_schema:                       # JSON Schema subset
  type: object
  required: [path]
  properties:
    path: { type: string, format: "local-readable-path" }
    since: { type: string, format: "date-time" }
output_schema:
  type: object
  required: [by_service]
  properties:
    by_service: { type: object }

# --- capability richieste (match esatto con policy.html §4) ---
capabilities:
  - fs-read:~/logs
  - fs-read:~/downloads/logs
  # no network, no shell, no fs-write

# --- quote al runtime ---
quotas:
  wall_time_s: 20
  cpu_time_s: 10
  ram_mb: 256
  max_stdout_kb: 512
  max_invocations_per_hour: 60

# --- sinapsi dichiarate (vincolo massimo; vedi synapse.html) ---
may_call:
  - summarizer          # può chiedere un riassunto LLM
  - fs-read             # tool base

# --- metadati per retrieval ---
tags: [log, observability, parsing]
embeddings_version: supra-embed-v1  # per invalidare l'index se cambia il modello

Campi obbligatori

4. Il corpo: Protocol Tool

Il corpo di un neurone implementa lo stesso Protocol Python dei tool nativi (tool.html §3). Non c'è distinzione a livello di runtime: un neurone è un tool che vive nel filesystem invece che in src/myclaw/tools/.

# workspace/neurons/log-parser/body.py
from myclaw.runtime import NeuronContext, ToolResult

async def run(ctx: NeuronContext, path: str, since: str | None = None) -> ToolResult:
    # ctx espone: ctx.open(path, "r"), ctx.call("summarizer", ...),
    # ctx.log, ctx.quota_remaining(). Niente import di sistema diretti.
    data = {}
    async with ctx.open(path, "r") as f:
        async for line in f:
            rec = ctx.json_loads(line)
            if since and rec["ts"] < since: continue
            if rec.get("level") in ("ERROR", "WARN"):
                data.setdefault(rec["service"], []).append(rec)
    return ToolResult(ok=True, value={"by_service": data})

Regole di scrittura

• Solo import dalla stdlib o dal namespace myclaw.runtime. Qualsiasi altro import fa fallire l'analisi statica.
• Nessun accesso diretto a os, subprocess, socket. L'I/O passa da ctx.
• Funzione run sempre async, firma tipata.
• Nessuno stato globale mutabile. Variabili di modulo sono costanti.

5. Firma HMAC e ciclo di fiducia

Algoritmo

payload = manifest.yaml_bytes + b"\n---\n"
        + body.py_bytes      + b"\n---\n"
        + test_birth.py_bytes

signature = HMAC-SHA256(key=neuron_signing_key, msg=payload)

# scritto come hex in signature.hmac, una sola riga, trailing newline.

Chiave di firma

• File: ~/.config/myclaw/neuron.key, 32 byte random, mode 0600.
• Generata al primo myclaw init. Mai versionata, mai esportata.
• Rotazione: comando dedicato myclaw neuron rotate-key → rifirma tutti i neuroni attivi dopo richiesta di approvazione singola (batch).

Verifica ad ogni load

1. All'avvio del gateway — e ad ogni caricamento a caldo — il loader ricalcola l'HMAC.
2. Mismatch → neurone NON caricato, stato quarantena, evento audit neuron.signature.invalid.
3. Match → neurone disponibile, stato attivo (o quello precedente).

6. Journal: counter, esiti, sinapsi osservate

Il journal è uno SQLite per neurone. Tenere i diari separati evita contention e permette di spostare/archiviare una directory senza toccare un DB centrale. Il grafo globale — unione dei journal — è costruito dal componente synapse a partire da queste sorgenti.

-- workspace/neurons/<nome>/journal.sqlite

CREATE TABLE invocations (
    invocation_id TEXT PRIMARY KEY,
    trace_id      TEXT NOT NULL,
    started_at    DATETIME NOT NULL,
    duration_ms   INTEGER NOT NULL,
    outcome       TEXT NOT NULL,   -- success | error | timeout | quota_exceeded
    error_class   TEXT,
    input_hash    TEXT,            -- sha256 input normalizzato (privacy)
    goal_hash     TEXT,            -- sha256 dello scopo corrente (per Gap)
    gap_pre       REAL,            -- riempito dal caller
    gap_post      REAL,
    cost_cents    REAL DEFAULT 0.0
);

CREATE TABLE co_activations (
    trace_id   TEXT NOT NULL,
    peer_name  TEXT NOT NULL,      -- neurone chiamato nella stessa trace
    direction  TEXT NOT NULL,      -- 'calls' | 'called_by'
    observed_at DATETIME NOT NULL
);

CREATE INDEX idx_inv_time ON invocations(started_at DESC);
CREATE INDEX idx_coact_peer ON co_activations(peer_name, observed_at);

L'utilità di una singola invocazione (vedi synapse §3) è u = gap_pre - gap_post; il journal non pre-aggrega per non congelare la formula.

7. Stati di vita

8. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class NeuronManifest:
    name: str
    version: str
    purpose: str
    entry: str                     # "body:run"
    input_schema: dict
    output_schema: dict
    capabilities: list[str]
    quotas: dict
    may_call: list[str]
    tags: list[str]
    created_at: datetime
    parent_trace: str | None

NeuronState = Literal["neonato", "attivo", "dormiente", "quarantena", "estinto"]

@dataclass
class NeuronHandle:
    manifest: NeuronManifest
    path: str                      # workspace/neurons/<nome>/
    state: NeuronState
    signature_ok: bool
    last_invocation: datetime | None

class NeuronLoader(Protocol):
    async def load_all(self) -> list[NeuronHandle]: ...

    async def reload(self, name: str) -> NeuronHandle: ...

    async def verify(self, name: str) -> bool:
        """Ricalcola HMAC, confronta con signature.hmac, aggiorna stato."""
        ...

    async def invoke(
        self,
        name: str,
        ctx: "NeuronContext",
        **kwargs,
    ) -> "ToolResult":
        """Valida input, esegue in sandbox, registra nel journal. Solleva
        SignatureError, QuotaExceededError, UndeclaredSynapseError, ..."""
        ...

    async def set_state(self, name: str, state: NeuronState, reason: str) -> None: ...

# Errori sollevabili dal loader
class SignatureError(Exception): ...
class UndeclaredSynapseError(Exception): ...
class QuotaExceededError(Exception): ...
class NeuronNotFoundError(Exception): ...
class InputSchemaError(Exception): ...
class OutputSchemaError(Exception): ...

9. Implementazione di default

10. Alternative considerate

11. Test di conformità

12. Riferimenti

Continua a leggere

myclaw — neuron microprogettazione v1.0 — 2026-04-22
Primo doc dell'estensione neuroni. Prossimo: synthesizer.html.