munawaba 0.1.0

data/config/routes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+Munawaba::Engine.routes.draw do
+  root "overviews#show"
+  resource :overview, only: :show
+  resource :calendar, only: :show
+  resources :people, except: :destroy do
+    member do
+      get :deactivation
+      patch :deactivate
+      patch :reactivate
+    end
+  end
+  resources :schedules, except: :destroy do
+    member do
+      post :preview_activation
+      post :activate
+      post :pause
+      post :preview_resume
+      post :resume
+      post :cancel_scheduled
+    end
+    resource :rotation, only: %i[edit update] do
+      post :preview
+    end
+    resource :slack_integration, only: %i[edit update] do
+      post :test
+      delete :remove
+    end
+  end
+  resources :shifts, only: :show do
+    resource :override, only: %i[new create edit update] do
+      post :preview
+      patch :revoke
+      patch :restore
+    end
+  end
+  get "activity", to: "audit_events#index", as: :activity
+  resources :notification_deliveries, only: :index do
+    member { post :retry }
+  end
+  patch "theme", to: "themes#update", as: :theme
+  get "assets/:version/:id", to: "frontends#show", as: :frontend_asset, format: false,
+                             constraints: { version: /[A-Za-z0-9._-]+/, id: /[A-Za-z0-9._-]+/ }
+end

data/db/migrate/20260905000001_create_munawaba_people.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class CreateMunawabaPeople < ActiveRecord::Migration[7.2]
+  def up
+    unless connection.adapter_name == "PostgreSQL" && connection.database_version >= 150000
+      raise ActiveRecord::MigrationError, "Munawaba requires PostgreSQL 15 or later"
+    end
+
+    create_table :munawaba_people do |t|
+      t.string :name, limit: 120, null: false
+      t.string :email, limit: 320, null: false
+      t.string :slack_member_id, limit: 32
+      t.boolean :active, null: false, default: true
+      t.column :deactivated_at, :timestamptz, precision: 6
+      t.integer :lock_version, null: false, default: 0
+      t.column :created_at, :timestamptz, precision: 6, null: false
+      t.column :updated_at, :timestamptz, precision: 6, null: false
+    end
+    add_index :munawaba_people, "lower(email)", unique: true, name: "mn_people_email_unique"
+    add_index :munawaba_people, :slack_member_id, unique: true, where: "slack_member_id IS NOT NULL",
+                                                  name: "mn_people_slack_unique"
+    add_check_constraint :munawaba_people,
+                         "name = btrim(name) AND name <> '' AND email = lower(btrim(email)) AND email <> ''", name: "mn_people_identity"
+    add_check_constraint :munawaba_people, "slack_member_id IS NULL OR slack_member_id ~ '^[A-Z][A-Z0-9]{1,31}$'",
+                         name: "mn_people_slack_format"
+    add_check_constraint :munawaba_people, "active = (deactivated_at IS NULL)", name: "mn_people_active"
+    add_check_constraint :munawaba_people, "lock_version >= 0", name: "mn_people_lock_version"
+  end
+
+  def down
+    drop_table :munawaba_people
+  end
+end

