# Eve watcher semantics record — 2026-09-09

- Task: 7.3
- Scope: pre-ui watcher semantic contract and persistence boundary
- Record digest:
  `51b65cb7dc4b1355318f36220ee6d21a83c8dd844ae34c4ee0a607487cc47f69`
- Product admission: **not-admitted**
- Phase/gaps: **open**

## Semantic decisions

| Area                 | Decision                                                                                                                                |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Source and truth     | Event and polling sources are distinct; truth is a bounded declarative DSL with no code or model.                                       |
| Evidence             | Past age is definition-bound; future skew is 30000 ms. Unauthorized evidence cannot advance a checkpoint.                               |
| Delivery             | at-least-once; canonical SHA-256 key; no exactly-once claim. Dispatch requires authority, durable CAS, invocation, then settlement.     |
| Missed runs and time | skip, latest, bounded backfill; IANA zones; real-instant DST traversal; local quiet hours.                                              |
| Budgets              | Fixed window over evaluations, unique-deliveries, delivery-attempts, tokens, cost-microusd.                                             |
| Failure              | Capped exponential retry, categorical errors, terminal `dead_letter`.                                                                   |
| Authority            | Rechecked for evaluate, deliver-every-attempt, manage, erase across every exact subject/resource/time binding.                          |
| Lifecycle            | active, paused, cancelled, expired; cancellation is terminal and expiry covers active/paused.                                           |
| Restart              | Initial creation cannot overwrite; interrupted dispatch returns pending with the same key/attempt count; revisions use compare-and-set. |
| Privacy              | Only allowlisted scalar evidence paths persist; cancellation/retention/exact-subject erasure are explicit; credentials are excluded.    |

## Implementation boundary

- `libs/oshun/assistant/src/watchers/watcher-contract.ts`
- `libs/oshun/assistant/src/watchers/watcher-engine.ts`
- `libs/oshun/assistant/src/watchers/watcher-store.ts`
- `libs/oshun/assistant/src/watchers/postgres-watcher-store.ts`
- `libs/oshun/assistant/src/watchers/index.ts`

Product consumers of this watcher API: **0**. No UI tool is present and no
worker starts. Tasks 7.4 and 7.5 own admission and live reliability.

## Automated verification

- `libs/oshun/assistant/src/watchers/watcher-contract.spec.ts`
- `libs/oshun/assistant/src/watchers/watcher-engine.spec.ts`
- `libs/oshun/assistant/src/watchers/watcher-store.spec.ts`

Layers: contract, state-machine, in-memory-restart, postgres-sql-boundary.

## Source evidence

| Path                                                          | Digest of        | SHA-256                                                            | Bytes |
| ------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------ | ----: |
| `EVE_SOTA_GAP_CLOSURE_TODOS_2026-09-01.md`                    | task-requirement | `8acf66c44561ed36aa456a6bdca78903b09a3411ae807565d46466534c5f5f0c` |   316 |
| `libs/oshun/assistant/src/watchers/watcher-contract.ts`       | file-bytes       | `17cbfdfe938f975b6a35b575572236b62ce51b5ee87507ef81b33a40f218100c` | 26900 |
| `libs/oshun/assistant/src/watchers/watcher-engine.ts`         | file-bytes       | `07c5b254279e0f140ffc7851b4fa878cfbf7a9730b480036e317ca052a3639f6` | 20053 |
| `libs/oshun/assistant/src/watchers/watcher-store.ts`          | file-bytes       | `dbeb189921200125e2efb6a857f6310bde2da9d03ad61662b3c79c5ed39d209a` |  9916 |
| `libs/oshun/assistant/src/watchers/postgres-watcher-store.ts` | file-bytes       | `43a5f5fe3faed7b8018a0bdb5ae4fc42576f002cc1e4f83b49a3cc394a8113a1` |  6354 |
| `libs/oshun/assistant/src/watchers/index.ts`                  | file-bytes       | `303b3e3c3a483b6a976e017b76c2a7e8af650da0d3a62139b97044513a8810c8` |   145 |
| `docs/adr/ADR-0081-eve-watcher-semantics-before-ui.md`        | file-bytes       | `9c19467c4ea22a8b102e1d6ecceb3fcf2eb3e33f7cac79346b821c309fdd019b` |  7439 |
| `libs/oshun/assistant/src/watchers/watcher-contract.spec.ts`  | file-bytes       | `b018a96649ee65dd6ee3d991a58c352f928f8697483f51eeaa9f92604e8a8195` | 11783 |
| `libs/oshun/assistant/src/watchers/watcher-engine.spec.ts`    | file-bytes       | `30c635008d919d54b1895e8772795edd1f9ae73f03e778178327f3cb3c288a5a` | 14011 |
| `libs/oshun/assistant/src/watchers/watcher-store.spec.ts`     | file-bytes       | `c5321d58a073358a1cb767a48beb2700602c4b127ac4809fb88db6a9c93cfb99` | 10907 |

## Honest limits

- No real event stream, polling source, destination, or Postgres service ran for
  Task 7.3.
- Cron occurrence enumeration and worker orchestration are not implemented by
  this semantic substrate.
- The SQL boundary is tested, but a live database restart and distributed race
  remain unproved.
- At-least-once delivery can redeliver after an acknowledgement crash;
  downstream adapters must honor the stable idempotency key.
- User-facing tools and notifications remain gated to Task 7.4; live reliability
  breadth remains Task 7.5.

Task 7.3 is closed by this contract. Phase 7 and
G3/G11/G12/G13/G14/G15/G16/G17/G18 remain open.