`41454b8`

S31: teams + policy max-of-sources (org owner | direct collab | team grant + parent)

Authored by

espadonne 4 days ago

SHA: 41454b8733f9bca9f0dd1838a3603fde1ff9921c
Parents: 3c50abc
Tree: e558583

9 changed files

Status	File	+	-
M	`internal/auth/policy/org_owner_test.go`	123	0
M	`internal/auth/policy/policy.go`	106	5
A	`internal/migrationsfs/migrations/0035_teams.sql`	103	0
A	`internal/orgs/queries/teams.sql`	109	0
M	`internal/orgs/sqlc/models.go`	158	0
M	`internal/orgs/sqlc/querier.go`	36	0
A	`internal/orgs/sqlc/teams.sql.go`	593	0
A	`internal/orgs/teams.go`	212	0
A	`internal/orgs/teams_test.go`	112	0

internal/auth/policy/org_owner_test.gomodified

  	"testing"
  	"github.com/jackc/pgx/v5/pgtype"
++	"github.com/jackc/pgx/v5/pgxpool"
  	"github.com/tenseleyFlow/shithub/internal/auth/policy"
  	"github.com/tenseleyFlow/shithub/internal/orgs"
+ 	}
+ }
++// TestTeamGrant_GivesWriteAccess pins the S31 contract: a team grant
++// at `write` on an org repo lets that team's members push, even
++// though they're plain org members (not owners) and have no direct
++// collaborator row.
++func TestTeamGrant_GivesWriteAccess(t *testing.T) {
++	pool := dbtest.NewTestDB(t)
++	ctx := context.Background()
++
++	creator, _ := usersdb.New().CreateUser(ctx, pool, usersdb.CreateUserParams{
++		Username: "alice", DisplayName: "Alice", PasswordHash: fixtureHash,
++	})
++	deps := orgs.Deps{Pool: pool}
++	org, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: creator.ID})
++	repo, _ := reposdb.New().CreateRepo(ctx, pool, reposdb.CreateRepoParams{
++		OwnerOrgID: pgtype.Int8{Int64: org.ID, Valid: true},
++		Name:       "demo", DefaultBranch: "trunk", Visibility: reposdb.RepoVisibilityPublic,
++	})
++	bob, _ := usersdb.New().CreateUser(ctx, pool, usersdb.CreateUserParams{
++		Username: "bob", DisplayName: "Bob", PasswordHash: fixtureHash,
++	})
++	if err := orgs.AddMember(ctx, deps, org.ID, bob.ID, creator.ID, "member"); err != nil {
++		t.Fatalf("add org member: %v", err)
++	}
++	team, _ := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "eng", CreatedByUserID: creator.ID,
++	})
++	if err := orgs.AddTeamMember(ctx, deps, team.ID, bob.ID, creator.ID, "member"); err != nil {
++		t.Fatalf("add team member: %v", err)
++	}
++	if err := orgs.GrantTeamRepoAccess(ctx, deps, team.ID, repo.ID, creator.ID, "write"); err != nil {
++		t.Fatalf("grant: %v", err)
++	}
++
++	ref := policy.NewRepoRefFromRepo(repo)
++	bobActor := policy.UserActor(bob.ID, "bob", false, false)
++	pdeps := policy.Deps{Pool: pool}
++
++	if got := policy.Can(ctx, pdeps, bobActor, policy.ActionRepoWrite, ref); !got.Allow {
++		t.Fatalf("team-granted write should allow: %+v", got)
++	}
++
++	// Demote to read → write must now deny.
++	if err := orgs.GrantTeamRepoAccess(ctx, deps, team.ID, repo.ID, creator.ID, "read"); err != nil {
++		t.Fatalf("demote: %v", err)
++	}
++	if got := policy.Can(ctx, pdeps, bobActor, policy.ActionRepoWrite, ref); got.Allow {
++		t.Fatal("after demote to read, write should deny")
++	}
++	// Reads still allow under read role.
++	if got := policy.Can(ctx, pdeps, bobActor, policy.ActionRepoRead, ref); !got.Allow {
++		t.Fatalf("read should still allow at read role: %+v", got)
++	}
++
++	// Revoke entirely → reads on a public repo still allow (visibility),
++	// but for the test of "team membership lost access" we use a
++	// private repo branch:
++	if _, err := pool.Exec(ctx, `UPDATE repos SET visibility='private' WHERE id=$1`, repo.ID); err != nil {
++		t.Fatalf("flip private: %v", err)
++	}
++	// Cache from the previous Can() call may still be hot — start a
++	// fresh request scope by using a new context.
++	if err := orgs.RevokeTeamRepoAccess(ctx, deps, team.ID, repo.ID); err != nil {
++		t.Fatalf("revoke: %v", err)
++	}
++	freshCtx := context.Background()
++	if got := policy.Can(freshCtx, pdeps, bobActor, policy.ActionRepoRead,
++		policy.NewRepoRefFromRepo(reposdbReload(t, pool, repo.ID))); got.Allow {
++		t.Fatalf("after revoke, private read should deny: %+v", got)
++	}
++}
++
++// TestTeamParent_Inheritance pins the one-level parent inheritance
++// rule: a child-team member inherits the parent team's repo grants.
++func TestTeamParent_Inheritance(t *testing.T) {
++	pool := dbtest.NewTestDB(t)
++	ctx := context.Background()
++	creator, _ := usersdb.New().CreateUser(ctx, pool, usersdb.CreateUserParams{
++		Username: "alice", DisplayName: "Alice", PasswordHash: fixtureHash,
++	})
++	deps := orgs.Deps{Pool: pool}
++	org, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: creator.ID})
++	repo, _ := reposdb.New().CreateRepo(ctx, pool, reposdb.CreateRepoParams{
++		OwnerOrgID: pgtype.Int8{Int64: org.ID, Valid: true},
++		Name:       "demo", DefaultBranch: "trunk", Visibility: reposdb.RepoVisibilityPublic,
++	})
++	bob, _ := usersdb.New().CreateUser(ctx, pool, usersdb.CreateUserParams{
++		Username: "bob", DisplayName: "Bob", PasswordHash: fixtureHash,
++	})
++	_ = orgs.AddMember(ctx, deps, org.ID, bob.ID, creator.ID, "member")
++
++	parent, _ := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "engineering", CreatedByUserID: creator.ID,
++	})
++	child, _ := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "eng-mobile", ParentTeamID: parent.ID,
++		CreatedByUserID: creator.ID,
++	})
++	// Bob is in the CHILD team only. Grant write on the PARENT team.
++	_ = orgs.AddTeamMember(ctx, deps, child.ID, bob.ID, creator.ID, "member")
++	if err := orgs.GrantTeamRepoAccess(ctx, deps, parent.ID, repo.ID, creator.ID, "write"); err != nil {
++		t.Fatalf("parent grant: %v", err)
++	}
++
++	ref := policy.NewRepoRefFromRepo(repo)
++	bobActor := policy.UserActor(bob.ID, "bob", false, false)
++	pdeps := policy.Deps{Pool: pool}
++	if got := policy.Can(ctx, pdeps, bobActor, policy.ActionRepoWrite, ref); !got.Allow {
++		t.Fatalf("child team should inherit parent's write grant: %+v", got)
++	}
++}
++
++// reposdbReload re-fetches a repo row so a follow-up policy.Can sees
++// fresh visibility after a raw UPDATE.
++func reposdbReload(t *testing.T, pool *pgxpool.Pool, id int64) reposdb.Repo {
++	t.Helper()
++	row, err := reposdb.New().GetRepoByID(context.Background(), pool, id)
++	if err != nil {
++		t.Fatalf("reload repo: %v", err)
++	}
++	return row
++}
++
  // TestOrgSuspended_BlocksWrites pins the S30 contract: when an org
  // is suspended, every write action against an org-owned repo is
  // denied — even for the org owner. Reads still allow.

internal/auth/policy/policy.gomodified

  	"net/http"
  	"github.com/jackc/pgx/v5"
++	"github.com/jackc/pgx/v5/pgtype"
  	"github.com/jackc/pgx/v5/pgxpool"
  	policydb "github.com/tenseleyFlow/shithub/internal/auth/policy/sqlc"
  		// lookup below.
+ 	}
++	// Effective role = MAX(direct collab, team grants). Team path
++	// runs only for org-owned repos (user-owned repos have no
++	// teams). One hop on parent_team_id captures the inherited
++	// grants per S31's one-level-deep rule.
++	best := RoleNone
  	q := policydb.New()
  	dbRole, err := q.GetCollabRole(ctx, d.Pool, policydb.GetCollabRoleParams{
  		RepoID: repo.ID,
  		UserID: actor.UserID,
  	})