data/db/migrate/20260905000002_create_munawaba_schedules.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+class CreateMunawabaSchedules < ActiveRecord::Migration[7.2]
+  def up
+    create_table :munawaba_schedules do |t|
+      t.string :name, limit: 120, null: false
+      t.string :state, null: false, default: "draft"
+      t.string :cadence, null: false
+      t.string :time_zone, limit: 100, null: false
+      t.date :anchor_local_date, null: false
+      t.integer :anchor_local_seconds, null: false
+      t.column :first_activated_at, :timestamptz, precision: 6
+      t.bigint :coverage_revision, null: false, default: 0
+      t.bigint :coverage_start_boundary
+      t.column :coverage_starts_at, :timestamptz, precision: 6
+      t.bigint :generated_through_boundary
+      t.bigint :rotation_revision, null: false, default: 0
+      t.bigint :rotation_effective_boundary
+      t.column :pause_effective_at, :timestamptz, precision: 6
+      t.bigint :lifecycle_revision, null: false, default: 0
+      t.bigint :notification_revision, null: false, default: 0
+      t.text :slack_webhook_url
+      t.boolean :slack_enabled, null: false, default: false
+      t.boolean :notify_advance, null: false, default: true
+      t.integer :advance_notice_seconds, null: false, default: 86400
+      t.boolean :notify_shift_start, null: false, default: true
+      t.boolean :notify_assignment_change, null: false, default: true
+      t.boolean :notify_next_assignment_change, null: false, default: true
+      t.column :slack_webhook_configured_at, :timestamptz, precision: 6
+      t.integer :lock_version, null: false, default: 0
+      t.column :created_at, :timestamptz, precision: 6, null: false
+      t.column :updated_at, :timestamptz, precision: 6, null: false
+    end
+    add_index :munawaba_schedules, "lower(name)", unique: true, name: "mn_schedules_name_unique"
+    add_index :munawaba_schedules, [:coverage_starts_at, :id], where: "state = 'scheduled'",
+                                                               name: "mn_schedules_scheduled_due"
+    add_index :munawaba_schedules, [:pause_effective_at, :id], where: "state = 'pausing'",
+                                                               name: "mn_schedules_pausing_due"
+    add_check_constraint :munawaba_schedules,
+                         "name = btrim(name) AND name <> '' AND time_zone = btrim(time_zone) AND time_zone <> ''", name: "mn_schedules_names"
+    add_check_constraint :munawaba_schedules,
+                         "state IN ('draft','scheduled','active','pausing','paused') AND cadence IN ('one_week','two_weeks','calendar_month')", name: "mn_schedules_enums"
+    add_check_constraint :munawaba_schedules,
+                         "anchor_local_seconds BETWEEN 0 AND 86340 AND anchor_local_seconds % 60 = 0", name: "mn_schedules_anchor_seconds"
+    add_check_constraint :munawaba_schedules,
+                         "coverage_revision >= 0 AND rotation_revision >= 0 AND lifecycle_revision >= 0 AND notification_revision >= 0 AND lock_version >= 0", name: "mn_schedules_versions"
+    add_check_constraint :munawaba_schedules,
+                         "(coverage_start_boundary IS NULL OR coverage_start_boundary >= 0) AND (generated_through_boundary IS NULL OR generated_through_boundary >= 0) AND (rotation_effective_boundary IS NULL OR rotation_effective_boundary >= 0)", name: "mn_schedules_boundary_indexes"
+    add_check_constraint :munawaba_schedules, "generated_through_boundary >= coverage_start_boundary",
+                         name: "mn_schedules_cursor"
+    add_check_constraint :munawaba_schedules,
+                         "state NOT IN ('active','scheduled') OR rotation_effective_boundary BETWEEN coverage_start_boundary AND generated_through_boundary", name: "mn_schedules_rotation_boundary"
+    add_check_constraint :munawaba_schedules, "first_activated_at <= coverage_starts_at",
+                         name: "mn_schedules_first_start"
+    add_check_constraint :munawaba_schedules, "coverage_revision > 0 OR state = 'draft'",
+                         name: "mn_schedules_revision_state"
+    add_check_constraint :munawaba_schedules, "advance_notice_seconds BETWEEN 60 AND 2592000",
+                         name: "mn_schedules_notice"
+    add_check_constraint :munawaba_schedules,
+                         "(slack_webhook_url IS NULL) = (slack_webhook_configured_at IS NULL) AND (NOT slack_enabled OR slack_webhook_url IS NOT NULL)", name: "mn_schedules_slack_presence"
+    add_check_constraint :munawaba_schedules, <<~SQL.squish, name: "mn_schedules_state_fields"
+      (state = 'draft' AND first_activated_at IS NULL AND coverage_start_boundary IS NULL AND coverage_starts_at IS NULL AND generated_through_boundary IS NULL AND rotation_effective_boundary IS NULL AND pause_effective_at IS NULL)
+      OR (state = 'scheduled' AND coverage_revision > 0 AND coverage_start_boundary IS NOT NULL AND coverage_starts_at IS NOT NULL AND generated_through_boundary IS NOT NULL AND rotation_effective_boundary IS NOT NULL AND pause_effective_at IS NULL)
+      OR (state = 'active' AND coverage_revision > 0 AND first_activated_at IS NOT NULL AND coverage_start_boundary IS NOT NULL AND coverage_starts_at IS NOT NULL AND generated_through_boundary IS NOT NULL AND rotation_effective_boundary IS NOT NULL AND pause_effective_at IS NULL)
+      OR (state = 'pausing' AND first_activated_at IS NOT NULL AND coverage_start_boundary IS NOT NULL AND coverage_starts_at IS NOT NULL AND generated_through_boundary IS NOT NULL AND rotation_effective_boundary IS NULL AND pause_effective_at IS NOT NULL AND pause_effective_at > coverage_starts_at)
+      OR (state = 'paused' AND first_activated_at IS NOT NULL AND coverage_start_boundary IS NULL AND coverage_starts_at IS NULL AND generated_through_boundary IS NULL AND rotation_effective_boundary IS NULL AND pause_effective_at IS NULL)
+    SQL
+  end
+
+  def down
+    drop_table :munawaba_schedules
+  end
+end

