openvibers/openvibe.contracts Commits

openvibe-contracts 0.128.2: events.read-result@1 documents latest_cursor (#81)

OP OpenVibers committed 10 Oct 2026 · 9396d2d038 · 37 files, +156 −65

`events.read-result@1` documents `latest_cursor` (OpenVibe.Events#45): the head of a pull as an opaque cursor. Its description says to keep `next_cursor` and read on with `after=`; the numeric `after_seq`/`next_after_seq`/`latest_seq` remain only until every consumer reads by cursor (plan T7). Community#45, Services#24 and Examples#11 already have.

0.128.2, additive (`compat.js v0.128.1`: no breaking changes). Fixtures: a page with `latest_cursor` passes, and an empty one is refused. Suite: 18349 checks passed.

Changes

ddiff --git a/CHANGELOG.md b/CHANGELOG.md
iindex 2c323974..491ae4aa 100644
---- a/CHANGELOG.md
++++ b/CHANGELOG.md
@@@ -4,6 +4,13 @@ All notable changes to `openvibe-contracts`. Releases are git tags (`vX.Y.Z`) th
  from `https://codeload.github.com/OpenVibers/OpenVibe.Contracts/tar.gz/refs/tags/<tag>`. Before v0.30.0,
  the notes were in the tag and commit messages (`git tag -n1`).
  
++## 0.128.2 — 2026-10-10
++
++- `events.read-result@1` documents `latest_cursor` (OpenVibe.Events#45), the head of a pull as an opaque cursor, and
++  says to keep `next_cursor` and read on with `after=`. The numeric `after_seq`, `next_after_seq` and `latest_seq`
++  remain only until every consumer reads by cursor (plan T7; Community, Services and the Examples have moved).
++  Additive.
++
  ## 0.128.1 — 2026-10-10
  
  - **Descriptions only.** `inventory.index_document.*` name Inventory's real item page, `/items/<id>` on
ddiff --git a/contracts/events/read-result.v1.json b/contracts/events/read-result.v1.json
iindex 26d2f94d..5c10b219 100644
---- a/contracts/events/read-result.v1.json
++++ b/contracts/events/read-result.v1.json
@@@ -2,7 +2,7 @@
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://openvibe.network/contracts/events/read-result.v1.json",
    "title": "EventsReadResult",
--  "description": "events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, gap? } (keep next_after_seq as the cursor: it moves past events that did not match; gap { from_seq, to_seq } says events after after_seq were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.",
++  "description": "events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, latest_cursor?, gap? } (keep next_cursor as the position and read on with after=: it moves past events that did not match; latest_cursor is the head, for a consumer that starts at now; the numeric after_seq, next_after_seq and latest_seq remain only until every consumer reads by cursor (plan T7); gap { from_seq, to_seq } says events after the position were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.",
    "anyOf": [
      {
        "type": "object",
@@@ -66,6 +66,12 @@
            "minLength": 1,
            "maxLength": 200,
            "description": "Opaque position after this page (ADR-042): pass it back as after= for the next page. Returned beside next_after_seq for one release."
++        },
++        "latest_cursor": {
++          "type": "string",
++          "minLength": 1,
++          "maxLength": 200,
++          "description": "The head as an opaque cursor (ADR-042): a consumer that starts at now stores it and reads on with after=, never needing latest_seq."
          }
        }
      },
ddiff --git a/fixtures/events.read-result/invalid/empty-latest-cursor.json b/fixtures/events.read-result/invalid/empty-latest-cursor.json
nnew file mode 100644
iindex 00000000..abaee460
---- /dev/null
++++ b/fixtures/events.read-result/invalid/empty-latest-cursor.json
@@@ -0,0 +1,31 @@
++{
++  "events": [
++    {
++      "seq": 88213,
++      "event": {
++        "event_id": "evt_01JAB2C3D4E5F6G7H8J9K0MNPR",
++        "event_type": "app.p01jab2c3d4e5f6g7h8j9k0mnpq.order.created",
++        "version": 1,
++        "source": "app-01jab2c3d4e5f6g7h8j9k0mnps",
++        "actor": {
++          "type": "app",
++          "id": "app_01JAB2C3D4E5F6G7H8J9K0MNPS"
++        },
++        "timestamp": "2026-09-23T12:00:00Z",
++        "visibility": "internal",
++        "subject": {
++          "type": "order",
++          "id": "42"
++        },
++        "payload": {
++          "total": 3
++        }
++      },
++      "cursor": "c1.e0.1"
++    }
++  ],
++  "next_after_seq": 88240,
++  "latest_seq": 88240,
++  "next_cursor": "c1.e0.next",
++  "latest_cursor": ""
++}
ddiff --git a/fixtures/events.read-result/valid/page-with-latest-cursor.json b/fixtures/events.read-result/valid/page-with-latest-cursor.json
nnew file mode 100644
iindex 00000000..982aaf25
---- /dev/null
++++ b/fixtures/events.read-result/valid/page-with-latest-cursor.json
@@@ -0,0 +1,31 @@
++{
++  "events": [
++    {
++      "seq": 88213,
++      "event": {
++        "event_id": "evt_01JAB2C3D4E5F6G7H8J9K0MNPR",
++        "event_type": "app.p01jab2c3d4e5f6g7h8j9k0mnpq.order.created",
++        "version": 1,
++        "source": "app-01jab2c3d4e5f6g7h8j9k0mnps",
++        "actor": {
++          "type": "app",
++          "id": "app_01JAB2C3D4E5F6G7H8J9K0MNPS"
++        },
++        "timestamp": "2026-09-23T12:00:00Z",
++        "visibility": "internal",
++        "subject": {
++          "type": "order",
++          "id": "42"
++        },
++        "payload": {
++          "total": 3
++        }
++      },
++      "cursor": "c1.e0.1"
++    }
++  ],
++  "next_after_seq": 88240,
++  "latest_seq": 88240,
++  "next_cursor": "c1.e0.next",
++  "latest_cursor": "c1.0.Nw"
++}
ddiff --git a/generated/json-schema/bundle.json b/generated/json-schema/bundle.json
iindex d094ba35..39a12768 100644
---- a/generated/json-schema/bundle.json
++++ b/generated/json-schema/bundle.json
@@@ -6095,7 +6095,7 @@
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "$id": "https://openvibe.network/contracts/events/read-result.v1.json",
          "title": "EventsReadResult",
--        "description": "events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, gap? } (keep next_after_seq as the cursor: it moves past events that did not match; gap { from_seq, to_seq } says events after after_seq were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.",
++        "description": "events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, latest_cursor?, gap? } (keep next_cursor as the position and read on with after=: it moves past events that did not match; latest_cursor is the head, for a consumer that starts at now; the numeric after_seq, next_after_seq and latest_seq remain only until every consumer reads by cursor (plan T7); gap { from_seq, to_seq } says events after the position were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.",
          "anyOf": [
            {
              "type": "object",
@@@ -6159,6 +6159,12 @@
                  "minLength": 1,
                  "maxLength": 200,
                  "description": "Opaque position after this page (ADR-042): pass it back as after= for the next page. Returned beside next_after_seq for one release."
++              },
++              "latest_cursor": {
++                "type": "string",
++                "minLength": 1,
++                "maxLength": 200,
++                "description": "The head as an opaque cursor (ADR-042): a consumer that starts at now stores it and reads on with after=, never needing latest_seq."
                }
              }
            },
ddiff --git a/generated/openapi/actor.json b/generated/openapi/actor.json
iindex e7e9da9a..e708a2b8 100644
---- a/generated/openapi/actor.json
++++ b/generated/openapi/actor.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Actor API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Actor as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Actor as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/ai.json b/generated/openapi/ai.json
iindex f948edd7..64c979c4 100644
---- a/generated/openapi/ai.json
++++ b/generated/openapi/ai.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.AI API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.AI as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.AI as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/billing.json b/generated/openapi/billing.json
iindex 97e70f08..a81e88f3 100644
---- a/generated/openapi/billing.json
++++ b/generated/openapi/billing.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Billing API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Billing as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Billing as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/blog.json b/generated/openapi/blog.json
iindex 05546e66..ecb6daab 100644
---- a/generated/openapi/blog.json
++++ b/generated/openapi/blog.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Blog API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Blog as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Blog as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/bot.json b/generated/openapi/bot.json
iindex ff713738..984369ad 100644
---- a/generated/openapi/bot.json
++++ b/generated/openapi/bot.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Bot API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Bot as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Bot as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/chat.json b/generated/openapi/chat.json
iindex e7fe0ba5..2dca32c6 100644
---- a/generated/openapi/chat.json
++++ b/generated/openapi/chat.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Chat API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Chat as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Chat as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/community.json b/generated/openapi/community.json
iindex ef185562..d96bd44d 100644
---- a/generated/openapi/community.json
++++ b/generated/openapi/community.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Community API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Community as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Community as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/coupons.json b/generated/openapi/coupons.json
iindex 0d827234..fd62ea95 100644
---- a/generated/openapi/coupons.json
++++ b/generated/openapi/coupons.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Coupons API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Coupons as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Coupons as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/deals.json b/generated/openapi/deals.json
iindex 068b9657..fac858ef 100644
---- a/generated/openapi/deals.json
++++ b/generated/openapi/deals.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Deals API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Deals as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Deals as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/events.json b/generated/openapi/events.json
iindex 6a7f8c47..49f15508 100644
---- a/generated/openapi/events.json
++++ b/generated/openapi/events.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Events API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Events as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Events as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
@@@ -1493,7 +1493,7 @@
     },
     "events.read-result.v1": {
      "title": "EventsReadResult",
--    "description": "events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, gap? } (keep next_after_seq as the cursor: it moves past events that did not match; gap { from_seq, to_seq } says events after after_seq were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.",
++    "description": "events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, latest_cursor?, gap? } (keep next_cursor as the position and read on with after=: it moves past events that did not match; latest_cursor is the head, for a consumer that starts at now; the numeric after_seq, next_after_seq and latest_seq remain only until every consumer reads by cursor (plan T7); gap { from_seq, to_seq } says events after the position were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.",
      "anyOf": [
       {
        "type": "object",
@@@ -1557,6 +1557,12 @@
          "minLength": 1,
          "maxLength": 200,
          "description": "Opaque position after this page (ADR-042): pass it back as after= for the next page. Returned beside next_after_seq for one release."
++       },
++       "latest_cursor": {
++        "type": "string",
++        "minLength": 1,
++        "maxLength": 200,
++        "description": "The head as an opaque cursor (ADR-042): a consumer that starts at now stores it and reads on with after=, never needing latest_seq."
         }
        }
       },