--	if errors.Is(err, pgx.ErrNoRows) {
++	switch {
--		cachePut(cache, key, RoleNone)
++	case err == nil:
++		best = roleFromDB(dbRole)
++	case errors.Is(err, pgx.ErrNoRows):
++		// no direct collab row — best stays RoleNone
++	default:
++		return RoleNone, err
++	}
++	if repo.OwnerOrgID != 0 {
++		teamRole, terr := teamGrantedRole(ctx, d, actor.UserID, repo.OwnerOrgID, repo.ID)
++		if terr != nil {
++			return RoleNone, terr
++		}
++		// roleStronger picks the higher-rank role. Don't use
++		// RoleAtLeast here — its `want > 0` guard treats RoleNone
++		// as un-comparable and blocks the legitimate "any role
++		// beats no role" branch.
++		if roleStronger(teamRole, best) {
++			best = teamRole
++		}
++	}
++	cachePut(cache, key, best)
++	return best, nil
++}
++
++// roleStronger reports whether `a` ranks strictly higher than `b`,
++// where RoleNone is the bottom (rank 0). Used to compose role
++// sources (direct collab, team grant, parent-team grant) into a
++// single max — the spec's "effective role = max of all sources"
++// rule.
++func roleStronger(a, b Role) bool {
++	return roleRank(a) > roleRank(b)
++}
++
++// teamGrantedRole computes the highest role the actor inherits from
++// any team in the org that has a grant on the repo. Walks parent
++// teams one hop (per the one-level-nesting cap from migration 0035).
++func teamGrantedRole(ctx context.Context, d Deps, userID, orgID, repoID int64) (Role, error) {
++	rows, err := d.Pool.Query(ctx,
++		`SELECT t.id, t.parent_team_id
++		   FROM team_members m
++		   JOIN teams t ON t.id = m.team_id
++		  WHERE t.org_id = $1 AND m.user_id = $2`,
++		orgID, userID)
++	if err != nil {
++		return RoleNone, err
++	}
++	defer rows.Close()
++	teamIDs := []int64{}
++	for rows.Next() {
++		var id int64
++		var parent pgtype.Int8
++		if err := rows.Scan(&id, &parent); err != nil {
++			return RoleNone, err
++		}
++		teamIDs = append(teamIDs, id)
++		if parent.Valid {
++			teamIDs = append(teamIDs, parent.Int64)
++		}
++	}
++	if err := rows.Err(); err != nil {
++		return RoleNone, err
++	}
++	if len(teamIDs) == 0 {
  		return RoleNone, nil
+ 	}
++	grantRows, err := d.Pool.Query(ctx,
++		`SELECT role::text FROM team_repo_access
++		  WHERE repo_id = $1 AND team_id = ANY($2::bigint[])`,
++		repoID, teamIDs)
  	if err != nil {
  		return RoleNone, err
+ 	}
--	r := roleFromDB(dbRole)
++	defer grantRows.Close()
--	cachePut(cache, key, r)
++	best := RoleNone
--	return r, nil
++	for grantRows.Next() {
++		var role string
++		if err := grantRows.Scan(&role); err != nil {
++			return RoleNone, err
++		}
++		if r := teamRepoRoleToPolicyRole(role); roleStronger(r, best) {
++			best = r
++		}
++	}
++	return best, grantRows.Err()
+ }
++// teamRepoRoleToPolicyRole maps the team_repo_role enum string to
++// the policy.Role string. Names align but the typed enums are in
++// different packages so the conversion is explicit.
++func teamRepoRoleToPolicyRole(s string) Role {
++	switch s {
++	case "read":
++		return RoleRead
++	case "triage":
++		return RoleTriage
++	case "write":
++		return RoleWrite
++	case "maintain":
++		return RoleMaintain
++	case "admin":
++		return RoleAdmin
++	}
++	return RoleNone
++}
++
++
  // minRoleFor returns the minimum collaborator role required for the
  // action against an existing repo. Owner is implicit admin, so this
  // table is the single source of truth for "what role grants what."

internal/migrationsfs/migrations/0035_teams.sqladded

