# OpenSpec Change: network-plugin-audit-mesh

- **Change ID**: network-plugin-audit-mesh
- **Package**: `@suaveplan/network-plugin-audit-mesh` (new)
- **Status**: PROPOSED
- **Type**: new-package
- **Date**: 2026-04-29

## Why

When the central server is offline, the mesh operates autonomously — but activity must still be auditable. Hosts generate signed logs of session events, peer joins/leaves, host elections, and state changes. These logs must be replicated across multiple hosts for durability (so a single host failure doesn't erase history) and must be retrievable by the server when it comes back online. This plugin provides tamper-evident, cryptographically signed, append-only log chains with cross-host replication.

## What changes

- **ADDED**: `AuditMeshPlugin` class implementing `NetworkPlugin`.
- **ADDED**: `SignedLog` — append-only log structure:

  ```typescript
  interface LogEntry {
    readonly seq: number;                    // monotonic sequence
    readonly timestamp: number;              // injectable Clock
    readonly meshId: string;
    readonly sessionId: string | null;
    readonly eventType: LogEventType;        // 'peer-joined' | 'peer-left' | 'host-elected' | 'session-created' | ...
    readonly payload: unknown;               // event-specific data
    readonly prevHash: string;               // BLAKE3 hash of previous entry
    readonly hostId: string;                 // host that produced this entry
    readonly hostSignature: Uint8Array;      // Ed25519 signature of hash(entry)
  }
  ```

- **ADDED**: `LogReplicator` — replicates logs to `R` sibling hosts (configurable, default 2). Uses mesh topology to select replication targets: Tier 0 replicates to other Tier 0s; Tier 1 replicates to its Tier 0 parent and a sibling Tier 1. Provides cross-tier durability.
- **ADDED**: `LogRetriever` — responds to log queries from other hosts or from the server bridge. Supports range queries: `getLogs(meshId, fromSeq, toSeq)`.
- **ADDED**: `IntegrityChecker` — verifies the hash chain on retrieval. Detects gaps, forks, or tampered entries. Reports `audit:corruption-detected` on the bus.
- **ADDED**: `ConflictResolver` — when the server retrieves logs from multiple hosts and finds divergent chains, resolves using: (1) longest chain wins, (2) if equal length, lexicographically smallest last-hash wins (deterministic tiebreak).
- **ADDED**: `LogCompaction` — periodically compacts old logs into checkpoints. A checkpoint is a signed snapshot of mesh/session state at a given sequence number. Reduces replay volume when server reconnects.
- **ADDED**: `NETWORK_AUDIT_CODES` — frozen error registry.

## Replication topology

```text
Tier 0 Host A (primary log for Mesh 1)
    │
    ├── replicates to ──► Tier 0 Host B (Mesh 2)
    │
    └── replicates to ──► Tier 1 SubHost C (Mesh 1, local redundancy)

Tier 1 SubHost C
    │
    ├── replicates to ──► Tier 0 Host A (parent)
    └── replicates to ──► Tier 1 SubHost D (sibling)
```

**Replication rules**:

- Every log entry is stored on at least `R+1` hosts (original + R replicas).
- Replicas are updated synchronously for CRITICAL events (host election, session creation).
- Replicas are updated asynchronously for NORMAL events (peer join/leave, state update).

## Server reconciliation flow

```text
Server comes online
    │
    ├── queries all Tier 0 hosts for log checkpoints
    ├── finds latest common checkpoint across hosts
    ├── requests differential logs from that checkpoint forward
    ├── validates all signatures and hash chains
    ├── detects conflicts → runs ConflictResolver
    ├── applies reconciled state to server database
    └── broadcasts `server:reconciled` to all mesh hosts
```

## Out of scope

- Server-side log storage and analysis → API gateway / audit-logging packages.
- Real-time streaming analytics → future `network-plugin-analytics`.
- Legal/compliance retention policies → future `network-plugin-compliance`.

## Source mapping

This derives from `../suaveplan/enterprise/audit-logging.md` and `../suaveplan/packages/universal/audit-logging/`.

| Requirement | Source lines | Notes |
|---|---|---|
| Structured audit logs | `audit-logging/README.md` §Logs | reworded; mesh-specific format |
| Log integrity | `audit-logging/README.md` §Integrity | reworded; hash chain + signatures |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| Cross-host log replication | Durability — single host failure must not erase audit history |
| Hash-chained append-only logs | Tamper evidence — any modification breaks the chain |
| Host signatures on every entry | Accountability — every event is attributable to a specific host |
| Conflict resolution for divergent chains | Required when hosts disagree on history during partition |
| Log compaction into checkpoints | Required for efficient server reconciliation after long outages |
| Synchronous replication for critical events | Host elections must be durable before acknowledged |

## Verification approach

- `src/log/signed-log.spec-conformance.test.ts` — pins append, hash chain, signature.
- `src/replicator/log-replicator.spec-conformance.test.ts` — pins R-copy replication, target selection.
- `src/integrity/integrity-checker.spec-conformance.test.ts` — pins gap detection, fork detection, tamper detection.
- `src/conflict/conflict-resolver.spec-conformance.test.ts` — pins longest-chain, tiebreak, merge.
- `src/compaction/log-compaction.spec-conformance.test.ts` — pins checkpoint creation, state snapshot.
- `src/retriever/log-retriever.spec-conformance.test.ts` — pins range queries, pagination.
- `src/error-codes.spec-conformance.test.ts` — frozen registry.

## Migration impact

None — additive only.