super_auth 0.7.0 → 0.9.0

data/lib/super_auth/edge.rb

@@ -7,6 +7,19 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
   many_to_one :role
   many_to_one :resource
 
+  # The columns of `authorizations`, in its order. compile! inserts the union
+  # straight into super_auth_authorizations under this list, so it is the
+  # contract between the five SELECTs below and the table: MySQL and Postgres
+  # both need the column list, and the table has columns the union does not
+  # fill (its own timestamps, the ActiveRecord migration's id).
+  AUTHORIZATION_COLUMNS = %i[
+    user_id user_name user_external_id user_external_type user_created_at user_updated_at
+    group_id group_name group_path group_name_path group_parent_id group_created_at group_updated_at
+    role_id role_name role_path role_name_path role_parent_id role_created_at role_updated_at
+    permission_id permission_name permission_created_at permission_updated_at
+    resource_id resource_name resource_external_id resource_external_type
+  ].freeze
+
   class << self
     # The five strategies are UNIONed positionally. A column that is a real
     # text column in one strategy and CAST(NULL AS ...) in another must be cast
@@ -39,6 +52,51 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
         .union(users_resources)
     end
 
+    # Every resource node a grant reaches: each granted node paired with
+    # itself and each of its descendants, as (ancestor_id, descendant_id).
+    # Anchored on the ids that appear in edges rather than on the whole table.
+    # Groups and roles are few, but resources are one row per protected
+    # record, and the unanchored CTE materialises every pair of the table once
+    # per strategy — 27s per strategy on MySQL at 300k resources, 0.025s
+    # anchored — so the walk is sized by the grants, not by the table. On a
+    # flat graph it is the identity relation and the compiled rows are exactly
+    # what the previous pk join produced. The walk never descends from a
+    # type-level node (Resource.descend_from): a granted (type, NULL) node
+    # pairs with itself and nothing beneath it, on every path that reads this
+    # relation, compile! or not.
+    def resource_subtrees
+      granted = db[:super_auth_edges].exclude(resource_id: nil).select(:resource_id)
+      SuperAuth::Resource.descendant_pairs(of: granted)
+    end
+
+    # The last hop of every strategy: from the resource id on an edge to the
+    # node it names and each node under it. The compiled row copies the
+    # descendant's own columns, so containment is not inheritance — a node
+    # keeps its own external_type — and the type-level tricks in ByCurrentUser
+    # still hold. No resource path columns, unlike groups and roles: nothing at
+    # runtime reads one, and super_auth_authorizations gains no columns.
+    def join_resource_subtree(ds, resource_id_column)
+      ds.
+        join(resource_subtrees.as(:resource_descendants), ancestor_id: resource_id_column).
+        join(Sequel[:super_auth_resources], id: Sequel[:resource_descendants][:descendant_id]).
+        # A (type, NULL) row — a type-level node, every record of its type —
+        # is only ever the node the grant named, never one reached through
+        # the tree; the walk itself refuses the other direction, a node
+        # reached through a type-level parent. Resource.assert_compilable!
+        # refuses both shapes loudly, but it is a separate statement from this
+        # one: under READ COMMITTED a write that nests a type-level node can
+        # land between the two, and the compiled table must not widen a
+        # container grant to a whole type, or a type-level grant to the nodes
+        # under it, because of it.
+        where(
+          Sequel.|(
+            { Sequel[:resource_descendants][:ancestor_id] => Sequel[:resource_descendants][:descendant_id] },
+            { Sequel[:super_auth_resources][:external_type] => nil },
+            Sequel.~(Sequel[:super_auth_resources][:external_id] => nil)
+          )
+        )
+    end
+
     def users_groups_roles_permissions_resources
       cast_type = string_cast_type
       # Join users to their group via edges. group_ancestors pairs that group with itself and
@@ -46,7 +104,7 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
       # expands the granted role to its whole subtree. Each step is correlated to the previous
       # one, so a role held by one group never reaches members of an unrelated group. The tree
       # CTEs (user_groups, granted_roles) are joined by id only to supply the path columns.