++-- SPDX-License-Identifier: AGPL-3.0-or-later
++--
++-- S31 — Teams within organizations.
++--
++-- One level of nesting is intentional and structurally enforced via
++-- two CHECKs:
++--   - parent_team_id != id  (no self-parent)
++--   - if parent_team_id IS NOT NULL then the parent's parent_team_id
++--     is NULL (validated via a trigger; can't express in a row CHECK)
++--
++-- team_repo_access is the per-team repo grant; the per-user grant
++-- continues to live in `repo_collaborators` (S15). Both contribute to
++-- the policy aggregator's max-of-sources rule.
++
++-- +goose Up
++
++CREATE TYPE team_privacy   AS ENUM ('visible', 'secret');
++CREATE TYPE team_role      AS ENUM ('member', 'maintainer');
++CREATE TYPE team_repo_role AS ENUM ('read', 'triage', 'write', 'maintain', 'admin');
++
++CREATE TABLE teams (
++    id                 bigserial    PRIMARY KEY,
++    org_id             bigint       NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
++    slug               citext       NOT NULL,
++    display_name       text         NOT NULL DEFAULT '',
++    description        text         NOT NULL DEFAULT '',
++    parent_team_id     bigint       REFERENCES teams(id) ON DELETE SET NULL,
++    privacy            team_privacy NOT NULL DEFAULT 'visible',
++    created_by_user_id bigint       REFERENCES users(id) ON DELETE SET NULL,
++    created_at         timestamptz  NOT NULL DEFAULT now(),
++    updated_at         timestamptz  NOT NULL DEFAULT now(),
++
++    CONSTRAINT teams_slug_length CHECK (char_length(slug::text) BETWEEN 1 AND 50),
++    CONSTRAINT teams_no_self_parent CHECK (parent_team_id IS NULL OR parent_team_id <> id),
++    CONSTRAINT teams_org_slug_unique UNIQUE (org_id, slug)
++);
++
++CREATE INDEX teams_org_idx ON teams (org_id);
++CREATE INDEX teams_parent_idx ON teams (parent_team_id) WHERE parent_team_id IS NOT NULL;
++
++CREATE TRIGGER set_updated_at BEFORE UPDATE ON teams
++    FOR EACH ROW EXECUTE FUNCTION tg_set_updated_at();
++
++-- One-level-deep nesting enforcement: a team's parent must itself
++-- have a NULL parent. Implemented as a trigger because the rule
++-- spans rows.
++-- +goose StatementBegin
++CREATE OR REPLACE FUNCTION tg_teams_one_level_nesting() RETURNS trigger AS $$
++DECLARE
++    grandparent_id bigint;
++BEGIN
++    IF NEW.parent_team_id IS NULL THEN
++        RETURN NEW;
++    END IF;
++    SELECT parent_team_id INTO grandparent_id FROM teams WHERE id = NEW.parent_team_id;
++    IF grandparent_id IS NOT NULL THEN
++        RAISE EXCEPTION 'teams: nesting limited to one level (parent already has a parent)'
++            USING ERRCODE = '23514';
++    END IF;
++    RETURN NEW;
++END;
++$$ LANGUAGE plpgsql;
++-- +goose StatementEnd
++
++CREATE TRIGGER tg_teams_one_level_nesting_iu
++    BEFORE INSERT OR UPDATE ON teams
++    FOR EACH ROW EXECUTE FUNCTION tg_teams_one_level_nesting();
++
++-- ─── team_members ─────────────────────────────────────────────────
++CREATE TABLE team_members (
++    team_id          bigint      NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
++    user_id          bigint      NOT NULL REFERENCES users(id) ON DELETE CASCADE,
++    role             team_role   NOT NULL DEFAULT 'member',
++    added_by_user_id bigint      REFERENCES users(id) ON DELETE SET NULL,
++    added_at         timestamptz NOT NULL DEFAULT now(),
++
++    PRIMARY KEY (team_id, user_id)
++);
++
++CREATE INDEX team_members_user_idx ON team_members (user_id);
++
++-- ─── team_repo_access ─────────────────────────────────────────────
++CREATE TABLE team_repo_access (
++    team_id          bigint         NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
++    repo_id          bigint         NOT NULL REFERENCES repos(id) ON DELETE CASCADE,
++    role             team_repo_role NOT NULL DEFAULT 'read',
++    added_by_user_id bigint         REFERENCES users(id) ON DELETE SET NULL,
++    added_at         timestamptz    NOT NULL DEFAULT now(),
++
++    PRIMARY KEY (team_id, repo_id)
++);
++
++CREATE INDEX team_repo_access_repo_idx ON team_repo_access (repo_id);
++
++-- +goose Down
++DROP TABLE IF EXISTS team_repo_access;
++DROP TABLE IF EXISTS team_members;
++DROP TRIGGER IF EXISTS tg_teams_one_level_nesting_iu ON teams;
++DROP FUNCTION IF EXISTS tg_teams_one_level_nesting();
++DROP TABLE IF EXISTS teams;
++DROP TYPE IF EXISTS team_repo_role;
++DROP TYPE IF EXISTS team_role;
++DROP TYPE IF EXISTS team_privacy;

internal/orgs/queries/teams.sqladded

++-- SPDX-License-Identifier: AGPL-3.0-or-later
++
++-- ─── teams ─────────────────────────────────────────────────────────
++
++-- name: CreateTeam :one
++INSERT INTO teams (org_id, slug, display_name, description, parent_team_id, privacy, created_by_user_id)
++VALUES ($1, $2, $3, $4, sqlc.narg(parent_team_id)::bigint, $5, sqlc.narg(created_by_user_id)::bigint)
++RETURNING *;
++
++-- name: GetTeamByID :one
++SELECT * FROM teams WHERE id = $1;
++
++-- name: GetTeamByOrgAndSlug :one
++SELECT * FROM teams WHERE org_id = $1 AND slug = $2;
++
++-- name: ListTeamsForOrg :many
++SELECT * FROM teams WHERE org_id = $1 ORDER BY slug ASC;
++
++-- name: ListChildTeams :many
++SELECT * FROM teams WHERE parent_team_id = $1 ORDER BY slug ASC;
++
++-- name: UpdateTeamProfile :exec
++UPDATE teams SET display_name = $2, description = $3, privacy = $4, updated_at = now()
++WHERE id = $1;
++
++-- name: SetTeamParent :exec
++-- The one-level-nesting BEFORE trigger blocks invalid moves; the
++-- caller surfaces the SQLSTATE 23514 as a friendly error.
++UPDATE teams SET parent_team_id = sqlc.narg(parent_team_id)::bigint, updated_at = now()
++WHERE id = $1;
++
++-- name: DeleteTeam :exec
++-- Children's parent_team_id flips to NULL via the FK ON DELETE SET NULL,
++-- promoting them to top-level — matches the "deleting parent doesn't
++-- delete children" intent in the spec's pitfalls.
++DELETE FROM teams WHERE id = $1;
++
++-- ─── team_members ─────────────────────────────────────────────────
++
++-- name: AddTeamMember :exec
++INSERT INTO team_members (team_id, user_id, role, added_by_user_id)
++VALUES ($1, $2, $3, sqlc.narg(added_by_user_id)::bigint)
++ON CONFLICT (team_id, user_id) DO NOTHING;
++
++-- name: SetTeamMemberRole :exec
++UPDATE team_members SET role = $3 WHERE team_id = $1 AND user_id = $2;
++
++-- name: RemoveTeamMember :exec
++DELETE FROM team_members WHERE team_id = $1 AND user_id = $2;
++
++-- name: ListTeamMembers :many
++SELECT m.team_id, m.user_id, m.role, m.added_by_user_id, m.added_at,
++       u.username, u.display_name
++FROM team_members m
++JOIN users u ON u.id = m.user_id
++WHERE m.team_id = $1 AND u.deleted_at IS NULL
++ORDER BY m.role ASC, u.username ASC;
++
++-- name: ListTeamsForUserInOrg :many
++-- Returns the teams a user directly belongs to within an org. The
++-- policy aggregator unions this with each row's parent_team_id to
++-- get the inherited set.
++SELECT t.id, t.org_id, t.slug, t.display_name, t.description,
++       t.parent_team_id, t.privacy, t.created_by_user_id,
++       t.created_at, t.updated_at,
++       m.role AS member_role
++FROM team_members m
++JOIN teams t ON t.id = m.team_id
++WHERE t.org_id = $1 AND m.user_id = $2;
++
++-- ─── team_repo_access ─────────────────────────────────────────────
++
++-- name: GrantTeamRepoAccess :exec
++INSERT INTO team_repo_access (team_id, repo_id, role, added_by_user_id)
++VALUES ($1, $2, $3, sqlc.narg(added_by_user_id)::bigint)
++ON CONFLICT (team_id, repo_id) DO UPDATE SET role = EXCLUDED.role;
++
++-- name: RevokeTeamRepoAccess :exec
++DELETE FROM team_repo_access WHERE team_id = $1 AND repo_id = $2;
++
++-- name: GetTeamRepoAccess :one
++SELECT * FROM team_repo_access WHERE team_id = $1 AND repo_id = $2;
++
++-- name: ListTeamRepoAccess :many
++-- All repos the team has any grant on; for the team-view page.
++SELECT a.team_id, a.repo_id, a.role, a.added_by_user_id, a.added_at,
++       r.name AS repo_name, r.visibility::text AS visibility
++FROM team_repo_access a
++JOIN repos r ON r.id = a.repo_id
++WHERE a.team_id = $1 AND r.deleted_at IS NULL
++ORDER BY r.name ASC;
++
++-- name: ListRepoTeamGrants :many
++-- All teams with grants on a single repo; for repo settings/access page.
++SELECT a.team_id, a.repo_id, a.role, a.added_by_user_id, a.added_at,
++       t.slug AS team_slug, t.display_name AS team_display_name,
++       t.privacy::text AS team_privacy
++FROM team_repo_access a
++JOIN teams t ON t.id = a.team_id
++WHERE a.repo_id = $1
++ORDER BY t.slug ASC;
++
++-- name: ListTeamAccessForRepoAndTeams :many
++-- Policy hot-path: given a repo and a set of team_ids the actor
++-- belongs to (incl. inherited), return the access rows. Caller picks
++-- the highest role.
++SELECT team_id, repo_id, role
++FROM team_repo_access
++WHERE repo_id = $1 AND team_id = ANY($2::bigint[]);

internal/orgs/sqlc/models.gomodified

  	return string(ns.RepoVisibility), nil
+ }
++type TeamPrivacy string
++
++const (
++	TeamPrivacyVisible TeamPrivacy = "visible"
++	TeamPrivacySecret  TeamPrivacy = "secret"
++)
++
++func (e *TeamPrivacy) Scan(src interface{}) error {
++	switch s := src.(type) {
++	case []byte:
++		*e = TeamPrivacy(s)
++	case string:
++		*e = TeamPrivacy(s)
++	default:
++		return fmt.Errorf("unsupported scan type for TeamPrivacy: %T", src)
++	}
++	return nil
++}
++
++type NullTeamPrivacy struct {
++	TeamPrivacy TeamPrivacy
++	Valid       bool // Valid is true if TeamPrivacy is not NULL
++}
++
++// Scan implements the Scanner interface.
++func (ns *NullTeamPrivacy) Scan(value interface{}) error {
++	if value == nil {
++		ns.TeamPrivacy, ns.Valid = "", false
++		return nil
++	}
++	ns.Valid = true
++	return ns.TeamPrivacy.Scan(value)
++}
++
++// Value implements the driver Valuer interface.
++func (ns NullTeamPrivacy) Value() (driver.Value, error) {
++	if !ns.Valid {
++		return nil, nil
++	}
++	return string(ns.TeamPrivacy), nil
++}
++
++type TeamRepoRole string
++
++const (
++	TeamRepoRoleRead     TeamRepoRole = "read"
++	TeamRepoRoleTriage   TeamRepoRole = "triage"
++	TeamRepoRoleWrite    TeamRepoRole = "write"
++	TeamRepoRoleMaintain TeamRepoRole = "maintain"
++	TeamRepoRoleAdmin    TeamRepoRole = "admin"
++)
++
++func (e *TeamRepoRole) Scan(src interface{}) error {
++	switch s := src.(type) {
++	case []byte:
++		*e = TeamRepoRole(s)
++	case string:
++		*e = TeamRepoRole(s)
++	default:
++		return fmt.Errorf("unsupported scan type for TeamRepoRole: %T", src)
++	}
++	return nil
++}
++
++type NullTeamRepoRole struct {
++	TeamRepoRole TeamRepoRole
++	Valid        bool // Valid is true if TeamRepoRole is not NULL
++}
++
++// Scan implements the Scanner interface.
++func (ns *NullTeamRepoRole) Scan(value interface{}) error {
++	if value == nil {
++		ns.TeamRepoRole, ns.Valid = "", false
++		return nil
++	}
++	ns.Valid = true
++	return ns.TeamRepoRole.Scan(value)
++}
++
++// Value implements the driver Valuer interface.
++func (ns NullTeamRepoRole) Value() (driver.Value, error) {
++	if !ns.Valid {
++		return nil, nil
++	}
++	return string(ns.TeamRepoRole), nil
++}
++
++type TeamRole string
++
++const (
++	TeamRoleMember     TeamRole = "member"
++	TeamRoleMaintainer TeamRole = "maintainer"
++)
++
++func (e *TeamRole) Scan(src interface{}) error {
++	switch s := src.(type) {
++	case []byte:
++		*e = TeamRole(s)
++	case string:
++		*e = TeamRole(s)
++	default:
++		return fmt.Errorf("unsupported scan type for TeamRole: %T", src)
++	}
++	return nil
++}
++
++type NullTeamRole struct {
++	TeamRole TeamRole
++	Valid    bool // Valid is true if TeamRole is not NULL
++}
++
++// Scan implements the Scanner interface.
++func (ns *NullTeamRole) Scan(value interface{}) error {
++	if value == nil {
++		ns.TeamRole, ns.Valid = "", false
++		return nil
++	}
++	ns.Valid = true
++	return ns.TeamRole.Scan(value)
++}
++
++// Value implements the driver Valuer interface.
++func (ns NullTeamRole) Value() (driver.Value, error) {
++	if !ns.Valid {
++		return nil, nil
++	}
++	return string(ns.TeamRole), nil
++}
++
  type TransferPrincipalKind string
  const (
  	StarredAt pgtype.Timestamptz
+ }
++type Team struct {
++	ID              int64
++	OrgID           int64
++	Slug            string
++	DisplayName     string
++	Description     string
++	ParentTeamID    pgtype.Int8
++	Privacy         TeamPrivacy
++	CreatedByUserID pgtype.Int8
++	CreatedAt       pgtype.Timestamptz
++	UpdatedAt       pgtype.Timestamptz
++}
++
++type TeamMember struct {
++	TeamID        int64
++	UserID        int64
++	Role          TeamRole
++	AddedByUserID pgtype.Int8
++	AddedAt       pgtype.Timestamptz
++}
++
++type TeamRepoAccess struct {
++	TeamID        int64
++	RepoID        int64
++	Role          TeamRepoRole
++	AddedByUserID pgtype.Int8
++	AddedAt       pgtype.Timestamptz
++}
++
  type User struct {
  	ID                int64
  	Username          string

internal/orgs/sqlc/querier.gomodified

  	// the member is new; existing rows keep their current role (use
  	// ChangeOrgMemberRole to update).
  	AddOrgMember(ctx context.Context, db DBTX, arg AddOrgMemberParams) error
++	// ─── team_members ─────────────────────────────────────────────────
++	AddTeamMember(ctx context.Context, db DBTX, arg AddTeamMemberParams) error
  	CancelOrgInvitation(ctx context.Context, db DBTX, id int64) error
  	ChangeOrgMemberRole(ctx context.Context, db DBTX, arg ChangeOrgMemberRoleParams) error
  	// Used by the last-owner protection: refuses to remove or demote the
  	// SPDX-License-Identifier: AGPL-3.0-or-later
  	// ─── org_invitations ───────────────────────────────────────────────
  	CreateOrgInvitation(ctx context.Context, db DBTX, arg CreateOrgInvitationParams) (OrgInvitation, error)
++	// SPDX-License-Identifier: AGPL-3.0-or-later
++	// ─── teams ─────────────────────────────────────────────────────────
++	CreateTeam(ctx context.Context, db DBTX, arg CreateTeamParams) (Team, error)
  	DeclineOrgInvitation(ctx context.Context, db DBTX, id int64) error
++	// Children's parent_team_id flips to NULL via the FK ON DELETE SET NULL,
++	// promoting them to top-level — matches the "deleting parent doesn't
++	// delete children" intent in the spec's pitfalls.
++	DeleteTeam(ctx context.Context, db DBTX, id int64) error
  	// Idempotency check before creating a new invite — so a re-issued
  	// invite to the same target doesn't accumulate stale rows.
  	GetExistingPendingInvitation(ctx context.Context, db DBTX, arg GetExistingPendingInvitationParams) (OrgInvitation, error)
  	GetOrgInvitationByID(ctx context.Context, db DBTX, id int64) (OrgInvitation, error)
  	GetOrgInvitationByTokenHash(ctx context.Context, db DBTX, tokenHash []byte) (OrgInvitation, error)
  	GetOrgMember(ctx context.Context, db DBTX, arg GetOrgMemberParams) (OrgMember, error)
++	GetTeamByID(ctx context.Context, db DBTX, id int64) (Team, error)
++	GetTeamByOrgAndSlug(ctx context.Context, db DBTX, arg GetTeamByOrgAndSlugParams) (Team, error)
++	GetTeamRepoAccess(ctx context.Context, db DBTX, arg GetTeamRepoAccessParams) (TeamRepoAccess, error)
++	// ─── team_repo_access ─────────────────────────────────────────────
++	GrantTeamRepoAccess(ctx context.Context, db DBTX, arg GrantTeamRepoAccessParams) error
  	// Final row removal after the cascade finished. The principals
  	// trigger drops the matching principals row in the same tx.
  	HardDeleteOrgRow(ctx context.Context, db DBTX, id int64) error
++	ListChildTeams(ctx context.Context, db DBTX, parentTeamID pgtype.Int8) ([]Team, error)
  	// Sweep input for the lifecycle worker: every soft-deleted org whose
  	// 14-day grace window has elapsed. The interval is intentionally a
  	// DB literal (not a parameter) so the policy lives next to the data.
  	// (claim-on-signup). Caller unions the two lookups when surfacing
  	// to the user.
  	ListPendingInvitationsForUser(ctx context.Context, db DBTX, targetUserID pgtype.Int8) ([]ListPendingInvitationsForUserRow, error)
++	// All teams with grants on a single repo; for repo settings/access page.
++	ListRepoTeamGrants(ctx context.Context, db DBTX, repoID int64) ([]ListRepoTeamGrantsRow, error)
++	// Policy hot-path: given a repo and a set of team_ids the actor
++	// belongs to (incl. inherited), return the access rows. Caller picks
++	// the highest role.
++	ListTeamAccessForRepoAndTeams(ctx context.Context, db DBTX, arg ListTeamAccessForRepoAndTeamsParams) ([]ListTeamAccessForRepoAndTeamsRow, error)
++	ListTeamMembers(ctx context.Context, db DBTX, teamID int64) ([]ListTeamMembersRow, error)
++	// All repos the team has any grant on; for the team-view page.
++	ListTeamRepoAccess(ctx context.Context, db DBTX, teamID int64) ([]ListTeamRepoAccessRow, error)
++	ListTeamsForOrg(ctx context.Context, db DBTX, orgID int64) ([]Team, error)
++	// Returns the teams a user directly belongs to within an org. The
++	// policy aggregator unions this with each row's parent_team_id to
++	// get the inherited set.
++	ListTeamsForUserInOrg(ctx context.Context, db DBTX, arg ListTeamsForUserInOrgParams) ([]ListTeamsForUserInOrgRow, error)
  	RemoveOrgMember(ctx context.Context, db DBTX, arg RemoveOrgMemberParams) error
++	RemoveTeamMember(ctx context.Context, db DBTX, arg RemoveTeamMemberParams) error
  	// ─── principals (read-only from this domain) ───────────────────────
  	// Single-query /{slug} resolver. Returns the (kind, id) tuple that
  	// /{slug}/* routes use to dispatch to the user-profile or org-profile
  	// impossible at the DB layer.
  	ResolvePrincipal(ctx context.Context, db DBTX, slug string) (Principal, error)
  	RestoreOrg(ctx context.Context, db DBTX, id int64) error
++	RevokeTeamRepoAccess(ctx context.Context, db DBTX, arg RevokeTeamRepoAccessParams) error
  	SetOrgAllowMemberRepoCreate(ctx context.Context, db DBTX, arg SetOrgAllowMemberRepoCreateParams) error
  	SetOrgAvatarKey(ctx context.Context, db DBTX, arg SetOrgAvatarKeyParams) error
  	SetOrgSuspended(ctx context.Context, db DBTX, arg SetOrgSuspendedParams) error
++	SetTeamMemberRole(ctx context.Context, db DBTX, arg SetTeamMemberRoleParams) error
++	// The one-level-nesting BEFORE trigger blocks invalid moves; the
++	// caller surfaces the SQLSTATE 23514 as a friendly error.
++	SetTeamParent(ctx context.Context, db DBTX, arg SetTeamParentParams) error
  	SoftDeleteOrg(ctx context.Context, db DBTX, id int64) error
  	UpdateOrgProfile(ctx context.Context, db DBTX, arg UpdateOrgProfileParams) error
++	UpdateTeamProfile(ctx context.Context, db DBTX, arg UpdateTeamProfileParams) error
+ }
  var _ Querier = (*Queries)(nil)