data/db/migrate/20260905000003_create_munawaba_schedule_memberships.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class CreateMunawabaScheduleMemberships < ActiveRecord::Migration[7.2]
+  def up
+    create_table :munawaba_schedule_memberships do |t|
+      t.bigint :schedule_id, null: false
+      t.bigint :person_id, null: false
+      t.integer :position, null: false
+      t.column :created_at, :timestamptz, precision: 6, null: false
+      t.column :updated_at, :timestamptz, precision: 6, null: false
+    end
+    add_foreign_key :munawaba_schedule_memberships, :munawaba_schedules, column: :schedule_id, on_delete: :restrict
+    add_foreign_key :munawaba_schedule_memberships, :munawaba_people, column: :person_id, on_delete: :restrict
+    add_index :munawaba_schedule_memberships, [:schedule_id, :person_id], unique: true,
+                                                                          name: "mn_memberships_person_unique"
+    add_index :munawaba_schedule_memberships, [:schedule_id, :position], unique: true,
+                                                                         name: "mn_memberships_position_unique"
+    add_index :munawaba_schedule_memberships, [:person_id, :schedule_id], name: "mn_memberships_person_schedule"
+    add_check_constraint :munawaba_schedule_memberships, "position >= 0", name: "mn_memberships_position"
+  end
+
+  def down
+    drop_table :munawaba_schedule_memberships
+  end
+end

data/db/migrate/20260905000004_create_munawaba_shifts.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+class CreateMunawabaShifts < ActiveRecord::Migration[7.2]
+  def up
+    begin
+      execute "CREATE EXTENSION IF NOT EXISTS btree_gist"
+    rescue ActiveRecord::StatementInvalid => error
+      raise ActiveRecord::MigrationError,
+            "Munawaba requires btree_gist. Ask the database owner to CREATE EXTENSION btree_gist before installing. (#{error.cause.class})"
+    end
+    create_table :munawaba_shifts do |t|
+      t.bigint :schedule_id, null: false
+      t.bigint :coverage_revision, null: false
+      t.bigint :boundary_index, null: false
+      t.column :starts_at, :timestamptz, precision: 6, null: false
+      t.column :ends_at, :timestamptz, precision: 6, null: false
+      t.bigint :base_person_id, null: false
+      t.bigint :effective_person_id, null: false
+      t.bigint :rotation_revision, null: false, default: 0
+      t.bigint :assignment_version, null: false, default: 1
+      t.bigint :timing_version, null: false, default: 1
+      t.column :canceled_at, :timestamptz, precision: 6
+      t.string :cancellation_reason
+      t.column :generated_at, :timestamptz, precision: 6, null: false
+      t.integer :lock_version, null: false, default: 0
+      t.column :created_at, :timestamptz, precision: 6, null: false
+      t.column :updated_at, :timestamptz, precision: 6, null: false
+    end
+    add_foreign_key :munawaba_shifts, :munawaba_schedules, column: :schedule_id, on_delete: :restrict
+    add_foreign_key :munawaba_shifts, :munawaba_people, column: :base_person_id, on_delete: :restrict
+    add_foreign_key :munawaba_shifts, :munawaba_people, column: :effective_person_id, on_delete: :restrict
+    add_index :munawaba_shifts, [:schedule_id, :coverage_revision, :boundary_index], unique: true,
+                                                                                     name: "mn_shifts_slot_unique"
+    add_index :munawaba_shifts, [:schedule_id, :boundary_index], unique: true, where: "canceled_at IS NULL",
+                                                                 name: "mn_shifts_live_slot_unique"
+    add_index :munawaba_shifts, [:schedule_id, :canceled_at, :starts_at], name: "mn_shifts_schedule_starts"
+    add_index :munawaba_shifts, [:effective_person_id, :starts_at, :ends_at], name: "mn_shifts_person_starts_ends"
+    execute "CREATE INDEX mn_shifts_person_overlap ON munawaba_shifts USING gist (effective_person_id, tstzrange(starts_at, ends_at, '[)')) WHERE canceled_at IS NULL"
+    execute "CREATE INDEX mn_shifts_calendar_overlap ON munawaba_shifts USING gist (tstzrange(starts_at, ends_at, '[)')) WHERE canceled_at IS NULL"
+    execute "ALTER TABLE munawaba_shifts ADD CONSTRAINT mn_shifts_no_live_overlap EXCLUDE USING gist (schedule_id WITH =, tstzrange(starts_at, ends_at, '[)') WITH &&) WHERE (canceled_at IS NULL) DEFERRABLE INITIALLY IMMEDIATE"
+    add_check_constraint :munawaba_shifts, "ends_at > starts_at", name: "mn_shifts_interval"
+    add_check_constraint :munawaba_shifts,
+                         "coverage_revision > 0 AND boundary_index >= 0 AND rotation_revision >= 0 AND assignment_version > 0 AND timing_version > 0 AND lock_version >= 0", name: "mn_shifts_versions"
+    add_check_constraint :munawaba_shifts,
+                         "(canceled_at IS NULL AND cancellation_reason IS NULL) OR (canceled_at IS NOT NULL AND cancellation_reason IS NOT NULL AND cancellation_reason IN ('pause','scheduled_run_canceled'))", name: "mn_shifts_cancellation"
+  end
+
+  def down
+    drop_table :munawaba_shifts
+  end
+end

