From 09db86340487c4696c23eea1886c570d27099e82 Mon Sep 17 00:00:00 2001
From: Henry Stern <henry@stern.ca>
Date: Sun, 21 Jun 2026 08:12:35 -0300
Subject: [PATCH] Clarify that RegisterEventType is the sole registration entry
 point
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spell out, in the RegisterEventType godoc and the README, that an event
vocabulary registers via a single RegisterEventType call per event type
placed in the package's init function — and that init is where the call
goes, not an alternative registration API. Frames it as the database/sql
driver idiom so an implementor reaches for the side-effect-import wiring
without second-guessing whether there is a non-init path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md   |  9 ++++++---
 registry.go | 12 +++++++++---
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 5daa4dc..ea22af4 100644
--- a/README.md
+++ b/README.md
@@ -127,9 +127,12 @@ is held as a `subjectid.SubjectIdentifier`, parsed and validated there.
 ### Register an event type
 
 An event vocabulary (such as OpenID CAEP or RISC) implements the `Event`
-interface for its payload and registers a decoder for its event-type URI,
-customarily from an `init` function so a side-effect import wires the whole
-vocabulary in. Registration is process-wide and permanent.
+interface for its payload and registers a decoder for its event-type URI.
+`RegisterEventType` is the only registration call — place it in the vocabulary
+package's `init` function (`init` is *where* you register, not an alternative
+to registering) so a single side-effect import wires the whole vocabulary in,
+the same idiom as `database/sql` drivers. Registration is process-wide and
+permanent.
 
 ```go
 const sessionRevokedURI = "https://schemas.openid.net/secevent/caep/event-type/session-revoked"
diff --git a/registry.go b/registry.go
index a2408b5..62e91ed 100644
--- a/registry.go
+++ b/registry.go
@@ -43,9 +43,15 @@ var eventRegistry = struct {
 
 // RegisterEventType registers decode as the decoder for the given event-type
 // URI, making LookupEventType (and the typed-access helpers built on it) able
-// to turn that event's raw payload bytes into a typed Event. An event
-// vocabulary calls this once per event type it defines, customarily from a
-// package init function so a side-effect import wires the whole vocabulary in.
+// to turn that event's raw payload bytes into a typed Event.
+//
+// This is the only registration mechanism. An event vocabulary makes one
+// RegisterEventType call per event type it defines and places those calls in
+// the vocabulary package's init function. The init function is not an
+// alternative to RegisterEventType — it is simply where the call goes, so that
+// a consumer can wire the whole vocabulary in with a single side-effect import
+// (import _ "example.com/your-vocabulary"), the same idiom as database/sql
+// drivers and image-format decoders.
 //
 // Registration is process-wide and permanent: there is no unregister. The uri
 // must be the same string the event's EventTypeURI method returns.