ddiff --git a/generated/openapi/food.json b/generated/openapi/food.json
iindex fa2966ab..96b1b8cb 100644
---- a/generated/openapi/food.json
++++ b/generated/openapi/food.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Food API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Food as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Food as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/games.json b/generated/openapi/games.json
iindex 10288f53..9267da62 100644
---- a/generated/openapi/games.json
++++ b/generated/openapi/games.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Games API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Games as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Games as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/host.json b/generated/openapi/host.json
iindex 744104d7..8761ce36 100644
---- a/generated/openapi/host.json
++++ b/generated/openapi/host.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Host API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Host as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Host as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/inventory.json b/generated/openapi/inventory.json
iindex a8c16acb..5d291566 100644
---- a/generated/openapi/inventory.json
++++ b/generated/openapi/inventory.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Inventory API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Inventory as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Inventory as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/live.json b/generated/openapi/live.json
iindex d902c2e8..e7975149 100644
---- a/generated/openapi/live.json
++++ b/generated/openapi/live.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Live API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Live as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Live as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/media.json b/generated/openapi/media.json
iindex 4c48e78d..f8b725c0 100644
---- a/generated/openapi/media.json
++++ b/generated/openapi/media.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Media API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Media as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Media as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/network.json b/generated/openapi/network.json
iindex 666a4159..1d73726d 100644
---- a/generated/openapi/network.json
++++ b/generated/openapi/network.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Network API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Network as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Network as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/news.json b/generated/openapi/news.json
iindex a92dde47..f5bcded0 100644
---- a/generated/openapi/news.json
++++ b/generated/openapi/news.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.News API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.News as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.News as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/openre.json b/generated/openapi/openre.json
iindex 628e79f3..a4e8fc2b 100644
---- a/generated/openapi/openre.json
++++ b/generated/openapi/openre.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenRestream API",
--  "version": "0.128.1",
--  "description": "Routes of OpenRestream as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenRestream as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/reviews.json b/generated/openapi/reviews.json
iindex f16a26dd..9678b1fb 100644
---- a/generated/openapi/reviews.json
++++ b/generated/openapi/reviews.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Reviews API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Reviews as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Reviews as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/run.json b/generated/openapi/run.json
iindex 954d3b80..f2460418 100644
---- a/generated/openapi/run.json
++++ b/generated/openapi/run.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Run API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Run as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Run as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/search.json b/generated/openapi/search.json
iindex 6a56e2b3..3fc9d1ec 100644
---- a/generated/openapi/search.json
++++ b/generated/openapi/search.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Search API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Search as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Search as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/services.json b/generated/openapi/services.json
iindex 5ceb067d..bb242e8b 100644
---- a/generated/openapi/services.json
++++ b/generated/openapi/services.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Services API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Services as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Services as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/sources.json b/generated/openapi/sources.json
iindex 27bb22f2..95cc7043 100644
---- a/generated/openapi/sources.json
++++ b/generated/openapi/sources.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Sources API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Sources as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Sources as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/tips.json b/generated/openapi/tips.json
iindex d5d9dd0f..654cc2e0 100644
---- a/generated/openapi/tips.json
++++ b/generated/openapi/tips.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Tips API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Tips as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Tips as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/tools.json b/generated/openapi/tools.json
iindex fb80896e..3e997232 100644
---- a/generated/openapi/tools.json
++++ b/generated/openapi/tools.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Tools API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Tools as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Tools as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/trade.json b/generated/openapi/trade.json
iindex 5393a568..a9f01427 100644
---- a/generated/openapi/trade.json
++++ b/generated/openapi/trade.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Trade API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Trade as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Trade as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/vip.json b/generated/openapi/vip.json
iindex 58f298ad..ef05c111 100644
---- a/generated/openapi/vip.json
++++ b/generated/openapi/vip.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.VIP API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.VIP as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.VIP as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/watch.json b/generated/openapi/watch.json
iindex eb6d96c7..687205d0 100644
---- a/generated/openapi/watch.json
++++ b/generated/openapi/watch.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Watch API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Watch as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Watch as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/openapi/wiki.json b/generated/openapi/wiki.json
iindex a02cf84f..12d92641 100644
---- a/generated/openapi/wiki.json
++++ b/generated/openapi/wiki.json
@@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
    "title": "OpenVibe.Wiki API",
