feedkit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fc80f79e7e3169ea207e7496284b8d1ab30722aa39e9de731e48e1dbc5f8192
-  data.tar.gz: 7ffc0fc5b23e1ba23cb9cbe97660a0b6ad6e57e2c9821b9790d446f5a038bdcd
+  metadata.gz: 74138d59abacb0faf60572624e29afc713f1fdf3e1fed0c553206cc86e357d71
+  data.tar.gz: dd88f9f5876b4e65ea21c92aad49aa351c7359aebd00f41b78ff479fa4710bb6
 SHA512:
-  metadata.gz: b2bb5d8e545f76d5a1e239a4c281ae96ed8a48fe8e75c0b6ff51050491e2d3ee52faca97460ae3952639947f1020f7e0354db603b05f00696bfed433c7973432
-  data.tar.gz: c0fa337cd9044a3832829dacad9691a4c602088e35a4988cbd8464648b1c3d5ac4dcc8894008d665d852b627321bc6e89950a0c203b48176e11ff0691ed284bf
+  metadata.gz: a2b97d983d035764a00b2dda527710269644737e5812e2bcdb4c119d3b03c6e7f9c1e1482ed3caa9b0a7a201aa58c292dd29394281b501d3b01a30411ba6145e
+  data.tar.gz: 805e9ed65e6fb34adbd42cdd8a0a36d6b5be2742605b1d76d6950782932f1c79c5538fd88b85e3f55d1cb7a581685a627fb1c71b381b3ac3b53e938e5670c33b

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-02-09
+
+### Added
+
+- `:year` schedules with `month:` and `day:` conditions
+
+### Changed
+
+- Schedule periods are now symbolic (`:hour`, `:day`, `:week`, `:month`, `:year`) instead of arbitrary `ActiveSupport::Duration` values
+- Schedule matching, naming, validation, and period boundary calculations were refactored into focused modules
+- Deduplication uses schedule boundaries (`period_start_at`) rather than sliding time windows
+- `week:` condition now supports ISO week parity only (`:odd`/`:even`)
+
+### Fixed
+
+- Handle DST transitions when calculating `period_start_at` (skip ambiguous/non-existent local ticks)
+- Documentation clarifications around weekday integers (`wday`), multi-tick schedules (ranges/arrays), and when deduplication applies
+
 ## [0.1.0] - 2026-02-05
 
 ### Added

data/README.md

@@ -6,7 +6,7 @@
 
 **Scheduled feed generation for Rails applications.**
 
-Feedkit is a Rails engine that lets you define generator classes that produce structured data feeds on a schedule. Generators auto-register when they inherit from `Feedkit::Generator` — define your class anywhere, add a schedule, and Feedkit handles the rest.
+Feedkit is a Rails engine for scheduled feed generation. You write generator classes that return a hash. Feedkit runs them on a schedule, stores the results, and deduplicates per schedule period.
 
 ## Table of Contents
 
@@ -27,9 +27,9 @@ Feedkit is a Rails engine that lets you define generator classes that produce st
 
 ## The Problem
 
-Applications often need to produce periodic data summaries — cost reports, usage digests, analytics snapshots. The typical approach scatters this logic across cron jobs, service objects, and ad-hoc scripts. When you have multiple report types, each with its own schedule, deduplication, and storage, things get messy fast.
+Most applications end up needing periodic snapshots: cost reports, usage digests, analytics rollups. In practice, that code gets spread across cron, one-off jobs, and service objects. After a few report types, you start re-solving the same problems (when to run, how to avoid duplicates, where to store the output).
 
-Feedkit gives you a single pattern: define a generator class, declare its schedule, implement a `#data` method that returns a hash. Feedkit handles dispatching, deduplication, and persistence.
+Feedkit keeps it in one place: define a generator class, declare its schedule, and implement `#data`. Feedkit takes care of dispatching, persistence, and "once per period" deduplication.
 
 ## Installation
 
