super_auth 0.4.0 → 0.8.0

data/USAGE.md

@@ -62,7 +62,7 @@ rails railties:install:migrations
 rails db:migrate
 ```
 
-This creates the `super_auth_*` tables (users, groups, roles, permissions, resources, edges, authorizations) alongside your application's tables.
+This creates the `super_auth_*` tables (users, groups, roles, permissions, resources, edges, authorizations) alongside your application's tables. The engine does not run its migrations by itself, so repeat both commands after upgrading to a version that ships a new one (0.8.0 adds migration 11, `parent_id` on resources).
 
 **Step 4.** Set the current user in your controller:
 
@@ -95,14 +95,18 @@ Post.all                        # only posts the current user can access
 Post.where(published: true)     # scoped AND filtered by authorization
 ```
 
-**Step 6 (optional).** Mount the visualization engine:
+**Step 6 (optional).** Mount the engine, which serves the graph editor. It has no
+authentication of its own, so mount it inside yours:
 
 ```ruby
 # config/routes.rb
-mount SuperAuth::Engine => '/super_auth'
+authenticate :admin do                 # Devise; or a constraints block
+  mount SuperAuth::Engine => '/super_auth'
+end
 ```
 
-Then visit `http://localhost:3000/super_auth/visualization` to see your authorization graph.
+Then open `http://localhost:3000/super_auth` to edit the graph. Edits take effect at
+runtime after **Recompile** (or `SuperAuth::ActiveRecord::Authorization.compile!`).
 
 ### Standalone Setup (without Rails)
 
@@ -130,7 +134,7 @@ SuperAuth models authorization as a graph with 5 entity types:
 | **Group**      | Organizational units (teams, departments, etc) | Yes (nested)  |
 | **Role**       | Job titles or permission sets                  | Yes (nested)  |
 | **Permission** | Actions (read, write, deploy, etc)             | No            |
-| **Resource**   | Things being protected (files, APIs, records)  | No            |
+| **Resource**   | Things being protected (files, APIs, records)  | Yes (nested)  |
 
 **Edges** are connections drawn between any two entities. SuperAuth traverses the graph to find all valid paths from a User to a Resource. If a path exists, access is granted.
 
@@ -241,22 +245,77 @@ write_perm  = SuperAuth::Permission.create(name: "write")
 deploy_perm = SuperAuth::Permission.create(name: "deploy")
 ```
 
-### Resources
+### Resources (hierarchical)
 
-Resources represent what you are protecting. They can link to your app's models.
+Resources represent what you are protecting. A node with neither `external_type` nor `external_id` is a container; a node with both points at one record of your application. Resources nest like groups and roles, and a grant on a node reaches the node and every node under it, so the usual shape is a container per folder, project, tenant or whatever your application nests records under, with the records registered beneath it.
 
 ```ruby
-# Named resource
+# A named resource with nothing behind it
 staging = SuperAuth::Resource.create(name: "staging")
 
