clickwrap 0.0.0 → 0.1.0

data/lib/generators/clickwrap/templates/create_clickwrap_external_action_tables.rb.erb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# The external-action outbox — `rails generate clickwrap:install
+# --with-external-actions`, or added later with the same command.
+#
+# Only `Clickwrap.authorize_external_action!` writes here, so an
+# application that never crosses a system boundary inside a capture can
+# never put a row in this table.
+class CreateClickwrapExternalActionTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, = primary_and_foreign_key_types
+
+    # ---------------------------------------------------------------------------
+    # clickwrap_external_actions
+    #
+    # The outbox. A provider cannot join your database transaction, so an
+    # external handoff gets a pending authorization committed locally, an
+    # idempotency key, and an explicit resolution — succeeded, failed, or
+    # genuinely unknown. `unknown` is a first-class state because a timeout is
+    # not a failure, and treating it as one is how a second debit happens.
+    # ---------------------------------------------------------------------------
+    create_table :clickwrap_external_actions, id: primary_key_type do |t|
+      t.string :event_id, limit: 26, null: false
+      t.string :policy_key, null: false
+      t.string :idempotency_key, null: false
+      t.string :provider_name
+
+      t.string :state, null: false, default: "pending"
+      t.integer :attempt_count, null: false, default: 0
+      t.send(json_column_type, :provider_receipt)
+      t.text :failure_reason
+
+      t.datetime :requested_at, precision: 6, null: false
+      t.datetime :resolved_at, precision: 6
+
+      t.timestamps precision: 6
+    end
+
+    add_index :clickwrap_external_actions, :idempotency_key, unique: true,
+              name: "index_clickwrap_external_actions_on_idempotency_key"
+    add_index :clickwrap_external_actions, :event_id, unique: true,
+              name: "index_clickwrap_external_actions_on_event"
+    add_index :clickwrap_external_actions, [ :state, :requested_at ],
+              name: "index_clickwrap_external_actions_on_state"
+    add_clickwrap_check_constraint :clickwrap_external_actions,
+                         "state IN (#{quoted_values(%w[pending succeeded failed unknown])})",
+                         name: "chk_clickwrap_external_actions_state"
+
+
+    add_clickwrap_foreign_key :clickwrap_external_actions, :clickwrap_events,
+                    column: :event_id, name: "fk_clickwrap_external_actions_event"
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint). Reads the
+  # same setting `rails g model` uses, so an app generated with
+  # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
+  # gets uuid clickwrap tables and uuid foreign keys, automatically.
+  #
+  # Note that clickwrap_events keeps a ULID string key regardless: its id is
+  # quoted verbatim in receipts and exports, so it has to be stable, sortable,
+  # and identical in every host.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.match?(/postg/) # postgresql, postgis
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns. Returns an empty-hash
+  # default for SQLite/PostgreSQL, nil for MySQL. The models handle nil
+  # gracefully by defaulting to {} in their accessors.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    {}
+  end
+
+  # Same MySQL caveat as `json_column_default`, but for list-shaped columns.
+  def json_array_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    []
+  end
+
+  # Legal documents are routinely longer than MySQL's 64 KB TEXT limit, and a
+  # silently truncated agreement is the worst possible failure for this gem.
+  # `:mediumtext` maps to MEDIUMTEXT on MySQL (16 MB) and to ordinary TEXT
+  # everywhere else.
+  def text_column_type
+    return :mediumtext if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    :text
+  end
+
+  def quoted_values(values)
+    values.map { |value| connection.quote(value) }.join(", ")
+  end
+
+  # SQLite implements both foreign keys and check constraints by rebuilding a
+  # table. During a long install migration, Active Record can otherwise rebuild
+  # from a schema-cache entry captured before the indexes/columns immediately
+  # above were added. Refreshing around every rebuild keeps the SQLite result
+  # identical to PostgreSQL/MySQL instead of quietly resurrecting stale shape.
+  def add_clickwrap_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+    add_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+  end
+
+  def add_clickwrap_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+    add_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+  end
+
+  def refresh_clickwrap_table_schema!(table)
+    connection.schema_cache.clear_data_source_cache!(table.to_s)
+  end
+end