data/db/migrate/20260905000005_create_munawaba_shift_overrides.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class CreateMunawabaShiftOverrides < ActiveRecord::Migration[7.2]
+  def up
+    create_table :munawaba_shift_overrides do |t|
+      t.bigint :shift_id, null: false
+      t.bigint :previous_person_id, null: false
+      t.bigint :replacement_person_id, null: false
+      t.text :reason
+      t.column :ended_at, :timestamptz, precision: 6
+      t.string :end_reason
+      t.column :created_at, :timestamptz, precision: 6, null: false
+      t.column :updated_at, :timestamptz, precision: 6, null: false
+    end
+    add_foreign_key :munawaba_shift_overrides, :munawaba_shifts, column: :shift_id, on_delete: :restrict
+    add_foreign_key :munawaba_shift_overrides, :munawaba_people, column: :previous_person_id, on_delete: :restrict
+    add_foreign_key :munawaba_shift_overrides, :munawaba_people, column: :replacement_person_id, on_delete: :restrict
+    add_index :munawaba_shift_overrides, :shift_id, unique: true, where: "ended_at IS NULL",
+                                                    name: "mn_overrides_live_unique"
+    add_index :munawaba_shift_overrides, [:replacement_person_id, :shift_id], where: "ended_at IS NULL",
+                                                                              name: "mn_overrides_replacement_live"
+    add_check_constraint :munawaba_shift_overrides, "previous_person_id <> replacement_person_id",
+                         name: "mn_overrides_people"
+    add_check_constraint :munawaba_shift_overrides,
+                         "reason IS NULL OR (reason = btrim(reason) AND reason <> '' AND char_length(reason) <= 1000)", name: "mn_overrides_reason"
+    add_check_constraint :munawaba_shift_overrides,
+                         "(ended_at IS NULL AND end_reason IS NULL) OR (ended_at IS NOT NULL AND end_reason IS NOT NULL AND ended_at >= created_at AND end_reason IN ('revoked','superseded','restored_to_base','shift_canceled'))", name: "mn_overrides_end"
+  end
+
+  def down
+    drop_table :munawaba_shift_overrides
+  end
+end

