munawaba 0.1.0

data/app/services/munawaba/notifications/validity.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Notifications
+    class Validity
+      Result = Struct.new(:status, :code, :schedule, :shift, keyword_init: true) do
+        def valid? = status.nil?
+      end
+      KIND_SETTINGS = { "advance_reminder" => :notify_advance, "shift_start" => :notify_shift_start,
+                        "assignment_change" => :notify_assignment_change, "next_assignment_change" => :notify_next_assignment_change }.freeze
+
+      def self.call(delivery, now: Time.current, allow_old_notification_revision: false)
+        # Bypass earlier cached reads so sending and lease recovery see committed changes.
+        ActiveRecord::Base.uncached do
+          validate(delivery, now: now, allow_old_notification_revision: allow_old_notification_revision)
+        end
+      end
+
+      def self.validate(delivery, now:, allow_old_notification_revision:)
+        context = Context::V1.validate!(kind: delivery.kind, context: delivery.context)
+        schedule = Schedule.find(delivery.schedule_id)
+        result = Result.new(schedule: schedule)
+        reject = ->(status, code) { result.status = status; result.code = code; result }
+        return reject.call(:stale, "expired") if delivery.expires_at <= now
+        return reject.call(:canceled,
+                           "integration_disabled") unless schedule.slack_enabled && schedule.slack_webhook_configured_at
+        unless allow_old_notification_revision || delivery.notification_revision == schedule.notification_revision
+          return reject.call(:stale, "notification_changed")
+        end
+
+        setting = KIND_SETTINGS[delivery.kind]
+        return reject.call(:canceled, "kind_disabled") if setting && !schedule.public_send(setting)
+        return result if delivery.kind == "test"
+        return reject.call(:stale, "coverage_changed") unless delivery.coverage_revision == schedule.coverage_revision
+        return reject.call(:canceled, "schedule_inactive") unless %w[scheduled active pausing].include?(schedule.state)
+
+        shift = Shift.find(delivery.shift_id || context.fetch("described_shift_id"))
+        result.shift = shift
+        return reject.call(:canceled, "shift_canceled") if shift.canceled_at
+        return reject.call(:stale,
+                           "shift_changed") unless shift.schedule_id == schedule.id && shift.coverage_revision == schedule.coverage_revision
+        return reject.call(:stale, "timing_changed") unless shift.timing_version == delivery.timing_version
+
+        if delivery.kind == "next_assignment_change"
+          return reject.call(:stale, "rotation_changed") unless schedule.rotation_revision == delivery.rotation_revision
+          raise Context::V1::Invalid unless shift.base_person_id == context["new_next_person_id"] && shift.id == context["described_shift_id"]
+
+          Person.find(context.fetch("previous_next_person_id"))
+          Person.find(context.fetch("new_next_person_id"))
+        else
+          return reject.call(:stale,
+                             "assignment_changed") unless delivery.assignment_version == shift.assignment_version
+
+          validate_transition!(context, shift) if delivery.kind == "assignment_change"
+        end
+        unless Timing::PersistedIntervalVerifier.valid?(shift: shift, now: now)
+          return reject.call(:stale, "timing_rules_changed")
+        end
+
+        result
+      rescue Context::V1::Invalid, ActiveRecord::RecordNotFound, KeyError
+        Result.new(status: :stale, code: "invalid_delivery_context")
+      end
+
+      def self.validate_transition!(context, shift)
+        previous = Person.find(context.fetch("previous_person_id"))
+        current = Person.find(context.fetch("new_person_id"))
+        raise Context::V1::Invalid unless current.id == shift.effective_person_id
+
+        replacement = ShiftOverride.find(context["override_id"]) if context["override_id"]
+        ended = ShiftOverride.find(context["ended_override_id"]) if context["ended_override_id"]
+        if replacement
+          raise Context::V1::Invalid unless replacement.shift_id == shift.id && replacement.ended_at.nil? && replacement.previous_person_id == previous.id && replacement.replacement_person_id == current.id
+        end
+        if ended
+          raise Context::V1::Invalid unless ended.shift_id == shift.id && ended.ended_at && ended.replacement_person_id == previous.id
+
+          expected_reason = { "override_superseded" => "superseded", "override_revoked" => "revoked",
+                              "override_restored_to_base" => "restored_to_base" }.fetch(context["transition_type"])
+          raise Context::V1::Invalid unless ended.end_reason == expected_reason
+        end
+        if !replacement && shift.base_person_id != current.id
+          raise Context::V1::Invalid
+        end
+
+        true
+      end
+    end
+  end
+end