data/lib/generators/clickwrap/templates/create_clickwrap_integrity_tables.rb.erb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# The higher integrity tiers — `rails generate clickwrap:install
+# --with-integrity`, or added later with the same command.
+#
+# Per-tenant event chaining, external anchoring, and third-party
+# timestamping are each off until the host brings an adapter
+# (`config.chain_event_history_with`, `config.anchor_event_history_with`,
+# `config.timestamp_receipts_with`). Until then neither table can receive a
+# row.
+class CreateClickwrapIntegrityTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, = primary_and_foreign_key_types
+
+    # ---------------------------------------------------------------------------
+    # clickwrap_chain_heads
+    #
+    # Optional tamper-evident chaining, off unless configured. The scope is per
+    # tenant or per aggregate, never one global chain: a single chain across
+    # unrelated tenants turns every capture into a queue behind every other one,
+    # and buys assurance nobody asked for at a cost everybody pays.
+    # ---------------------------------------------------------------------------
+    create_table :clickwrap_chain_heads, id: primary_key_type do |t|
+      t.string :chain_scope, null: false
+      t.string :last_event_id, limit: 26
+      t.string :last_event_digest
+      t.bigint :chain_sequence, null: false, default: 0
+
+      t.datetime :checkpointed_at, precision: 6
+      t.string :checkpoint_digest
+      t.string :anchor_reference
+      t.send(json_column_type, :anchor_receipt)
+
+      t.timestamps precision: 6
+    end
+
+    add_index :clickwrap_chain_heads, :chain_scope, unique: true,
+              name: "index_clickwrap_chain_heads_on_scope"
+    add_index :clickwrap_chain_heads, :last_event_id,
+              name: "index_clickwrap_chain_heads_on_last_event"
+
+
+    # ---------------------------------------------------------------------------
+    # clickwrap_integrity_attestations
+    #
+    # One row per attempt to have an outside party vouch for an exact event
+    # digest, carrying the provider's own result and this gem's verification of
+    # it as separate facts. An unverified issue is recorded as unverified.
+    # ---------------------------------------------------------------------------
+    create_table :clickwrap_integrity_attestations, id: primary_key_type do |t|
+      t.string :event_id, limit: 26, null: false
+      t.string :kind, null: false
+      t.string :state, null: false
+      t.string :provider_name, null: false
+      t.string :subject_digest, null: false
+      t.string :chain_scope
+      t.bigint :chain_sequence
+      t.string :provider_reference
+      t.send(json_column_type, :provider_result, null: false)
+      t.send(json_column_type, :verification, null: false)
+      t.send(json_column_type, :adapter_capabilities, null: false)
+      t.string :attestation_digest, null: false
+      t.datetime :attempted_at, precision: 6, null: false
+      t.datetime :provider_reported_at, precision: 6
+      t.datetime :created_at, precision: 6, null: false
+    end
+
+    add_index :clickwrap_integrity_attestations, [ :event_id, :kind, :attempted_at ],
+              name: "index_clickwrap_integrity_attestations_on_event"
+    add_clickwrap_check_constraint :clickwrap_integrity_attestations,
+                         "kind IN (#{quoted_values(%w[event_anchor third_party_timestamp])})",
+                         name: "chk_clickwrap_attestations_kind"
+    add_clickwrap_check_constraint :clickwrap_integrity_attestations,
+                         "state IN (#{quoted_values(%w[verified issued_unverified unavailable failed])})",
+                         name: "chk_clickwrap_attestations_state"
+
+    add_clickwrap_foreign_key :clickwrap_chain_heads, :clickwrap_events,
+                    column: :last_event_id, name: "fk_clickwrap_chain_heads_event"
+    add_clickwrap_foreign_key :clickwrap_integrity_attestations, :clickwrap_events,
+                    column: :event_id, name: "fk_clickwrap_attestations_event"
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint). Reads the
+  # same setting `rails g model` uses, so an app generated with
+  # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
+  # gets uuid clickwrap tables and uuid foreign keys, automatically.
+  #
+  # Note that clickwrap_events keeps a ULID string key regardless: its id is
+  # quoted verbatim in receipts and exports, so it has to be stable, sortable,
+  # and identical in every host.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.match?(/postg/) # postgresql, postgis
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns. Returns an empty-hash
+  # default for SQLite/PostgreSQL, nil for MySQL. The models handle nil
+  # gracefully by defaulting to {} in their accessors.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    {}
+  end
+
+  # Same MySQL caveat as `json_column_default`, but for list-shaped columns.
+  def json_array_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    []
+  end
+
+  # Legal documents are routinely longer than MySQL's 64 KB TEXT limit, and a
+  # silently truncated agreement is the worst possible failure for this gem.
+  # `:mediumtext` maps to MEDIUMTEXT on MySQL (16 MB) and to ordinary TEXT
+  # everywhere else.
+  def text_column_type
+    return :mediumtext if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    :text
+  end
+
+  def quoted_values(values)
+    values.map { |value| connection.quote(value) }.join(", ")
+  end
+
+  # SQLite implements both foreign keys and check constraints by rebuilding a
+  # table. During a long install migration, Active Record can otherwise rebuild
+  # from a schema-cache entry captured before the indexes/columns immediately
+  # above were added. Refreshing around every rebuild keeps the SQLite result
+  # identical to PostgreSQL/MySQL instead of quietly resurrecting stale shape.
+  def add_clickwrap_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+    add_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+  end
+
+  def add_clickwrap_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+    add_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+  end
+
+  def refresh_clickwrap_table_schema!(table)
+    connection.schema_cache.clear_data_source_cache!(table.to_s)
+  end
+end

