1. Scopo e confini

types è l'unico doc che elenca in modo autorevole tutti i tipi dati che attraversano più di un componente di myclaw. Non li ridefinisce: li indicizza. Ogni tipo ha un solo doc-proprietario; qui si traccia chi lo definisce, chi lo consuma, e le regole per evitare drift.

Cos'è

• L'indice canonico di tutti i tipi cross-componente.
• La sede di definizione dei due tipi che non hanno un owner naturale: PlannedAction (bridge policy↔constitution) e TrustScore (autonomia adattiva).
• La disciplina di versioning: chi può rompere uno schema, quando, e con quale annuncio.
• Il test di drift: garanzia automatica che nessun doc ridefinisca un tipo posseduto da un altro.

Cosa non è

• Non è un modulo Python (esisterà src/myclaw/types/, ma questo doc descrive il contratto, non il package).
• Non contiene primitive di dominio usate da un solo componente (es. BudgetLedger sta in policy, SessionToken sta in gateway).
• Non duplica la documentazione di dettaglio: per capire perché un campo esiste, leggi il doc-proprietario.

2. Principio: definizione unica, replica proibita

La revisione incrociata dei 17 doc di fase 0 ha mostrato che gli stessi tipi (ExecutionTrace, ApprovalRequest, ViolationReport, …) erano usati da 3-6 componenti ciascuno, ma definiti — o peggio, redefiniti in piccolo — in doc diversi. Prima di scrivere una riga di codice, fissiamo una regola:

Perché non un modulo Python con tutti i tipi? Perché creerebbe un cerchio: agent_runtime importa da types, types importa da constitution per ViolationReport, e così via. Preferiamo il pattern "owner doc → package di componente": ogni tipo vive nel package del suo componente (src/myclaw/constitution/types.py, src/myclaw/approval/types.py), e src/myclaw/types/__init__.py li re-esporta per scrittura ergonomica (from myclaw.types import ExecutionTrace, ApprovalRequest). Zero dipendenze circolari, unica sorgente di verità.

3. Mappa dei tipi condivisi

La tabella sottostante è l'anagrafe canonica dei tipi cross-componente di myclaw. Ogni riga è la coppia <tipo, owner>. Modifiche al tipo richiedono edit del solo owner-doc e allineamento di questa tabella.

4. Tipi trasversali nuovi

Due tipi non hanno un owner naturale: attraversano più componenti senza appartenere a nessuno in particolare. Vivono qui.

4.1 PlannedAction — bridge policy ↔ constitution

constitution.html §10 dichiara Constitution.check(action: PlannedAction) ma non definisce mai PlannedAction. È una lacuna della revisione incrociata (gap semantico B2). Il tipo serve come richiesta strutturata che la policy sottopone alla constitution prima di decidere il verdetto.

from dataclasses import dataclass
from datetime import datetime
from typing import Literal
from uuid import UUID

EffectKind = Literal[
    "fs_read", "fs_write", "fs_delete",
    "shell_exec", "network_out", "network_in",
    "memory_write", "memory_delete",
    "neuron_spawn", "neuron_invoke", "neuron_promote",
    "outbound_message",          # verso utente / terzi
    "cost_spend",                # LLM / API
    "config_change", "self_modify",
]

@dataclass(frozen=True)
class PlannedAction:
    """
    Descrizione canonica di un'azione che sta per avvenire.
    Passata a Constitution.check() dalla Policy.evaluate().
    Immutable: riflette l'intento registrato, non l'esito.
    """
    kind: EffectKind
    tool_name: str                # tool richiesto (anche "neuron:<name>")
    args_digest: str              # SHA-256 dei parametri (no PII in log)
    args_preview: dict            # versione redatta per UI/prompt
    sender: str                   # "cli:roberto" | "telegram:@roberto" | "cron:..."
    trace_id: UUID
    session_id: str
    autonomy: Literal["read_only", "supervised", "full"]
    targets: list[str]            # path, URL, neuron name — quel che viene toccato
    reversibility: Literal["reversible", "reversible_with_cost", "irreversible"]
    est_cost_eur: float           # 0 se non applicabile
    planned_at: datetime

Perché qui e non in constitution? Perché è costruita dalla policy, letta dalla constitution, persistita dall'observability, e serializzata nella trace. Nessun owner unico naturale. Centralizzandola in types evitiamo dipendenze circolari fra policy e constitution.

Relazione con ApprovalRequestDraft

gateway.html §4.1 introduce ApprovalRequestDraft come output della Policy. I due tipi non sono sinonimi: hanno ruoli distinti e qui li fissiamo canonicamente.

@dataclass(frozen=True)
class ApprovalRequestDraft:
    """
    Restituito dalla Policy quando il verdetto è 'approve_required'.
    È un PlannedAction arricchito di ciò che la Policy ha deciso ma che non
    sa ancora rendere in UI: il Gateway lo completa con canale, sender, timeout
    per produrre una ApprovalRequest finale.
    """
    action: PlannedAction           # riferimento immutabile all'intento
    effect_class: str               # es. "fs_write:workspace"
    summary: str                    # linea leggibile per l'utente
    risk: Literal["low", "medium", "high"]
    policy_reasons: list[str]       # perché richiesta (per explain-mode)

Regola: la Policy NON costruisce ApprovalRequest. Emette solo il Draft. Il Gateway è l'unico che crea la request finale (vedi gateway.html §4.1, decisione "owner unico del flusso"). Questo risolve l'incongruenza §3.3 della review di coerenza.

4.2 TrustScore — asse di autonomia adattiva

La revisione cross-doc ha convergiato su un principio: ridurre il carico di approvazione umana senza perdere sicurezza richiede un'autonomia trust-weighted. Ogni coppia (neurone, effect_class) accumula uno score calcolato da trace storiche; la policy usa lo score per promuovere dinamicamente approve_required → allow sotto soglia di rischio. Nessun training, solo aggregazione.

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

