refactor: adopt golang-standards/project-layout

Move the legacy kernel wrapper `waku/*` to `pkg/kernel/*` and rename its
package `waku` -> `kernel`; nothing outside the package imported it, so this is
a mechanical import-path/prefix change. Update the relocated Makefile's
relative dep path, the legacy CI workflows (CI/endurance/repeated) build paths,
README, and .gitignore accordingly (preserving the libwaku-cache CI from #109).

Add scaffolding for the upcoming Messaging API work: `internal/ffi` (cgo
bridge), `pkg/messaging` (high-level Node API), and `examples/`. Document
`pkg/kernel` as legacy until logos-delivery#3851 consolidates the C libraries.

Also stop tracking the accidentally-committed `waku-bindings` build artifact
and gitignore the kernel build output.

No behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.github/workflows/CI.yml

@@ -33,10 +33,10 @@ jobs:
           cd ../..
 
       - name: Verify paths
-        run: make -C waku print-paths
+        run: make -C pkg/kernel print-paths
 
       - name: Verify libwaku artifacts
-        run: make -C waku check-folders
+        run: make -C pkg/kernel check-folders
 
       - name: Install Go dependencies
         run: |
@@ -49,7 +49,7 @@ jobs:
           export LOGOS_DELIVERY_DIR=$(pwd)/vendor/logos-delivery
           export CGO_CFLAGS="-I${LOGOS_DELIVERY_DIR}/library/"
           export CGO_LDFLAGS="-L${LOGOS_DELIVERY_DIR}/build/ -lwaku -Wl,-rpath,${LOGOS_DELIVERY_DIR}/build/" 
-          make -C waku build
+          make -C pkg/kernel build
 
       - name: Increase ulimit
         run: sudo sh -c "ulimit -n 8192"
@@ -57,8 +57,7 @@ jobs:
       - name: Run daily test
         run: |
           set -euo pipefail
-          cd waku
-          export LOGOS_DELIVERY_DIR=$(pwd)/vendor/logos-delivery
+          cd pkg/kernel          export LOGOS_DELIVERY_DIR=$(pwd)/vendor/logos-delivery
           export CGO_CFLAGS="-I${LOGOS_DELIVERY_DIR}/library/"
           export CGO_LDFLAGS="-L${LOGOS_DELIVERY_DIR}/build/ -lwaku -Wl,-rpath,${LOGOS_DELIVERY_DIR}/build/"
           go test -count=10 -p=1 -v -timeout=360m . | tee ../testlogs.log

.github/workflows/CI_endurance.yml

@@ -39,7 +39,7 @@ jobs:
           make libwaku
 
       - name: Build waku bindings
-        run: make -C waku build
+        run: make -C pkg/kernel build
 
       - name: Increase ulimit
         run: sudo sh -c "ulimit -n 8192"
@@ -49,7 +49,7 @@ jobs:
         run: |
           set -euo pipefail
           go test -tags stress  \
-          -p=1 -v ./waku -count=1 -timeout=360m -run '^(TestStressMemoryUsageForThreeNodes|TestStressStoreQuery5kMessagesWithPagination|TestStressHighThroughput10kPublish|TestStressLargePayloadEphemeralMessagesEndurance|TestStressConnectDisconnect1kIteration)$' | tee testlogs1.log
+          -p=1 -v ./pkg/kernel -count=1 -timeout=360m -run '^(TestStressMemoryUsageForThreeNodes|TestStressStoreQuery5kMessagesWithPagination|TestStressHighThroughput10kPublish|TestStressLargePayloadEphemeralMessagesEndurance|TestStressConnectDisconnect1kIteration)$' | tee testlogs1.log
 
       - name: Upload Test Logs (Group 1)
         uses: actions/upload-artifact@v4
@@ -98,7 +98,7 @@ jobs:
           make libwaku
 
       - name: Build waku bindings
-        run: make -C waku build
+        run: make -C pkg/kernel build
 
       - name: Increase ulimit
         run: sudo sh -c "ulimit -n 8192"
@@ -109,7 +109,7 @@ jobs:
         run: |
           set -euo pipefail
           go test -tags stress \
-          -p=1 -v ./waku -count=1 -timeout=360m -run '^(TestStressRandomNodesInMesh|TestStress2Nodes2kIterationTearDown|TestPeerExchangePXLoad)$' | tee testlogs2.log
+          -p=1 -v ./pkg/kernel -count=1 -timeout=360m -run '^(TestStressRandomNodesInMesh|TestStress2Nodes2kIterationTearDown|TestPeerExchangePXLoad)$' | tee testlogs2.log
 
       - name: Upload Test Logs (Group 2)
         uses: actions/upload-artifact@v4

.github/workflows/Repeated_tests_endurancce.yml

@@ -39,7 +39,7 @@ jobs:
           make libwaku
 
       - name: Build waku bindings
-        run: make -C waku build
+        run: make -C pkg/kernel build
 
       - name: Clean environment
         run: go clean -cache

.gitignore

@@ -23,15 +23,18 @@ go.work
 # Generated dependencies and cache
 nimcache
 
-waku/store.sqlite3
+pkg/kernel/store.sqlite3
 
-waku/store.sqlite3-shm
+pkg/kernel/store.sqlite3-shm
 
-waku/store.sqlite3-wal
+pkg/kernel/store.sqlite3-wal
 
-waku/test_repeated_start_stop.log
+pkg/kernel/test_repeated_start_stop.log
 
 third_party/
 
 # JetBrains IDEs
-.idea/
+.idea/
+# Kernel bindings build output
+/pkg/kernel/kernel-bindings
+/pkg/kernel/waku-bindings

README.md

@@ -23,13 +23,13 @@ export CGO_CFLAGS="-I${LOGOS_DELIVERY_DIR}/library"
 export CGO_LDFLAGS="-L${LOGOS_DELIVERY_DIR}/build -lwaku -Wl,-rpath,${LOGOS_DELIVERY_DIR}/build"
 
 # compile all packages
-make -C waku build
+make -C pkg/kernel build
 
 # run all tests
-make -C waku test
+make -C pkg/kernel test
 
 # run a specific test
-make -C waku test TEST=TestConnectedPeersInfo
+make -C pkg/kernel test TEST=TestConnectedPeersInfo
 ```
 
 ## Development
@@ -39,9 +39,9 @@ When working on this repository itself, `logos-delivery` is included as a git su
 - Initialize and update the submodule, then build `libwaku`
     ```sh
     git submodule update --init --recursive
-    make -C waku build-libwaku
+    make -C pkg/kernel build-libwaku
     ```
 - Build the project. Submodule paths are used by default to find `libwaku`.
     ```shell
-    make -C waku build
+    make -C pkg/kernel build
     ```

examples/README.md

@@ -0,0 +1,6 @@
+# Examples
+
+Runnable examples for the Go bindings.
+
+A `messaging/` example (create a node, subscribe, send, print received events)
+will be added alongside the Messaging API implementation.

internal/ffi/doc.go

@@ -0,0 +1,8 @@
+// Package ffi holds the cgo bridge over the logos-delivery C libraries: the
+// synchronous request/callback plumbing, the global event callback, and the
+// handle registry. It exposes Go-typed primitives so the public packages
+// (e.g. messaging) stay pure Go.
+//
+// Scaffolding only for now; the Messaging API bindings land here (over
+// liblogosdelivery) in a follow-up.
+package ffi

pkg/kernel/Makefile

@@ -1,7 +1,7 @@
 # Makefile for Waku Go Bindings
 
 # Path to logos-delivery submodule
-export LOGOS_DELIVERY_DIR ?= $(shell pwd)/../vendor/logos-delivery
+export LOGOS_DELIVERY_DIR ?= $(shell pwd)/../../vendor/logos-delivery
 
 # Debugging output
 print-paths:
@@ -52,7 +52,7 @@ check-folders:
 
 build:
 	@echo "Building Logos Messaging Go Bindings (manual)..."
-	CGO_CFLAGS="$(CGO_CFLAGS)" CGO_LDFLAGS="$(CGO_LDFLAGS)" go build -o waku-bindings .
+	CGO_CFLAGS="$(CGO_CFLAGS)" CGO_LDFLAGS="$(CGO_LDFLAGS)" go build -o kernel-bindings .
 
 test: build
 	@echo "Running tests (manual)..."
@@ -65,4 +65,4 @@ test: build
 # Clean up generated files
 clean:
 	@echo "Cleaning up..."
-	@rm -f waku-bindings
+	@rm -f kernel-bindings

pkg/kernel/common/envelope.go

@@ -3,7 +3,7 @@ package common
 import (
 	"encoding/json"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/pb"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/pb"
 )
 
 // Envelope contains information about the pubsub topic of a WakuMessage

pkg/kernel/doc.go

@@ -0,0 +1,9 @@
+// Package kernel is the low-level Go wrapper over the logos-delivery Kernel API
+// (libwaku): relay, store, lightpush, filter, peer management, discovery.
+//
+// It mirrors go-waku's shape and predates the Messaging API. It is considered
+// legacy: once logos-delivery#3851 consolidates libwaku and liblogosdelivery
+// into a single tiered library, the kernel surface will be re-pointed at that
+// library and exposed as accessors on the messaging Node rather than as a
+// standalone package. New consumers should prefer the messaging package.
+package kernel

pkg/kernel/logging.go

@@ -1,4 +1,4 @@
-package waku
+package kernel
 
 import (
 	"sync"

pkg/kernel/nodes_basic_test.go

@@ -1,10 +1,10 @@
-package waku
+package kernel
 
 import (
 	"testing"
 	"time"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
 	"github.com/stretchr/testify/require"
 )
 

pkg/kernel/nwaku.go

@@ -1,4 +1,4 @@
-package waku
+package kernel
 
 /*
 	#include <libwaku.h>
@@ -352,17 +352,17 @@ import (
 	"time"
 	"unsafe"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/timesource"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/timesource"
 
 	"github.com/ethereum/go-ethereum/crypto"
 	"github.com/ethereum/go-ethereum/p2p/enode"
 	"github.com/libp2p/go-libp2p/core/peer"
 	libp2pproto "github.com/libp2p/go-libp2p/core/protocol"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/pb"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/utils"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/pb"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/utils"
 	"github.com/multiformats/go-multiaddr"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
 )
 
 const requestTimeout = 30 * time.Second

pkg/kernel/nwaku_test.go

@@ -1,4 +1,4 @@
-package waku
+package kernel
 
 import (
 	"context"
@@ -13,9 +13,9 @@ import (
 
 	"github.com/cenkalti/backoff/v3"
 	"github.com/libp2p/go-libp2p/core/peer"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/pb"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/store"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/pb"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/store"
 	ma "github.com/multiformats/go-multiaddr"
 	"github.com/stretchr/testify/require"
 )

pkg/kernel/nwaku_test_utils.go

@@ -1,4 +1,4 @@
-package waku
+package kernel
 
 import (
 	"context"
@@ -16,9 +16,9 @@ import (
 
 	"github.com/cenkalti/backoff/v3"
 	"github.com/libp2p/go-libp2p/core/peer"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/pb"
 	"github.com/logos-messaging/logos-delivery-go-bindings/utils"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/pb"
 	"google.golang.org/protobuf/proto"
 )
 

pkg/kernel/peer_connections_test.go

@@ -1,11 +1,11 @@
-package waku
+package kernel
 
 import (
 	"slices"
 	"testing"
 	"time"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
 	"github.com/stretchr/testify/require"
 )
 

pkg/kernel/relay_test.go

@@ -1,4 +1,4 @@
-package waku
+package kernel
 
 import (
 	"fmt"
@@ -7,8 +7,8 @@ import (
 	"time"
 
 	"github.com/cenkalti/backoff/v3"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/pb"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/pb"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/protobuf/proto"
 )

pkg/kernel/store_test.go

@@ -1,4 +1,4 @@
-package waku
+package kernel
 
 import (
 	"fmt"
@@ -6,10 +6,10 @@ import (
 	"time"
 
 	"github.com/cenkalti/backoff/v3"
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/pb"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/pb"
 	"github.com/stretchr/testify/require"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
 	"google.golang.org/protobuf/proto"
 )
 

pkg/kernel/stress_test.go

@@ -1,7 +1,7 @@
 //go:build stress
 // +build stress
 
-package waku
+package kernel
 
 import (
 	"fmt"
@@ -10,7 +10,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
 	"github.com/stretchr/testify/require"
 
 	//	"go.uber.org/zap/zapcore"

pkg/kernel/test_data.go

@@ -1,10 +1,10 @@
-package waku
+package kernel
 
 import (
 	"fmt"
 	"time"
 
-	"github.com/logos-messaging/logos-delivery-go-bindings/waku/common"
+	"github.com/logos-messaging/logos-delivery-go-bindings/pkg/kernel/common"
 	"google.golang.org/protobuf/proto"
 )
 

pkg/messaging/doc.go

@@ -0,0 +1,10 @@
+// Package messaging is the high-level, idiomatic Go binding for the
+// logos-delivery Messaging API (an opinionated layer over the kernel protocols
+// that owns reliability, re-subscriptions, store-based catch-up and the
+// Messaging event surface).
+//
+// It will expose a Node type (create/start/stop, send/subscribe/unsubscribe)
+// and a unified Events channel, backed by cgo calls into liblogosdelivery via
+// the internal/ffi package. Scaffolding only for now; the implementation lands
+// in a follow-up.
+package messaging