@@ -48,11 +48,11 @@ rails db:migrate
 ```
 
 This creates three things:
-- `config/initializers/feedkit.rb` — configuration file
+- `config/initializers/feedkit.rb`: configuration file
 - A migration for the `feedkit_feeds` table
-- `app/generators/` — directory for your generator classes
+- `app/generators/`: directory for your generator classes
 
-> **Note:** Feedkit currently requires PostgreSQL. The migration uses `jsonb` for the feed data column.
+> **Note:** Feedkit requires PostgreSQL. The migration uses `jsonb` for the feed data column.
 
 If your models use UUID primary keys, pass the `--owner_id_type` option:
 
@@ -86,8 +86,8 @@ This creates `app/generators/cost_overview.rb` and a corresponding test file.
 class CostOverview < Feedkit::Generator
   owned_by Organization
 
-  schedule every: 1.day, at: { hour: 13 }, as: :daily
-  schedule every: 1.week, at: { hour: 14, weekday: :tuesday }, as: :weekly
+  every :day, at: { hour: 13 }, as: :daily
+  every :week, at: { hour: 14, weekday: :tuesday }, as: :weekly
 
   private
 
@@ -124,7 +124,7 @@ feedkit_dispatch:
   class: Feedkit::DispatchJob
 ```
 
-How often you run the dispatch job depends on your schedules. Running it hourly works well for most setups — it only enqueues work for generators that are actually due.
+How often you run the dispatch job depends on your schedules. Running it hourly works well for most setups. Feedkit does not backfill missed ticks; it only enqueues work for schedules that are due at the time `DispatchJob` runs.
 
 ## Generators
 
@@ -134,7 +134,10 @@ A generator is a class that inherits from `Feedkit::Generator`. It defines what
 class WeeklyDigest < Feedkit::Generator
   owned_by Organization
 
-  schedule every: 1.week, at: { hour: 9, weekday: :monday }, as: :weekly
+  # Optional: override the stored feed_type (defaults to the underscored class name)
+  # feed_type :weekly_digest
+
+  every :week, at: { hour: 9, weekday: :monday }, as: :weekly
 
   private
 
@@ -149,23 +152,47 @@ end
 
 ### Auto-registration
 
-Generators are automatically registered when their class is loaded. There is no manual registration step. Define the class, and Feedkit discovers it.
+Generators register themselves when their class is loaded. There is no manual registration step.
 
-In production (with `config.eager_load = true`), Rails loads all classes at boot, so all generators in `app/generators/` are registered automatically.
+In production (with `config.eager_load = true`), Rails loads application code at boot, so generator classes under `app/generators/` are loaded and registered automatically.
 
 In development, Feedkit calls `eager_load_generators!` before each dispatch cycle to ensure all generator files are loaded from the configured `generator_paths`.
 
 ### The `#data` method
 
-This is the only method you need to implement. It receives no arguments — access the owner via the `owner` accessor.
+This is the only method you need to implement. It receives no arguments. Access the owner via the `owner` accessor.
 
 - Return a **Hash** to create a feed record with that data
 - Return **`nil`** to skip feed creation (useful for conditional feeds)
 
+### The `owned_by` macro
+
+Use `owned_by` when you want `Feedkit::DispatchJob` to run a generator automatically for every record of an owner model. It tells Feedkit what class to iterate over when dispatching scheduled runs.
+
+If you only run a generator manually, `owned_by` is optional. You can still pass an owner instance to `new`, and Feedkit will persist the feed under that owner.
+
 ### The `owner` accessor
 
 Inside your generator, `owner` gives you the model instance that the feed belongs to. Use it to query for the data you need.
 
+### The `feed_type` macro
+
+By default, Feedkit stores feeds under a `feed_type` derived from the generator class name (including namespaces). You can override it per generator:
+
+```ruby
+class CostOverview < Feedkit::Generator
+  owned_by Organization
+
+  feed_type :cost_overview
+
+  private
+
+  def data
+    { total_cost: owner.costs.sum(:amount) }
+  end
+end
+```
+
 ### The `options` accessor
 
 Generators accept arbitrary keyword arguments that are available via the `options` accessor. This is useful for passing context when triggering generators manually:
@@ -203,19 +230,19 @@ rails generate feedkit:generator SystemHealthCheck
 
 ## Scheduling
 