-      SuperAuth::User.db[:super_auth_users].
+      ds = SuperAuth::User.db[:super_auth_users].
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         join(SuperAuth::Group.ancestor_pairs.as(:group_ancestors), descendant_id: Sequel[:user_edges][:group_id]).
         join(Sequel[:super_auth_edges].as(:group_role_edges), group_id: Sequel[:group_ancestors][:ancestor_id]).
@@ -56,8 +114,8 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
         join(SuperAuth::Role.from(SuperAuth::Role.trees).as(:granted_roles), Sequel[:granted_roles][:id] => Sequel[:role_descendants][:descendant_id]).
         join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:role_id] => Sequel[:granted_roles][:id]).
         join(Sequel[:super_auth_permissions], id: Sequel[:permission_edges][:permission_id]).
-        join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-        join(Sequel[:super_auth_resources], id: Sequel[:resource_edges][:resource_id]).
+        join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:resource_edges][:resource_id]).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
           Sequel[:super_auth_users][:name].as(:user_name),
@@ -100,14 +158,14 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
       # Join users to their group via edges. group_ancestors pairs that group with itself and
       # every ancestor, so a group -> permission edge on any of them applies. user_groups (the
       # tree) is joined by id only to supply the path columns.
-      SuperAuth::User.db[:super_auth_users].
+      ds = SuperAuth::User.db[:super_auth_users].
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         join(SuperAuth::Group.ancestor_pairs.as(:group_ancestors), descendant_id: Sequel[:user_edges][:group_id]).
         join(Sequel[:super_auth_edges].as(:group_edges), group_id: Sequel[:group_ancestors][:ancestor_id]).
         join(SuperAuth::Group.from(SuperAuth::Group.trees).as(:user_groups), Sequel[:user_groups][:id] => Sequel[:user_edges][:group_id]).
         join(Sequel[:super_auth_permissions], id: Sequel[:group_edges][:permission_id]).
-        join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-        join(Sequel[:super_auth_resources], id: Sequel[:permission_edges][:resource_id]).
+        join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:permission_edges][:resource_id]).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
           Sequel[:super_auth_users][:name].as(:user_name),
@@ -150,7 +208,7 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
 
       # Join users to the roles they hold directly. role_descendants expands each held role to
       # its whole subtree; granted_roles (the tree) is joined by id only to supply the path columns.
-      SuperAuth::User.db[:super_auth_users].
+      ds = SuperAuth::User.db[:super_auth_users].
       join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
       where(Sequel.~(Sequel[:user_edges][:role_id] => nil)).
       join(SuperAuth::Role.descendant_pairs.as(:role_descendants), ancestor_id: Sequel[:user_edges][:role_id]).
@@ -192,14 +250,13 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
       # Join permission and resource edges on the expanded role
       join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:role_id] => Sequel[:granted_roles][:id]).
       join(Sequel[:super_auth_permissions], id: Sequel[:permission_edges][:permission_id]).
-      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-      join(Sequel[:super_auth_resources], id: Sequel[:resource_edges][:resource_id]).
-      distinct
+      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:resource_edges][:resource_id]).distinct
     end
 
     def users_permissions_resources
       cast_type = string_cast_type
-      SuperAuth::User.
+      ds = SuperAuth::User.
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
@@ -237,14 +294,13 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
         ).
       join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:user_id] => Sequel[:super_auth_users][:id]).
       join(Sequel[:super_auth_permissions], id: Sequel[:permission_edges][:permission_id]).
-      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-      join(Sequel[:super_auth_resources], id: Sequel[:resource_edges][:resource_id]).
-      distinct
+      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:resource_edges][:resource_id]).distinct
     end
 
     def users_resources
       cast_type = string_cast_type
-      SuperAuth::User.
+      ds = SuperAuth::User.
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
@@ -279,9 +335,8 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
           Sequel[:super_auth_resources][:name].as(:resource_name),
           Sequel[:super_auth_resources][:external_id].as(:resource_external_id),
           Sequel[:super_auth_resources][:external_type].as(:resource_external_type)
-        ).
-      join(Sequel[:super_auth_resources], Sequel[:user_edges][:resource_id] => Sequel[:super_auth_resources][:id]).
-      distinct
+        )
+      join_resource_subtree(ds, Sequel[:user_edges][:resource_id]).distinct
     end
   end
 

