openvibers/openvibe.contracts Commits

Contracts 0.132.0: an Events position is an opaque cursor only (#85)

OP OpenVibers committed 10 Oct 2026 · tag v0.132 · 0 files, +0 −0

Plan T7, ADR-042 decision 7: an Events position is an opaque cursor and nothing else. `events.read-result@1` and `events.read-request@1` drop the numeric positions their own descriptions kept "only until every consumer reads by cursor".

Every consumer reads by cursor now. I checked across the estate:
- Community's relay (Community #56, deployed);
- the SDK's pull, iterate, checkpoints and realtime (openvibe-sdk 0.42.0);
- Shared's bell and release watcher (3.0.1);
- Examples (#14);
- Chat's e2e test (#64);
- Services' project archive, which already read by cursor.

**Schema changes:**
- **Pages:** `{ events: [{ seq, cursor, event }], next_cursor, latest_cursor, gap? }`.
  - `next_after_seq` and `latest_seq` are gone.
  - `next_cursor`, `latest_cursor` and each item's `cursor` are required (Events always sends them).
  - Without `after=`, a page starts at the oldest retained event; `after_seq` is refused.
- **Single event:** `cursor` is required beside `seq`.
- **Checkpoints:** `PUT { topic, cursor, carrier? }` takes an opaque cursor string; a number is refused. Answers are `{ consumer, topic, cursor, carrier, updated_at }`, with the cursor as stored (null when none is).
- **Realtime (description):** the SSE id is the cursor, and `Last-Event-ID` resumes only from a cursor.
- **Per-event `seq`:** stays, documented as informational. Deleting it, with `X-OpenVibe-Seq` and the global-order promise, is ADR-042's last step; clients already dedupe by `event_id` (SDK 0.42, Shared 3.0.1).
- **ADR-042:** records what decision 7 became.

**Fixtures:** pages and checkpoints with cursors only. Three new invalid fixtures: a numeric page, a numeric checkpoint answer, a numeric checkpoint request. A valid stored checkpoint is added.

**Compat:** `node scripts/compat.js v0.131.0` reports no breaking changes. The gate does not descend into `anyOf` schemas. The removal is the one v1 announced, and the consumer check above is what makes it safe.

`node test/run.js`: 18,388 checks passed; `generated/` is up to date.