internal/orgs/sqlc/teams.sql.goadded

++// Code generated by sqlc. DO NOT EDIT.
++// versions:
++//   sqlc v1.31.1
++// source: teams.sql
++
++package orgsdb
++
++import (
++	"context"
++
++	"github.com/jackc/pgx/v5/pgtype"
++)
++
++const addTeamMember = `-- name: AddTeamMember :exec
++
++INSERT INTO team_members (team_id, user_id, role, added_by_user_id)
++VALUES ($1, $2, $3, $4::bigint)
++ON CONFLICT (team_id, user_id) DO NOTHING
++`
++
++type AddTeamMemberParams struct {
++	TeamID        int64
++	UserID        int64
++	Role          TeamRole
++	AddedByUserID pgtype.Int8
++}
++
++// ─── team_members ─────────────────────────────────────────────────
++func (q *Queries) AddTeamMember(ctx context.Context, db DBTX, arg AddTeamMemberParams) error {
++	_, err := db.Exec(ctx, addTeamMember,
++		arg.TeamID,
++		arg.UserID,
++		arg.Role,
++		arg.AddedByUserID,
++	)
++	return err
++}
++
++const createTeam = `-- name: CreateTeam :one
++
++
++INSERT INTO teams (org_id, slug, display_name, description, parent_team_id, privacy, created_by_user_id)
++VALUES ($1, $2, $3, $4, $6::bigint, $5, $7::bigint)
++RETURNING id, org_id, slug, display_name, description, parent_team_id, privacy, created_by_user_id, created_at, updated_at
++`
++
++type CreateTeamParams struct {
++	OrgID           int64
++	Slug            string
++	DisplayName     string
++	Description     string
++	Privacy         TeamPrivacy
++	ParentTeamID    pgtype.Int8
++	CreatedByUserID pgtype.Int8
++}
++
++// SPDX-License-Identifier: AGPL-3.0-or-later
++// ─── teams ─────────────────────────────────────────────────────────
++func (q *Queries) CreateTeam(ctx context.Context, db DBTX, arg CreateTeamParams) (Team, error) {
++	row := db.QueryRow(ctx, createTeam,
++		arg.OrgID,
++		arg.Slug,
++		arg.DisplayName,
++		arg.Description,
++		arg.Privacy,
++		arg.ParentTeamID,
++		arg.CreatedByUserID,
++	)
++	var i Team
++	err := row.Scan(
++		&i.ID,
++		&i.OrgID,
++		&i.Slug,
++		&i.DisplayName,
++		&i.Description,
++		&i.ParentTeamID,
++		&i.Privacy,
++		&i.CreatedByUserID,
++		&i.CreatedAt,
++		&i.UpdatedAt,
++	)
++	return i, err
++}
++
++const deleteTeam = `-- name: DeleteTeam :exec
++DELETE FROM teams WHERE id = $1
++`
++
++// Children's parent_team_id flips to NULL via the FK ON DELETE SET NULL,
++// promoting them to top-level — matches the "deleting parent doesn't
++// delete children" intent in the spec's pitfalls.
++func (q *Queries) DeleteTeam(ctx context.Context, db DBTX, id int64) error {
++	_, err := db.Exec(ctx, deleteTeam, id)
++	return err
++}
++
++const getTeamByID = `-- name: GetTeamByID :one
++SELECT id, org_id, slug, display_name, description, parent_team_id, privacy, created_by_user_id, created_at, updated_at FROM teams WHERE id = $1
++`
++
++func (q *Queries) GetTeamByID(ctx context.Context, db DBTX, id int64) (Team, error) {
++	row := db.QueryRow(ctx, getTeamByID, id)
++	var i Team
++	err := row.Scan(
++		&i.ID,
++		&i.OrgID,
++		&i.Slug,
++		&i.DisplayName,
++		&i.Description,
++		&i.ParentTeamID,
++		&i.Privacy,
++		&i.CreatedByUserID,
++		&i.CreatedAt,
++		&i.UpdatedAt,
++	)
++	return i, err
++}
++
++const getTeamByOrgAndSlug = `-- name: GetTeamByOrgAndSlug :one
++SELECT id, org_id, slug, display_name, description, parent_team_id, privacy, created_by_user_id, created_at, updated_at FROM teams WHERE org_id = $1 AND slug = $2
++`
++
++type GetTeamByOrgAndSlugParams struct {
++	OrgID int64
++	Slug  string
++}
++
++func (q *Queries) GetTeamByOrgAndSlug(ctx context.Context, db DBTX, arg GetTeamByOrgAndSlugParams) (Team, error) {
++	row := db.QueryRow(ctx, getTeamByOrgAndSlug, arg.OrgID, arg.Slug)
++	var i Team
++	err := row.Scan(
++		&i.ID,
++		&i.OrgID,
++		&i.Slug,
++		&i.DisplayName,
++		&i.Description,
++		&i.ParentTeamID,
++		&i.Privacy,
++		&i.CreatedByUserID,
++		&i.CreatedAt,
++		&i.UpdatedAt,
++	)
++	return i, err
++}
++
++const getTeamRepoAccess = `-- name: GetTeamRepoAccess :one
++SELECT team_id, repo_id, role, added_by_user_id, added_at FROM team_repo_access WHERE team_id = $1 AND repo_id = $2
++`
++
++type GetTeamRepoAccessParams struct {
++	TeamID int64
++	RepoID int64
++}
++
++func (q *Queries) GetTeamRepoAccess(ctx context.Context, db DBTX, arg GetTeamRepoAccessParams) (TeamRepoAccess, error) {
++	row := db.QueryRow(ctx, getTeamRepoAccess, arg.TeamID, arg.RepoID)
++	var i TeamRepoAccess
++	err := row.Scan(
++		&i.TeamID,
++		&i.RepoID,
++		&i.Role,
++		&i.AddedByUserID,
++		&i.AddedAt,
++	)
++	return i, err
++}
++
++const grantTeamRepoAccess = `-- name: GrantTeamRepoAccess :exec
++
++INSERT INTO team_repo_access (team_id, repo_id, role, added_by_user_id)
++VALUES ($1, $2, $3, $4::bigint)
++ON CONFLICT (team_id, repo_id) DO UPDATE SET role = EXCLUDED.role
++`
++
++type GrantTeamRepoAccessParams struct {
++	TeamID        int64
++	RepoID        int64
++	Role          TeamRepoRole
++	AddedByUserID pgtype.Int8
++}
++
++// ─── team_repo_access ─────────────────────────────────────────────
++func (q *Queries) GrantTeamRepoAccess(ctx context.Context, db DBTX, arg GrantTeamRepoAccessParams) error {
++	_, err := db.Exec(ctx, grantTeamRepoAccess,
++		arg.TeamID,
++		arg.RepoID,
++		arg.Role,
++		arg.AddedByUserID,
++	)
++	return err
++}
++
++const listChildTeams = `-- name: ListChildTeams :many
++SELECT id, org_id, slug, display_name, description, parent_team_id, privacy, created_by_user_id, created_at, updated_at FROM teams WHERE parent_team_id = $1 ORDER BY slug ASC
++`
++
++func (q *Queries) ListChildTeams(ctx context.Context, db DBTX, parentTeamID pgtype.Int8) ([]Team, error) {
++	rows, err := db.Query(ctx, listChildTeams, parentTeamID)
++	if err != nil {
++		return nil, err
++	}
++	defer rows.Close()
++	items := []Team{}
++	for rows.Next() {
++		var i Team
++		if err := rows.Scan(
++			&i.ID,
++			&i.OrgID,
++			&i.Slug,
++			&i.DisplayName,
++			&i.Description,
++			&i.ParentTeamID,
++			&i.Privacy,
++			&i.CreatedByUserID,
++			&i.CreatedAt,
++			&i.UpdatedAt,
++		); err != nil {
++			return nil, err
++		}
++		items = append(items, i)
++	}
++	if err := rows.Err(); err != nil {
++		return nil, err
++	}
++	return items, nil
++}
++
++const listRepoTeamGrants = `-- name: ListRepoTeamGrants :many
++SELECT a.team_id, a.repo_id, a.role, a.added_by_user_id, a.added_at,
++       t.slug AS team_slug, t.display_name AS team_display_name,
++       t.privacy::text AS team_privacy
++FROM team_repo_access a
++JOIN teams t ON t.id = a.team_id
++WHERE a.repo_id = $1
++ORDER BY t.slug ASC
++`
++
++type ListRepoTeamGrantsRow struct {
++	TeamID          int64
++	RepoID          int64
++	Role            TeamRepoRole
++	AddedByUserID   pgtype.Int8
++	AddedAt         pgtype.Timestamptz
++	TeamSlug        string
++	TeamDisplayName string
++	TeamPrivacy     string
++}
++
++// All teams with grants on a single repo; for repo settings/access page.
++func (q *Queries) ListRepoTeamGrants(ctx context.Context, db DBTX, repoID int64) ([]ListRepoTeamGrantsRow, error) {
++	rows, err := db.Query(ctx, listRepoTeamGrants, repoID)
++	if err != nil {
++		return nil, err
++	}
++	defer rows.Close()
++	items := []ListRepoTeamGrantsRow{}
++	for rows.Next() {
++		var i ListRepoTeamGrantsRow
++		if err := rows.Scan(
++			&i.TeamID,
++			&i.RepoID,
++			&i.Role,
++			&i.AddedByUserID,
++			&i.AddedAt,
++			&i.TeamSlug,
++			&i.TeamDisplayName,
++			&i.TeamPrivacy,
++		); err != nil {
++			return nil, err
++		}
++		items = append(items, i)
++	}
++	if err := rows.Err(); err != nil {
++		return nil, err
++	}
++	return items, nil
++}
++
++const listTeamAccessForRepoAndTeams = `-- name: ListTeamAccessForRepoAndTeams :many
++SELECT team_id, repo_id, role
++FROM team_repo_access
++WHERE repo_id = $1 AND team_id = ANY($2::bigint[])
++`
++
++type ListTeamAccessForRepoAndTeamsParams struct {
++	RepoID  int64
++	Column2 []int64
++}
++
++type ListTeamAccessForRepoAndTeamsRow struct {
++	TeamID int64
++	RepoID int64
++	Role   TeamRepoRole
++}
++
++// Policy hot-path: given a repo and a set of team_ids the actor
++// belongs to (incl. inherited), return the access rows. Caller picks
++// the highest role.
++func (q *Queries) ListTeamAccessForRepoAndTeams(ctx context.Context, db DBTX, arg ListTeamAccessForRepoAndTeamsParams) ([]ListTeamAccessForRepoAndTeamsRow, error) {
++	rows, err := db.Query(ctx, listTeamAccessForRepoAndTeams, arg.RepoID, arg.Column2)
++	if err != nil {
++		return nil, err
++	}
++	defer rows.Close()
++	items := []ListTeamAccessForRepoAndTeamsRow{}
++	for rows.Next() {
++		var i ListTeamAccessForRepoAndTeamsRow
++		if err := rows.Scan(&i.TeamID, &i.RepoID, &i.Role); err != nil {
++			return nil, err
++		}
++		items = append(items, i)
++	}
++	if err := rows.Err(); err != nil {
++		return nil, err
++	}
++	return items, nil
++}
++
++const listTeamMembers = `-- name: ListTeamMembers :many
++SELECT m.team_id, m.user_id, m.role, m.added_by_user_id, m.added_at,
++       u.username, u.display_name
++FROM team_members m
++JOIN users u ON u.id = m.user_id
++WHERE m.team_id = $1 AND u.deleted_at IS NULL
++ORDER BY m.role ASC, u.username ASC
++`
++
++type ListTeamMembersRow struct {
++	TeamID        int64
++	UserID        int64
++	Role          TeamRole
++	AddedByUserID pgtype.Int8
++	AddedAt       pgtype.Timestamptz
++	Username      string
++	DisplayName   string
++}
++
++func (q *Queries) ListTeamMembers(ctx context.Context, db DBTX, teamID int64) ([]ListTeamMembersRow, error) {
++	rows, err := db.Query(ctx, listTeamMembers, teamID)
++	if err != nil {
++		return nil, err
++	}
++	defer rows.Close()
++	items := []ListTeamMembersRow{}
++	for rows.Next() {
++		var i ListTeamMembersRow
++		if err := rows.Scan(
++			&i.TeamID,
++			&i.UserID,
++			&i.Role,
++			&i.AddedByUserID,
++			&i.AddedAt,
++			&i.Username,
++			&i.DisplayName,
++		); err != nil {
++			return nil, err
++		}
++		items = append(items, i)
++	}
++	if err := rows.Err(); err != nil {
++		return nil, err
++	}
++	return items, nil
++}
++
++const listTeamRepoAccess = `-- name: ListTeamRepoAccess :many
++SELECT a.team_id, a.repo_id, a.role, a.added_by_user_id, a.added_at,
++       r.name AS repo_name, r.visibility::text AS visibility
++FROM team_repo_access a
++JOIN repos r ON r.id = a.repo_id
++WHERE a.team_id = $1 AND r.deleted_at IS NULL
++ORDER BY r.name ASC
++`
++
++type ListTeamRepoAccessRow struct {
++	TeamID        int64
++	RepoID        int64
++	Role          TeamRepoRole
++	AddedByUserID pgtype.Int8
++	AddedAt       pgtype.Timestamptz
++	RepoName      string
++	Visibility    string
++}
++
++// All repos the team has any grant on; for the team-view page.
++func (q *Queries) ListTeamRepoAccess(ctx context.Context, db DBTX, teamID int64) ([]ListTeamRepoAccessRow, error) {
++	rows, err := db.Query(ctx, listTeamRepoAccess, teamID)
++	if err != nil {
++		return nil, err
++	}
++	defer rows.Close()
++	items := []ListTeamRepoAccessRow{}
++	for rows.Next() {
++		var i ListTeamRepoAccessRow
++		if err := rows.Scan(
++			&i.TeamID,
++			&i.RepoID,
++			&i.Role,
++			&i.AddedByUserID,
++			&i.AddedAt,
++			&i.RepoName,
++			&i.Visibility,
++		); err != nil {
++			return nil, err
++		}
++		items = append(items, i)
++	}
++	if err := rows.Err(); err != nil {
++		return nil, err
++	}
++	return items, nil
++}
++
++const listTeamsForOrg = `-- name: ListTeamsForOrg :many
++SELECT id, org_id, slug, display_name, description, parent_team_id, privacy, created_by_user_id, created_at, updated_at FROM teams WHERE org_id = $1 ORDER BY slug ASC
++`
++
++func (q *Queries) ListTeamsForOrg(ctx context.Context, db DBTX, orgID int64) ([]Team, error) {
++	rows, err := db.Query(ctx, listTeamsForOrg, orgID)
++	if err != nil {
++		return nil, err
++	}
++	defer rows.Close()
++	items := []Team{}
++	for rows.Next() {
++		var i Team
++		if err := rows.Scan(
++			&i.ID,
++			&i.OrgID,
++			&i.Slug,
++			&i.DisplayName,
++			&i.Description,
++			&i.ParentTeamID,
++			&i.Privacy,
++			&i.CreatedByUserID,
++			&i.CreatedAt,
++			&i.UpdatedAt,
++		); err != nil {
++			return nil, err
++		}
++		items = append(items, i)
++	}
++	if err := rows.Err(); err != nil {
++		return nil, err
++	}
++	return items, nil
++}
++
++const listTeamsForUserInOrg = `-- name: ListTeamsForUserInOrg :many
++SELECT t.id, t.org_id, t.slug, t.display_name, t.description,
++       t.parent_team_id, t.privacy, t.created_by_user_id,
++       t.created_at, t.updated_at,
++       m.role AS member_role
++FROM team_members m
++JOIN teams t ON t.id = m.team_id
++WHERE t.org_id = $1 AND m.user_id = $2
++`
++
++type ListTeamsForUserInOrgParams struct {
++	OrgID  int64
++	UserID int64
++}
++
++type ListTeamsForUserInOrgRow struct {
++	ID              int64
++	OrgID           int64
++	Slug            string
++	DisplayName     string
++	Description     string
++	ParentTeamID    pgtype.Int8
++	Privacy         TeamPrivacy
++	CreatedByUserID pgtype.Int8
++	CreatedAt       pgtype.Timestamptz
++	UpdatedAt       pgtype.Timestamptz
++	MemberRole      TeamRole
++}
++
++// Returns the teams a user directly belongs to within an org. The
++// policy aggregator unions this with each row's parent_team_id to
++// get the inherited set.
++func (q *Queries) ListTeamsForUserInOrg(ctx context.Context, db DBTX, arg ListTeamsForUserInOrgParams) ([]ListTeamsForUserInOrgRow, error) {
++	rows, err := db.Query(ctx, listTeamsForUserInOrg, arg.OrgID, arg.UserID)
++	if err != nil {
++		return nil, err
++	}
++	defer rows.Close()
++	items := []ListTeamsForUserInOrgRow{}
++	for rows.Next() {
++		var i ListTeamsForUserInOrgRow
++		if err := rows.Scan(
++			&i.ID,
++			&i.OrgID,
++			&i.Slug,
++			&i.DisplayName,
++			&i.Description,
++			&i.ParentTeamID,
++			&i.Privacy,
++			&i.CreatedByUserID,
++			&i.CreatedAt,
++			&i.UpdatedAt,
++			&i.MemberRole,
++		); err != nil {
++			return nil, err
++		}
++		items = append(items, i)
++	}
++	if err := rows.Err(); err != nil {
++		return nil, err
++	}
++	return items, nil
++}
++
++const removeTeamMember = `-- name: RemoveTeamMember :exec
++DELETE FROM team_members WHERE team_id = $1 AND user_id = $2
++`
++
++type RemoveTeamMemberParams struct {
++	TeamID int64
++	UserID int64
++}
++
++func (q *Queries) RemoveTeamMember(ctx context.Context, db DBTX, arg RemoveTeamMemberParams) error {
++	_, err := db.Exec(ctx, removeTeamMember, arg.TeamID, arg.UserID)
++	return err
++}
++
++const revokeTeamRepoAccess = `-- name: RevokeTeamRepoAccess :exec
++DELETE FROM team_repo_access WHERE team_id = $1 AND repo_id = $2
++`
++
++type RevokeTeamRepoAccessParams struct {
++	TeamID int64
++	RepoID int64
++}
++
++func (q *Queries) RevokeTeamRepoAccess(ctx context.Context, db DBTX, arg RevokeTeamRepoAccessParams) error {
++	_, err := db.Exec(ctx, revokeTeamRepoAccess, arg.TeamID, arg.RepoID)
++	return err
++}
++
++const setTeamMemberRole = `-- name: SetTeamMemberRole :exec
++UPDATE team_members SET role = $3 WHERE team_id = $1 AND user_id = $2
++`
++
++type SetTeamMemberRoleParams struct {
++	TeamID int64
++	UserID int64
++	Role   TeamRole
++}
++
++func (q *Queries) SetTeamMemberRole(ctx context.Context, db DBTX, arg SetTeamMemberRoleParams) error {
++	_, err := db.Exec(ctx, setTeamMemberRole, arg.TeamID, arg.UserID, arg.Role)
++	return err
++}
++
++const setTeamParent = `-- name: SetTeamParent :exec
++UPDATE teams SET parent_team_id = $2::bigint, updated_at = now()
++WHERE id = $1
++`
++
++type SetTeamParentParams struct {
++	ID           int64
++	ParentTeamID pgtype.Int8
++}
++
++// The one-level-nesting BEFORE trigger blocks invalid moves; the
++// caller surfaces the SQLSTATE 23514 as a friendly error.
++func (q *Queries) SetTeamParent(ctx context.Context, db DBTX, arg SetTeamParentParams) error {
++	_, err := db.Exec(ctx, setTeamParent, arg.ID, arg.ParentTeamID)
++	return err
++}
++
++const updateTeamProfile = `-- name: UpdateTeamProfile :exec
++UPDATE teams SET display_name = $2, description = $3, privacy = $4, updated_at = now()
++WHERE id = $1
++`
++
++type UpdateTeamProfileParams struct {
++	ID          int64
++	DisplayName string
++	Description string
++	Privacy     TeamPrivacy
++}
++
++func (q *Queries) UpdateTeamProfile(ctx context.Context, db DBTX, arg UpdateTeamProfileParams) error {
++	_, err := db.Exec(ctx, updateTeamProfile,
++		arg.ID,
++		arg.DisplayName,
++		arg.Description,
++		arg.Privacy,
++	)
++	return err
++}

