# API: hyper-p2p-cron-gossip

**Protocol:** `cron-gossip/v1`

**Export:** `{ HyperP2PCronGossip, PROTOCOL }`

## Overview

`HyperP2PCronGossip` stores jobs in a local `Map` keyed by `jobId`. `schedule(expr, jobId)` registers an expression. `tick(now)` evaluates due jobs, emits `fire`, and gossips `cron-fire` to peers. Remote fires update `lastRun` and emit `remote-fire`. Expressions support `@every Nms|s|m|h` or five-field UTC cron (`minute hour day month weekday`).

## Constructor

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` \| `Buffer` \| `null` | `null` | Hyperswarm topic |
| `keyPair` | `KeyPair` | `hypercore-crypto.keyPair()` | Swarm identity; `peerHex` derived for gossip |

## Methods

### `schedule(expr, jobId)`

- **Returns:** `{ jobId, expr, lastRun, at }` job record
- **Throws:** `ValidationError` if `jobId` or `expr` empty
- **Emits:** `schedule`

### `unschedule(jobId)`

- **Returns:** `boolean` — whether job existed

### `tick(now = Date.now())`

Evaluates all jobs; fires due ones.

- **Returns:** `string[]` — fired `jobId` list
- **Emits:** `fire` per local job

### `list()` / `get(jobId)`

Snapshots of registered jobs.

### `async ready()` / `async close()`

`close()` clears jobs, destroys swarm, emits `closed`.

### `getStats()`

| Field | Type | Description |
|-------|------|-------------|
| `scheduled` | `number` | `schedule` calls |
| `fired` | `number` | Local tick fires |
| `gossipIn` / `gossipOut` | `number` | Wire counters |
| `jobs` | `number` | Map size |
| `protocol` | `string` | `cron-gossip/v1` |

## Events

| Event | Payload | When |
|-------|---------|------|
| `schedule` | job object | `schedule()` |
| `fire` | `{ jobId, at }` | Local `tick` fired job |
| `remote-fire` | `{ jobId, peer, at }` | Inbound `cron-fire` |
| `closed` | — | `close()` |

## getStats()

Shallow copy with live `jobs` count.

## Wire

| type | fields | direction | behavior |
|------|--------|-----------|----------|
| `cron-fire` | `jobId`, `expr`, `peer`, `at` | bidirectional | Update/create job `lastRun`; emit `remote-fire` |

Gossip only sends when `_peerMsgs` is populated (after `ready()` + connections).

## Cron expression helpers

| Form | Example | Semantics |
|------|---------|-----------|
| `@every` | `@every 30s` | Interval since `lastRun` |
| Five-field | `0 * * * *` | UTC minute/hour/day/month/weekday match |

## Errors

| Message | Source |
|---------|--------|
| `jobId is required` / `expr is required` | `schedule` |
| `topic is required for createSwarm` | swarm |

## Testing

```bash
cd modules/scheduling-queues/hyper-p2p-cron-gossip
npm install && npm test
bare examples/basic.js
```

Drive `tick` with injected `now` for deterministic tests.