1. Scopo: la Legge 3 in forma operativa

La Legge 3 — tracciabilità — dice che myclaw preserva il proprio audit log e non occulta le proprie azioni. Qui la implementiamo: append-only, firmata, queryable, backed-up. Più tre canali complementari: structured logging per debug, metrics per monitoring, digest umano perché Roberto possa chiedere a colpo d'occhio "cosa ha combinato oggi?".

Cosa copre

• L'audit log JSONL append-only: fonte di verità.
• Lo structured log operativo (stdout → journald).
• Le metrics Prometheus-style su /metrics.
• L'health check su /health.
• Il daily digest umano per Roberto.
• Backup e rotation.

Cosa non copre

• Alerting esterno (Pushgateway, PagerDuty). Fuori scope domestico.
• Tracing distribuito (OpenTelemetry). Overkill per single-process.

2. Tre fonti, tre registri

Gerarchia delle sorgenti di verità

Più componenti scrivono journal (neuroni, sinapsi, trace, approvazioni). Per evitare che il lettore li tratti come equivalenti, qui la gerarchia canonica:

3. Audit log (append-only JSONL)

Layout

/opt/myclaw/workspace/.audit/
├── 2026-04.jsonl              # traces del mese corrente
├── 2026-03.jsonl              # precedenti
├── approvals.jsonl            # storico approvazioni (separato per query veloci)
├── workspace.jsonl            # modifiche ai 5 file markdown
├── constitution.jsonl         # modifiche a SOUL.md (raro, importante)
├── budget.json                # contatori correnti (non log)
└── archived/                  # episodi retention-spostati da memory

Formato record

// esempio: un trace chiusa
{
  "kind": "trace",
  "trace_id": "01HQWK3...",
  "session_id": "s_4a7b...",
  "channel": "telegram:@roberto",
  "started_at": "2026-04-22T14:03:22Z",
  "finished_at": "2026-04-22T14:03:28Z",
  "user_message": "scarica il rapporto di marzo",
  "final_response": "Fatto. Scaricati 2.4 MB in ~/downloads/rapporto_marzo.pdf.",
  "steps_count": 5,
  "tool_calls": [
    {"name": "web_fetch", "args_summary": "drive.google.com/...", "outcome": "success"},
    {"name": "fs_write", "args_summary": "~/downloads/rapporto_marzo.pdf", "outcome": "success"}
  ],
  "cost_usd": 0.023,
  "wall_time_ms": 5840,
  "outcome": "success",
  "approvals_requested": 1,
  "approvals_granted": 1
}

// esempio: una approvazione
{
  "kind": "approval",
  "request_id": "ar_...",
  "trace_id": "01HQWK3...",
  "sender": "telegram:@roberto",
  "tool_name": "fs_write",
  "effect_class": "fs_write:~/downloads/*",
  "granted": true,
  "via": "batch",
  "batch_window_expires_at": "2026-04-22T14:13:22Z",
  "at": "2026-04-22T14:03:24Z"
}

// esempio: modifica workspace
{
  "kind": "workspace_edit",
  "file": "MEMORY.md",
  "author": "agent|manual",
  "trace_id": "01HQWK3...",              // null se manual
  "size_before": 3421,
  "size_after": 3498,
  "diff_stat": "+3 -0",
  "approved_by_request_id": "ar_...",
  "at": "2026-04-22T14:03:28Z"
}

// esempio: constitution
{
  "kind": "constitution_modified",
  "hash_before": "sha256:...",
  "hash_after": "sha256:...",
  "diff": "...",                         // pieno
  "at": "2026-04-22T22:15:00Z",
  "notes": "Added Legge 4 omeostasi"
}

Append-only: garanzie

• Il file è aperto in modalità append (O_APPEND); ogni write è atomica.
• Il processo del gateway non ha capability di cancellare file di audit — ProtectSystem=strict + audit dir in lista ReadWritePaths, ma niente unlink.
• La rotazione mensile è fatta solo rinominando (mai troncando).
• Ogni record ha at ISO8601 UTC. Line-parsing = record-parsing (JSON per riga).

4. Structured logging (operativo)

Per il debug e il troubleshooting. Non sostituisce l'audit.

import structlog

logger = structlog.get_logger(__name__)

# uso tipico
logger.info(
    "tool_call_completed",
    trace_id=str(trace.trace_id),
    tool_name="fs_read",
    wall_ms=42,
)

