refactor(10.2-01): nest framework packages under modules

- Move remaining beach packages and embedded admin assets\n- Rewrite framework, example, build, and gate paths

modules/lagoon/relations.go

@@ -0,0 +1,28 @@
+package lagoon
+
+import (
+	"fmt"
+
+	"gorm.io/gorm"
+)
+
+// RegisterJoinTable wraps db.SetupJoinTable so a nil db returns an error
+// instead of panicking.
+//
+// Pivot-write contract: pivot tables with business columns (sort_order,
+// role, granted_at, granted_by) are never written through
+// db.Model(&owner).Association(field).Append/Replace(...). GORM's
+// Association Mode has no documented path to set those columns. Writes go
+// through an explicit delete-then-bulk-insert (or ON CONFLICT DO UPDATE)
+// against the join table directly, in the same transaction as the parent
+// save. Reads use Preload(field) plus .Order(...) on the pivot's own
+// columns once RegisterJoinTable has run.
+func RegisterJoinTable(db *gorm.DB, owner any, field string, joinModel any) error {
+	if db == nil {
+		return fmt.Errorf("lagoon: register join table: db is nil")
+	}
+	if err := db.SetupJoinTable(owner, field, joinModel); err != nil {
+		return fmt.Errorf("lagoon: register join table: %w", err)
+	}
+	return nil
+}