data/lib/super_auth/editor/index.html

@@ -53,8 +53,8 @@
   .region{display:grid;gap:10px;min-height:0}
   .region.top{flex:1.15;grid-template-columns:1fr 1fr;grid-template-rows:1fr 1fr;
     grid-template-areas:"group role" "user perm"}
-  .region.bottom{flex:.85;grid-template-columns:1fr 1fr;grid-template-rows:1fr;
-    grid-template-areas:"resource user2"}
+  .region.bottom{flex:.85;grid-template-columns:1fr;grid-template-rows:1fr;
+    grid-template-areas:"resource"}
 
   /* ---- box ---- */
   .box{background:var(--panel);border:1px solid var(--line);border-radius:10px;display:flex;flex-direction:column;min-height:0;overflow:hidden}
@@ -63,7 +63,6 @@
   .box[data-area=user]{grid-area:user;--accent:var(--c-user)}
   .box[data-area=permission]{grid-area:perm;--accent:var(--c-perm)}
   .box[data-area=resource]{grid-area:resource;--accent:var(--c-resource)}
-  .box[data-area=user2]{grid-area:user2;--accent:var(--c-user)}
   .box-head{display:flex;align-items:center;gap:9px;padding:9px 12px;border-bottom:1px solid var(--line);flex:none}
   .box-head .swatch{width:10px;height:10px;border-radius:3px;background:var(--accent);flex:none;box-shadow:0 0 10px -2px var(--accent)}
   .box-head .title{font-family:var(--mono);font-weight:600;font-size:13px;letter-spacing:.02em}
@@ -122,7 +121,6 @@
   </section>
   <section class="region bottom">
     <div class="box" data-area="resource" data-type="resource"></div>
-    <div class="box" data-area="user2"     data-type="user"></div>
   </section>
 </main>
 
@@ -130,7 +128,7 @@
 // The app may be mounted under a prefix; every API call is relative to this page.
 const API = location.pathname.replace(/\/$/, "");
 const TITLES = {group:"Groups", role:"Roles", user:"Users", permission:"Permissions", resource:"Resources"};
-const NESTED = new Set(["group","role"]);
+const NESTED = new Set(["group","role","resource"]);
 
 let GRAPH = null;           // {groups,roles,users,permissions,resources,edges,authorizations_count}
 let selection = null;       // {type,id}