data/db/migrate/20260905000006_create_munawaba_notification_deliveries.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+class CreateMunawabaNotificationDeliveries < ActiveRecord::Migration[7.2]
+  def up
+    create_table :munawaba_notification_deliveries do |t|
+      t.bigint :schedule_id, null: false
+      t.bigint :shift_id
+      t.bigint :retry_of_delivery_id
+      t.string :kind, null: false
+      t.string :status, null: false, default: "pending"
+      t.string :event_key, limit: 255, null: false
+      t.bigint :coverage_revision
+      t.bigint :assignment_version
+      t.bigint :timing_version
+      t.bigint :rotation_revision
+      t.bigint :notification_revision, null: false
+      t.jsonb :context, null: false, default: {}
+      t.column :due_at, :timestamptz, precision: 6, null: false
+      t.column :next_attempt_at, :timestamptz, precision: 6
+      t.column :expires_at, :timestamptz, precision: 6, null: false
+      t.uuid :claim_token
+      t.column :enqueued_at, :timestamptz, precision: 6
+      t.column :processing_at, :timestamptz, precision: 6
+      t.column :lease_expires_at, :timestamptz, precision: 6
+      t.column :last_attempt_at, :timestamptz, precision: 6
+      t.integer :attempt_count, null: false, default: 0
+      t.integer :last_http_status
+      t.string :last_error_code, limit: 64
+      t.column :delivered_at, :timestamptz, precision: 6
+      t.column :created_at, :timestamptz, precision: 6, null: false
+      t.column :updated_at, :timestamptz, precision: 6, null: false
+    end
+    add_foreign_key :munawaba_notification_deliveries, :munawaba_schedules, column: :schedule_id, on_delete: :restrict
+    add_foreign_key :munawaba_notification_deliveries, :munawaba_shifts, column: :shift_id, on_delete: :restrict
+    add_foreign_key :munawaba_notification_deliveries, :munawaba_notification_deliveries,
+                    column: :retry_of_delivery_id, on_delete: :restrict
+    add_index :munawaba_notification_deliveries, :event_key, unique: true, name: "mn_deliveries_event_unique"
+    add_index :munawaba_notification_deliveries, :retry_of_delivery_id, unique: true,
+                                                                        where: "retry_of_delivery_id IS NOT NULL", name: "mn_deliveries_retry_unique"
+    add_index :munawaba_notification_deliveries, [:next_attempt_at, :id], where: "status = 'pending'",
+                                                                          name: "mn_deliveries_pending_due"
+    add_index :munawaba_notification_deliveries, [:expires_at, :id], where: "status = 'pending'",
+                                                                     name: "mn_deliveries_pending_expiry"
+    add_index :munawaba_notification_deliveries, [:lease_expires_at, :id],
+              where: "status IN ('enqueued','processing')", name: "mn_deliveries_lease_expiry"
+    add_index :munawaba_notification_deliveries, [:shift_id, :kind, :assignment_version, :timing_version],
+              name: "mn_deliveries_shift_versions"
+    add_index :munawaba_notification_deliveries,
+              [:schedule_id, :kind, :coverage_revision, :rotation_revision, :timing_version, :notification_revision], name: "mn_deliveries_schedule_versions"
+    add_index :munawaba_notification_deliveries, [:schedule_id, :created_at, :id],
+              order: { created_at: :desc, id: :desc }, name: "mn_deliveries_schedule_history"
+    add_index :munawaba_notification_deliveries, [:created_at, :id], order: { created_at: :desc, id: :desc },
+                                                                     name: "mn_deliveries_history"
+    add_index :munawaba_notification_deliveries, [:status, :created_at, :id], order: { created_at: :desc, id: :desc },
+                                                                              name: "mn_deliveries_status_history"
+    add_index :munawaba_notification_deliveries, [:schedule_id, :status, :created_at, :id],
+              order: { created_at: :desc, id: :desc }, name: "mn_deliveries_schedule_status_history"
+    add_check_constraint :munawaba_notification_deliveries,
+                         "kind IN ('advance_reminder','shift_start','assignment_change','next_assignment_change','test') AND status IN ('pending','enqueued','processing','delivered','failed','canceled','stale')", name: "mn_deliveries_enums"
+    add_check_constraint :munawaba_notification_deliveries, "event_key = btrim(event_key) AND event_key <> ''",
+                         name: "mn_deliveries_event_key"
+    add_check_constraint :munawaba_notification_deliveries,
+                         "attempt_count >= 0 AND notification_revision >= 0 AND (coverage_revision IS NULL OR coverage_revision > 0) AND (assignment_version IS NULL OR assignment_version > 0) AND (timing_version IS NULL OR timing_version > 0) AND (rotation_revision IS NULL OR rotation_revision >= 0)", name: "mn_deliveries_versions"
+    add_check_constraint :munawaba_notification_deliveries, "expires_at > due_at", name: "mn_deliveries_expiration"
+    add_check_constraint :munawaba_notification_deliveries,
+                         "(next_attempt_at IS NOT NULL) = (status = 'pending') AND (claim_token IS NOT NULL) = (status IN ('enqueued','processing')) AND (lease_expires_at IS NOT NULL) = (status IN ('enqueued','processing')) AND (delivered_at IS NOT NULL) = (status = 'delivered')", name: "mn_deliveries_status_fields"
+    add_check_constraint :munawaba_notification_deliveries,
+                         "(status <> 'pending' OR (enqueued_at IS NULL AND processing_at IS NULL)) AND (status <> 'enqueued' OR (enqueued_at IS NOT NULL AND processing_at IS NULL)) AND (status <> 'processing' OR (enqueued_at IS NOT NULL AND processing_at IS NOT NULL))", name: "mn_deliveries_claim_times"
+    add_check_constraint :munawaba_notification_deliveries,
+                         "(last_error_code IS NULL OR last_error_code ~ '^[a-z][a-z0-9_]{0,63}$') AND (status <> 'failed' OR (last_error_code IS NOT NULL AND last_error_code <> '')) AND (last_http_status IS NULL OR last_http_status BETWEEN 100 AND 599)", name: "mn_deliveries_safe_result"
+    add_check_constraint :munawaba_notification_deliveries, <<~SQL.squish, name: "mn_deliveries_kind_fields"
+      (kind IN ('advance_reminder','shift_start','assignment_change') AND shift_id IS NOT NULL AND coverage_revision IS NOT NULL AND assignment_version IS NOT NULL AND timing_version IS NOT NULL AND rotation_revision IS NULL)
+      OR (kind = 'next_assignment_change' AND shift_id IS NULL AND coverage_revision IS NOT NULL AND rotation_revision IS NOT NULL AND timing_version IS NOT NULL AND assignment_version IS NULL)
+      OR (kind = 'test' AND shift_id IS NULL AND coverage_revision IS NULL AND assignment_version IS NULL AND timing_version IS NULL AND rotation_revision IS NULL)
+    SQL
+    add_check_constraint :munawaba_notification_deliveries,
+                         "jsonb_typeof(context) = 'object' AND octet_length(context::text) <= 16384", name: "mn_deliveries_context"
+  end
+
+  def down
+    drop_table :munawaba_notification_deliveries
+  end
+end