data/app/services/munawaba/notifications/wake_dispatcher.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Notifications
+    class WakeDispatcher
+      def self.call
+        ActiveRecord.after_all_transactions_commit do
+          begin
+            DispatchDueNotificationsJob.perform_later
+          rescue StandardError
+            Munawaba.signal("dispatcher_wake_failed")
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/munawaba/preview.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Munawaba
+  Preview = Struct.new(:token, :projection, :conflicts, :details, keyword_init: true)
+end

data/app/services/munawaba/result.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Munawaba
+  Result = Struct.new(:status, :record, :errors, :preview, keyword_init: true) do
+    def success? = status < 400
+  end
+end

data/app/services/munawaba/shifts/normalize_future_timing.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Shifts
+    class NormalizeFutureTiming
+      SCHEDULE_FIELDS = %w[state coverage_starts_at first_activated_at lifecycle_revision coverage_start_boundary
+                           generated_through_boundary rotation_effective_boundary pause_effective_at].freeze
+      Prepared = Struct.new(:schedule, :virtual_schedule, :rows, :slots, :changes,
+                            :clipping, :conflicts, :audit_before, :finalized, keyword_init: true) do
+        def changed? = changes.any? || SCHEDULE_FIELDS.any? { |key| schedule[key] != virtual_schedule[key] }
+      end
+      SLOT_FIELDS = %i[id schedule_id coverage_revision boundary_index starts_at ends_at base_person_id
+                       effective_person_id rotation_revision assignment_version timing_version].freeze
+
+      def self.call(schedule:, now: nil)
+        ActiveRecord::Base.transaction(requires_new: true) do
+          schedule.lock!("FOR NO KEY UPDATE")
+          captured = Canonical.time(now || Time.current)
+          prepared = locked_preparation(schedule, captured)
+          apply!(prepared, now: captured)
+          prepared
+        end
+      end
+
+      def self.locked_preparation(schedule, now)
+        live = Shift.where(schedule_id: schedule.id, coverage_revision: schedule.coverage_revision, canceled_at: nil)
+        # The latest started shift fixes the boundary with coverage already underway.
+        ids = case schedule.state
+              when "scheduled", "active"
+                future_ids = live.where("starts_at > ?", now).pluck(:id)
+                if schedule.state == "active" || schedule.coverage_starts_at <= now
+                  preceding_id = live.where("starts_at <= ?", now).order(starts_at: :desc, id: :desc).pick(:id)
+                end
+                first_id = live.where(boundary_index: schedule.coverage_start_boundary).pick(:id) if schedule.state == "scheduled"
+                future_ids + [preceding_id, first_id].compact
+              when "pausing"
+                live.where(boundary_index: schedule.generated_through_boundary).pluck(:id)
+              else []
+              end
+        shifts = live.where(id: ids.uniq).order(:id).lock("FOR NO KEY UPDATE").to_a
+        ShiftOverride.where(shift_id: shifts.map(&:id), ended_at: nil).order(:id).lock("FOR NO KEY UPDATE").load
+        NotificationDelivery.where(schedule_id: schedule.id,
+                                   status: %w[pending enqueued
+                                              processing]).order(:id).lock("FOR NO KEY UPDATE").load
+        prepare(schedule: schedule, now: now, shifts: shifts)
+      end
+
+      def self.slot(shift)
+        SLOT_FIELDS.to_h { |key| [key, shift.public_send(key)] }
+      end
+
+      def self.prepare(schedule:, now:, shifts: nil, provider: Timing::BoundaryCalculator.method(:timezone))
+        rows = shifts || Shift.where(schedule_id: schedule.id, coverage_revision: schedule.coverage_revision,
+                                     canceled_at: nil).order(:id).to_a
+        rows = rows.select { |row|
+          row.canceled_at.nil? && row.coverage_revision == schedule.coverage_revision
+        }.sort_by(&:boundary_index)
+        virtual = schedule.dup
+        virtual.id = schedule.id
+        slots = rows.map { |row| slot(row) }
+        changes = []
+        clipping = false
+        if %w[scheduled active].include?(schedule.state) && rows.any?
+          calculator = Timing::BoundaryCalculator.new(schedule, provider: provider)
+          first = rows.first
+          scheduled = schedule.state == "scheduled"
+          first_new_start = calculator.boundary(first.boundary_index).resolved_at
+          # If a changed rule moves the start into the past, begin at now instead
+          # of creating coverage for time that has already passed.
+          scheduled_moved = scheduled && first_new_start != schedule.coverage_starts_at
+          clipping = scheduled_moved && first_new_start <= now
+          slots.each_with_index do |item, index|
+            next unless item[:starts_at] > now || scheduled_moved
+
+            left = calculator.boundary(item[:boundary_index]).resolved_at
+            right = calculator.boundary(item[:boundary_index] + 1).resolved_at
+            prior = index.positive? && slots[index - 1]
+            left = prior[:ends_at] if prior && (prior[:starts_at] <= now || scheduled_moved)
+            left = now if clipping && index.zero?
+            raise ArgumentError, "Timing maintenance is required: an interval is no longer positive" unless right > left
+
+            if item[:starts_at] != left || item[:ends_at] != right
+              item[:starts_at] = left
+              item[:ends_at] = right
+              item[:timing_version] += 1
+              changes << item
+            end
+          end
+          if scheduled
+            start = slots.first[:starts_at]
+            moved = start != schedule.coverage_starts_at
+            virtual.coverage_starts_at = start
+            if start <= now
+              virtual.state = "active"
+              virtual.first_activated_at ||= start
+            end
+            virtual.lifecycle_revision += 1 if moved || virtual.state != schedule.state
+          end
+        elsif schedule.state == "pausing" && schedule.pause_effective_at <= now
+          virtual.assign_attributes(state: "paused", coverage_start_boundary: nil, coverage_starts_at: nil,
+                                    generated_through_boundary: nil, rotation_effective_boundary: nil, pause_effective_at: nil,
+                                    lifecycle_revision: schedule.lifecycle_revision + 1)
+        end
+        slots.each_cons(2) do |left, right|
+          raise ArgumentError,
+                "Timing maintenance would overlap retained intervals" if left[:ends_at] > right[:starts_at]
+        end
+        Prepared.new(schedule: schedule, virtual_schedule: virtual, rows: rows, slots: slots,
+                     changes: changes, clipping: clipping)
+      end
+
+      # Keep preparation separate so confirmations can verify the signed preview
+      # and its conflicts before changing stored shifts.
+      def self.apply!(prepared, now:, operation_id: SecureRandom.uuid, defer: false)
+        schedule = prepared.schedule
+        prepared.audit_before = { start: schedule.coverage_starts_at, state: schedule.state,
+                                  pause: schedule.pause_effective_at, first_ever: schedule.first_activated_at.nil? }
+        Shift.connection.execute("SET CONSTRAINTS ALL DEFERRED") if prepared.changes.any?
+        prepared.changes.each do |slot|
+          prepared.rows.find { |row|
+            row.id == slot[:id]
+          }.update!(starts_at: slot[:starts_at], ends_at: slot[:ends_at], timing_version: slot[:timing_version])
+        end
+        changes = SCHEDULE_FIELDS.select { |key| prepared.schedule[key] != prepared.virtual_schedule[key] }
+        prepared.schedule.update!(prepared.virtual_schedule.attributes.slice(*changes)) if changes.any?
+        finalize!(prepared, now: now, operation_id: operation_id) unless defer
+        prepared
+      end
+
+      # Combined changes publish timing effects after the final assignments are saved.
+      def self.finalize!(prepared, now:, operation_id:)
+        return if prepared.finalized
+
+        prepared.finalized = true
+        schedule = prepared.schedule
+        before_start, before_state, before_pause, first_ever = prepared.audit_before.values_at(:start, :state, :pause, :first_ever)
+        audit_attributes = { schedule: schedule, operation_id: operation_id, occurred_at: now }
+
+        if prepared.changes.any?
+          conflicts = prepared.conflicts || Conflicts::Finder.call(slots: prepared.changes)
+          rows = Shift.where(id: prepared.changes.map { |slot| slot[:id] }).order(:id).to_a
+          Notifications::Planner.call(schedule: schedule, now: now, operation: "timing", shifts: rows,
+                                      invalidation_shift_ids: rows.map(&:id))
+          if conflicts.any?
+            ActiveSupport::Notifications.instrument("timing.conflicts.munawaba", schedule_id: schedule.id,
+                                                                                 conflict_count: conflicts.length)
+          end
+          Audit::Recorder.record!(**audit_attributes, event_type: "timing.future_projection_recomputed", metadata: {
+                                    changed_count: rows.length,
+                                    coverage_starts_at_before: Canonical.instant(before_start),
+                                    coverage_starts_at_after: Canonical.instant(schedule.coverage_starts_at),
+                                    state_before: before_state, state_after: schedule.state
+                                  })
+        end
+
+        if before_state == "scheduled" && schedule.state == "active"
+          first = prepared.rows.min_by(&:boundary_index)
+          event = first_ever ? "schedule.activated" : "schedule.resumed"
+          Audit::Recorder.record!(**audit_attributes, event_type: event, shift: first, metadata: {
+                                    state_before: before_state, state_after: schedule.state,
+                                    coverage_starts_at: schedule.coverage_starts_at, next_person_id: first.base_person_id
+                                  })
+        elsif before_state == "pausing" && schedule.state == "paused"
+          last = prepared.rows.max_by(&:boundary_index)
+          Audit::Recorder.record!(**audit_attributes, event_type: "schedule.paused", shift: last, metadata: {
+                                    state_before: before_state, state_after: schedule.state, effective_at: before_pause
+                                  })
+        end
+      end
+    end
+  end
+end