logger.warning(
    "rate_limit_hit",
    sender=sender,
    counter=current,
    limit=limit,
)

Destinazioni

• stdout in formato JSON strutturato (structlog default).
• systemd cattura → journald. Query via journalctl --user -u myclaw-gateway.
• Rotation: automatica da journald (config SystemMaxUse=500M in drop-in).

Livelli e filtro

5. Metrics (Prometheus-style)

Endpoint: GET /metrics (auth admin). Formato Prometheus text exposition.

# HELP myclaw_traces_total Numero totale di trace chiuse
# TYPE myclaw_traces_total counter
myclaw_traces_total{outcome="success"} 1247
myclaw_traces_total{outcome="tool_hallucination"} 3
myclaw_traces_total{outcome="policy_denied"} 12
myclaw_traces_total{outcome="user_aborted"} 5
myclaw_traces_total{outcome="budget_hit"} 1
myclaw_traces_total{outcome="timeout_steps"} 2

# HELP myclaw_cost_eur_today Costo aggregato di oggi
# TYPE myclaw_cost_eur_today gauge
myclaw_cost_eur_today 1.23

# HELP myclaw_trace_latency_ms Latenza wall della trace (p50/p95/p99)
# TYPE myclaw_trace_latency_ms summary
myclaw_trace_latency_ms{quantile="0.5"} 2100
myclaw_trace_latency_ms{quantile="0.95"} 6200
myclaw_trace_latency_ms{quantile="0.99"} 11400

# HELP myclaw_active_sessions Sessioni attualmente attive
# TYPE myclaw_active_sessions gauge
myclaw_active_sessions{channel="telegram"} 1
myclaw_active_sessions{channel="cli"} 0

# HELP myclaw_budget_remaining_eur Budget rimanente oggi
# TYPE myclaw_budget_remaining_eur gauge
myclaw_budget_remaining_eur{cap="soft"} 0.77
myclaw_budget_remaining_eur{cap="hard"} 3.77

# HELP myclaw_tool_calls_total Chiamate per tool
# TYPE myclaw_tool_calls_total counter
myclaw_tool_calls_total{tool="fs_read"} 423
myclaw_tool_calls_total{tool="shell_run"} 128
myclaw_tool_calls_total{tool="web_fetch"} 67
# ...

# HELP myclaw_approvals_total Approvazioni chieste/concesse/negate
# TYPE myclaw_approvals_total counter
myclaw_approvals_total{verdict="granted",via="explicit"} 89
myclaw_approvals_total{verdict="granted",via="batch"} 214
myclaw_approvals_total{verdict="denied"} 7
myclaw_approvals_total{verdict="timeout"} 3

# HELP myclaw_llm_tier_calls_total Chiamate LLM per tier
# TYPE myclaw_llm_tier_calls_total counter
myclaw_llm_tier_calls_total{tier="local-fast"} 1876
myclaw_llm_tier_calls_total{tier="frontier"} 1203

6. Health check

GET /health

{
  "status": "ok",                       // "ok" | "degraded" | "down"
  "version": "0.0.1",
  "uptime_s": 86430,
  "gateway_pid": 12345,

  "workspace": {
    "mounted": true,
    "soul_hash_matches": true           // SOUL.md non modificato senza restart
  },

  "suprastructure": {
    "reachable": true,
    "llm_default_provider": "anthropic",
    "stt_default": "faster-whisper",
    "last_successful_call_at": "2026-04-22T14:02:18Z"
  },

  "channels": {
    "cli": "listening",
    "telegram": "pump_active"
  },

  "memory": {
    "episodic_db_size_mb": 8.2,
    "embeddings_db_size_mb": 3.4,
    "last_reflection": "2026-04-22T03:00:00Z",
    "pending_proposals": 7
  },

  "budget": {
    "soft_cap_eur": 2.0,
    "hard_cap_eur": 5.0,
    "spent_today_eur": 1.23,
    "override_active": false
  },

  "recent_errors_1h": 0
}

status è "degraded" se: budget soft hit, un canale non risponde, supra non raggiungibile ma riprovabile. "down" se: SOUL.md manca, workspace non scrivibile, supra irraggiungibile per > 5 minuti.

7. Activity digest (umanamente leggibile)