data/db/migrate/20260905000007_create_munawaba_audit_events.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class CreateMunawabaAuditEvents < ActiveRecord::Migration[7.2]
+  def up
+    create_table :munawaba_audit_events do |t|
+      t.uuid :operation_id, null: false
+      t.string :event_type, limit: 100, null: false
+      t.bigint :schedule_id
+      t.bigint :person_id
+      t.bigint :shift_id
+      t.string :actor_type, limit: 100
+      t.string :actor_id, limit: 255
+      t.string :actor_name, limit: 255
+      t.jsonb :metadata, null: false, default: {}
+      t.column :occurred_at, :timestamptz, precision: 6, null: false
+      t.column :created_at, :timestamptz, precision: 6, null: false
+    end
+    add_foreign_key :munawaba_audit_events, :munawaba_schedules, column: :schedule_id, on_delete: :restrict
+    add_foreign_key :munawaba_audit_events, :munawaba_people, column: :person_id, on_delete: :restrict
+    add_foreign_key :munawaba_audit_events, :munawaba_shifts, column: :shift_id, on_delete: :restrict
+    add_index :munawaba_audit_events, [:occurred_at, :id], name: "mn_audit_history"
+    [:schedule_id, :person_id, :shift_id, :event_type].each do |column|
+      add_index :munawaba_audit_events, [column, :occurred_at, :id], order: { occurred_at: :desc, id: :desc },
+                                                                     name: "mn_audit_#{column}_history"
+    end
+    add_index :munawaba_audit_events, [:actor_type, :actor_id, :occurred_at, :id],
+              order: { occurred_at: :desc, id: :desc }, name: "mn_audit_actor_history"
+    add_index :munawaba_audit_events, :operation_id, name: "mn_audit_operation"
+    add_check_constraint :munawaba_audit_events,
+                         "jsonb_typeof(metadata) = 'object' AND octet_length(metadata::text) <= 131072", name: "mn_audit_metadata"
+  end
+
+  def down
+    drop_table :munawaba_audit_events
+  end
+end