data/app/services/munawaba/shifts/project.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Shifts
+    class Project
+      def self.call(schedule:, observed_revision: nil, now: nil)
+        operation_id = SecureRandom.uuid
+        ActiveRecord::Base.transaction(requires_new: true) do
+          schedule.lock!("FOR NO KEY UPDATE")
+          captured = now ? Canonical.time(now) : Canonical.time(Time.current)
+          next [] unless %w[scheduled active].include?(schedule.state)
+          next [] if observed_revision && schedule.coverage_revision != observed_revision
+
+          prepared = NormalizeFutureTiming.locked_preparation(schedule, captured)
+          NormalizeFutureTiming.apply!(prepared, now: captured, operation_id: operation_id)
+          next [] unless %w[scheduled active].include?(schedule.state)
+
+          calculator = Timing::BoundaryCalculator.new(schedule)
+          target = ProjectionPlan.target(calculator, schedule.coverage_start_boundary,
+                                         captured + Defaults::SHIFT_GENERATION_HORIZON)
+          cursor = schedule.generated_through_boundary
+          next [] if cursor >= target
+
+          ids = schedule.ordered_person_ids
+          raise ArgumentError,
+                "A live schedule requires active rotation members" if ids.empty? || Person.active.where(id: ids).count != ids.length
+
+          last = prepared.slots.max_by { |slot| slot[:boundary_index] }
+          slots = ((cursor + 1)..target).map do |index|
+            person_id = ids[(index - schedule.rotation_effective_boundary) % ids.length]
+            start = index == cursor + 1 && last ? last[:ends_at] : calculator.boundary(index).resolved_at
+            { id: nil, schedule_id: schedule.id, coverage_revision: schedule.coverage_revision, boundary_index: index,
+              starts_at: start, ends_at: calculator.boundary(index + 1).resolved_at,
+              base_person_id: person_id, effective_person_id: person_id, rotation_revision: schedule.rotation_revision, assignment_version: 1, timing_version: 1 }
+          end
+          conflicts = Conflicts::Finder.call(slots: slots)
+          rows = Shift.persist_projection!(schedule: schedule, slots: slots, now: captured)
+          schedule.update!(generated_through_boundary: target)
+          Notifications::Planner.call(schedule: schedule, now: captured, operation: "project", shifts: rows)
+          Audit::Recorder.record!(event_type: "timing.projection_extended", schedule: schedule,
+                                  operation_id: operation_id, occurred_at: captured,
+                                  metadata: { inserted_count: rows.length, projected_until: rows.last.ends_at })
+          ActiveSupport::Notifications.instrument("projection.conflicts.munawaba", schedule_id: schedule.id,
+                                                                                   conflict_count: conflicts.length) if conflicts.any?
+          rows
+        end
+      end
+    end
+  end
+end