-### The `schedule` DSL
+### The `every` DSL
 
 Each generator can define one or more schedules:
 
 ```ruby
-schedule every: <period>, at: <conditions>, as: <name>, superseded_by: <names>
+every <period>, at: <conditions>, as: <name>, superseded_by: <names>
 ```
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `every:` | Yes | Any `ActiveSupport::Duration` — `1.hour`, `1.day`, `1.week`, `2.weeks`, `1.month`, `1.year`, `6.hours`, etc. |
+| `every` | Yes | One of: `:hour`, `:day`, `:week`, `:month`, `:year` |
 | `at:` | Yes | Hash of conditions that must all match for the schedule to be due |
-| `as:` | No | Name for this schedule (auto-generated from period and conditions if omitted) |
+| `as:` | No | Name for this schedule (must be unique per generator; auto-generated from period and conditions if omitted) |
 | `superseded_by:` | No | Array of schedule names that take precedence when both are due |
 
 ### Conditions
@@ -226,38 +253,40 @@ Conditions are AND-ed together. All must match for the schedule to fire.
 |-----------|--------|---------|
 | `hour:` | `0..23` | `hour: 6`, `hour: [6, 12, 18]`, `hour: 9..17` |
 | `day:` | `1..31`, `:first`, `:last` | `day: 1`, `day: :last`, `day: 1..15` |
-| `weekday:` | `0..6`, `:sunday`..`:saturday` | `weekday: :monday`, `weekday: :monday..:friday` |
-| `week:` | `1..53`, `:even`, `:odd` | `week: 42`, `week: :even` |
+| `weekday:` | `0..6` (Ruby/Rails `wday`: `0` = Sunday), `:sunday`..`:saturday` | `weekday: :monday`, `weekday: :monday..:friday` |
+| `week:` | `:odd`, `:even` (ISO week parity, `Date#cweek`) | `week: :odd` |
 | `month:` | `1..12`, `:january`..`:december` | `month: :january`, `month: :january..:march` |
 
-All condition types accept integers, symbols (where applicable), ranges, and arrays.
+All condition types except `week:` accept integers, symbols (where applicable), ranges, and arrays. `week:` only accepts `:odd` or `:even`.
+
+Ranges/arrays expand to multiple matching values. If that results in multiple occurrences within a period (for example `every :day, at: { hour: [6, 12, 18] }`), Feedkit treats each occurrence as a distinct tick and generates one feed per tick (per owner).
 
 ### Examples
 
 ```ruby
 # Every day at 6 AM
-schedule every: 1.day, at: { hour: 6 }, as: :daily
+every :day, at: { hour: 6 }, as: :daily
 
 # Every Monday at 7 AM
-schedule every: 1.week, at: { hour: 7, weekday: :monday }, as: :weekly
+every :week, at: { hour: 7, weekday: :monday }, as: :weekly
+
+# Every Monday at 7 AM on odd ISO weeks
+every :week, at: { hour: 7, weekday: :monday, week: :odd }
 
 # First of every month at 8 AM
-schedule every: 1.month, at: { hour: 8, day: 1 }, as: :monthly
+every :month, at: { hour: 8, day: 1 }, as: :monthly
 
 # January 15 at 9 AM (yearly)
-schedule every: 1.year, at: { hour: 9, month: :january, day: 15 }, as: :annual
-
-# Every even week
-schedule every: 2.weeks, at: { hour: 6, week: :even }
+every :year, at: { hour: 9, month: :january, day: 15 }, as: :annual
 
 # Weekdays only at 6 AM
-schedule every: 1.day, at: { hour: 6, weekday: :monday..:friday }
+every :day, at: { hour: 6, weekday: :monday..:friday }
 
-# Multiple times per day
-schedule every: 1.day, at: { hour: [6, 12, 18] }
+# Any of these hours (one feed per scheduled hour)
+every :day, at: { hour: [6, 12, 18] }
 
 # Q1 only
-schedule every: 1.month, at: { hour: 6, day: 1, month: :january..:march }
+every :month, at: { hour: 6, day: 1, month: :january..:march }
 ```
 
 ### Schedule precedence with `superseded_by`
