feat(05-01): add Paginate envelope and RegisterJoinTable

- Page/PageMeta emit {data, meta} with no links key
- RegisterJoinTable fails loud on nil db; document pivot-write contract

lagoon/paginate_test.go

@@ -0,0 +1,42 @@
+package lagoon
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestPaginateEnvelope(t *testing.T) {
+	got := Paginate([]string{"a", "b", "c"}, 1, 2, 3)
+	if got.Meta.CurrentPage != 1 || got.Meta.LastPage != 2 || got.Meta.PerPage != 2 || got.Meta.Total != 3 {
+		t.Fatalf("meta = %+v", got.Meta)
+	}
+	raw, err := json.Marshal(got)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(raw), "links") {
+		t.Fatalf("envelope must not contain links: %s", raw)
+	}
+	if !strings.Contains(string(raw), `"data"`) || !strings.Contains(string(raw), `"meta"`) {
+		t.Fatalf("missing data/meta: %s", raw)
+	}
+}
+
+func TestPaginateZeroPerPage(t *testing.T) {
+	got := Paginate([]int{1}, 1, 0, 10)
+	if got.Meta.LastPage != 1 {
+		t.Fatalf("last_page = %d, want 1", got.Meta.LastPage)
+	}
+}
+
+func TestPaginateNilDataIsEmptyArray(t *testing.T) {
+	got := Paginate[string](nil, 1, 10, 0)
+	raw, err := json.Marshal(got)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(raw), `"data":[]`) {
+		t.Fatalf("nil rows must marshal as []: %s", raw)
+	}
+}