data/app/services/munawaba/shifts/projection_plan.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Shifts
+    class ProjectionPlan
+      MAX_BIGINT = 9_223_372_036_854_775_807
+      attr_reader :state, :coverage_revision, :rotation_revision, :first_boundary, :target_boundary,
+                  :boundaries, :slots, :canonical
+
+      def initialize(schedule:, operation_kind:, now:, person_ids:, first_boundary:, target_boundary: nil,
+                     conflict_check_at: nil, provider: Timing::BoundaryCalculator.method(:timezone))
+        @schedule_id = schedule.id
+        @operation_kind = operation_kind.to_s
+        @first_boundary = Integer(first_boundary)
+        @coverage_revision = schedule.coverage_revision + 1
+        @rotation_revision = schedule.rotation_revision + (@operation_kind == "resume" ? 1 : 0)
+        @conflict_check_at = conflict_check_at && Canonical.time(conflict_check_at)
+        @calculator = Timing::BoundaryCalculator.new(schedule, provider: provider)
+        @state = @operation_kind == "immediate_activation" || @calculator.boundary(@first_boundary).resolved_at == now ? "active" : "scheduled"
+        @target_boundary = target_boundary.nil? ? self.class.target(@calculator, @first_boundary,
+                                                                    now + Defaults::SHIFT_GENERATION_HORIZON) : Integer(target_boundary)
+        validate!(person_ids)
+        @boundaries = (@first_boundary..(@target_boundary + 1)).map { |index| @calculator.boundary(index) }.freeze
+        @slots = (@first_boundary..@target_boundary).map do |index|
+          left, right = @boundaries[index - @first_boundary, 2]
+          immediate = index == @first_boundary && @operation_kind == "immediate_activation"
+          base = person_ids[(index - @first_boundary) % person_ids.length]
+          { schedule_id: @schedule_id, id: nil, coverage_revision: @coverage_revision, boundary_index: index,
+            starts_at: immediate ? @conflict_check_at : left.resolved_at, ends_at: right.resolved_at,
+            base_person_id: base, effective_person_id: base, rotation_revision: @rotation_revision,
+            assignment_version: 1, timing_version: 1, start_resolution: immediate ? nil : left.resolution,
+            start_adjustment_seconds: immediate ? nil : left.adjustment_seconds,
+            end_resolution: right.resolution, end_adjustment_seconds: right.adjustment_seconds,
+            start_basis: immediate ? "activation_conflict_check" : "canonical" }
+        end
+        @slots.each { |slot|
+          raise ArgumentError, "Invalid projected interval" unless slot[:ends_at] > slot[:starts_at]
+        }
+        Canonical.deep_freeze(@slots)
+        @canonical = [1, @operation_kind, @schedule_id, @state, @coverage_revision, @rotation_revision,
+                      @first_boundary, @target_boundary, @operation_kind == "immediate_activation" ? "confirmation_now_subset" : "canonical",
+                      @conflict_check_at && Canonical.micros(@conflict_check_at),
+                      [schedule.cadence, schedule.time_zone, schedule.anchor_local_date.iso8601, schedule.anchor_local_seconds],
+                      @boundaries.map { |b|
+                        [b.index, b.nominal_local_date.iso8601, b.nominal_local_seconds, Canonical.micros(b.resolved_at), b.resolution, b.adjustment_seconds, b.utc_offset_seconds]
+                      },
+                      @slots.map { |s|
+                        [s[:boundary_index], Canonical.micros(s[:starts_at]), Canonical.micros(s[:ends_at]), s[:base_person_id], s[:effective_person_id], s[:start_resolution], s[:start_adjustment_seconds], s[:end_resolution], s[:end_adjustment_seconds], s[:rotation_revision], s[:assignment_version], s[:timing_version], s[:start_basis]]
+                      }]
+        Canonical.deep_freeze(@canonical)
+        freeze
+      end
+
+      def digest = Canonical.digest(@canonical)
+
+      def persistence_slots(now:)
+        return @slots unless @operation_kind == "immediate_activation"
+        raise ArgumentError,
+              "Immediate activation left its acknowledged slot" unless @conflict_check_at <= now && now < @slots.first[:ends_at]
+
+        Canonical.deep_freeze(@slots.map.with_index { |slot, index| index.zero? ? slot.merge(starts_at: now) : slot })
+      end
+
+      def self.target(calculator, first_boundary, cutoff)
+        cutoff = [cutoff, calculator.boundary(first_boundary + 1).resolved_at].max
+        [first_boundary, calculator.slot_at(cutoff)].max
+      end
+
+      private
+
+      def validate!(person_ids)
+        valid = %w[immediate_activation future_activation resume].include?(@operation_kind) &&
+                @schedule_id.is_a?(Integer) && @schedule_id.between?(1, MAX_BIGINT) &&
+                @coverage_revision.between?(1, MAX_BIGINT) && @rotation_revision.between?(0, MAX_BIGINT) &&
+                @first_boundary.between?(0,
+                                         MAX_BIGINT - 1) && @target_boundary.between?(@first_boundary,
+                                                                                      MAX_BIGINT - 1) &&
+                person_ids.present? && person_ids.uniq == person_ids && person_ids.all? { |id|
+                                                                          id.is_a?(Integer) && id.between?(1,
+                                                                                                           MAX_BIGINT)
+                                                                        }
+        valid &&= @operation_kind == "immediate_activation" ? !@conflict_check_at.nil? : @conflict_check_at.nil?
+        valid &&= @first_boundary.zero? if @operation_kind == "future_activation"
+        valid &&= @calculator.boundary(@first_boundary).resolved_at <= @conflict_check_at if @operation_kind == "immediate_activation"
+        raise ArgumentError, "Invalid projection plan" unless valid
+      end
+    end
+  end
+end