@@ -268,13 +297,9 @@ When a generator has multiple schedules, you sometimes want a longer-period sche
 class CostOverview < Feedkit::Generator
   owned_by Organization
 
-  schedule every: 1.day, at: { hour: 6 }, as: :daily,
-           superseded_by: %i[weekly monthly]
-
-  schedule every: 1.week, at: { hour: 6, weekday: :monday }, as: :weekly,
-           superseded_by: :monthly
-
-  schedule every: 1.month, at: { hour: 6, day: 1 }, as: :monthly
+  every :day, at: { hour: 6 }, as: :daily, superseded_by: %i[weekly monthly]
+  every :week, at: { hour: 6, weekday: :monday }, as: :weekly, superseded_by: :monthly
+  every :month, at: { hour: 6, day: 1 }, as: :monthly
 
   private
 
@@ -288,9 +313,13 @@ On a regular Tuesday at 6 AM, only `:daily` fires. On a Monday at 6 AM, only `:w
 
 ### Deduplication
 
-Scheduled generators automatically deduplicate within their period. If a daily generator already created a feed for today, calling it again is a no-op. This prevents duplicates if the dispatch job runs more than once in the same period.
+Scheduled generators automatically deduplicate within their period. If a generator already created a feed for the current schedule period (for example, for the current scheduled hour), calling it again is a no-op. This prevents duplicates if the dispatch job runs more than once in the same period.
+
+Deduplication is based on **schedule boundaries**, not a sliding `period.ago` window. For scheduled feeds, Feedkit computes a `period_start_at` timestamp from the schedule and stores it on the feed record. Subsequent runs in the same schedule period are skipped.
+
+`period_start_at` is computed in the app's time zone. Around DST transitions, some local times don't exist or repeat; Feedkit skips ticks that can't be represented as a stable local timestamp.
 
-Deduplication checks `created_at > period.ago` scoped to the owner and feed type. No configuration needed.
+Deduplication only applies when a generator is invoked as a scheduled run (with `period_name:` set, which is what `DispatchJob` does) and an owner is present. Ad-hoc calls do not deduplicate, including calling a scheduled generator without `period_name:` and ownerless generators.
 
 ## Ad-hoc Generators
 
@@ -315,12 +344,10 @@ end
 SystemHealthReport.new.call
 ```
 
-### Owned but unscheduled
+### Run a generator for an owner
 
 ```ruby
 class AuditReport < Feedkit::Generator
-  owned_by Organization
-
   private
 
   def data
@@ -332,7 +359,9 @@ end
 AuditReport.new(organization).call
 ```
 
-Ad-hoc generators (no schedule) skip deduplication entirely — each call creates a new feed.
+If you want this generator to be dispatched automatically on a schedule, add `owned_by Organization` and one or more `every ...` schedules.
+
+Ad-hoc generators (no schedule) skip deduplication entirely. Each call creates a new feed.
 
 ## Querying Feeds
 
@@ -366,8 +395,9 @@ Feedkit::Feed.by_type(:system_health_report).recent(5)
 | Attribute | Type | Description |
 |-----------|------|-------------|
 | `owner` | Polymorphic | The owner record (can be `nil` for ownerless feeds) |
-| `feed_type` | String | Derived from the generator class name (e.g., `"cost_overview"`) |
+| `feed_type` | String | Derived from the generator class name (namespaces included, e.g., `"admin_digest"` for `Admin::Digest`) |
 | `period_name` | String | Schedule name (e.g., `"daily"`, `"weekly"`) or `nil` for ad-hoc |
+| `period_start_at` | DateTime | Start of the schedule period used for deduplication (`nil` for ad-hoc feeds) |
 | `data` | Hash | The payload returned by `#data` (stored as `jsonb`) |
 | `created_at` | DateTime | When the feed was generated |
 
@@ -412,13 +442,13 @@ end
 
 Feedkit has four main components:
 
-1. **Generator** — Base class with auto-registration via Ruby's `inherited` hook. When you define `class MyGen < Feedkit::Generator`, it's automatically added to the registry.
+1. **Generator**: Base class with auto-registration via Ruby's `inherited` hook. When you define `class MyGen < Feedkit::Generator`, it is added to the registry.
 