data/lib/generators/clickwrap/templates/create_clickwrap_presentation_tables.rb.erb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# Persisted pre-submit presentations — `rails generate clickwrap:install
+# --with-persisted-presentations`, or added later with the same command.
+#
+# A default install writes nothing on GET, so this table can never receive
+# a row until a policy declares
+# `persist_presentations_before_submission_for`. It ships separately so an
+# installation's schema says what that installation actually records.
+class CreateClickwrapPresentationTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    # ---------------------------------------------------------------------------
+    # clickwrap_presentations
+    #
+    # The default path signs the manifest into a short-lived token and writes
+    # NOTHING on GET — a render is not evidence, and a table row per page view
+    # would be both slow and more personal data than the job needs.
+    #
+    # Rows land here in two cases: a policy explicitly retains pre-submit
+    # presentations for a documented reason, and every successful capture, whose
+    # accepted manifest is persisted with the event. An abandoned GET is
+    # `presented_by_server` — never `accepted`, and never `seen_by_human`,
+    # because a server cannot know whether a human saw anything.
+    # ---------------------------------------------------------------------------
+    create_table :clickwrap_presentations, id: primary_key_type do |t|
+      t.string :policy_key, null: false
+      t.references :policy_revision, null: false, type: foreign_key_type, index: false,
+                                     foreign_key: { to_table: :clickwrap_policy_revisions }
+
+      t.string :nonce, null: false
+      t.send(json_column_type, :manifest, null: false)
+      t.string :manifest_digest, null: false
+
+      # Stable references drive every evidence query. These optional convenience
+      # pointers are strings so one polymorphic column can safely point at host
+      # models whose primary keys are integers, UUIDs, or domain strings.
+      t.string :actor_type
+      t.string :actor_id
+      t.string :actor_reference
+      t.string :registration_flow_id
+      t.string :represented_party_type
+      t.string :represented_party_id
+      t.string :represented_party_reference
+      t.string :tenant_key
+      t.string :subject_type
+      t.string :subject_id
+      t.string :subject_fingerprint
+
+      t.string :locale, null: false, default: "en"
+      t.string :capture_channel, null: false, default: "web_browser"
+      t.string :state, null: false, default: "presented_by_server"
+
+      t.datetime :issued_at, precision: 6, null: false
+      t.datetime :expires_at, precision: 6, null: false
+      t.datetime :submitted_at, precision: 6
+      t.datetime :retain_until, precision: 6
+
+      t.datetime :created_at, precision: 6, null: false
+    end
+
+    add_index :clickwrap_presentations, :nonce, unique: true,
+              name: "index_clickwrap_presentations_on_nonce"
+    add_index :clickwrap_presentations, [ :actor_type, :actor_id ],
+              name: "index_clickwrap_presentations_on_actor"
+    add_index :clickwrap_presentations, :retain_until,
+              name: "index_clickwrap_presentations_on_retain_until"
+    add_index :clickwrap_presentations, :expires_at,
+              name: "index_clickwrap_presentations_on_expires_at"
+    add_index :clickwrap_presentations, :actor_reference,
+              name: "index_clickwrap_presentations_on_actor_reference"
+    add_clickwrap_check_constraint :clickwrap_presentations,
+                         "state IN (#{quoted_values(%w[presented_by_server accepted rejected expired])})",
+                         name: "chk_clickwrap_presentations_state"
+    add_clickwrap_check_constraint :clickwrap_presentations,
+                         "capture_channel IN (#{quoted_values(%w[web_browser native_app api_client operator background_job imported_provider system])})",
+                         name: "chk_clickwrap_presentations_channel"
+
+    # `clickwrap_events.presentation_id` is created by the core migration and
+    # gains its foreign key here, with the table it points at.
+    add_clickwrap_foreign_key :clickwrap_events, :clickwrap_presentations,
+                    column: :presentation_id, name: "fk_clickwrap_events_presentation"
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint). Reads the
+  # same setting `rails g model` uses, so an app generated with
+  # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
+  # gets uuid clickwrap tables and uuid foreign keys, automatically.
+  #
+  # Note that clickwrap_events keeps a ULID string key regardless: its id is
+  # quoted verbatim in receipts and exports, so it has to be stable, sortable,
+  # and identical in every host.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.match?(/postg/) # postgresql, postgis
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns. Returns an empty-hash
+  # default for SQLite/PostgreSQL, nil for MySQL. The models handle nil
+  # gracefully by defaulting to {} in their accessors.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    {}
+  end
+
+  # Same MySQL caveat as `json_column_default`, but for list-shaped columns.
+  def json_array_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    []
+  end
+
+  # Legal documents are routinely longer than MySQL's 64 KB TEXT limit, and a
+  # silently truncated agreement is the worst possible failure for this gem.
+  # `:mediumtext` maps to MEDIUMTEXT on MySQL (16 MB) and to ordinary TEXT
+  # everywhere else.
+  def text_column_type
+    return :mediumtext if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    :text
+  end
+
+  def quoted_values(values)
+    values.map { |value| connection.quote(value) }.join(", ")
+  end
+
+  # SQLite implements both foreign keys and check constraints by rebuilding a
+  # table. During a long install migration, Active Record can otherwise rebuild
+  # from a schema-cache entry captured before the indexes/columns immediately
+  # above were added. Refreshing around every rebuild keeps the SQLite result
+  # identical to PostgreSQL/MySQL instead of quietly resurrecting stale shape.
+  def add_clickwrap_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+    add_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+  end
+
+  def add_clickwrap_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+    add_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+  end
+
+  def refresh_clickwrap_table_schema!(table)
+    connection.schema_cache.clear_data_source_cache!(table.to_s)
+  end
+end