TrustSubject = tuple[str, str]  # (neuron_name | "core", effect_class)

@dataclass
class TrustScore:
    """
    Score aggregato di fiducia per una coppia (attore, classe d'effetto).
    Non è gradient-learned: è media ponderata di segnali oggettivi.
    Tutti i campi in [0.0, 1.0] salvo n_samples.
    """
    subject: TrustSubject
    # Componenti (aggiornate da rl_offline via trace reduce):
    tool_success: float           # % ActionStep con exec_result ok
    human_approval_rate: float    # approve / (approve + deny) storico
    cost_efficiency: float        # 1 − (cost_effettivo / cost_mediano_classe), clip
    constitution_clean: float     # 1 − (n_violation / n_samples)
    undo_rate: float              # % di Approval seguite da undo (invertito nello score)
    # Aggregato:
    score: float                  # 0 = sempre richiedi approvazione, 1 = massima fiducia
    # Metadati:
    n_samples: int                # trace considerate
    last_updated: datetime
    last_decay_at: datetime       # pesi esponenziali Ebbinghaus-like (decay 30g default)
    window: Literal["7d", "30d", "90d", "lifetime"] = "30d"

@dataclass(frozen=True)
class TrustThreshold:
    """Soglia sotto cui la policy promuove approve_required → allow."""
    effect_class: str
    risk_band: Literal["low", "medium", "high"]
    min_score: float              # score minimo richiesto per promozione
    min_samples: int              # n_samples minimi richiesti
    cap_autonomy: Literal[
        "read_only", "supervised", "full",
    ] = "supervised"              # non promuovere sopra questo livello

4.3 Invariante di interazione

I due tipi sono agganciati: la policy costruisce una PlannedAction, legge il TrustScore associato al subject = (tool_name, effect_class), e decide:

# Pseudocodice — la firma reale sta in policy.html §7
def evaluate(tc: dict, trace: ExecutionTrace, sender: str, autonomy: str) -> PolicyDecision:
    action = PlannedAction.from_tool_call(tc, sender, trace, autonomy)

    # 1. Leggi costituzionale, mai scavalcabile
    viol = constitution.check(action)
    if viol and viol.law in ("law.0", "law.1"):
        return PolicyDecision(verdict="deny", reason=viol.reason, ...)

    # 2. Trust-gating per azioni a side-effect
    if action.kind in SIDE_EFFECT_KINDS:
        score = trust_store.get(subject=(action.tool_name, effect_class_of(action)))
        threshold = trust_thresholds.for_effect(effect_class_of(action), action.reversibility)
        if score.n_samples >= threshold.min_samples \
                and score.score >= threshold.min_score \
                and autonomy_le(autonomy, threshold.cap_autonomy):
            return PolicyDecision(verdict="allow", via="trust_promoted", ...)
        return PolicyDecision(verdict="approve_required", ...)

    return PolicyDecision(verdict="allow", ...)

5. Disciplina di versioning e serializzazione

Serializzazione: JSON append-only, schema versionato

Tutti i tipi che finiscono in workspace/.audit/ o in risposta REST seguono un contratto comune.

1. Campo schema_version obbligatorio in ogni oggetto top-level persistito (es. ExecutionTrace, ApprovalRequest, NeuronManifest). Valore semver corto: "1.0", "1.1", "2.0".
2. Codifica: JSON UTF-8, datetime come ISO-8601 con Z, UUID come stringa, bytes come base64. Enum Literal sono stringhe.
3. Append-only: i file di audit sono .jsonl (una riga = un oggetto). Mai riscrivere, mai editare in-place. L'edit di una trace è una nuova trace.
4. Retro-compatibilità: il loader deve accettare tutti gli schema_version precedenti dello stesso major; campi sconosciuti vengono preservati in unknown_fields: dict per round-trip.
5. Segreti banditi dal serialized: niente token, niente path con ~/private/, niente chiavi API. La redazione avviene prima della serializzazione (PlannedAction.args_preview è l'esempio canonico).

Versioning degli schema: chi, quando, come

6. Cosa NON va qui

Per evitare di trasformare types.html in un doppione universale, vale questa lista di esclusione:

• Tipi usati da un solo componente. BudgetLedger (policy), SessionToken (gateway), WorkspaceLayout (workspace): restano nel loro doc.
• Protocolli di componente. Policy, Channel, Memory: restano nel loro doc-proprietario. Qui elenchiamo solo i dati.
• Implementazioni concrete. Questo doc è contratti; le classi concrete (TelegramChannel, HybridPolicy) vivono nel codice, non nei doc di architettura.
• Primitive di dominio esterno. FastAPI, httpx.Response, pydantic.BaseModel: non sono tipi myclaw.
• Errori di tool specifici. Gli Exception interni a un componente (es. ToolNetworkError) restano in tool.html; qui citiamo solo ToolError (dataclass pubblico).

7. Test di conformità (drift detection)

Il drift fra doc e codice è il peggior nemico di questa struttura. I test sotto sono obbligatori in CI (come gate di eval.html) e contract-enforcing.

8. Riferimenti incrociati

Ogni tipo linkato in §3 punta al doc-proprietario. Questa sezione è il riassunto per lettura rapida.

Per il razionale architetturale (perché esistono i 4 strati, perché le 4 Leggi, perché il trust-weighted) vedi i doc di Livello 1: Architettura Intro, Prospettive & Giudizio, Neuroni & Memoria.

Continua a leggere

myclaw — types microprogettazione v1.0 — 2026-04-22
Doc trasversale. Sblocca B1 della revisione incrociata. Introduce PlannedAction e TrustScore.