internal/orgs/teams.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++package orgs
++
++import (
++	"context"
++	"errors"
++	"fmt"
++	"regexp"
++	"strings"
++
++	"github.com/jackc/pgx/v5"
++	"github.com/jackc/pgx/v5/pgconn"
++	"github.com/jackc/pgx/v5/pgtype"
++
++	orgsdb "github.com/tenseleyFlow/shithub/internal/orgs/sqlc"
++)
++
++// Errors surfaced by the team orchestrator.
++var (
++	ErrTeamNotFound        = errors.New("orgs: team not found")
++	ErrTeamSlugInvalid     = errors.New("orgs: team slug must be lowercase letters, digits, and hyphens (1-50)")
++	ErrTeamSlugTaken       = errors.New("orgs: team slug already in use in this org")
++	ErrTeamNestingTooDeep  = errors.New("orgs: team nesting limited to one level (parent already has a parent)")
++	ErrTeamSelfParent      = errors.New("orgs: a team cannot be its own parent")
++	ErrTeamCrossOrgParent  = errors.New("orgs: parent team must belong to the same org")
++	ErrTeamMissingActor    = errors.New("orgs: actor required for team mutation")
++	ErrTeamRoleInvalid     = errors.New("orgs: invalid team role")
++	ErrTeamRepoRoleInvalid = errors.New("orgs: invalid team repo-access role")
++)
++
++// teamSlugRE matches the team slug shape (lowercase letters, digits,
++// hyphens, dots; can't start/end with hyphen). 50 chars matches the
++// migration's CHECK.
++var teamSlugRE = regexp.MustCompile(`^[a-z0-9](?:[a-z0-9._-]{0,48}[a-z0-9])?$`)
++
++// CreateTeamParams describes a new-team request.
++type CreateTeamParams struct {
++	OrgID           int64
++	Slug            string
++	DisplayName     string
++	Description     string
++	ParentTeamID    int64  // 0 → top-level
++	Privacy         string // "visible" | "secret"
++	CreatedByUserID int64
++}
++
++// CreateTeam inserts a team row. Validates slug format, checks
++// parent-team org match, and translates the trigger's nesting-violation
++// SQLSTATE into a friendly error.
++func CreateTeam(ctx context.Context, deps Deps, p CreateTeamParams) (orgsdb.Team, error) {
++	slug := strings.ToLower(strings.TrimSpace(p.Slug))
++	if !teamSlugRE.MatchString(slug) {
++		return orgsdb.Team{}, ErrTeamSlugInvalid
++	}
++	if p.CreatedByUserID == 0 {
++		return orgsdb.Team{}, ErrTeamMissingActor
++	}
++	priv, err := parsePrivacy(p.Privacy)
++	if err != nil {
++		return orgsdb.Team{}, err
++	}
++	q := orgsdb.New()
++	if p.ParentTeamID != 0 {
++		parent, perr := q.GetTeamByID(ctx, deps.Pool, p.ParentTeamID)
++		if perr != nil {
++			if errors.Is(perr, pgx.ErrNoRows) {
++				return orgsdb.Team{}, ErrTeamNotFound
++			}
++			return orgsdb.Team{}, perr
++		}
++		if parent.OrgID != p.OrgID {
++			return orgsdb.Team{}, ErrTeamCrossOrgParent
++		}
++	}
++	row, err := q.CreateTeam(ctx, deps.Pool, orgsdb.CreateTeamParams{
++		OrgID:           p.OrgID,
++		Slug:            slug,
++		DisplayName:     strings.TrimSpace(p.DisplayName),
++		Description:     strings.TrimSpace(p.Description),
++		ParentTeamID:    pgtype.Int8{Int64: p.ParentTeamID, Valid: p.ParentTeamID != 0},
++		Privacy:         priv,
++		CreatedByUserID: pgtype.Int8{Int64: p.CreatedByUserID, Valid: true},
++	})
++	if err != nil {
++		return orgsdb.Team{}, translateTeamError(err)
++	}
++	return row, nil
++}
++
++// SetParent changes a team's parent. Both the no-self-parent CHECK
++// and the one-level-nesting trigger fire here; we translate to the
++// orchestrator-level errors.
++func SetTeamParent(ctx context.Context, deps Deps, teamID, parentTeamID int64) error {
++	if parentTeamID == teamID {
++		return ErrTeamSelfParent
++	}
++	err := orgsdb.New().SetTeamParent(ctx, deps.Pool, orgsdb.SetTeamParentParams{
++		ID:           teamID,
++		ParentTeamID: pgtype.Int8{Int64: parentTeamID, Valid: parentTeamID != 0},
++	})
++	return translateTeamError(err)
++}
++
++// AddTeamMember inserts (team, user) at the given role. Idempotent on
++// the pair (the sqlc query uses ON CONFLICT DO NOTHING). Caller
++// resolves the policy gate; this orchestrator just shapes the row.
++func AddTeamMember(ctx context.Context, deps Deps, teamID, userID, addedByUserID int64, role string) error {
++	r, err := parseTeamRole(role)
++	if err != nil {
++		return err
++	}
++	return orgsdb.New().AddTeamMember(ctx, deps.Pool, orgsdb.AddTeamMemberParams{
++		TeamID:        teamID,
++		UserID:        userID,
++		Role:          r,
++		AddedByUserID: pgtype.Int8{Int64: addedByUserID, Valid: addedByUserID != 0},
++	})
++}
++
++// RemoveTeamMember drops the (team, user) pair. No last-maintainer
++// protection here — teams without maintainers are fine; org owners
++// can always still mutate the team via the org-owner policy bypass.
++func RemoveTeamMember(ctx context.Context, deps Deps, teamID, userID int64) error {
++	return orgsdb.New().RemoveTeamMember(ctx, deps.Pool, orgsdb.RemoveTeamMemberParams{
++		TeamID: teamID, UserID: userID,
++	})
++}
++
++// GrantRepoAccess upserts the team's role on a repo. ON CONFLICT
++// DO UPDATE so re-granting at a new role is one call.
++func GrantTeamRepoAccess(ctx context.Context, deps Deps, teamID, repoID, addedByUserID int64, role string) error {
++	r, err := parseTeamRepoRole(role)
++	if err != nil {
++		return err
++	}
++	return orgsdb.New().GrantTeamRepoAccess(ctx, deps.Pool, orgsdb.GrantTeamRepoAccessParams{
++		TeamID:        teamID,
++		RepoID:        repoID,
++		Role:          r,
++		AddedByUserID: pgtype.Int8{Int64: addedByUserID, Valid: addedByUserID != 0},
++	})
++}
++
++// RevokeTeamRepoAccess drops the team's grant. Effective immediately
++// (next request denies; per-request policy cache means in-flight
++// requests can still pass — same staleness as collaborator changes).
++func RevokeTeamRepoAccess(ctx context.Context, deps Deps, teamID, repoID int64) error {
++	return orgsdb.New().RevokeTeamRepoAccess(ctx, deps.Pool, orgsdb.RevokeTeamRepoAccessParams{
++		TeamID: teamID, RepoID: repoID,
++	})
++}
++
++// ─── helpers ───────────────────────────────────────────────────────
++
++func parsePrivacy(s string) (orgsdb.TeamPrivacy, error) {
++	switch s {
++	case "", "visible":
++		return orgsdb.TeamPrivacyVisible, nil
++	case "secret":
++		return orgsdb.TeamPrivacySecret, nil
++	}
++	return "", fmt.Errorf("orgs: invalid team privacy %q", s)
++}
++
++func parseTeamRole(s string) (orgsdb.TeamRole, error) {
++	switch s {
++	case "", "member":
++		return orgsdb.TeamRoleMember, nil
++	case "maintainer":
++		return orgsdb.TeamRoleMaintainer, nil
++	}
++	return "", ErrTeamRoleInvalid
++}
++
++func parseTeamRepoRole(s string) (orgsdb.TeamRepoRole, error) {
++	switch s {
++	case "read":
++		return orgsdb.TeamRepoRoleRead, nil
++	case "triage":
++		return orgsdb.TeamRepoRoleTriage, nil
++	case "write":
++		return orgsdb.TeamRepoRoleWrite, nil
++	case "maintain":
++		return orgsdb.TeamRepoRoleMaintain, nil
++	case "admin":
++		return orgsdb.TeamRepoRoleAdmin, nil
++	}
++	return "", ErrTeamRepoRoleInvalid
++}
++
++// translateTeamError maps Postgres errors back to the orchestrator's
++// typed errors. The migration's nesting trigger raises CHECK
++// (SQLSTATE 23514); the unique index on (org_id, slug) raises 23505.
++func translateTeamError(err error) error {
++	if err == nil {
++		return nil
++	}
++	var pgErr *pgconn.PgError
++	if errors.As(err, &pgErr) {
++		switch pgErr.Code {
++		case "23505":
++			return ErrTeamSlugTaken
++		case "23514":
++			if strings.Contains(pgErr.Message, "no_self_parent") {
++				return ErrTeamSelfParent
++			}
++			return ErrTeamNestingTooDeep
++		}
++	}
++	return err
++}

