refactor: adopt golang-standards/project-layout (#111)

* 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>

* chore: cleanup

* fix: repair references to removed utils package

nwaku_test_utils.go now uses pkg/kernel/utils.GetRSSKB; the memory_record
tool is self-contained (local helpers, missing mutex restored).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

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
     ```

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,3 @@
+// Package kernel is the low-level Go wrapper over the logos-delivery Kernel API
+// (libwaku): relay, store, lightpush, filter, peer management, discovery.
+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/utils"
-	"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/logos-messaging/logos-delivery-go-bindings/pkg/kernel/utils"
 	"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,5 @@
+// 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).
+package messaging

tools/memory_record.go

@@ -1,18 +1,23 @@
 package main
 
 import (
+	"encoding/csv"
 	"flag"
 	"fmt"
+	"io"
 	"os"
 	"runtime"
-
-	"github.com/logos-messaging/logos-delivery-go-bindings/utils"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
 )
 
 var (
 	testName  string
 	iteration int
 	phase     string
+	mu        sync.Mutex
 )
 
 func main() {
@@ -25,14 +30,72 @@ func main() {
 	runtime.ReadMemStats(&memStats)
 	heapKB := memStats.HeapAlloc / 1024
 
-	rssKB, err := utils.GetRSSKB()
+	rssKB, err := GetRSSKB()
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "Failed to get RSS:", err)
 		rssKB = 0
 	}
 
-	if err := utils.RecordMemoryMetricsCSV(testName, iteration, phase, heapKB, rssKB); err != nil {
+	if err := RecordMemoryMetricsCSV(testName, iteration, phase, heapKB, rssKB); err != nil {
 		fmt.Fprintln(os.Stderr, "Error recording metrics:", err)
 		os.Exit(1)
 	}
 }
+
+func RecordMemoryMetricsCSV(testName string, iter int, phase string, heapKB, rssKB uint64) error {
+	mu.Lock()
+	defer mu.Unlock()
+
+	f, err := os.OpenFile("memory_metrics.csv", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = f.Close() }()
+
+	w := csv.NewWriter(f)
+	defer w.Flush()
+
+	stat, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	if stat.Size() == 0 {
+		header := []string{"TestName", "Iteration", "Phase", "HeapAlloc(KB)", "RSS(KB)", "Timestamp"}
+		if err := w.Write(header); err != nil {
+			return err
+		}
+	}
+
+	row := []string{
+		testName,
+		strconv.Itoa(iter),
+		phase,
+		strconv.FormatUint(heapKB, 10),
+		strconv.FormatUint(rssKB, 10),
+		time.Now().Format(time.RFC3339),
+	}
+
+	return w.Write(row)
+}
+
+func GetRSSKB() (uint64, error) {
+	f, err := os.Open("/proc/self/statm")
+	if err != nil {
+		return 0, err
+	}
+	defer func() { _ = f.Close() }()
+	data, err := io.ReadAll(f)
+	if err != nil {
+		return 0, err
+	}
+	fields := strings.Fields(string(data))
+	if len(fields) < 2 {
+		return 0, fmt.Errorf("unexpected /proc/self/statm format")
+	}
+	rssPages, err := strconv.ParseUint(fields[1], 10, 64)
+	if err != nil {
+		return 0, err
+	}
+	pageSize := os.Getpagesize()
+	return (rssPages * uint64(pageSize)) / 1024, nil
+}

utils/utils.go

@@ -1,77 +0,0 @@
-package utils
-
-import (
-	"encoding/csv"
-	"fmt"
-	"io"
-	"os"
-	"strconv"
-	"strings"
-	"sync"
-	"time"
-)
-
-var (
-	testName  string
-	iteration int
-	phase     string
-	mu        sync.Mutex
-)
-
-func RecordMemoryMetricsCSV(testName string, iter int, phase string, heapKB, rssKB uint64) error {
-	mu.Lock()
-	defer mu.Unlock()
-
-	f, err := os.OpenFile("memory_metrics.csv", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
-	if err != nil {
-		return err
-	}
-	defer f.Close()
-
-	w := csv.NewWriter(f)
-	defer w.Flush()
-
-	stat, err := f.Stat()
-	if err != nil {
-		return err
-	}
-	if stat.Size() == 0 {
-		header := []string{"TestName", "Iteration", "Phase", "HeapAlloc(KB)", "RSS(KB)", "Timestamp"}
-		if err := w.Write(header); err != nil {
-			return err
-		}
-	}
-
-	row := []string{
-		testName,
-		strconv.Itoa(iter),
-		phase,
-		strconv.FormatUint(heapKB, 10),
-		strconv.FormatUint(rssKB, 10),
-		time.Now().Format(time.RFC3339),
-	}
-
-	return w.Write(row)
-}
-
-func GetRSSKB() (uint64, error) {
-	f, err := os.Open("/proc/self/statm")
-	if err != nil {
-		return 0, err
-	}
-	defer f.Close()
-	data, err := io.ReadAll(f)
-	if err != nil {
-		return 0, err
-	}
-	fields := strings.Fields(string(data))
-	if len(fields) < 2 {
-		return 0, fmt.Errorf("unexpected /proc/self/statm format")
-	}
-	rssPages, err := strconv.ParseUint(fields[1], 10, 64)
-	if err != nil {
-		return 0, err
-	}
-	pageSize := os.Getpagesize()
-	return (rssPages * uint64(pageSize)) / 1024, nil
-}