data/app/services/munawaba/slack/client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "timeout"
+
+module Munawaba
+  module Slack
+    class Client
+      Result = Struct.new(:status, :http_status, :error_code, :retry_after, :unknown, keyword_init: true)
+      class DeadlineExceeded < StandardError; end
+      class ResponseTooLarge < StandardError; end
+      MAX_RESPONSE_BYTES = 16_384
+
+      def self.monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def self.call(webhook:, payload:, deadline:)
+        new.call(webhook: webhook, payload: payload, deadline: deadline)
+      end
+
+      def call(webhook:, payload:, deadline:)
+        transmitted = false
+        http = nil
+        uri = WebhookValidator.validate!(webhook)
+        remaining = deadline - self.class.monotonic
+        raise DeadlineExceeded if remaining <= 0
+
+        http = Net::HTTP.new(uri.host, uri.port, nil)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.max_retries = 0
+        http.open_timeout = [Defaults::SLACK_OPEN_TIMEOUT.to_f, remaining].min
+        http.read_timeout = [Defaults::SLACK_READ_TIMEOUT.to_f, remaining].min
+        http.write_timeout = [Defaults::SLACK_WRITE_TIMEOUT.to_f, remaining].min
+        request = Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json")
+        request.body = JSON.generate(payload)
+        result = nil
+        Timeout.timeout(remaining, DeadlineExceeded) do
+          http.start do
+            budget = deadline - self.class.monotonic
+            raise DeadlineExceeded if budget <= 0
+
+            http.read_timeout = [Defaults::SLACK_READ_TIMEOUT.to_f, budget].min
+            http.write_timeout = [Defaults::SLACK_WRITE_TIMEOUT.to_f, budget].min
+            transmitted = true
+            http.request(request) do |response|
+              bytes = 0
+              response.read_body do |chunk|
+                bytes += chunk.bytesize
+                raise ResponseTooLarge if bytes > MAX_RESPONSE_BYTES
+                raise DeadlineExceeded if self.class.monotonic >= deadline
+              end
+              raise DeadlineExceeded if self.class.monotonic >= deadline
+
+              code = response.code.to_i
+              retry_after = response["Retry-After"].to_s
+              seconds = retry_after.match?(/\A\d+\z/) ? retry_after.to_i : nil
+              result = classify(code, seconds)
+            end
+          end
+        end
+        result
+      rescue WebhookValidator::Invalid, JSON::GeneratorError
+        Result.new(status: :failed, error_code: "invalid_webhook", unknown: false)
+      rescue OpenSSL::SSL::SSLError
+        Result.new(status: :failed, error_code: transmitted ? "delivery_outcome_unknown" : "tls_failure",
+                   unknown: transmitted)
+      rescue DeadlineExceeded, Timeout::Error
+        Result.new(status: :retry, error_code: transmitted ? "delivery_outcome_unknown" : "network_timeout",
+                   unknown: transmitted)
+      rescue SocketError, SystemCallError, IOError, ResponseTooLarge, Net::HTTPBadResponse, Net::ProtocolError
+        Result.new(status: :retry, error_code: transmitted ? "delivery_outcome_unknown" : "network_error",
+                   unknown: transmitted)
+      ensure
+        begin
+          http.finish if http&.started?
+        rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+          # Return fixed error codes, without Slack response bodies or exception messages.
+        end
+      end
+
+      private
+
+      def classify(code, retry_after)
+        case code
+        when 200..299
+          Result.new(status: :delivered, http_status: code, unknown: false)
+        when 300..399
+          Result.new(status: :failed, http_status: code, error_code: "redirect_rejected", unknown: false)
+        when 429
+          if retry_after && retry_after > Defaults::NOTIFICATION_RETRY_AFTER_CAP
+            Result.new(status: :failed, http_status: code, error_code: "retry_after_out_of_bounds", unknown: false)
+          else
+            Result.new(status: :retry, http_status: code, error_code: "rate_limited",
+                       retry_after: retry_after&.positive? ? retry_after : nil, unknown: false)
+          end
+        when 408, 500..599
+          Result.new(status: :retry, http_status: code, error_code: "upstream_unavailable", unknown: false)
+        else
+          Result.new(status: :failed, http_status: code, error_code: "slack_rejected", unknown: false)
+        end
+      end
+    end
+  end
+end