-2. **Registry** — Tracks all generator classes. Knows which are scheduled, which have owners, and which are due at any given time.
+2. **Registry**: Tracks generator classes. Knows which are scheduled, which have owners, and which are due at a given time.
 
-3. **DispatchJob** — An ActiveJob that asks the registry "what's due right now?", then enqueues a `GenerateFeedJob` for each owner of each due generator.
+3. **DispatchJob**: An ActiveJob that asks the registry what is due, then enqueues a `GenerateFeedJob` for each owner of each due generator.
 
-4. **GenerateFeedJob** — An ActiveJob that instantiates a single generator for a single owner, calls `#data`, and persists the result as a `Feedkit::Feed` record.
+4. **GenerateFeedJob**: An ActiveJob that instantiates one generator for one owner, calls `#data`, and persists the result as a `Feedkit::Feed` record.
 
 ### Dispatch Flow
 
@@ -427,8 +457,8 @@ DispatchJob (hourly cron)
   → Registry.due_at(Time.current)
     → For each due generator:
       → generator.owner_class.find_each do |owner|
-        → GenerateFeedJob.perform_later(owner, generator, period_name)
-          → generator.new(owner, period_name:).call
+        → GenerateFeedJob.perform_later(..., period_name:, scheduled_at:)
+          → generator.new(owner, period_name:).call(run_at: scheduled_at)
             → Check deduplication (skip if already generated this period)
             → Call #data (skip if nil)
             → Create Feedkit::Feed record
@@ -436,10 +466,10 @@ DispatchJob (hourly cron)
 
 ### Error Handling
 
-`GenerateFeedJob` handles errors gracefully:
+`GenerateFeedJob` logs errors and does not re-raise:
 
