Publish HyperMeow as its own Go module

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: go-imports-repo
         args:
           - "-local"
-          - "go.mau.fi/whatsmeow"
+          - "github.com/polymorfa/hypermeow"
           - "-w"
       - id: go-vet-repo-mod
       # TODO enable this

README.md

@@ -1,9 +1,57 @@
 # HyperMeow
-[![Go Reference](https://pkg.go.dev/badge/github.com/polymorfa/whatsmeow.svg)](https://pkg.go.dev/github.com/polymorfa/whatsmeow)
+[![Go Reference](https://pkg.go.dev/badge/github.com/polymorfa/hypermeow.svg)](https://pkg.go.dev/github.com/polymorfa/hypermeow)
 
 HyperMeow is a library used at Polymorfa to ship WhatsApp at scale. We forked from tulir's project since these performance changes are somewhat experimental and diverge from tulir's minimalist philosophy. For Polymorfa to succeed, we needed all the WhatsApp Web functions in one place, meanwhile tulir prefers the core functionalities / messaging be the scope of whatsmeow.
 
-The module path and package names remain `go.mau.fi/whatsmeow` for compatibility. Consumers can test HyperMeow with a Go module `replace` directive while the fork is validated against upstream behavior.
+HyperMeow is its own Go module, imported directly as `github.com/polymorfa/hypermeow`. It no longer requires a `replace` directive:
+
+```go
+import whatsmeow "github.com/polymorfa/hypermeow"
+```
+
+```sh
+go get github.com/polymorfa/hypermeow
+```
+
+### The module is `hypermeow`, the package is `whatsmeow`
+
+Only the *module path* moved. The Go *package* names are unchanged from upstream, so the root package is still declared `package whatsmeow`. Both of these are expected:
+
+- godoc renders the title as **"whatsmeow package - github.com/polymorfa/hypermeow"**;
+- the import path's last element (`hypermeow`) does not match the package name (`whatsmeow`), so import the root package under an explicit alias as shown above.
+
+This is deliberate. Keeping the upstream package names means no call site changes when migrating - `whatsmeow.Client`, `whatsmeow.NewClient` and friends all still resolve - and merges from tulir's upstream do not conflict on the package clause of every file. Sub-packages are unaffected, since their path element already matches their package name (`.../store` is `package store`, and so on).
+
+### Only one whatsmeow may be linked into a binary
+
+HyperMeow keeps upstream's generated protobuf descriptor paths (`waCommon/WACommon.proto` and friends) and their symbol namespaces. Those are registered in a process-global registry, so linking HyperMeow **and** upstream `go.mau.fi/whatsmeow` into the same binary panics before `main`:
+
+```
+proto: file "waCommon/WACommon.proto" is already registered
+```
+
+The old `replace` arrangement made this impossible, because both import paths resolved to one module. A distinct module path removes that guarantee, so a partially migrated dependency graph — where one of your dependencies still requires `go.mau.fi/whatsmeow` — is not safe.
+
+The failure is loud and immediate rather than silent, but it surfaces at process start. Check for it at build time instead:
+
+```sh
+go mod why -m go.mau.fi/whatsmeow   # should report the module is not needed
+```
+
+Use `-m`. Without it, `go mod why` asks about the *package* `go.mau.fi/whatsmeow`, and a dependency that imports only a subpackage — say `go.mau.fi/whatsmeow/proto/waCommon` — makes it answer "main module does not need package" while the upstream module is linked and its descriptors still collide.
+
+A stricter check inspects the link graph directly:
+
+```sh
+deps="$(go list -deps -test ./...)" || exit 1
+case "$deps" in *go.mau.fi/whatsmeow*) exit 1 ;; esac
+```
+
+Exit 0 means safe. There is deliberately no pipeline and no external command here. `-test` matters because `go list -deps` omits test-only dependencies, and a project importing upstream only from a `_test.go` still links both copies under `go test`. Capturing the output first means a failed `go list` propagates through `||` instead of being mistaken for an empty result, and matching with `case` avoids `grep`, whose exit status is 0 on a match — so a naive form of this check passes precisely when the graph is unsafe.
+
+or assert it in a test via `debug.ReadBuildInfo()`, failing if any entry in `Deps` reports the module path `go.mau.fi/whatsmeow`.
+
+Migrating from the previous `replace go.mau.fi/whatsmeow => github.com/polymorfa/hypermeow` setup: drop the `replace` line, add a normal `require` on `github.com/polymorfa/hypermeow`, and rewrite `go.mau.fi/whatsmeow` import paths to `github.com/polymorfa/hypermeow`. A `replace` directive is only honoured in the main module, so the previous arrangement did not carry to anything that depended on your module in turn; a direct requirement does.
 
 The reproducible Barback and PostgreSQL benchmark is documented in [`benchmark/barback`](benchmark/barback/README.md).
 
@@ -13,8 +61,8 @@ Discord server (#hypermeow channel): https://whiskey.so/discord
 
 ## Usage
 
-The [godoc](https://pkg.go.dev/github.com/polymorfa/whatsmeow) includes docs for all methods and event types.
-There's also a [simple example](https://pkg.go.dev/github.com/polymorfa/whatsmeow#example-package) at the top.
+The [godoc](https://pkg.go.dev/github.com/polymorfa/hypermeow) includes docs for all methods and event types.
+There's also a [simple example](https://pkg.go.dev/github.com/polymorfa/hypermeow#example-package) at the top.
 
 ## Features
 

appstate.go

@@ -17,13 +17,13 @@ import (
 	"go.mau.fi/util/exslices"
 	"go.mau.fi/util/ptr"
 
-	"go.mau.fi/whatsmeow/appstate"
-	waBinary "go.mau.fi/whatsmeow/binary"
-	"go.mau.fi/whatsmeow/proto/waE2E"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/store"
-	"go.mau.fi/whatsmeow/types"
-	"go.mau.fi/whatsmeow/types/events"
+	"github.com/polymorfa/hypermeow/appstate"
+	waBinary "github.com/polymorfa/hypermeow/binary"
+	"github.com/polymorfa/hypermeow/proto/waE2E"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/store"
+	"github.com/polymorfa/hypermeow/types"
+	"github.com/polymorfa/hypermeow/types/events"
 )
 
 // FetchAppState fetches updates to the given type of app state. If fullSync is true, the current

appstate/decode.go

@@ -17,11 +17,11 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	waBinary "go.mau.fi/whatsmeow/binary"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/proto/waSyncAction"
-	"go.mau.fi/whatsmeow/store"
-	"go.mau.fi/whatsmeow/util/cbcutil"
+	waBinary "github.com/polymorfa/hypermeow/binary"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/proto/waSyncAction"
+	"github.com/polymorfa/hypermeow/store"
+	"github.com/polymorfa/hypermeow/util/cbcutil"
 )
 
 // PatchList represents a decoded response to getting app state patches from the WhatsApp servers.

appstate/encode.go

@@ -9,11 +9,11 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow/proto/waCommon"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/proto/waSyncAction"
-	"go.mau.fi/whatsmeow/types"
-	"go.mau.fi/whatsmeow/util/cbcutil"
+	"github.com/polymorfa/hypermeow/proto/waCommon"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/proto/waSyncAction"
+	"github.com/polymorfa/hypermeow/types"
+	"github.com/polymorfa/hypermeow/util/cbcutil"
 )
 
 // MutationInfo contains information about a single mutation to the app state.

appstate/encode_label_test.go

@@ -3,7 +3,7 @@ package appstate
 import (
 	"testing"
 
-	"go.mau.fi/whatsmeow/types"
+	"github.com/polymorfa/hypermeow/types"
 )
 
 func TestBuildLabelChatChangesUsesOnePatch(t *testing.T) {

appstate/hash.go

@@ -14,9 +14,9 @@ import (
 	"fmt"
 	"hash"
 
-	"go.mau.fi/whatsmeow/appstate/lthash"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/proto/waSyncAction"
+	"github.com/polymorfa/hypermeow/appstate/lthash"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/proto/waSyncAction"
 )
 
 type Mutation struct {

appstate/keys.go

@@ -12,9 +12,9 @@ import (
 	"encoding/base64"
 	"sync"
 
-	"go.mau.fi/whatsmeow/store"
-	"go.mau.fi/whatsmeow/util/hkdfutil"
-	waLog "go.mau.fi/whatsmeow/util/log"
+	"github.com/polymorfa/hypermeow/store"
+	"github.com/polymorfa/hypermeow/util/hkdfutil"
+	waLog "github.com/polymorfa/hypermeow/util/log"
 )
 
 // WAPatchName represents a type of app state patch.

appstate/lthash/lthash.go

@@ -13,7 +13,7 @@ package lthash
 import (
 	"encoding/binary"
 
-	"go.mau.fi/whatsmeow/util/hkdfutil"
+	"github.com/polymorfa/hypermeow/util/hkdfutil"
 )
 
 type LTHash struct {

appstate/recovery.go

@@ -17,10 +17,10 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow/proto/waE2E"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/proto/waSyncdSnapshotRecovery"
-	"go.mau.fi/whatsmeow/store"
+	"github.com/polymorfa/hypermeow/proto/waE2E"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/proto/waSyncdSnapshotRecovery"
+	"github.com/polymorfa/hypermeow/store"
 )
 
 func ParseRecovery(

appstate_label_events_test.go

@@ -7,10 +7,10 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow/appstate"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/proto/waSyncAction"
-	"go.mau.fi/whatsmeow/types/events"
+	"github.com/polymorfa/hypermeow/appstate"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/proto/waSyncAction"
+	"github.com/polymorfa/hypermeow/types/events"
 )
 
 func TestSelectiveFullSyncLabelEvents(t *testing.T) {

armadillomessage.go

@@ -12,14 +12,14 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	armadillo "go.mau.fi/whatsmeow/proto"
-	"go.mau.fi/whatsmeow/proto/armadilloutil"
-	"go.mau.fi/whatsmeow/proto/instamadilloTransportPayload"
-	"go.mau.fi/whatsmeow/proto/waCommon"
-	"go.mau.fi/whatsmeow/proto/waMsgApplication"
-	"go.mau.fi/whatsmeow/proto/waMsgTransport"
-	"go.mau.fi/whatsmeow/types"
-	"go.mau.fi/whatsmeow/types/events"
+	armadillo "github.com/polymorfa/hypermeow/proto"
+	"github.com/polymorfa/hypermeow/proto/armadilloutil"
+	"github.com/polymorfa/hypermeow/proto/instamadilloTransportPayload"
+	"github.com/polymorfa/hypermeow/proto/waCommon"
+	"github.com/polymorfa/hypermeow/proto/waMsgApplication"
+	"github.com/polymorfa/hypermeow/proto/waMsgTransport"
+	"github.com/polymorfa/hypermeow/types"
+	"github.com/polymorfa/hypermeow/types/events"
 )
 
 func (cli *Client) handleDecryptedArmadillo(ctx context.Context, info *types.MessageInfo, decrypted []byte, retryCount int) (handlerFailed, protobufFailed bool) {

benchmark/barback/Dockerfile

@@ -7,7 +7,7 @@ WORKDIR /src
 COPY . .
 COPY --from=library . /library
 WORKDIR /src/benchmark/barback
-RUN go mod edit -replace=go.mau.fi/whatsmeow=/library
+RUN go mod edit -replace=github.com/polymorfa/hypermeow=/library
 RUN --mount=type=cache,target=/go/pkg/mod go mod tidy
 RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,target=/root/.cache/go-build \
     CGO_ENABLED=0 go build -tags="${BENCH_BUILD_TAGS}" -trimpath -ldflags="-s -w -X main.revision=${BUILD_REV}" -o /out/hypermeow-bench ./cmd/bench

benchmark/barback/Dockerfile.clientmem

@@ -6,7 +6,7 @@ WORKDIR /src
 COPY . .
 COPY --from=library . /library
 WORKDIR /src/benchmark/barback
-RUN go mod edit -replace=go.mau.fi/whatsmeow=/library
+RUN go mod edit -replace=github.com/polymorfa/hypermeow=/library
 RUN --mount=type=cache,target=/go/pkg/mod go mod tidy
 RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,target=/root/.cache/go-build \
     CGO_ENABLED=0 go build -trimpath -ldflags="-s -w -X main.revision=${BUILD_REV}" -o /out/clientmem ./cmd/clientmem

benchmark/barback/cmd/bench/business_app_smoke.go

@@ -6,8 +6,8 @@ import (
 	"context"
 	"fmt"
 
-	"go.mau.fi/whatsmeow"
-	"go.mau.fi/whatsmeow/types"
+	whatsmeow "github.com/polymorfa/hypermeow"
+	"github.com/polymorfa/hypermeow/types"
 )
 
 func businessAppSmokeSupported() bool {

benchmark/barback/cmd/bench/business_app_smoke_legacy.go

@@ -5,7 +5,7 @@ package main
 import (
 	"context"
 
-	"go.mau.fi/whatsmeow"
+	whatsmeow "github.com/polymorfa/hypermeow"
 )
 
 func businessAppSmokeSupported() bool {

benchmark/barback/cmd/bench/main.go

@@ -28,12 +28,12 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow"
-	"go.mau.fi/whatsmeow/proto/waE2E"
-	"go.mau.fi/whatsmeow/store/sqlstore"
-	"go.mau.fi/whatsmeow/types"
-	"go.mau.fi/whatsmeow/types/events"
-	waLog "go.mau.fi/whatsmeow/util/log"
+	whatsmeow "github.com/polymorfa/hypermeow"
+	"github.com/polymorfa/hypermeow/proto/waE2E"
+	"github.com/polymorfa/hypermeow/store/sqlstore"
+	"github.com/polymorfa/hypermeow/types"
+	"github.com/polymorfa/hypermeow/types/events"
+	waLog "github.com/polymorfa/hypermeow/util/log"
 )
 
 var revision = "working-tree"

benchmark/barback/cmd/bench/main_test.go

@@ -12,10 +12,10 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow"
-	"go.mau.fi/whatsmeow/proto/waE2E"
-	"go.mau.fi/whatsmeow/types"
-	"go.mau.fi/whatsmeow/types/events"
+	whatsmeow "github.com/polymorfa/hypermeow"
+	"github.com/polymorfa/hypermeow/proto/waE2E"
+	"github.com/polymorfa/hypermeow/types"
+	"github.com/polymorfa/hypermeow/types/events"
 )
 
 func TestLoadConfigWorkload(t *testing.T) {

benchmark/barback/cmd/bench/phone_consent_sync.go

@@ -2,7 +2,7 @@
 
 package main
 
-import "go.mau.fi/whatsmeow"
+import whatsmeow "github.com/polymorfa/hypermeow"
 
 func enablePhoneConsentReceiveBarrier(client *whatsmeow.Client) {
 	client.DangerousInternals().SetSynchronousMessageNameUpdates(true)

benchmark/barback/cmd/bench/phone_consent_sync_legacy.go

@@ -2,6 +2,6 @@
 
 package main
 
-import "go.mau.fi/whatsmeow"
+import whatsmeow "github.com/polymorfa/hypermeow"
 
 func enablePhoneConsentReceiveBarrier(_ *whatsmeow.Client) {}

benchmark/barback/cmd/bench/security_code_smoke.go

@@ -9,9 +9,9 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow"
-	"go.mau.fi/whatsmeow/proto/waFingerprint"
-	"go.mau.fi/whatsmeow/types"
+	whatsmeow "github.com/polymorfa/hypermeow"
+	"github.com/polymorfa/hypermeow/proto/waFingerprint"
+	"github.com/polymorfa/hypermeow/types"
 )
 
 func validateIdentityVerificationCodes(ctx context.Context, client *whatsmeow.Client, userID types.JID) error {

benchmark/barback/cmd/bench/security_code_smoke_legacy.go

@@ -5,8 +5,8 @@ package main
 import (
 	"context"
 
-	"go.mau.fi/whatsmeow"
-	"go.mau.fi/whatsmeow/types"
+	whatsmeow "github.com/polymorfa/hypermeow"
+	"github.com/polymorfa/hypermeow/types"
 )
 
 func validateIdentityVerificationCodes(context.Context, *whatsmeow.Client, types.JID) error {

benchmark/barback/cmd/bench/security_code_smoke_legacy_test.go

@@ -6,7 +6,7 @@ import (
 	"context"
 	"testing"
 
-	"go.mau.fi/whatsmeow/types"
+	"github.com/polymorfa/hypermeow/types"
 )
 
 func TestLegacySecurityCodeValidationIsSkipped(t *testing.T) {

benchmark/barback/cmd/bench/workload_messages.go

@@ -9,9 +9,9 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow"
-	"go.mau.fi/whatsmeow/proto/waCommon"
-	"go.mau.fi/whatsmeow/proto/waE2E"
+	whatsmeow "github.com/polymorfa/hypermeow"
+	"github.com/polymorfa/hypermeow/proto/waCommon"
+	"github.com/polymorfa/hypermeow/proto/waE2E"
 )
 
 var (

benchmark/barback/cmd/clientmem/main.go

@@ -9,9 +9,9 @@ import (
 	"strconv"
 	"syscall"
 
-	"go.mau.fi/whatsmeow"
-	"go.mau.fi/whatsmeow/store"
-	waLog "go.mau.fi/whatsmeow/util/log"
+	whatsmeow "github.com/polymorfa/hypermeow"
+	"github.com/polymorfa/hypermeow/store"
+	waLog "github.com/polymorfa/hypermeow/util/log"
 )
 
 var revision = "working-tree"

benchmark/barback/go.mod

@@ -6,7 +6,7 @@ toolchain go1.26.5
 
 require (
 	github.com/jackc/pgx/v5 v5.10.0
-	go.mau.fi/whatsmeow v0.0.0
+	github.com/polymorfa/hypermeow v0.0.0
 	google.golang.org/protobuf v1.36.11
 )
 
@@ -31,4 +31,4 @@ require (
 	golang.org/x/text v0.40.0 // indirect
 )
 
-replace go.mau.fi/whatsmeow => ../..
+replace github.com/polymorfa/hypermeow => ../..