internal/orgs/teams_test.goadded

++// SPDX-License-Identifier: AGPL-3.0-or-later
++
++package orgs_test
++
++import (
++	"context"
++	"errors"
++	"testing"
++
++	"github.com/tenseleyFlow/shithub/internal/orgs"
++)
++
++func TestCreateTeam_HappyPath(t *testing.T) {
++	_, deps, alice := setup(t)
++	ctx := context.Background()
++	org, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: alice})
++	team, err := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "engineering", DisplayName: "Engineering",
++		CreatedByUserID: alice,
++	})
++	if err != nil {
++		t.Fatalf("CreateTeam: %v", err)
++	}
++	if string(team.Slug) != "engineering" {
++		t.Fatalf("slug: want engineering, got %q", team.Slug)
++	}
++}
++
++func TestCreateTeam_RejectsInvalidSlug(t *testing.T) {
++	_, deps, alice := setup(t)
++	ctx := context.Background()
++	org, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: alice})
++	_, err := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "BAD SLUG", CreatedByUserID: alice,
++	})
++	if !errors.Is(err, orgs.ErrTeamSlugInvalid) {
++		t.Fatalf("want ErrTeamSlugInvalid, got %v", err)
++	}
++}
++
++func TestCreateTeam_RejectsDuplicateSlug(t *testing.T) {
++	_, deps, alice := setup(t)
++	ctx := context.Background()
++	org, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: alice})
++	if _, err := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "eng", CreatedByUserID: alice,
++	}); err != nil {
++		t.Fatalf("first: %v", err)
++	}
++	_, err := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "eng", CreatedByUserID: alice,
++	})
++	if !errors.Is(err, orgs.ErrTeamSlugTaken) {
++		t.Fatalf("want ErrTeamSlugTaken, got %v", err)
++	}
++}
++
++// One-level-deep nesting: creating a team with a parent that already
++// has a parent must be refused at the trigger.
++func TestCreateTeam_RejectsTwoLevelNesting(t *testing.T) {
++	_, deps, alice := setup(t)
++	ctx := context.Background()
++	org, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: alice})
++	gp, err := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "g", CreatedByUserID: alice,
++	})
++	if err != nil {
++		t.Fatalf("create grandparent: %v", err)
++	}
++	parent, err := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "p", ParentTeamID: gp.ID, CreatedByUserID: alice,
++	})
++	if err != nil {
++		t.Fatalf("create parent: %v", err)
++	}
++	_, err = orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "c", ParentTeamID: parent.ID, CreatedByUserID: alice,
++	})
++	if !errors.Is(err, orgs.ErrTeamNestingTooDeep) {
++		t.Fatalf("want ErrTeamNestingTooDeep, got %v", err)
++	}
++}
++
++func TestSetTeamParent_RejectsSelfParent(t *testing.T) {
++	_, deps, alice := setup(t)
++	ctx := context.Background()
++	org, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: alice})
++	team, _ := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org.ID, Slug: "eng", CreatedByUserID: alice,
++	})
++	err := orgs.SetTeamParent(ctx, deps, team.ID, team.ID)
++	if !errors.Is(err, orgs.ErrTeamSelfParent) {
++		t.Fatalf("want ErrTeamSelfParent, got %v", err)
++	}
++}
++
++func TestCreateTeam_RejectsCrossOrgParent(t *testing.T) {
++	pool, deps, alice := setup(t)
++	ctx := context.Background()
++	bob := mustUser(t, pool, "bob")
++	org1, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "acme", CreatedByUserID: alice})
++	org2, _ := orgs.Create(ctx, deps, orgs.CreateParams{Slug: "beta", CreatedByUserID: bob})
++	parent, _ := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org2.ID, Slug: "g", CreatedByUserID: bob,
++	})
++	_, err := orgs.CreateTeam(ctx, deps, orgs.CreateTeamParams{
++		OrgID: org1.ID, Slug: "c", ParentTeamID: parent.ID, CreatedByUserID: alice,
++	})
++	if !errors.Is(err, orgs.ErrTeamCrossOrgParent) {
++		t.Fatalf("want ErrTeamCrossOrgParent, got %v", err)
++	}
++}