# Host telemetry contract

Version 0.1 — SAND-WP-0008. Extends `docs/meta-framework.md` Host resource with
read-only observability. sand-boxer collects and exports telemetry; it does not
own long-term metrics storage.

---

## Types

### HostSnapshot

Point-in-time host metrics collected over SSH (≤10s, non-root-safe).

| Field | Description |
|-------|-------------|
| `load_1m`, `load_5m`, `load_15m` | `/proc/loadavg` |
| `cpu_count` | Logical CPUs |
| `mem_total_mb`, `mem_available_mb` | From `free -m` |
| `disk_root_used_pct`, `disk_root_avail_gb` | Root filesystem |
| `running_containers` | All running containers (podman/docker) |
| `sandbox_containers` | Containers with `sbx-*` compose project label |

### SandboxInventory

Known sandbox artifacts on a host.

| Entry type | Source |
|------------|--------|
| `directory` | `{base_dir}/{sandbox_id}` |
| `compose_project` | `sbx-*` or legacy `e2e-*` compose labels |

Each entry: `id`, `path`, `age_hours`, `profile_hint` (inferred from project name).

### StaleCandidate

| Kind | Meaning | Suggested action |
|------|---------|------------------|
| `orphan_dir` | Dir on host, not in local store | `reap` |
| `orphan_compose` | Compose project on host, not in store | `reap` |
| `zombie_record` | Store record not `destroyed`, missing on host | `inspect` |
| `aged_dir` | Dir older than threshold | `reap` |

Actions: `reap`, `inspect`, `ignore`. Automatic reap requires `--apply` on CLI.

### ProvisionDelta

`before` and `after` HostSnapshot pair with computed deltas:

- `load_1m_delta`, `mem_available_mb_delta`, `running_containers_delta`

### IntrospectionReport

Bundled canary output attached to `SandboxStatus.telemetry` on `ready`:

```json
{
  "schema_version": "0.1",
  "host": "92.205.130.254",
  "sandbox_id": "abc12345",
  "profile_id": "profile.sandbox-canary",
  "collected_at": "2026-06-23T...",
  "provision_delta": { "before": {}, "after": {}, "load_1m_delta": 0.1 },
  "inventory": { "entries": [], "host": "..." },
  "stale_candidates": []
}
```

---

## Privacy and retention

- No secret paths, env files, or full `docker inspect` dumps
- Telemetry JSON retained locally under `~/.local/share/sandboxer/telemetry/`
- State Hub events include report in `detail` — same redaction rules apply
- Operators may set `SANDBOXER_NO_STATE_HUB=1` to skip remote emission

---

## Export sinks

| Sink | Status |
|------|--------|
| State Hub `progress/` | Implemented |
| Local JSON artifact | Implemented |
| `TelemetrySink` protocol | Stub for artifact-store / Prometheus / ClickHouse |

---

## Profile trigger

Telemetry collection runs when:

- Profile id is `profile.sandbox-canary`, or
- `profile.metadata.observability` is `canary`