data/lib/generators/clickwrap/templates/create_clickwrap_request_evidence_tables.rb.erb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# The optional request-evidence annex — `rails generate clickwrap:install
+# --with-request-evidence`, or added later with the same command.
+#
+# Nothing personal is recorded until a policy names a field with a purpose
+# and a deletion rule, so on a default install this table can never receive
+# a row. It ships separately for the same reason the fields are off: an
+# application's schema should not imply it collects things it does not.
+class CreateClickwrapRequestEvidenceTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, = primary_and_foreign_key_types
+
+    # ---------------------------------------------------------------------------
+    # clickwrap_request_evidence
+    #
+    # The optional annex: IP address, browser user-agent, and provider-estimated
+    # IP geolocation, none of it recorded unless a policy names the field.
+    #
+    # It is a separate table on purpose. Personal request evidence needs its own
+    # deletion schedule, and welding it into the core event payload would make a
+    # lawful deletion request either impossible or destructive of the historical
+    # record. Here it can be removed on its own clock while the agreement it
+    # accompanied stays intact and verifiable.
+    #
+    # Every IP-geolocation value carries its provenance in the same row.
+    # Coordinates without an accuracy radius, or a country without knowing which
+    # provider guessed it, would read as far more certain than they are.
+    # ---------------------------------------------------------------------------
+    create_table :clickwrap_request_evidence, id: primary_key_type do |t|
+      t.string :event_id, limit: 26, null: false
+      t.send(json_column_type, :authorized_fields, null: false)
+
+      t.text :ip_address_ciphertext
+      t.string :ip_address_reader_name
+      t.string :trusted_proxy_configuration_digest
+      t.datetime :ip_address_recorded_at, precision: 6
+      t.datetime :ip_address_delete_after, precision: 6
+      t.string :ip_address_retain_until_rule
+      t.datetime :ip_address_deleted_at, precision: 6
+      t.string :ip_address_unavailable_reason
+
+      t.text :browser_user_agent_ciphertext
+      t.boolean :browser_user_agent_was_client_supplied, null: false, default: true
+      t.datetime :browser_user_agent_recorded_at, precision: 6
+      t.datetime :browser_user_agent_delete_after, precision: 6
+      t.string :browser_user_agent_retain_until_rule
+      t.datetime :browser_user_agent_deleted_at, precision: 6
+      t.string :browser_user_agent_unavailable_reason
+
+      t.string :ip_geolocation_country_code
+      t.string :ip_geolocation_country_name
+      t.string :ip_geolocation_region_name
+      t.string :ip_geolocation_region_code
+      t.string :ip_geolocation_city_name
+      t.string :ip_geolocation_postal_code
+
+      # Coordinates are strings, not decimals, for two reasons that point the
+      # same way. A receipt serializes them as strings anyway, so storing the
+      # decimal and formatting it back would introduce a rounding step between
+      # what the provider said and what the evidence shows. And a string column
+      # can carry ciphertext, which is what lets `encrypt_recorded_ip_geolocation`
+      # actually apply to the most identifying field in this table rather than
+      # being a setting that quietly does nothing.
+      t.string :ip_geolocation_latitude
+      t.string :ip_geolocation_longitude
+
+      t.string :ip_geolocation_timezone
+      t.string :ip_geolocation_continent_code
+      t.string :ip_geolocation_metro_code
+
+      t.string :ip_geolocation_provider_name
+      t.string :ip_geolocation_provider_source
+      t.string :ip_geolocation_database_version
+      t.string :ip_geolocation_database_sha256
+      t.integer :ip_geolocation_accuracy_radius_in_kilometers
+      t.integer :ip_geolocation_accuracy_radius_confidence_percentage
+      t.boolean :ip_geolocation_was_estimated, null: false, default: true
+      t.boolean :ip_geolocation_source_was_verified_by_host, null: false, default: false
+      t.datetime :ip_geolocation_resolved_at, precision: 6
+      t.string :ip_geolocation_unavailable_reason
+      t.datetime :ip_geolocation_recorded_at, precision: 6
+      t.datetime :ip_geolocation_delete_after, precision: 6
+      t.string :ip_geolocation_retain_until_rule
+      t.datetime :ip_geolocation_deleted_at, precision: 6
+
+      t.datetime :created_at, precision: 6, null: false
+    end
+
+    add_index :clickwrap_request_evidence, :event_id, unique: true,
+              name: "index_clickwrap_request_evidence_on_event"
+    add_index :clickwrap_request_evidence, :ip_address_delete_after,
+              name: "index_clickwrap_request_evidence_on_ip_address_delete_after"
+    add_index :clickwrap_request_evidence, :browser_user_agent_delete_after,
+              name: "index_clickwrap_request_evidence_on_user_agent_delete_after"
+    add_index :clickwrap_request_evidence, :ip_geolocation_delete_after,
+              name: "index_clickwrap_request_evidence_on_geolocation_delete_after"
+
+
+    add_clickwrap_foreign_key :clickwrap_events, :clickwrap_request_evidence,
+                    column: :request_evidence_id, name: "fk_clickwrap_events_request_evidence"
+    add_clickwrap_foreign_key :clickwrap_request_evidence, :clickwrap_events,
+                    column: :event_id, name: "fk_clickwrap_request_evidence_event"
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint). Reads the
+  # same setting `rails g model` uses, so an app generated with
+  # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
+  # gets uuid clickwrap tables and uuid foreign keys, automatically.
+  #
+  # Note that clickwrap_events keeps a ULID string key regardless: its id is
+  # quoted verbatim in receipts and exports, so it has to be stable, sortable,
+  # and identical in every host.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [ primary_key_type, foreign_key_type ]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.match?(/postg/) # postgresql, postgis
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns. Returns an empty-hash
+  # default for SQLite/PostgreSQL, nil for MySQL. The models handle nil
+  # gracefully by defaulting to {} in their accessors.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    {}
+  end
+
+  # Same MySQL caveat as `json_column_default`, but for list-shaped columns.
+  def json_array_default
+    return nil if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    []
+  end
+
+  # Legal documents are routinely longer than MySQL's 64 KB TEXT limit, and a
+  # silently truncated agreement is the worst possible failure for this gem.
+  # `:mediumtext` maps to MEDIUMTEXT on MySQL (16 MB) and to ordinary TEXT
+  # everywhere else.
+  def text_column_type
+    return :mediumtext if connection.adapter_name.downcase.match?(/mysql|trilogy/)
+
+    :text
+  end
+
+  def quoted_values(values)
+    values.map { |value| connection.quote(value) }.join(", ")
+  end
+
+  # SQLite implements both foreign keys and check constraints by rebuilding a
+  # table. During a long install migration, Active Record can otherwise rebuild
+  # from a schema-cache entry captured before the indexes/columns immediately
+  # above were added. Refreshing around every rebuild keeps the SQLite result
+  # identical to PostgreSQL/MySQL instead of quietly resurrecting stale shape.
+  def add_clickwrap_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+    add_check_constraint(table, expression, **options)
+    refresh_clickwrap_table_schema!(table)
+  end
+
+  def add_clickwrap_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+    add_foreign_key(from_table, to_table, **options)
+    refresh_clickwrap_table_schema!(from_table)
+  end
+
+  def refresh_clickwrap_table_schema!(table)
+    connection.schema_cache.clear_data_source_cache!(table.to_s)
+  end
+end