data/db/migrate/20260905000008_simplify_munawaba_activity.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class SimplifyMunawabaActivity < ActiveRecord::Migration[7.2]
+  def up
+    execute "DROP TRIGGER IF EXISTS munawaba_audit_append_only ON munawaba_audit_events"
+    execute "DROP FUNCTION IF EXISTS munawaba_reject_audit_mutation()"
+    %w[mn_audit_catalog mn_audit_actor mn_audit_envelope].each do |name|
+      remove_check_constraint :munawaba_audit_events, name: name, if_exists: true
+    end
+  end
+
+  def down
+    # Existing activity may now contain custom events and optional actors. Do not
+    # reinstate legacy restrictions that could reject or lock those records.
+  end
+end

data/lib/generators/munawaba/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Munawaba
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+    class_option :migrations, type: :boolean, default: true, desc: "Copy Munawaba's migrations"
+    class_option :initializer, type: :boolean, default: true, desc: "Copy Munawaba's initializer"
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    def install
+      template "munawaba.rb", "config/initializers/munawaba.rb" if options[:initializer]
+      if options[:migrations]
+        Dir[Munawaba::Engine.root.join("db/migrate/*.rb")].each do |path|
+          basename = File.basename(path).sub(/\A\d+_/, "")
+          next if Dir[File.join(destination_root, "db/migrate/*_#{basename}")].any?
+
+          migration_template path, "db/migrate/#{basename}"
+        end
+      end
+      say "Configure access in config/initializers/munawaba.rb."
+      say 'Add to config/routes.rb: mount Munawaba::Engine => "/on-call"'
+      say "Run bin/rails db:migrate, then schedule the background jobs:"
+      say "https://github.com/milkstrawai/munawaba#background-jobs"
+    end
+  end
+end

data/lib/generators/munawaba/templates/munawaba.rb

@@ -0,0 +1,23 @@
+Munawaba.configure do |config|
+  config.parent_controller = "ApplicationController"
+
+  # A callback must return exactly true to allow the request.
+  config.authenticate = ->(_controller) { false }
+  config.authorize = ->(_controller, _action, _record) { false }
+  # Optional attribution for activity entries: {type: "User", id: user.id.to_s, name: user.name}
+  config.actor = ->(_controller) { nil }
+
+  # Full engine URL, including the mount path, for links in Slack messages.
+  config.application_base_url = nil # "https://example.com/on-call"
+  config.default_schedule_time_zone = "UTC"
+  config.organization_time_zone = "UTC"
+  config.week_starts_on = :monday
+  config.job_queue_name = :munawaba
+
+  # Slack delivery requires Active Record Encryption and a configured webhook.
+  config.notifications_enabled = -> { ENV.fetch("MUNAWABA_NOTIFICATIONS_ENABLED", "false") == "true" }
+  # Maintenance mode pauses scheduling changes and Slack delivery.
+  # Before deploying timezone-data updates, follow:
+  # https://github.com/milkstrawai/munawaba/blob/main/docs/usage.md#timezone-data-updates
+  config.maintenance_mode = -> { ENV.fetch("MUNAWABA_MAINTENANCE_MODE", "false") == "true" }
+end