Ogni sera alle 22:00 (o quando Roberto chiede myclaw digest today): un messaggio strutturato, breve, con l'essenziale. Questa è la reificazione della critica #5 del giudizio (audit JSONL illeggibile come "cosa ha fatto oggi il mio maggiordomo").

myclaw · digest · 2026-04-22

📨 Richieste gestite: 23
  ├─ 21 completate con successo
  ├─ 1 annullata (tu hai negato)
  └─ 1 fallita (tool hallucination, LLM inventava un tool)

🔧 Tool usati più di 3 volte:
  - fs_read         (8)
  - supra_llm       (23 — ogni Thought)
  - web_fetch       (4)
  - shell_run       (5)

✅ Approvazioni:
  - 14 concesse esplicitamente
  - 3 approvate via batch (fs_write:~/downloads/*)
  - 1 negata (tentativo di scrivere in /opt/suprastructure/)

💰 Costo: 1.23 € (soft cap 2€)
⏱  Latenza p95: 6.2s (stabile)

🧠 Memoria:
  - 23 nuovi episodi indicizzati
  - 7 proposte di reflection pronte (digest mattutino approverà)

⚠ Cose notevoli:
  - Alle 14:03 tentativo di indirect prompt injection da una pagina web
    (pattern "IGNORA ISTRUZIONI" intercettato dal boundary untrusted). Nessun effetto.
  - Alle 19:47 Tutor mode è scattato per fs_write:~/downloads/*
    (10a approvazione consecutiva). Tu hai confermato, tutto regolare.

Nessuna constitution o workspace edit.
🟢 stato: regolare.

Il digest viene costruito da un job cron notturno che legge audit JSONL del giorno e produce il testo via LLM tier summarize-rich (~0.01€ per digest) con template strutturato.

8. Backup e rotation

Audit rotation

• File JSONL suddivisi per mese (YYYY-MM.jsonl).
• A fine mese: compressione gzip del file precedente (YYYY-MM.jsonl.gz).
• Retention: indefinita (audit è legge). Solo la compressione libera spazio.

Backup periodico via systemd timer

# ~/.config/systemd/user/myclaw-backup.service
[Unit]
Description=myclaw daily backup
Requires=myclaw-gateway.service

[Service]
Type=oneshot
ExecStart=/bin/bash -c '\
  tar czf /var/backups/myclaw/workspace-$(date +%%Y%%m%%d-%%H%%M).tar.gz \
    /opt/myclaw/workspace/ \
  && find /var/backups/myclaw/ -name "workspace-*.tar.gz" -mtime +30 \
    ! -newermt $(date -d "first day of month" +%%Y-%%m-%%d) \
    -delete'

# ~/.config/systemd/user/myclaw-backup.timer
[Unit]
Description=Daily workspace backup

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Retention: ultimi 30 daily + primo di ogni mese per 12 mesi.

9. Contratto Python

from typing import Protocol, Literal

class AuditLog(Protocol):
    async def append(self, record: dict) -> None:
        """Append atomico di un record JSON. record['kind'] obbligatorio."""
        ...

    async def query(
        self,
        kind: str | None = None,
        since: datetime | None = None,
        until: datetime | None = None,
        sender: str | None = None,
        limit: int = 100,
    ) -> list[dict]: ...

    async def verify_integrity(self) -> IntegrityReport:
        """Controlla gaps nei timestamp, JSON malformed, size anomalies."""
        ...

class Metrics(Protocol):
    def inc(self, name: str, labels: dict | None = None, value: float = 1.0) -> None: ...
    def gauge(self, name: str, value: float, labels: dict | None = None) -> None: ...
    def observe(self, name: str, value: float, labels: dict | None = None) -> None: ...
    def render_prometheus(self) -> str: ...

class HealthChecker(Protocol):
    async def check(self) -> HealthStatus: ...

@dataclass
class HealthStatus:
    status: Literal["ok", "degraded", "down"]
    details: dict
    checked_at: datetime

class DigestBuilder(Protocol):
    async def build_daily(self, date: date, sender: str) -> str:
        """Costruisce il digest markdown per un giorno specifico."""
        ...

10. Test di conformità

11. Riferimenti

Continua a leggere

myclaw — observability microprogettazione v1.0 — 2026-04-22
Fase 2 completa. Prossimo: pairing.html (fase 3).