@@ -157,8 +155,8 @@ async function load(){
 // Authorization flows user → group → role → permission → resource. From the
 // selected node we collect everything DOWNSTREAM (what it can reach) and
 // everything UPSTREAM (what can reach it). So a user shows what they can access;
-// a resource shows who can access it. Group/role hierarchy is bidirectional
-// (a parent's grants apply to children, and a parent "contains" its children).
+// a resource shows who can access it. The group, role and resource trees are
+// each folded in as one more directed hop (see buildDirected).
 const RANK = {user:0, group:1, role:2, permission:3, resource:4};
 
 function buildDirected(){
@@ -184,9 +182,13 @@ function buildDirected(){
   //    inherits ANCESTOR grants → a child group is upstream of its parent.
   //  • Role grants flow to DESCENDANT roles, so holding a parent role includes
   //    its children → a parent role is upstream of its child.
+  //  • Resource grants reach DESCENDANT resources: a grant on a container
+  //    covers everything under it → a parent resource is upstream of its
+  //    children, the same direction as roles and the opposite of groups.
   // (Selecting a child group therefore reaches its ancestors, never its siblings.)
   for(const g of GRAPH.groups) if(g.parent_id) dir(key("group",g.id), key("group",g.parent_id));
   for(const r of GRAPH.roles)  if(r.parent_id) dir(key("role",r.parent_id), key("role",r.id));
+  for(const r of GRAPH.resources) if(r.parent_id) dir(key("resource",r.parent_id), key("resource",r.id));
   return {fwd,bwd};
 }
 
@@ -248,11 +250,15 @@ function render(){
       const name = n.name ?? "";
       // The external record occupies one slot: its label when the graph
       // stored one, otherwise the Type#id that used to be the only
-      // rendering. Either way the other half is the tooltip.
+      // rendering. Either way the other half is the tooltip. A type with no
+      // id is the type-level (wildcard) node — every record of the type —
+      // and its tooltip says so, since Type#* alone reads as a typo.
+      const wildcard = type === "resource" && !!n.external_type && n.external_id == null;
       const ref = n.external_type ? `${escapeHtml(n.external_type)}#${escapeHtml(n.external_id ?? "*")}` : "";
+      const kind = wildcard ? "type-level grant" : "external record";
       const ext = !ref ? "" : (n.super_auth_label
-        ? `<span class="ext" title="${ref}">${escapeHtml(n.super_auth_label)}</span>`
-        : `<span class="ext" title="external record">${ref}</span>`);
+        ? `<span class="ext" title="${wildcard ? `${ref} · ${kind}` : ref}">${escapeHtml(n.super_auth_label)}</span>`
+        : `<span class="ext" title="${kind}">${ref}</span>`);
       return `<div class="item ${isSel?'selected':''} ${isCF?'connect-first':''}" data-id="${n.id}" ${pad}>
         <span class="tick"></span>
         ${arrow}<span class="name" title="${escapeHtml(name)}">${escapeHtml(name)}</span>${ext}

data/lib/super_auth/editor/seed.rb

@@ -15,6 +15,11 @@ module SuperAuth
     #     does not.
     #   - "Support Lead" is the PARENT role of "Support Agent": a lead inherits
     #     the agent's abilities plus refunds; an agent does not get refunds.
+    #   - "clusters" is a CONTAINER resource holding production_cluster and
+    #     staging_cluster. deploy is granted on the container and reaches both
+    #     clusters through the tree; restart_server and Morgan's direct grant
+    #     name production_cluster alone, so the tree shows a container grant
+    #     and a leaf grant side by side.
     #
     # Special people:
     #   - Riley (Auditor): read-only into BOTH Finance and Support
@@ -68,8 +73,9 @@ module SuperAuth
 
           # ===== RESOURCES (disjoint per department) =====
           source_repo        = res_m.create(name: "source_repo")
-          production_cluster = res_m.create(name: "production_cluster")
-          staging_cluster    = res_m.create(name: "staging_cluster")
+          clusters           = res_m.create(name: "clusters")                                   # container
+          production_cluster = res_m.create(name: "production_cluster", parent_id: clusters.id)
+          res_m.create(name: "staging_cluster", parent_id: clusters.id)  # reached only through clusters
           app_database       = res_m.create(name: "app_database")      # Backend
           marketing_site     = res_m.create(name: "marketing_site")    # Frontend
           general_ledger     = res_m.create(name: "general_ledger")
@@ -99,8 +105,8 @@ module SuperAuth
           edg.create(role_id: developer.id, permission_id: deploy.id)
           edg.create(permission_id: merge_code.id, resource_id: source_repo.id)
           edg.create(permission_id: read_repo.id,  resource_id: source_repo.id)
-          edg.create(permission_id: deploy.id,     resource_id: production_cluster.id)
-          edg.create(permission_id: deploy.id,     resource_id: staging_cluster.id)
+          # One grant on the container reaches both clusters.
+          edg.create(permission_id: deploy.id,     resource_id: clusters.id)
           # Child-group-specific grants (Alice gets one, Bob the other)
           edg.create(group_id: backend.id,  permission_id: run_migrations.id)
           edg.create(permission_id: run_migrations.id, resource_id: app_database.id)
@@ -153,7 +159,7 @@ module SuperAuth
       def clear!
         SuperAuth::Edge.dataset.delete
         SuperAuth::Authorization.dataset.delete
-        [SuperAuth::Group, SuperAuth::Role].each { |m| m.dataset.update(parent_id: nil) }
+        [SuperAuth::Group, SuperAuth::Role, SuperAuth::Resource].each { |m| m.dataset.update(parent_id: nil) }
         [SuperAuth::Group, SuperAuth::Role, SuperAuth::User, SuperAuth::Permission, SuperAuth::Resource].each do |m|
           m.dataset.delete
         end

data/lib/super_auth/editor.rb

@@ -3,7 +3,8 @@ require "super_auth"
 
 module SuperAuth
   # A small Rack application that edits the authorization graph: five boxes of
-  # records, client-side traversal, node and edge CRUD, and a Recompile button.
+  # records (groups, roles and resources drawn as trees), client-side
+  # traversal, node and edge CRUD, and a Recompile button.
   # Rails-free; it needs only SuperAuth.db to be connected and the tables to
   # exist. Mount it as `run SuperAuth::Editor` (Rack) or
   # `mount SuperAuth::Editor => "/super_auth/editor"` (Rails), or run
@@ -19,7 +20,9 @@ module SuperAuth
   #
   # Edits change the graph, not runtime access: ByCurrentUser and the RLS
   # policies read the compiled super_auth_authorizations table, so the UI
-  # shows its row count and offers POST /api/compile.
+  # shows its row count and offers POST /api/compile. A compile the models
+  # refuse (SuperAuth::Error, the wildcard guard) comes back as a 422 with
+  # the model's own message, like any other rejected write.
   class Editor
     TYPES = {
       "user" => :User, "group" => :Group, "role" => :Role,
@@ -29,7 +32,7 @@ module SuperAuth
       "user" => :user_id, "group" => :group_id, "role" => :role_id,
       "permission" => :permission_id, "resource" => :resource_id,
     }.freeze
-    NESTED = %w[group role].freeze
+    NESTED = %w[group role resource].freeze
     # The pairs the path strategies read (see Edge.authorizations), unordered.
     # The models also accept group->resource and role->resource rows, but no
     # strategy reads them, so they would grant nothing.
@@ -69,6 +72,8 @@ module SuperAuth
       end
 
       route(method, path, env)
+    rescue SuperAuth::Error => e
+      json(422, error: e.message)
     rescue Sequel::Error
       json(422, error: "the database rejected the change")
     end
@@ -103,7 +108,7 @@ module SuperAuth
         roles: nodes(:Role, :parent_id),
         users: nodes(:User, :external_id, :external_type),
         permissions: nodes(:Permission),
-        resources: nodes(:Resource, :external_id, :external_type, :super_auth_label),
+        resources: nodes(:Resource, :parent_id, :external_id, :external_type, :super_auth_label),
         edges: SuperAuth::Edge.order(:id).map { |e| edge_json(e) },
         authorizations_count: SuperAuth::Authorization.count,
       }
@@ -122,9 +127,12 @@ module SuperAuth
     # indentation, so a child has to arrive immediately after its parent or
     # it reads as nested under whatever happens to sort above it — which is
     # the one question an auditor opens this editor to answer. Sorting by the
-    # ancestors' [name, id] pairs, outermost first, puts every child under its
-    # own parent and leaves siblings alphabetical. Both node sets are small
-    # enough to order in Ruby, and the client's depthOf is unaffected.
+    # ancestors' [name, label, id] triples, outermost first, puts every child
+    # under its own parent and leaves siblings alphabetical; the label only
+    # separates same-named siblings, which synced resources are (one "Claim"
+    # per record), and is absent from groups and roles. All three node sets
+    # are small enough to order in Ruby, and the client's depthOf is
+    # unaffected.
     #
     # The key is total, so the order stays defined for broken trees: a row
     # whose parent_id names a missing row sorts as a root, and a parent cycle
@@ -137,7 +145,7 @@ module SuperAuth
         node = row
         while node && !seen[node[:id]]
           seen[node[:id]] = true
-          path.unshift([node[:name].to_s, node[:id]])
+          path.unshift([node[:name].to_s, node[:super_auth_label].to_s, node[:id]])
           node = by_id[node[:parent_id]]
         end
         path
@@ -158,7 +166,14 @@ module SuperAuth
       unless parent.nil?
         return json(422, error: "#{type} records cannot have a parent") unless NESTED.include?(type)
         return json(422, error: "parent_id must be an integer") unless integer_id?(parent)
-        return json(422, error: "parent not found") unless model[parent.to_i]
+        parent_node = model[parent.to_i]
+        return json(422, error: "parent not found") unless parent_node
+        # "Wildcard nodes are flat": compile! refuses a tree with a type-level
+        # node in it, so refuse the shape at the door with the reason instead.
+        if type == "resource" && parent_node.external_type && parent_node.external_id.nil?
+          return json(422, error: "type-level (wildcard) resources are flat and cannot contain other resources; " \
+                                  "make a container (a resource with no external type) instead")
+        end
         attrs[:parent_id] = parent.to_i
       end
 
@@ -172,8 +187,17 @@ module SuperAuth
 
       SuperAuth.db.transaction do
         SuperAuth::Edge.where(COLUMNS[type] => record.id).delete
-        # Children become roots: the deny-safe choice, and required before the
-        # delete on MySQL, which checks the self-referencing key row by row.
+        # The node's own compiled rows go with it: runtime reads only that
+        # table, and a row naming a node that no longer exists would keep
+        # granting until the next compile. Rows compiled through it for its
+        # descendants stay until one runs, as after any other revocation.
+        SuperAuth::Authorization.where(COLUMNS[type] => record.id).delete
+        # Children become roots, deliberately, and the client's confirm says
+        # so: not the grandparent's children, whose grants would then reach
+        # them, and not deleted with the node, which is not what "delete this
+        # container" asks. A root grants nothing by itself, so it is the
+        # deny-safe choice. Also required before the delete on MySQL, which
+        # checks the self-referencing key row by row.
         model.where(parent_id: record.id).update(parent_id: nil) if NESTED.include?(type)
         model.where(id: record.id).delete
       end

data/lib/super_auth/nestable.rb

@@ -24,6 +24,44 @@ module SuperAuth::Nestable
     end
   end
 
+  # A node may not be its own parent, nor sit under one of its own
+  # descendants: either closes a parent_id cycle. The pair CTEs terminate on
+  # one (UNION), so a cycle does not hang a compile; it does something
+  # quieter and worse. Every node in a cycle is an ancestor of every other,
+  # so a grant on any of them reaches all of their subtrees — a container
+  # pointed at one of its own children turned a single per-record read into
+  # the container's whole membership, with nothing raised anywhere. Checked
+  # only when parent_id changes, by walking UP from the new parent: that is
+  # one row per level however large the subtree, and unlike the descendant
+  # walk it does not stop at a type-level node
+  # (SuperAuth::Resource.descend_from), so a cycle through one is caught too.
+  # assert_acyclic! covers writes that bypass the model.
+  def validate
+    super
+    return if parent_id.nil? || !changed_columns.include?(:parent_id)
+
+    if parent_id == id
+      errors.add(:parent_id, "cannot be the node itself")
+    elsif !new? && model.ancestor_pairs(of: [parent_id]).where(ancestor_id: id).count > 0
+      errors.add(:parent_id, "is inside the node's own subtree, which would close a cycle")
+    end
+  end
+
+  # A deleted node takes its compiled rows and its edges with it, in the
+  # transaction that deletes the row: runtime reads only the compiled table,
+  # and a row naming a node that no longer exists would keep granting until
+  # the next compile. Children are not touched. The foreign key refuses to
+  # orphan them, and whether they are re-rooted or deleted is the caller's
+  # decision (the editor re-roots them, deliberately). Rows compiled through
+  # this node for its descendants stay until the next compile, as after any
+  # other revocation.
+  def before_destroy
+    super
+    column = :"#{model.singularize}_id"
+    SuperAuth::Authorization.where(column => id).delete
+    SuperAuth::Edge.where(column => id).delete
+  end
+
   module ClassMethods
     # Helper method to get the appropriate string cast type for the database
     def string_cast_type
@@ -53,24 +91,87 @@ module SuperAuth::Nestable
     # pairs on equality; matching ids inside the comma-separated path strings
     # with LIKE forced a nested loop no planner could index, and compile time
     # grew roughly cubically with the graph.
-    def ancestor_pairs
+    #
+    # Both pair CTEs recurse with UNION rather than UNION ALL. The pair
+    # relation is finite (at most n² rows), so UNION stops as soon as a step
+    # produces nothing new, which on a parent_id cycle is the first time round;
+    # UNION ALL re-derives the same pairs forever and compile! never returns.
+    # On a valid tree no step repeats a pair, so the output is the same.
+    #
+    # `of:` (a dataset or an array of ids) restricts the anchor to those
+    # nodes, so only their ancestor chains are walked: one row per level.
+    def ancestor_pairs(of: nil)
       table = pluralize
       name = :"#{singularize}_ancestor_pairs"
       anchor = db[table].select(Sequel[:id].as(:descendant_id), Sequel[:id].as(:ancestor_id))
+      anchor = anchor.where(id: of) unless of.nil?
       step = db[name].join(table, id: :ancestor_id).exclude(Sequel[table][:parent_id] => nil).
         select(Sequel[name][:descendant_id], Sequel[table][:parent_id])
-      db.from(name).with_recursive(name, anchor, step, args: [:descendant_id, :ancestor_id])
+      db.from(name).with_recursive(name, anchor, step, args: [:descendant_id, :ancestor_id], union_all: false)
     end
 
     # Every node paired with itself and each of its descendants, as
     # (ancestor_id, descendant_id). Granting a role grants its whole subtree.
-    def descendant_pairs
+    #
+    # `of:` (a dataset or an array of ids) restricts the anchor to those nodes,
+    # so only their subtrees are walked. Groups and roles are few and the
+    # whole table is cheap; resources are one row per protected record, and an
+    # unanchored CTE materialises every pair of the whole table once per
+    # strategy that joins it.
+    #
+    # The recursive step joins the parent row only when the model puts a
+    # condition on it (descend_from); the pair CTE itself never carries more
+    # than the two ids.
+    def descendant_pairs(of: nil)
       table = pluralize
       name = :"#{singularize}_descendant_pairs"
+      parent = :"#{singularize}_parent"
       anchor = db[table].select(Sequel[:id].as(:ancestor_id), Sequel[:id].as(:descendant_id))
+      anchor = anchor.where(id: of) unless of.nil?
       step = db[name].join(table, parent_id: :descendant_id).
         select(Sequel[name][:ancestor_id], Sequel[table][:id])
-      db.from(name).with_recursive(name, anchor, step, args: [:ancestor_id, :descendant_id])
+      if (condition = descend_from(parent))
+        step = step.join(Sequel[table].as(parent), id: Sequel[name][:descendant_id]).where(condition)
+      end
+      db.from(name).with_recursive(name, anchor, step, args: [:ancestor_id, :descendant_id], union_all: false)
+    end
+
+    # Whether descendant_pairs continues below a node: a Sequel condition on
+    # the parent row, addressed through the alias `parent`, or nil to descend
+    # from every node. Groups and roles descend from everything.
+    # SuperAuth::Resource stops at a type-level node, so a grant on one yields
+    # its own row and nothing beneath it on every path that reads the walk.
+    def descend_from(parent)
+      nil
+    end
+
+    # Every node some root reaches, walking parent_id downward from the rows
+    # that have none. On a valid forest that is the whole table; what it
+    # misses is exactly the nodes on or under a parent_id cycle (and, where
+    # no foreign key stands, a node whose parent is missing). No path
+    # columns, unlike trees: this runs over the whole resources table before
+    # every compile, and needs only the ids.
+    def rooted
+      table = pluralize
+      name = :"rooted_#{table}"
+      anchor = db[table].where(parent_id: nil).select(:id)
+      step = db[name].join(table, parent_id: :id).select(Sequel[table][:id])
+      db.from(name).with_recursive(name, anchor, step, args: [:id], union_all: false)
+    end
+
+    # Refuses a table with a parent_id cycle in it, naming the nodes no root
+    # reaches. compile! calls this for groups, roles and resources before
+    # touching the compiled table, because a cycle does not fail a compile:
+    # the walks terminate, and every node in the cycle is an ancestor of
+    # every other, so a grant on any of them silently reaches all of their
+    # subtrees. validate refuses the shape at the model; this catches it
+    # after a write that went around the model.
+    def assert_acyclic!
+      unreachable = dataset.exclude(id: rooted).select_order_map(:id)
+      return if unreachable.empty?
+
+      raise SuperAuth::Error, "#{pluralize} has a parent_id cycle: node(s) #{unreachable.join(', ')} " \
+        "cannot be reached from any root. Point one of them at a root, or at no parent, and recompile."
     end
 
     def cte(id = nil, direction = :desc)

data/lib/super_auth/reach.rb

@@ -0,0 +1,88 @@
+# The reach map: which authorization rows admit a row of a protected table.
+#
+# Both layers take the same two keywords, resource_type: and parent:, and
+# both ask the same question of every row: does the current user hold a
+# compiled authorization that reaches it? A row is reached through its own
+# id (a per-record grant, or a type-level grant on the class's own type) or
+# through a column holding another record's id (a parent grant: the row's
+# tenancy, read off the row itself). The reach map is that question in one
+# shape, an ordered Hash from column to the types whose rows admit through
+# it, with :id always the first step:
+#
+#   SuperAuth::Reach.normalize(
+#     resource_type: "Claim",
+#     parent: { column: :organization_id, resource_type: %w[Organization::Member Organization::Admin] })
+#   # => { id: ["Claim"], organization_id: ["Organization::Member", "Organization::Admin"] }
+#
+# The RLS policy and the ByCurrentUser scope each emit one step per entry,
+# and both build from this map rather than from the raw keywords so they
+# cannot drift: an argument shape one layer accepted and the other rejected,
+# or a column one saw and the other did not, is a row the ORM shows and the
+# database hides, or the reverse, which is the dangerous direction. Every
+# entry is a list because RLS must never be narrower than any tier's ORM
+# scope over the same table: a table whose readers key on
+# Organization::Member and whose writers on Organization::CaseWriter names
+# both under the column, so the holder of one without the other is still
+# admitted at the database.
+#
+# :id is refused as a parent column since it is the per-record step, already
+# declared by resource_type:. A column declared twice is refused because the
+# second entry would silently shadow the first; every type a column admits
+# goes in one list.
+module SuperAuth
+  module Reach
+    class << self
+      def normalize(resource_type:, parent: nil)
+        reach = { id: types(resource_type, "resource_type:") }
+        entries(parent).each do |entry|
+          unless entry.is_a?(Hash) && (entry.keys - %i[column resource_type]).empty?
+            raise Error, "parent: must be a Hash {column:, resource_type:} or an Array of them, got #{entry.inspect}"
+          end
+          column = column_name(entry[:column])
+          if reach.key?(column)
+            raise Error, "parent: column #{column.inspect} is declared twice; list every type it admits under one entry"
+          end
+          reach[column] = types(entry[:resource_type], "parent: #{column} resource_type:")
+        end
+        reach.freeze
+      end
+
+      # The column steps alone, for the layer emitting one per parent and for
+      # recording what a policy was built from.
+      def parents(reach)
+        reach.reject { |column, _| column == :id }
+      end
+
+      private
+
+      def entries(parent)
+        case parent
+        when nil then []
+        when Hash then [parent]
+        when Array then parent
+        else raise Error, "parent: must be a Hash {column:, resource_type:} or an Array of them, got #{parent.inspect}"
+        end
+      end
+
+      def column_name(column)
+        name = column.to_s if column.is_a?(Symbol) || column.is_a?(String)
+        if name.nil? || name.empty?
+          raise Error, "parent: column: must be a Symbol or String naming a column, got #{column.inspect}"
+        end
+        if name == "id"
+          raise Error, "parent: column: :id is the per-record step, which resource_type: already declares; a parent is a column holding another record's id"
+        end
+        name.to_sym
+      end
+
+      # Frozen copies rather than freezing the caller's strings in place.
+      def types(value, label)
+        list = value.is_a?(Array) ? value : [value]
+        unless !list.empty? && list.all? { |type| type.is_a?(String) && !type.empty? }
+          raise Error, "#{label} must be a String or a non-empty Array of Strings, got #{value.inspect}"
+        end
+        list.uniq.map { |type| -type }.freeze
+      end
+    end
+  end
+end