data/app/services/munawaba/slack/renderer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Munawaba
+  module Slack
+    class Renderer
+      LABELS = { "advance_reminder" => "Upcoming on-call shift", "shift_start" => "On-call shift started",
+                 "assignment_change" => "On-call assignment changed", "next_assignment_change" => "Next assignment changed",
+                 "test" => "Munawaba test message" }.freeze
+
+      def self.escape(value, limit: 255)
+        value.to_s.truncate(limit, omission: "…").gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+
+      def self.person(person)
+        id = person.slack_member_id
+        id.present? && id.match?(/\A[A-Z][A-Z0-9]{1,31}\z/) ? "<@#{id}>" : escape(person.name)
+      end
+
+      def self.call(delivery:, schedule:, shift: nil)
+        context = Notifications::Context::V1.validate!(kind: delivery.kind, context: delivery.context)
+        lines = ["#{LABELS.fetch(delivery.kind)} · #{escape(schedule.name, limit: 120)}"]
+        if delivery.kind == "assignment_change"
+          previous, current = Person.find(context.fetch("previous_person_id")),
+Person.find(context.fetch("new_person_id"))
+          lines << "#{person(previous)} → #{person(current)}"
+          override = ShiftOverride.find(context["override_id"] || context.fetch("ended_override_id"))
+          lines << "Reason: #{escape(override.reason, limit: 500)}" if override.reason.present?
+        elsif delivery.kind == "next_assignment_change"
+          lines << "#{person(Person.find(context.fetch("previous_next_person_id")))} → #{person(Person.find(context.fetch("new_next_person_id")))}"
+          shift ||= Shift.find(context.fetch("described_shift_id"))
+        elsif shift
+          lines << "On call: #{person(shift.effective_person)}"
+        end
+        if shift
+          zone = ActiveSupport::TimeZone[schedule.time_zone]
+          lines << "#{shift.starts_at.in_time_zone(zone).strftime("%b %-d, %Y %H:%M")} – #{shift.ends_at.in_time_zone(zone).strftime("%b %-d, %Y %H:%M")} (#{escape(schedule.time_zone)})"
+        else
+          lines << "Timezone: #{escape(schedule.time_zone)}"
+        end
+        if Munawaba.config.application_base_url
+          base = Munawaba.config.application_base_url.sub(%r{/+\z}, "")
+          lines << "<#{base}/schedules/#{schedule.id}|View schedule>"
+        end
+        { text: lines.join("\n"), unfurl_links: false, unfurl_media: false }
+      end
+    end
+  end
+end

