EventCoordinate should own its persistenceId|sequenceNr string format #47

New issue

Open

opened 2026-08-30 10:45:09 +00:00 by mph · 0 comments

mph commented

2026-08-30 10:45:09 +00:00

Owner

EventCoordinate has a wire format — persistenceId|sequenceNr — but no owner for it.
Every consumer that needs to put a coordinate into a string (a Mongo _id, an HTTP path
segment) has to reinvent the serialize/parse pair, and each reinvention is a place where a
malformed input can throw instead of decoding into an error.

Trigger. In mdr-poptavky (MEDECA-447) the format was reimplemented at four call sites —
two TimelineDoc.idOf and two tapir Codec[String, EventCoordinate, ...] path codecs. Code
review flagged it as duplication. EventCoordinate is monomorphic, so there is nothing
per-module about the format and no reason for four copies. The project consolidated them into a
project-local model/shared/src/main/scala/mdr/EventCoordinateFormat.scala with serialize /
parse, where parse returns an Option and rejects a negative sequenceNr (a journal
sequence number is never negative, and toLongOption alone accepted -5).

Ask. EventCoordinate's companion object should carry the format itself — serialize /
parse, or a Codec — so consumers delegate instead of reimplementing. Once released, the
project-local mdr.EventCoordinateFormat is retired.

Reference implementation (project-local, to be superseded):
model/shared/src/main/scala/mdr/EventCoordinateFormat.scala and its spec
model/shared/src/test/scala/mdr/EventCoordinateFormatSpec.scala in
CMI/mdr/medeca-modul-poptavky, branch MEDECA-447. parse must reject a negative
sequenceNr, so the round trip is total in one direction only.

Raised from MEDECA-447 lesson triage.

`EventCoordinate` has a wire format — `persistenceId|sequenceNr` — but no owner for it. Every consumer that needs to put a coordinate into a string (a Mongo `_id`, an HTTP path segment) has to reinvent the serialize/parse pair, and each reinvention is a place where a malformed input can throw instead of decoding into an error. **Trigger.** In `mdr-poptavky` (MEDECA-447) the format was reimplemented at four call sites — two `TimelineDoc.idOf` and two tapir `Codec[String, EventCoordinate, ...]` path codecs. Code review flagged it as duplication. `EventCoordinate` is monomorphic, so there is nothing per-module about the format and no reason for four copies. The project consolidated them into a project-local `model/shared/src/main/scala/mdr/EventCoordinateFormat.scala` with `serialize` / `parse`, where `parse` returns an `Option` and rejects a negative `sequenceNr` (a journal sequence number is never negative, and `toLongOption` alone accepted `-5`). **Ask.** `EventCoordinate`'s companion object should carry the format itself — `serialize` / `parse`, or a `Codec` — so consumers delegate instead of reimplementing. Once released, the project-local `mdr.EventCoordinateFormat` is retired. **Reference implementation** (project-local, to be superseded): `model/shared/src/main/scala/mdr/EventCoordinateFormat.scala` and its spec `model/shared/src/test/scala/mdr/EventCoordinateFormatSpec.scala` in `CMI/mdr/medeca-modul-poptavky`, branch `MEDECA-447`. `parse` must reject a negative `sequenceNr`, so the round trip is total in one direction only. Raised from MEDECA-447 lesson triage.