-- **Owner deleted** between dispatch and execution — the job is silently skipped (the record no longer exists, so there's nothing to generate for)
-- **Generator errors** — logged via `Feedkit.logger` with the full backtrace, job does not re-raise
+- If an **owner is deleted** between dispatch and execution, the job is skipped.
+- If a **generator raises**, the error is logged via `Feedkit.logger` (with a full backtrace).
 
 ### Database Schema
 
@@ -449,7 +479,7 @@ The migration creates a `feedkit_feeds` table with three indexes:
 |-------|---------|---------|
 | `created_at` | `created_at` | Ordering and pagination |
 | `idx_feedkit_feeds_lookup` | `owner_type, owner_id, feed_type, created_at` | Querying feeds for an owner |
-| `idx_feedkit_feeds_dedup` | `owner_type, owner_id, feed_type, period_name` | Deduplication checks |
+| `idx_feedkit_feeds_dedup` | `owner_type, owner_id, feed_type, period_name, period_start_at` | Deduplication checks |
 
 ## Requirements
 
@@ -462,11 +492,11 @@ The migration creates a `feedkit_feeds` table with three indexes:
 
 Features we're considering for future releases:
 
-- [ ] **MySQL support** — Adapter pattern for non-PostgreSQL databases (currently requires `jsonb`)
-- [ ] **Feed retention policies** — Auto-cleanup of old feeds based on age or count per generator
-- [ ] **Callbacks** — `before_generate` and `after_generate` hooks for logging, notifications, or side effects
-- [ ] **Web dashboard** — Mountable engine with a UI for browsing feeds and monitoring generator health
-- [ ] **Feed versioning** — Schema version tracking for feed data to handle generator changes over time
+- [ ] **MySQL support**: Adapter pattern for non-PostgreSQL databases (Feedkit uses `jsonb` today)
+- [ ] **Feed retention policies**: Auto-cleanup of old feeds based on age or count per generator
+- [ ] **Callbacks**: `before_generate` and `after_generate` hooks for logging, notifications, or side effects
+- [ ] **Web dashboard**: Mountable engine with a UI for browsing feeds and monitoring generator health
+- [ ] **Feed versioning**: Schema version tracking for feed data to handle generator changes over time
 
 Have a feature request? [Open an issue](https://github.com/milkstrawai/feedkit/issues) to discuss it!
 
@@ -504,9 +534,9 @@ bundle exec appraisal rake test
 
 ### Test Coverage
 
-The project maintains high test coverage standards:
+Coverage is enforced:
 - Line coverage: 100%
-- Branch coverage: 90%
+- Branch coverage: 95%
 
 ### Multi-version Testing
 
@@ -516,11 +546,11 @@ Feedkit is tested against a matrix of Ruby and Rails versions using [Appraisal](
 |---|---|---|---|---|---|
 | Ruby 3.2 | ✓ | ✓ | ✓ | ✓ | ✓ |
 | Ruby 3.3 | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Ruby 3.4 | — | ✓ | ✓ | ✓ | ✓ |
+| Ruby 3.4 | n/a | ✓ | ✓ | ✓ | ✓ |
 
 ## Contributing
 
-Contributions are welcome! Here's how you can help:
+Contributions are welcome. Typical flow:
 
 1. **Fork** the repository
 2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)

data/app/jobs/feedkit/dispatch_job.rb

@@ -12,19 +12,20 @@ module Feedkit
 
       due_feeds.each do |config|
         config[:generator].owner_class.find_each do |owner|
-          enqueue_feed_job(owner, config[:generator], config[:period_name])
+          enqueue_feed_job(owner, config[:generator], config[:period_name], time)
         end
       end
     end
 
     private
 
-    def enqueue_feed_job(owner, generator, period_name)
+    def enqueue_feed_job(owner, generator, period_name, scheduled_at)
       Feedkit::GenerateFeedJob.perform_later(
         owner_id: owner.id,
         owner_class: owner.class.name,
         generator_class: generator.name,
-        period_name: period_name
+        period_name:,
+        scheduled_at:
       )
     end
   end

data/app/jobs/feedkit/generate_feed_job.rb

@@ -4,11 +4,11 @@ module Feedkit
   class GenerateFeedJob < ActiveJob::Base
     queue_as :default
 
-    def perform(owner_id:, owner_class:, generator_class:, period_name:)
+    def perform(owner_id:, owner_class:, generator_class:, period_name:, scheduled_at: Time.current)
       owner = owner_class.constantize.find(owner_id)
       generator = generator_class.constantize
 
-      generator.new(owner, period_name: period_name).call
+      generator.new(owner, period_name:).call(run_at: scheduled_at)
     rescue ActiveRecord::RecordNotFound
       # Owner deleted between dispatch and execution - skip silently
     rescue StandardError => e

data/app/models/feedkit/feed.rb

@@ -9,7 +9,7 @@ module Feedkit
     validates :feed_type, presence: true
     validates :data, presence: true, unless: -> { data == {} }
 
-    scope :for_owner, ->(owner) { where(owner: owner) }
+    scope :for_owner, ->(owner) { where(owner:) }
     scope :latest, -> { order(created_at: :desc) }
     scope :by_type, ->(type) { where(feed_type: type) }
     scope :recent, ->(limit = 50) { latest.limit(limit) }

data/lib/feedkit/generator.rb

@@ -21,8 +21,14 @@ module Feedkit
         @owner_class
       end
 
-      def feed_type
-        name.demodulize.underscore.to_sym
+      def feed_type(value = nil)
+        @feed_type = value.to_sym if value
+
+        @feed_type || default_feed_type
+      end
+
+      def default_feed_type
+        name.underscore.tr("/", "_").to_sym
       end
 
       def scheduled?
@@ -38,11 +44,12 @@ module Feedkit
       raise ArgumentError, "Unknown schedule: #{period_name}" if period_name && !@schedule
     end
 
-    def call
-      return if already_generated?
+    def call(run_at: Time.current)
+      period_start = period_start_at(run_at)
+      return if already_generated?(period_start)
       return unless (payload = data)
 
-      create_feed!(payload)
+      create_feed!(payload, period_start)
     end
 
     private
@@ -61,20 +68,31 @@ module Feedkit
       @schedule&.period_name
     end
 
-    def already_generated?
+    def period_start_at(run_at)
+      @schedule&.period_start_at(run_at)
+    end
+
+    def already_generated?(period_start)
       return false unless @schedule
       return false unless @owner
 
-      feed_scope.where(feed_type: self.class.feed_type, period_name: period_name)
-                .exists?(["created_at > ?", period.ago])
+      feed_scope.where(feed_type: self.class.feed_type, period_name:)
+                .exists?(period_start_at: period_start)
     end
 
-    def create_feed!(payload)
+    def create_feed!(payload, period_start)
+      attrs = { feed_type: self.class.feed_type, period_name:, data: payload }
+      attrs[:period_start_at] = period_start if @schedule
+
       if @owner
-        feed_scope.create!(feed_type: self.class.feed_type, period_name: period_name, data: payload)
+        feed_scope.create!(attrs)
       else
-        Feedkit::Feed.create!(feed_type: self.class.feed_type, period_name: period_name, data: payload)
+        Feedkit::Feed.create!(attrs)
       end
+    rescue ActiveRecord::RecordNotUnique
+      # Concurrency-safe dedup: another worker created this feed for the same
+      # (owner, feed_type, period_name, period_start_at) after our check.
+      nil
     end
 
     def feed_scope

data/lib/feedkit/registry.rb

@@ -43,7 +43,7 @@ module Feedkit
 
         dispatchable_generators.flat_map do |generator|
           generator.schedules_due(time).map do |schedule|
-            { generator: generator, period_name: schedule.period_name }
+            { generator:, period_name: schedule.period_name }
           end
         end
       end

data/lib/feedkit/schedulable.rb

@@ -11,13 +11,21 @@ module Feedkit
         @schedules ||= []
       end
 
-      def schedule(every:, at:, as: nil, superseded_by: [])
-        schedules << Feedkit::Schedule.new(every: every, at: at, as: as, superseded_by: superseded_by)
+      def every(period, at:, as: nil, superseded_by: [])
+        schedule = Feedkit::Schedule.new(period:, at:, as:, superseded_by:)
+
+        if schedules.any? { |s| s.period_name == schedule.period_name }
+          raise ArgumentError,
+                "Duplicate schedule name '#{schedule.period_name}' for #{name || self}. " \
+                "Schedule names must be unique per generator."
+        end
+
+        schedules << schedule
       end
 
       def schedules_due(time = Time.current)
         due = schedules.select { |s| s.due?(time) }
-        due_names = due.map(&:period_name)
+        due_names = due.to_set(&:period_name)
         due.reject { |s| s.superseded_by.any? { |name| due_names.include?(name) } }
       end
 

data/lib/feedkit/schedule/constants.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Feedkit
+  class Schedule
+    VALID_PERIODS = %i[hour day week month year].freeze
+    VALID_CONDITION_TYPES = %i[hour day weekday week month].freeze
+    CONDITION_NAME_ORDER = %i[hour day weekday week month].freeze
+
+    VALID_HOUR_RANGE = (0..23)
+    VALID_DAY_RANGE = (1..31)
+    VALID_WEEKDAY_RANGE = (0..6)
+    VALID_MONTH_RANGE = (1..12)
+
+    SYMBOLIC_DAY_VALUES = %i[first last].freeze
+    SYMBOLIC_WEEK_VALUES = %i[odd even].freeze
+
+    WEEKDAYS = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6
+    }.freeze
+
+    MONTHS = {
+      january: 1,
+      february: 2,
+      march: 3,
+      april: 4,
+      may: 5,
+      june: 6,
+      july: 7,
+      august: 8,
+      september: 9,
+      october: 10,
+      november: 11,
+      december: 12
+    }.freeze
+
+    CONDITION_ABBREVIATIONS = {
+      hour: "h",
+      day: "d",
+      weekday: "wd",
+      week: "wk",
+      month: "m"
+    }.freeze
+
+    PERIOD_ABBREVIATIONS = {
+      hour: "h1",
+      day: "d1",
+      week: "w1",
+      month: "m1",
+      year: "y1"
+    }.freeze
+
+    ARRAY_VALUE_CANONICALIZERS = {
+      hour: :canonicalize_hour_array,
+      day: :canonicalize_day_array,
+      weekday: :canonicalize_weekday_array,
+      month: :canonicalize_month_array
+    }.freeze
+  end
+end