data/app/services/munawaba/slack/webhook_validator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+module Munawaba
+  module Slack
+    class WebhookValidator
+      class Invalid < Munawaba::Error
+        def initialize(*) = super("Enter a valid allowed HTTPS Slack webhook")
+      end
+
+      def self.validate!(value)
+        raise Invalid unless value.is_a?(String) && !value.match?(/[\x00-\x20\x7f]/)
+
+        uri = URI.parse(value)
+        raise Invalid unless uri.is_a?(URI::HTTPS) && uri.port == 443 && uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+        raise Invalid unless Munawaba.config.slack_allowed_hosts.include?(uri.host&.downcase)
+        raise Invalid unless uri.path.present? && uri.path != "/" && !uri.path.match?(/%(?:0[0-9a-f]|1[0-9a-f]|7f)/i)
+
+        if %w[hooks.slack.com hooks.slack-gov.com].include?(uri.host.downcase)
+          raise Invalid unless uri.path.match?(%r{\A/services/[A-Za-z0-9_-]+/[A-Za-z0-9_-]+/[A-Za-z0-9_-]+\z})
+        end
+        uri
+      rescue URI::InvalidURIError
+        raise Invalid
+      end
+
+      def self.valid?(value)
+        validate!(value)
+        true
+      rescue Invalid
+        false
+      end
+    end
+  end
+end