data/lib/munawaba/configuration.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Munawaba
+  class Configuration
+    ATTRIBUTES = %i[parent_controller authenticate authorize actor application_base_url
+                    default_schedule_time_zone organization_time_zone week_starts_on job_queue_name
+                    calendar_future_limit calendar_past_limit calendar_max_span notifications_enabled
+                    slack_allowed_hosts maintenance_mode].freeze
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize
+      @parent_controller = "ApplicationController"
+      @default_schedule_time_zone = @organization_time_zone = "UTC"
+      @week_starts_on = :monday
+      @job_queue_name = :munawaba
+      @calendar_future_limit = 12.months
+      @calendar_past_limit = 24.months
+      @calendar_max_span = 3.months
+      @notifications_enabled = false
+      @maintenance_mode = false
+      @slack_allowed_hosts = ["hooks.slack.com"]
+    end
+
+    def validate!
+      raise ConfigurationError,
+            "ActiveRecord.default_timezone must be :utc" unless ActiveRecord.default_timezone == :utc
+
+      %i[default_schedule_time_zone organization_time_zone].each { |name| TZInfo::Timezone.get(public_send(name)) }
+      %i[calendar_future_limit calendar_past_limit calendar_max_span].each do |name|
+        value = public_send(name)
+        raise ConfigurationError,
+              "#{name} must be positive" unless value.respond_to?(:to_f) && value.to_f.finite? && value.to_f > 0
+      end
+      if calendar_future_limit > Defaults::SHIFT_GENERATION_HORIZON
+        raise ConfigurationError, "calendar_future_limit exceeds the 13-month projection horizon"
+      end
+      raise ConfigurationError, "week_starts_on must be a weekday" unless Date::DAYS_INTO_WEEK.key?(week_starts_on)
+      raise ConfigurationError, "job_queue_name is required" if job_queue_name.to_s.strip.empty?
+
+      unless slack_allowed_hosts.is_a?(Array) && slack_allowed_hosts.present? && slack_allowed_hosts.all? { |host|
+        host.is_a?(String) && host.match?(/\A[a-z0-9]+(?:[.-][a-z0-9]+)*\z/)
+      }
+        raise ConfigurationError, "Slack hosts must be normalized exact hostnames"
+      end
+
+      %i[notifications_enabled maintenance_mode].each do |name|
+        value = public_send(name)
+        unless value == true || value == false || (value.respond_to?(:call) && value.respond_to?(:arity) && value.arity == 0)
+          raise ConfigurationError, "#{name} must be boolean or a zero-argument callable"
+        end
+      end
+      validate_base_url!
+      self
+    rescue TZInfo::InvalidTimezoneIdentifier
+      raise ConfigurationError, "Timezones must be valid IANA identifiers"
+    end
+
+    def notifications_enabled?
+      result = notifications_enabled.respond_to?(:call) ? notifications_enabled.call : notifications_enabled
+      Munawaba.signal("notifications_disabled") unless result == true
+      result == true && !maintenance_mode?
+    rescue StandardError
+      Munawaba.signal("notification_switch_error")
+      false
+    end
+
+    def maintenance_mode?
+      value = maintenance_mode.respond_to?(:call) ? maintenance_mode.call : maintenance_mode
+      value != false
+    rescue StandardError
+      true
+    end
+
+    private
+
+    def validate_base_url!
+      return if application_base_url.nil?
+
+      uri = URI.parse(application_base_url)
+      local = %w[localhost 127.0.0.1 ::1 [::1]].include?(uri.host)
+      scheme_valid = uri.scheme == "https" || (uri.scheme == "http" && local && !Rails.env.production?)
+      unless uri.host.present? && scheme_valid && uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil? && !application_base_url.match?(/[\x00-\x20\x7f]/)
+        raise ConfigurationError, "application_base_url must be a trusted absolute HTTPS engine URL"
+      end
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "application_base_url is invalid"
+    end
+  end
+end

data/lib/munawaba/defaults.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Defaults
+    MAXIMUM_SCHEDULE_MEMBERS = 100
+    SHIFT_GENERATION_HORIZON = 13.months.freeze
+    START_NOTIFICATION_GRACE_PERIOD = 1.hour.freeze
+    NOTIFICATION_ENQUEUE_LEASE = 30.minutes.freeze
+    NOTIFICATION_PROCESSING_LEASE = 2.minutes.freeze
+    NOTIFICATION_BATCH_SIZE = 100
+    NOTIFICATION_MAX_ATTEMPTS = 8
+    NOTIFICATION_BACKOFF_BASE = 30.seconds.freeze
+    NOTIFICATION_BACKOFF_CAP = 30.minutes.freeze
+    NOTIFICATION_RETRY_AFTER_CAP = 1.hour.freeze
+    SLACK_OPEN_TIMEOUT = 3
+    SLACK_READ_TIMEOUT = 5
+    SLACK_WRITE_TIMEOUT = 5
+    SLACK_TOTAL_TIMEOUT = 20
+  end
+end

data/lib/munawaba/engine.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Munawaba
+  class Engine < ::Rails::Engine
+    isolate_namespace Munawaba
+    engine_name "munawaba_engine"
+
+    initializer "munawaba.filter_secrets" do |app|
+      app.config.filter_parameters += [:slack_webhook_url]
+    end
+
+    config.after_initialize do
+      Munawaba.configuration.validate!
+    end
+  end
+end

data/lib/munawaba/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Munawaba
+  VERSION = "0.1.0"
+end

data/lib/munawaba.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext"
+require "active_record"
+require "active_job"
+require "action_controller/railtie"
+require "tzinfo"
+require_relative "munawaba/version"
+
+module Munawaba
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+  class << self
+    alias config configuration
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.signal(event, **values)
+    ActiveSupport::Notifications.instrument("#{event}.munawaba", values)
+  end
+end
+
+require_relative "munawaba/defaults"
+require_relative "munawaba/configuration"
+require_relative "munawaba/engine"