-# Linked to an ActiveRecord model
-posts = SuperAuth::Resource.create(
-  name: "posts",
-  external_id: nil,
-  external_type: "Post"
+# A container, and a record of your app registered under it
+reports = SuperAuth::Resource.create(name: "reports")
+q3 = SuperAuth::Resource.create(
+  name: "Q3 report",
+  external_type: "Post",
+  external_id: post.id,
+  parent: reports
 )
+
+# A grant on the container reaches q3, and every node registered under
+# reports later, as of the next compile!
+SuperAuth::Edge.create(permission: read_perm, resource: reports)
 ```
 
+Navigate the tree the same way as groups:
+
+```ruby
+SuperAuth::Resource.roots        # nodes with no parent
+reports.children_dataset.all     # => [q3]
+q3.parent                        # => reports
+```
+
+The compiled row for `q3` carries `q3`'s own `external_type` and `external_id` whether the edge was drawn to `q3` or to `reports`: runtime reads the record a grant reaches and nothing about how it got there. There are no resource path columns in the compiled table; "granted through which container" is a question for the graph (`parent`, `children_dataset`) and the editor.
+
+#### Deprecated: type-level (wildcard) nodes
+
+A node with an `external_type` and no `external_id` is a type-level, or wildcard, node: at runtime it means every record of that type, present and future. `ByCurrentUser` skips per-record filtering when one matches, and the row-level security policy's `resource_external_id IS NULL OR` clause does the same in the database.
+
+```ruby
+# Deprecated: every Post, present and future
+posts = SuperAuth::Resource.create(name: "posts", external_type: "Post")
+```
+
+Wildcard nodes are deprecated as of 0.8.0 and still work: `compile!` warns once per compile naming the ones that exist (silence it with `SuperAuth.deprecator.silenced = true`, or in Rails through `config.active_support.deprecation`), and no removal version is promised. What `compile!` refuses, with a `SuperAuth::Error` naming the node ids, is a wildcard with a parent or children: nested in the tree it would reach every record of its type through its ancestors' grants. A wildcard stays at the root with no children, or gets an `external_id`.
+
+Under Postgres row-level security a wildcard remains the only way to authorize INSERT this release. The policy is `FOR ALL` with `USING` reused as `WITH CHECK`, and a per-record row can only match an id that has already been registered and compiled. A container is not a replacement for it there: it loses INSERT, it needs a node saved and a full recompile for every new record, and saving that node needs a role that can write the gem's tables, which `enable` grants `SELECT` on only. The successor is a grant on a parent record (`SuperAuth::RLS.enable(:documents, resource_type: "Document", parent: { column: :folder_id, resource_type: "Folder" })`, with a `ByCurrentUser` mirror), planned for the next release.
+
+##### Migrating a wildcard to a container
+
+Where the type is not under row-level security, or INSERT is not needed, a wildcard becomes a container plus one node per record. Move the edges off the wildcard before destroying it, so the grants survive, then compile. `Post` is a `super_auth` model, so its default scope hides every row from a process with no current user — the loop reads through `unscoped`; where RLS is installed the database enforces the same rule, so the work runs as the system user:
+
+```ruby
+wildcard = SuperAuth::Resource.where(external_type: "Post", external_id: nil).first
+
+migrate = proc do
+  container = SuperAuth::Resource.create(name: "posts")            # untyped: a container
+  Post.unscoped.find_each do |post|                                  # ByCurrentUser hides every row without a current user
+    SuperAuth::Resource.create(name: post.title, external_type: "Post", external_id: post.id, parent: container)
+  end
+  SuperAuth::Edge.where(resource_id: wildcard.id).update(resource_id: container.id)  # update_all on the ActiveRecord twin
+  wildcard.destroy
+end
+
+if SuperAuth::RLS.installed?
+  SuperAuth.as(SuperAuth::User.system, &migrate)
+else
+  SuperAuth.db.transaction(&migrate)
+end
+SuperAuth::Authorization.compile!   # SuperAuth::ActiveRecord::Authorization.compile! in Rails
+```
+
+Under row-level security this loses INSERT on `posts` until the parent-record grant exists, and a `Post` created afterwards needs its own node and a recompile before anyone sees it.
+
 ## Drawing Edges
 
 Edges are the core of SuperAuth. Each edge connects exactly two entities.
@@ -307,6 +366,8 @@ SuperAuth automatically evaluates 5 pathing strategies and unions the results. Y
 
 When groups or roles are nested, SuperAuth considers the full tree. If you assign a user to a parent group, they can access resources through roles attached to that group *and all its descendants*.
 
+Resources nest too, at the other end of the path: a grant on a container reaches every node registered under it (see [Resources](#resources-hierarchical)).
+
 ```ruby
 # Bethany is in Company (the root group)
 SuperAuth::Edge.create(user: bethany, group: company)
@@ -345,6 +406,8 @@ auth[:resource_id]      # Integer
 auth[:resource_name]    # "staging"
 ```
 
+`resource_id` and `resource_name` are the node the grant reaches: a row compiled through a container names the descendant, not the container, and there is no resource path column (see [Resources](#resources-hierarchical)).
+
 ### Filter by user
 
 ```ruby
@@ -457,6 +520,8 @@ Post::PostPublishPermission.find(id) # needs a "Post::PostPublishPermission" gra
 
 Approve the subclass like any other resource — register a `SuperAuth::Resource` with `external_type: "Post::PostPublishPermission"` and draw edges to it, then recompile with `SuperAuth::ActiveRecord::Authorization.compile!`.
 
+The resource tree is containment, not inheritance. A row compiled through a container copies the descendant node's own `external_type`, which is why the rule above survives nesting — but a `"Post::PostPublishPermission"` node registered *under* the `"Post"` node is a descendant of it and receives every grant on `"Post"`. Register capability nodes as siblings of their base-class nodes, or in a container beside them, never as their children.
+
 For database-side enforcement of the same rules see "Postgres Row-Level Security" in the README (`SuperAuth::RLS.enable` — visibility is derived automatically from `SuperAuth.current_user`).
 
 ### Linking to your app's models
@@ -471,14 +536,15 @@ sa_user = SuperAuth::User.create(
   external_type: "User"
 )
 
-# Link a SuperAuth resource to your app's Post model
+# Link a SuperAuth resource to one Post
 sa_resource = SuperAuth::Resource.create(
-  name: "posts",
-  external_type: "Post"
+  name: post.title,
+  external_type: "Post",
+  external_id: post.id
 )
 ```
 
-When `super_auth` is included in a model, the default scope matches the current user's `id` and class name against `external_id` / `external_type` in the authorizations table. This means your application user objects work directly -- no need to convert to SuperAuth users in the controller.
+When `super_auth` is included in a model, the default scope matches the current user's `id` and class name against `external_id` / `external_type` in the authorizations table. This means your application user objects work directly -- no need to convert to SuperAuth users in the controller. On the resource side it matches the record's class name and `id` against `resource_external_type` / `resource_external_id`; a node with the type and no id matches every record of the type, the deprecated wildcard shape described under [Resources](#resources-hierarchical).
 
 ### ActiveRecord models
 
@@ -533,25 +599,25 @@ deployers.map { |a| a[:user_name] }.uniq
 
 ## Visualization
 
-SuperAuth includes an interactive graph visualization UI. After mounting the engine:
+The graph editor shows the whole graph as five boxes (groups, roles, users,
+permissions, resources), drawing groups, roles and resources as trees; click any record
+to trace what it can reach and what reaches it, connect records to draw edges, create
+records (including a resource container under a chosen parent), delete records and
+edges, and recompile. The editor makes containers; your application registers records
+under them. See the README's "Graph editor" section for the full description.
 
-```ruby
-# config/routes.rb
-mount SuperAuth::Engine => '/super_auth'
-```
+- Rails: mount the engine inside your own authentication (Step 6 above) and open
+  `http://localhost:3000/super_auth`.
+- Anywhere else: `super_auth-editor` serves it on loopback against
+  `SUPER_AUTH_DATABASE_URL`, or `require "super_auth/editor"` and mount
+  `SuperAuth::Editor` in any Rack app, inside your authentication.
 
-Load sample data (optional):
+Load sample data (optional, Rails):
 
 ```bash
 rails runner "load File.join(SuperAuth::Engine.root, 'db/seeds/sample_data.rb')"
 ```
 
-Visit `http://localhost:3000/super_auth/visualization` to see:
-
-- Color-coded nodes for each entity type
-- Interactive path finding
-- Real-time authorization queries
-
 ## Full Example
 
 Here's a complete example modeling a company with departments, roles, and resources:
@@ -575,8 +641,8 @@ write  = SuperAuth::Permission.create(name: "write")
 deploy = SuperAuth::Permission.create(name: "deploy")
 
 # Resources
-api       = SuperAuth::Resource.create(name: "api", external_type: "API")
-dashboard = SuperAuth::Resource.create(name: "dashboard", external_type: "Dashboard")
+api       = SuperAuth::Resource.create(name: "api")
+dashboard = SuperAuth::Resource.create(name: "dashboard")
 prod_db   = SuperAuth::Resource.create(name: "production_db")
 
 # Users
@@ -629,6 +695,7 @@ auths = SuperAuth::Edge.authorizations.all
 | `SuperAuth.current_user`        | Get the current user                                 |
 | `SuperAuth.install_migrations`  | Create all `super_auth_*` tables                     |
 | `SuperAuth.uninstall_migrations`| Drop all `super_auth_*` tables                       |
+| `SuperAuth.deprecator`          | Where deprecation warnings go; `silenced = true` quiets them |
 
 ### Environment Variables
 

data/config/routes.rb

@@ -1,73 +1,11 @@
+require "super_auth/editor"
+
+# The engine serves the graph editor at its mount point. Mount it inside your
+# own authentication: it has none of its own.
+#
+#   authenticate :admin do
+#     mount SuperAuth::Engine => "/super_auth"
+#   end
 SuperAuth::Engine.routes.draw do
-  # Main graph visualization interface
-  get '/', to: 'graph#index', as: :root
-  get '/graph', to: 'graph#index'
-
-  # Graph data API
-  get '/graph/data', to: 'graph#data'
-  get '/graph/orphaned', to: 'graph#orphaned'
-  post '/graph/compile_authorizations', to: 'graph#compile_authorizations'
-
-  # Authorization check
-  get '/graph/authorize', to: 'graph#authorize'
-
-  # Legacy visualization endpoint
-  get '/visualization', to: 'graph#visualization'
-
-  # CRUD operations for graph entities
-  scope :graph do
-    resources :users, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_user
-      end
-      member do
-        delete '/', action: :delete_user
-      end
-    end
-
-    resources :groups, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_group
-      end
-      member do
-        delete '/', action: :delete_group
-      end
-    end
-
-    resources :roles, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_role
-      end
-      member do
-        delete '/', action: :delete_role
-      end
-    end
-
-    resources :permissions, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_permission
-      end
-      member do
-        delete '/', action: :delete_permission
-      end
-    end
-
-    resources :graph_resources, only: [:create, :destroy], controller: 'graph', path: 'resources' do
-      collection do
-        post '/', action: :create_resource
-      end
-      member do
-        delete '/', action: :delete_resource
-      end
-    end
-
-    resources :edges, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_edge
-      end
-      member do
-        delete '/', action: :delete_edge
-      end
-    end
-  end
+  mount SuperAuth::Editor, at: "/"
 end

data/db/migrate/10_add_super_auth_label_to_resources.rb

@@ -0,0 +1,13 @@
+Sequel.migration do
+  up do
+    alter_table(:super_auth_resources) do
+      add_column :super_auth_label, String
+    end
+  end
+
+  down do
+    alter_table(:super_auth_resources) do
+      drop_column :super_auth_label
+    end
+  end
+end

data/db/migrate/11_add_parent_id_to_resources.rb

@@ -0,0 +1,32 @@
+Sequel.migration do
+  # Resources nest like groups and roles (2_groups.rb): same integer type as
+  # the pk, deferrable only where supported. The index is skipped on MySQL
+  # for the reason in 8_add_indexes_to_edges.rb — InnoDB indexes the foreign
+  # key column itself and will not drop that index while the constraint
+  # stands. Both branches compute database_type before alter_table: inside
+  # the block self is the generator.
+  up do
+    is_postgres = database_type == :postgres
+    is_mysql = [:mysql, :mysql2].include?(database_type)
+
+    alter_table(:super_auth_resources) do
+      if is_postgres
+        add_foreign_key :parent_id, :super_auth_resources, deferrable: true, type: :integer
+      else
+        add_foreign_key :parent_id, :super_auth_resources, type: :integer
+      end
+      add_index :parent_id unless is_mysql
+    end
+  end
+
+  # drop_foreign_key drops the constraint and then the column; MySQL refuses
+  # to drop a column a constraint still depends on.
+  down do
+    is_mysql = [:mysql, :mysql2].include?(database_type)
+
+    alter_table(:super_auth_resources) do
+      drop_index :parent_id unless is_mysql
+      drop_foreign_key :parent_id
+    end
+  end
+end

data/db/migrate_activerecord/20250101000010_add_super_auth_label_to_super_auth_resources.rb

@@ -0,0 +1,5 @@
+class AddSuperAuthLabelToSuperAuthResources < ActiveRecord::Migration[7.0]
+  def change
+    add_column :super_auth_resources, :super_auth_label, :string
+  end
+end

data/db/migrate_activerecord/20250101000011_add_parent_id_to_super_auth_resources.rb

@@ -0,0 +1,9 @@
+class AddParentIdToSuperAuthResources < ActiveRecord::Migration[7.0]
+  # Mirrors db/migrate/11_add_parent_id_to_resources.rb. No index on MySQL:
+  # InnoDB indexes the foreign key column itself.
+  def change
+    add_column :super_auth_resources, :parent_id, :bigint
+    add_foreign_key :super_auth_resources, :super_auth_resources, column: :parent_id
+    add_index :super_auth_resources, :parent_id unless connection.adapter_name.match?(/mysql|trilogy/i)
+  end
+end

data/db/seeds/sample_data.rb

@@ -29,6 +29,7 @@ puts "Clearing existing data..."
 Edge.delete_all
 Group.update_all(parent_id: nil)
 Role.update_all(parent_id: nil)
+Resource.update_all(parent_id: nil)
 User.delete_all
 Group.delete_all
 Role.delete_all

data/exe/super_auth-editor

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# Serves the super_auth graph editor on loopback. See `super_auth-editor --help`.
+require "super_auth/editor/cli"
+
+begin
+  SuperAuth::Editor::CLI.run(ARGV)
+rescue SuperAuth::Error => e
+  abort "super_auth-editor: #{e.message}"
+end

data/lib/generators/super_auth/install/templates/README

@@ -4,26 +4,33 @@ SuperAuth initializer created at config/initializers/super_auth.rb
 
 Next steps:
 
-1. Run migrations to create the database tables:
+1. Copy the engine's migrations into your app and run them:
 
-   SuperAuth.install_migrations
+   rails railties:install:migrations
+   rails db:migrate
 
-   You can run this in the Rails console or add it to a rake task.
+   (the engine does not run its migrations by itself; repeat both after an
+   upgrade that ships a new one)
 
-2. Mount the engine in config/routes.rb:
+2. Mount the engine in config/routes.rb, inside your own authentication.
+   It serves the graph editor, which has no authentication of its own:
 
-   mount SuperAuth::Engine => '/super_auth'
+   authenticate :admin do
+     mount SuperAuth::Engine => '/super_auth'
+   end
 
-3. (Optional) Load sample data to see the visualization in action:
+3. (Optional) Load sample data to have a graph to look at:
 
    rails runner "load File.join(SuperAuth::Engine.root, 'db/seeds/sample_data.rb')"
 
-4. Start your Rails server and visit:
+4. Start your Rails server and open the editor:
 
-   http://localhost:3000/super_auth/visualization
+   http://localhost:3000/super_auth
 
-For more information, see:
-- VISUALIZATION.md for full documentation
-- README.md for usage examples
+   Edits change the graph; runtime access comes from the compiled table,
+   so press Recompile (or run SuperAuth::ActiveRecord::Authorization.compile!)
+   after editing.
+
+For more information, see README.md ("Graph editor") and USAGE.md.
 
 ===============================================================================

data/lib/generators/super_auth/rls/templates/migration.rb.erb

@@ -3,6 +3,8 @@ class EnableSuperAuthRls < ActiveRecord::Migration[<%= ActiveRecord::Migration.c
 <% model_names.each do |model| -%>
     SuperAuth::RLS.enable(:<%= model.tableize.tr('/', '_') %>, resource_type: "<%= model.camelize %>")
 <% end -%>
+    # Roles allowed to bypass the policies (migrations, seeds, admin jobs):
+    # SuperAuth::RLS.grant_system(:app_admin)
   end
 
   def down

data/lib/super_auth/active_record/authorization.rb

@@ -9,11 +9,18 @@ class SuperAuth::ActiveRecord::Authorization < ActiveRecord::Base
     end
 
     # Clears and repopulates the authorizations table from the current graph.
+    # The wildcard guard runs before the delete, so a refused compile leaves
+    # the previous rows in place; the deprecation notice follows the commit.
     def compile!
       transaction do
+        # Sequel runs on this transaction's connection (sequel-activerecord_connection),
+        # so the JIT switch lands in it; see SuperAuth::Authorization.compile!.
+        SuperAuth.db.run "SET LOCAL jit = off" if SuperAuth.db.database_type == :postgres
+        SuperAuth::Resource.assert_compilable!
         delete_all
         from_graph.each { |auth| create!(auth.attributes.except("id")) }
       end
+      SuperAuth::Resource.warn_deprecated_wildcards
       count
     end
   end

data/lib/super_auth/active_record/by_current_user.rb

@@ -30,7 +30,7 @@ module SuperAuth::ActiveRecord::ByCurrentUser
         self
       else
         user_where =
-        if SuperAuth.current_user.is_a?(SuperAuth::ActiveRecord::User)
+        if SuperAuth.internal_user?(SuperAuth.current_user)
           { user_id: SuperAuth.current_user.id }
         else
           { user_external_id: SuperAuth.current_user.id, user_external_type: SuperAuth.current_user.class.name }

data/lib/super_auth/active_record/resource.rb

@@ -1,4 +1,49 @@
 class SuperAuth::ActiveRecord::Resource < ActiveRecord::Base
   self.table_name = 'super_auth_resources'
   belongs_to :external, polymorphic: true, optional: true
+  # optional: is load-bearing: Rails hosts set belongs_to_required_by_default,
+  # the gem's own suite does not, so a missing one passes CI and fails the
+  # host on every root node.
+  belongs_to :parent, class_name: 'SuperAuth::ActiveRecord::Resource', optional: true
+
+  # `super_auth_label` is a stored snapshot of the application record's human
+  # name, so the editor can render "Gulf War presumptive" instead of
+  # Claim#3a00b6fa and `super_auth-editor` can do it against a bare
+  # SUPER_AUTH_DATABASE_URL with no application loaded. It carries the prefix
+  # for the same reason the opt-in method on the host's model does: `label` is
+  # a name applications want for themselves.
+  #
+  # Deriving it here means a host that already syncs its resources gets labels
+  # with no extra wiring; renames still need refresh_label!, since they do not
+  # write this row.
+  before_save :set_label, if: :external_id?
+
+  # Re-derive the label after the application record is renamed. Hosts call it
+  # from whatever already syncs the node; super_auth:labels:backfill calls it
+  # for every row.
+  def refresh_label!
+    derived = derived_label
+    update_column(:super_auth_label, derived) unless derived.nil?
+  end
+
+  private
+
+  def set_label
+    derived = derived_label
+    self.super_auth_label = derived unless derived.nil?
+  end
+
+  # ponytail: a nil derivation never overwrites a stored label, in either
+  # path, and never fails the save. Three things derive nil and none of them
+  # means "this record has no name": RLS makes the application record
+  # unreadable without an asserted identity, external_type is a plain string
+  # that can name a class this process has not loaded, and id-less rows — a
+  # container, or a deprecated wildcard — have no record to name at all.
+  # Writing nil for any of them would turn "this label is stale" into data,
+  # which is the failure this column exists to avoid.
+  def derived_label
+    SuperAuth.label_for(external)
+  rescue NameError
+    nil
+  end
 end

data/lib/super_auth/active_record/user.rb

@@ -5,7 +5,9 @@ class SuperAuth::ActiveRecord::User < ActiveRecord::Base
 
   def model_name = ActiveModel::Name.new(:user)
 
-  def system? = self.class.system == self
+  # A read: runtime roles only get SELECT on this table. `.system` creates
+  # the row when missing and belongs to migrations, seeds and consoles.
+  def system? = self.class.find_by(name: "system") == self
   def self.system = find_or_create_by(name: "system")
 
   has_many :edges, class_name: 'SuperAuth::ActiveRecord::Edge'

data/lib/super_auth/authorization.rb

@@ -1,2 +1,26 @@
 class SuperAuth::Authorization < Sequel::Model(:super_auth_authorizations)
+  # Clears and repopulates the compiled table from the current graph, inside
+  # one transaction, and returns the row count. Row by row, like
+  # SuperAuth::ActiveRecord::Authorization.compile!; a single INSERT ... SELECT
+  # is a separate change. Runtime enforcement (ByCurrentUser, the RLS policies)
+  # reads only this table, so every edit to the graph is inert until this runs.
+  # The wildcard guard runs first, before the delete, so a refused compile
+  # leaves the previous rows in place rather than an empty table; the
+  # deprecation notice comes after the commit, for a compile that happened.
+  #
+  # Postgres JIT-compiles the union's expressions on every run: 539 LLVM
+  # functions, 1.6-2.2s of optimisation and emission for a query that then
+  # executes in milliseconds. SET LOCAL scopes the switch to this transaction,
+  # so nothing leaks to the pooled connection.
+  def self.compile!
+    count = db.transaction do
+      db.run "SET LOCAL jit = off" if db.database_type == :postgres
+      SuperAuth::Resource.assert_compilable!
+      dataset.delete
+      SuperAuth::Edge.authorizations.each { |row| dataset.insert(row) }
+      dataset.count
+    end
+    SuperAuth::Resource.warn_deprecated_wildcards
+    count
+  end
 end