--  "version": "0.128.1",
--  "description": "Routes of OpenVibe.Wiki as the OpenVibe contracts describe them (openvibe-contracts 0.128.1): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
++  "version": "0.128.2",
++  "description": "Routes of OpenVibe.Wiki as the OpenVibe contracts describe them (openvibe-contracts 0.128.2): each operation lists the capabilities it performs; a token for the service's audience must carry one of them unless the route is open. Generated by openvibe-contracts lib/openapi.js; do not edit.",
    "license": {
     "name": "MIT",
     "identifier": "MIT"
ddiff --git a/generated/typescript/index.d.ts b/generated/typescript/index.d.ts
iindex abe86881..3280d8b3 100644
---- a/generated/typescript/index.d.ts
++++ b/generated/typescript/index.d.ts
@@@ -11203,7 +11203,7 @@ export type EventsReadRequest =
  
  /** [email protected] (owner: events) */
  /**
-- * events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, gap? } (keep next_after_seq as the cursor: it moves past events that did not match; gap { from_seq, to_seq } says events after after_seq were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.
++ * events.read-result@1: answers of the pull API on OpenVibe.Events. GET /api/v1/events → { events: [{ seq, cursor?, event }], next_after_seq, next_cursor?, latest_seq, latest_cursor?, gap? } (keep next_cursor as the position and read on with after=: it moves past events that did not match; latest_cursor is the head, for a consumer that starts at now; the numeric after_seq, next_after_seq and latest_seq remain only until every consumer reads by cursor (plan T7); gap { from_seq, to_seq } says events after the position were already pruned by retention); GET /api/v1/events/:event_id → { seq, event }; GET|PUT /api/v1/checkpoints → { consumer, topic, cursor, updated_at } (cursor 0 and updated_at null when none is stored). GET /realtime/stream?topics= (events.event.read) is a Server-Sent Events feed whose messages carry the same { seq, event } (id: the cursor once Events sends one, else the seq; a gap message when the cursor is older than retention). An app sees only its project's events in its token's environment plus public first-party events.
   */
  export type EventsReadResult =
    | {
@@@ -11228,6 +11228,10 @@ export type EventsReadResult =
         * Opaque position after this page (ADR-042): pass it back as after= for the next page. Returned beside next_after_seq for one release.
         */
        next_cursor?: string;
++      /**
++       * The head as an opaque cursor (ADR-042): a consumer that starts at now stores it and reads on with after=, never needing latest_seq.
++       */
++      latest_cursor?: string;
      }
    | {
        seq: number;
ddiff --git a/package.json b/package.json
iindex 3a3cbd54..2f795efb 100644
---- a/package.json
++++ b/package.json
@@@ -1,6 +1,6 @@
  {
    "name": "openvibe-contracts",
--  "version": "0.128.1",
++  "version": "0.128.2",
    "description": "Machine-readable contracts for the OpenVibe network: schemas, manifests, ids, error envelope, capability checks.",
    "main": "index.js",
    "types": "generated/typescript/index.d.ts",