insika 0.2.0 → 0.7.0

data/lib/insika/context/providers/briefing.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Read path for the session briefing: the per-session
+      # working-state the agent keeps and asks for. Thin adapter over the
+      # SessionStore, same pattern as Memory: one `:system` fragment,
+      # deterministic. The MISSING list is rendered, never implied — that list
+      # is what stops the model re-asking for a field already given.
+      class Briefing < ContextProvider
+        def initialize(session_store:)
+          @session_store = session_store
+        end
+
+        # Stable id -> the context-trace category "briefing".
+        def id = "briefing"
+
+        # Pack-declared: no briefing_fields -> no provider (the Builder still
+        # applies the `context_providers` allowlist on top — two gates, like Memory).
+        def enabled_for?(profile)
+          fields = profile.respond_to?(:briefing_fields) ? profile.briefing_fields : nil
+          !Array(fields).empty?
+        end
+
+        # required? == false (default): a store failure degrades via the Builder's
+        # warning path, never aborts the turn.
+        def call(request)
+          session = request.respond_to?(:session) ? request.session : nil
+          return [] if session.nil? # one-shot turns have no briefing
+
+          briefing = briefing_for(session)
+          fields = briefing["fields"] || {}
+          declared = Array(request.profile.briefing_fields)
+          return [] if declared.empty? # defensive; enabled_for? already gates
+
+          block = format_block(declared, fields, briefing["next_step"])
+          return [] if block.nil?
+
+          [ContextFragment.build(content: block, placement: :system,
+                                 priority: Context::Priority::BRIEFING,
+                                 source: id)]
+        end
+
+        private
+
+        # Re-reads the briefing from the store, like the Session provider: the
+        # persisted record is the source of truth, not the request's turn-start
+        # snapshot. A read failure propagates to the Builder, which degrades it
+        # to a :provider_warning (required? == false).
+        def briefing_for(session)
+          @session_store.find(session.id)&.briefing || {}
+        end
+
+        # Byte contract (the specs assert this shape):
+        #   <briefing>
+        #   known:
+        #     size: M
+        #   still missing: delivery_day
+        #   next step: send the payment link tomorrow at 10
+        #   </briefing>
+        # Rules: `known` renders only when at least one declared field has a
+        # stored value; `still missing` renders every declared field with no
+        # stored value (including the all-missing case — that is the block's
+        # job); `next step` renders only when non-nil; stored keys NOT in the
+        # declaration are never rendered (they stay in the store and reappear if
+        # the pack re-declares them).
+        def format_block(declared, fields, next_step)
+          known = declared.filter_map do |name|
+            "  #{name}: #{flatten(fields[name])}" if Coercion.present?(fields[name])
+          end
+          missing = declared.reject { |name| Coercion.present?(fields[name]) }
+
+          lines = []
+          lines << "known:" unless known.empty?
+          lines.concat(known)
+          lines << "still missing: #{missing.join(', ')}" unless missing.empty?
+          lines << "next step: #{flatten(next_step)}" if Coercion.present?(next_step)
+          return nil if lines.empty?
+
+          <<~BLOCK.strip
+            <briefing>
+            #{lines.join("\n")}
+            </briefing>
+          BLOCK
+        end
+
+        # utf8 the value and flatten newlines/whitespace so a value can never
+        # break the block's line structure.
+        def flatten(value)
+          Coercion.utf8(value.to_s).gsub(/\s+/, " ").strip
+        end
+      end
+    end
+  end
+end

data/lib/insika/context/providers/knowledge.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level 1 (progressive disclosure) of what the engine has LEARNED, as
+      # opposed to what a human curated (Skill) or the model wrote mid-turn
+      # (Memory). Retrieval is per-message and dynamic, so — like
+      # `SkillTrigger`, unlike the static `CatalogProvider` subclasses — this
+      # builds its `<knowledge>` block directly in `call`, never a fixed list.
+      class Knowledge < ContextProvider
+        def initialize(store:)
+          @store = store
+          # One Index PER TYPE, built once and reused for every agent/turn —
+          # never per call. This provider instance itself lives for the
+          # process's lifetime (built once at boot, see wiring), so an
+          # Index rebuilt fresh each call would throw away its own read
+          # cache (Index::Scan's dominant cost is re-parsing YAML
+          # frontmatter; measured, not assumed) on every single turn.
+          # Keyed by the config's `index` string so a future FTS5 agent
+          # gets its own instance, never Scan's.
+          @indexes = Hash.new { |h, index_name| h[index_name] = Insika::Knowledge::Index.build({ "index" => index_name }, store: @store) }
+        end
+
+        # Per-agent opt-in (`knowledge.retrieve`), like Memory's `profile.memory`.
+        def enabled_for?(profile) = !!(profile.knowledge && Coercion.truthy?(profile.knowledge["retrieve"]))
+
+        # required? == false (default): a store failure degrades to a
+        # :provider_warning, never aborts the turn.
+        def call(request)
+          config = request.profile.knowledge
+          return [] unless config
+
+          top_k = positive_int(config["top_k"]) || 5
+          index = @indexes[config["index"].to_s]
+          matches = index.search(request.profile.id, tenant: request.tenant,
+                                 query: request.message.to_s, top_k: top_k)
+          return [] if matches.empty?
+
+          hits = matches.map { |c| [c, "top-K match"] } +
+                 expand_links(matches, request, top_k).map { |c| [c, "one-hop link"] }
+
+          [ContextFragment.build(
+            content: format_block(hits), placement: :system,
+            priority: Context::Priority::KNOWLEDGE, source: id,
+            labels: hits.map { |c, reason| { "name" => c[:name], "reason" => reason } }
+          )]
+        end
+
+        private
+
+        def positive_int(value)
+          n = value.to_i
+          n.positive? ? n : nil
+        end
+
+        # ONE level, deliberately — the same "cannot work without" reasoning
+        # `SkillTrigger#companions` applies to a skill's declared companions:
+        # a transitive walk would make a cycle a hang and a chain a budget
+        # blowout. Newly-discovered concepts (not already in the top-K) are
+        # capped at top_k again — "that one hop is the whole graph benefit at
+        # ~1% of the graph cost", not a second unbounded retrieval.
+        def expand_links(matches, request, top_k)
+          known = matches.map { |c| c[:name] }
+          discovered = []
+          matches.each do |concept|
+            Insika::Knowledge::Concept.links(concept[:body]).each do |name|
+              next if known.include?(name) || discovered.any? { |d| d[:name] == name }
+
+              found = fetch(request, name)
+              discovered << found if found
+            end
+          end
+          discovered.first(top_k)
+        end
+
+        def fetch(request, name)
+          raw = @store.get(request.profile.id, name, tenant: request.tenant)
+          raw && Insika::Knowledge::Concept.parse(raw)
+        end
+
+        # Level 1 only — name/description/confidence/provenance, never the
+        # body (that is `load_knowledge`'s job). The instruction is the exact
+        # lesson the knowledge-adoption experiment drew: a polite "when to
+        # use" scored near zero; an explicit, ordered rule naming the tool
+        # held up. Present only when there is something to point at.
+        def format_block(hits)
+          entries = hits.map do |c, _reason|
+            %(  <concept name="#{c[:name]}" confidence="#{format('%.2f', c[:confidence])}" ) +
+              %(provenance="#{c[:provenance]}">#{c[:description]}</concept>)
+          end.join("\n")
+
+          <<~BLOCK.strip
+            <knowledge>
+            #{entries}
+            </knowledge>
+
+            If the customer's question needs more than the summary above, call
+            `load_knowledge("name")` FIRST — before any other lookup for that
+            topic. This is learned from past conversations, not official
+            policy: never state a `provenance="observed"` concept to the
+            customer as a guarantee.
+          BLOCK
+        end
+      end
+    end
+  end
+end

data/lib/insika/context/providers/memory.rb

@@ -20,7 +20,7 @@ module Insika
         # required? == false (default): a failure (store unavailable) becomes a
         # :provider_warning + graceful degradation — never aborts the turn.
         def call(request)
-          tenant = memory_tenant(request)
+          tenant = memory_scope(request)
           facts = @store.facts(tenant: tenant)
           notes = @store.notes(tenant: tenant, limit: @notes_limit)
           return [] if facts.empty? && notes.empty?
@@ -33,15 +33,24 @@ module Insika
 
         private
 
-        # Engine memory scope: an EXPLICIT tenant from the Command wins
-        # (multi-merchant override); otherwise the SESSION (=chat) — engine-owner
-        # memory is per-chat. No session (one-shot) and no tenant -> nil (MemoryStore
-        # applies _default). Symmetric to the write path (`state.tenant` in the Executor).
-        def memory_tenant(request)
+        # Engine memory scope (WS8): the request's CUSTOMER-scoped cell
+        # ("[tenant:]customer" — engine-owner memory is per customer, never per
+        # tenant) wins; otherwise an EXPLICIT tenant from the Command (the
+        # multi-merchant override); otherwise the SESSION (=chat), MARKED like
+        # the write path ("chat:<session id>" —  : a session cell is
+        # never a bare cell, so the drill cannot read a conversation as a
+        # customer). No session (one-shot) and no tenant -> nil (MemoryStore
+        # applies _default). Symmetric to the write path (`state.tenant` in the
+        # Executor).
+        def memory_scope(request)
+          scoped = request.respond_to?(:memory_scope) ? request.memory_scope : nil
+          return scoped if scoped
+
           explicit = request.respond_to?(:tenant) ? request.tenant : nil
           return explicit if explicit
 
-          request.respond_to?(:session) ? request.session&.id : nil
+          session = request.respond_to?(:session) ? request.session : nil
+          session && session.id ? "#{Insika::MemoryStore::SESSION_TAG}:#{session.id}" : nil
         end
 
         # Passive <memory> (no instruction — the HOW of writing lives in the `remember` tool).

data/lib/insika/context/providers/prompt.rb

@@ -8,30 +8,58 @@ module Insika
       # a WRONG agent, not a degraded one. prompt_refs: priority 90 pinned
       # fragments, from the PromptCatalog (catalog defaults to nil).
       #
-      # PER-AGENT identity. `profile.prompt_files` (file names)
-      # wins over the wiring's `files:` — this fixes the limitation of a new
-      # agent inheriting Bia's prompt. The content comes from `agent_files`
-      # (AgentFileStore, lives in the Store), with a File.read fallback
-      # for on-disk paths (compat/seed). Without prompt_files -> uses the wiring's
-      # `files:` (deployment default; byte-for-byte parity).
+      # PER-AGENT identity, from `profile.prompt_files`/`base_prompt` only — an
+      # agent that declares neither has no identity here, and there is no
+      # deployment-wide fallback file to borrow one from. A shared fallback
+      # (a prior design: an agent without prompt_files silently inherited a
+      # wiring-level default) is exactly how a real deployment answered as the
+      # WRONG business: a `copilot` data agent provisioned without its own
+      # identity inherited the deployment's demo persona ("Bia, Pizzaria do
+      # Zé") byte for byte, confirmed live. An agent never wears another
+      # agent's identity — `@base`/`system_files` stay legitimate (the same
+      # generic content for every agent, never one agent's specific persona).
       class Prompt < ContextProvider
-        def initialize(base: "", files: [], catalog: nil, agent_files: nil, system_files: nil)
+        # Engine-owned execution discipline, appended AFTER the agent's identity.
+        # The one behavior every reference harness bakes into its base prompt
+        # (OpenClaw's "Execution Bias") and this engine was missing: a weak tool
+        # result read as final. A constant — byte-identical every turn, so
+        # prompt_caching pays ONE write on the deploy that introduces it, never
+        # per turn. Opt-out per profile (`tool_persistence false`), the single
+        # default-ON profile flag: the proven-good behavior is the default, the
+        # exception is the thing an operator declares.
+        TOOL_PERSISTENCE = "## Tool discipline\n" \
+          "- Weak or empty tool result: try again with a different approach — rephrase the " \
+          "query, use a synonym or broader term, drop a secondary filter — before telling " \
+          "the user you found nothing. Do not narrate the retries. Then conclude.\n" \
+          "- Tool error: read the error, fix the arguments or try another path; never " \
+          "repeat the exact same call.\n" \
+          "- A URL in a tool result (e.g. a `url` field): quote it byte-for-byte. Never " \
+          "construct, guess, or rewrite the domain, host, or path."
+
+        def initialize(base: "", catalog: nil, agent_files: nil, system_files: nil)
           @base = base
-          @files = Array(files)
           @catalog = catalog
           @agent_files = agent_files
           @system_files = system_files
         end
 
         def required? = true
+        # identity (config/agent-file derived — already pinned).
+        def layer = :identity
 
         def call(request)
-          fragments = []
           identity = build_identity(request.profile)
-          unless identity.empty?
-            fragments << ContextFragment.build(content: identity, placement: :system,
-                                               priority: Context::Priority::IDENTITY, source: id, pinned: true)
+          if identity.empty?
+            raise ContextError.new(
+              "agent '#{request.profile&.id}' has no identity of its own (no base_prompt, " \
+              "no prompt_files) — refusing to run rather than answer with no identity or " \
+              "another agent's",
+              provider: id
+            )
           end
+
+          fragments = [ContextFragment.build(content: identity, placement: :system,
+                                             priority: Context::Priority::IDENTITY, source: id, pinned: true)]
           fragments.concat(ref_fragments(request.profile))
           fragments
         end
@@ -42,10 +70,9 @@ module Insika
         # A SINGLE fragment preserves the internal base->files order (sorting
         # acts only BETWEEN fragments) and guarantees byte-for-byte parity.
         #
-        # profile.prompt_files (names) wins over @files (wiring): an agent with
-        # its own identity does not inherit the deployment's. Each source resolves
-        # via AgentFileStore (per agent) OR File.read (on-disk path) — in that
-        # order. Without prompt_files, falls back to the wiring's @files.
+        # profile.prompt_files: each source resolves via AgentFileStore (per
+        # agent) OR File.read (on-disk path) — in that order. No other agent's
+        # files are ever read for this one; there is no wiring-level fallback.
         def build_identity(profile)
           parts = [@base]
           parts.concat(system_parts) # global system files, for EVERY agent
@@ -56,13 +83,20 @@ module Insika
           # NO identity at all, and a chatty model answered plausibly enough to hide
           # it. Additive to prompt_files, not exclusive: an agent may carry both.
           parts << profile&.base_prompt.to_s
-          sources = Array(profile&.prompt_files)
-          if sources.empty?
-            @files.each { |f| parts << File.read(f, encoding: "UTF-8") if File.exist?(f) }
-          else
-            sources.each { |src| parts << read_source(profile&.id, src.to_s) }
-          end
-          parts.reject { |p| p.nil? || p.strip.empty? }.join("\n\n")
+          Array(profile&.prompt_files).each { |src| parts << read_source(profile&.id, src.to_s) }
+          identity = parts.reject { |p| p.nil? || p.strip.empty? }.join("\n\n")
+          # Discipline rides an EXISTING identity, never substitutes one: an
+          # empty identity here is fatal (`call` raises), not silently patched
+          # with the engine's own boilerplate.
+          return identity if identity.empty? || !tool_persistence?(profile)
+
+          "#{identity}\n\n#{TOOL_PERSISTENCE}"
+        end
+
+        # nil/absent/true = ON (the engine default); only an explicit `false`
+        # turns it off. Defensive respond_to?: a minimal profile stub reads ON.
+        def tool_persistence?(profile)
+          !(profile.respond_to?(:tool_persistence) && profile.tool_persistence == false)
         end
 
         # GLOBAL system files: apply to every agent,

data/lib/insika/context/providers/skill.rb

@@ -10,6 +10,8 @@ module Insika
       class Skill < CatalogProvider
         # priority 80: above deferred tools (70), below pinned identity.
         def priority = Context::Priority::SKILL
+        # catalog + allowlist — config only.
+        def layer = :identity
 
         private
 

data/lib/insika/context/providers/tool_search.rb

@@ -10,6 +10,8 @@ module Insika
       class ToolSearch < CatalogProvider
         # priority 70: below skills (80) in the sacrifice order.
         def priority = Context::Priority::TOOL_SEARCH
+        # tool registry + tools_deferred — config only.
+        def layer = :identity
 
         private
 

data/lib/insika/context_trace_store.rb

@@ -24,7 +24,8 @@ module Insika
     # suspends (approval) and resumes re-runs the context stage, and the
     # re-record replaces the first one instead of duplicating it. (`turn` is
     # 1-based PER TASK, so the task is part of the key.) Missing session_id ->
-    # no-op.
+    # no-op. -> the sanitized entry (parks it on TurnState for the
+    # stage-8 cache merge).
     def record(session_id:, entry:)
       sid = session_id.to_s
       return if sid.empty?
@@ -33,6 +34,7 @@ module Insika
       key = [e["task_id"], e["turn"]]
       list = (@store.get(SCOPE, sid) || []).reject { |x| [x["task_id"], x["turn"]] == key } + [e]
       @store.set(SCOPE, sid, list.last(MAX_PER_SESSION))
+      e
     rescue StandardError
       nil
     end
@@ -63,6 +65,11 @@ module Insika
           cat = { "tokens" => int(c[:tokens] || c["tokens"]),
                   "fragments" => int(c[:fragments] || c["fragments"]),
                   "pinned" => int(c[:pinned] || c["pinned"]) }
+          # which cache layer the category belongs to ("identity" |
+          # "volatile"). Absent for a category recorded before the contract (or
+          # one that never learned it) — the view guards on nil.
+          layer = c[:layer] || c["layer"]
+          cat["layer"] = layer.to_s if layer
           # WHAT the category carried and WHY ({name, reason}) — still ids only, so
           # the no-masking-needed contract above holds. Omitted when empty: most
           # categories have nothing to name and an empty key is just noise.
@@ -71,8 +78,36 @@ module Insika
           acc[name.to_s] = cat
         end,
         "tools" => { "count" => int(tools[:count] || tools["count"]),
-                     "tokens" => int(tools[:tokens] || tools["tokens"]) }
+                     "tokens" => int(tools[:tokens] || tools["tokens"]) },
+        "fingerprints" => fingerprints_of(e[:fingerprints] || e["fingerprints"]),
+        "cache" => cache_of(e[:cache] || e["cache"])
+      }.compact
+    end
+
+    # { name => sha256-hex }; names stringified, non-strings
+    # dropped. Absent when the caller passed nothing (a trace recorded before
+    # this feature has no key and the view guards on nil).
+    def fingerprints_of(raw)
+      return nil unless raw.is_a?(Hash) && !raw.empty?
+
+      raw.each_with_object({}) do |(name, hex), acc|
+        acc[name.to_s] = hex.to_s if hex.is_a?(String)
+      end.then { |h| h.empty? ? nil : h }
+    end
+
+    # { hit_pct, cached_tokens, prompt_tokens, invalidation_reason }.
+    # Unknown keys dropped. Present only when the caller passed it.
+    def cache_of(raw)
+      return nil unless raw.is_a?(Hash)
+
+      c = {
+        "hit_pct" => int_or_nil(raw[:hit_pct] || raw["hit_pct"]),
+        "cached_tokens" => int(raw[:cached_tokens] || raw["cached_tokens"]),
+        "prompt_tokens" => int(raw[:prompt_tokens] || raw["prompt_tokens"]),
+        "invalidation_reason" => raw[:invalidation_reason] || raw["invalidation_reason"]
       }
+      c["invalidation_reason"] = c["invalidation_reason"].to_s unless c["invalidation_reason"].nil?
+      c
     end
 
     # Labels are {name, reason} in string keys (ContextFragment.label). A bare string
@@ -88,5 +123,6 @@ module Insika
     end
 
     def int(value) = Integer(value || 0)
+    def int_or_nil(value) = value.nil? ? nil : Integer(value)
   end
 end

data/lib/insika/cron.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Insika
+  # A cron expression, parsed. The engine's documented subset:
+  #
+  #   minute hour day-of-month month day-of-week     (5 fields, whitespace-separated)
+  #
+  # Per field: `*`, a single value, a range (N-M), a step (`*/N`, `N-M/N`,
+  # `N/N`), or a comma list of those. `?` and `*` both mean "any". `L`, `W`,
+  # `#` and month/day NAMES are NOT — the engine refuses them loudly at
+  # creation, never silently dropping a cron that only some dates understand.
+  #
+  # Day-of-week: 0-7, 7 == 0 (Sunday). When BOTH day fields are restricted, a
+  # date matches on EITHER (standard cron OR semantics).
+  #
+  # `next_after(time)` returns the first occurrence STRICTLY after `time`,
+  # materialized in the schedule's tz (returned as a UTC Time), or nil when
+  # the expression can never fire within 400 years (`0 0 31 2 *`). The bound
+  # keeps a syntactic-but-unreachable expression from hanging a pass.
+  class Cron
+    MONTHS_31 = [1, 3, 5, 7, 8, 10, 12].freeze
+
+    # One field: the sorted accepted values + whether it was a bare "*"
+    # (the day-of-week OR rule needs to know which fields are restricted).
+    class Field
+      def initialize(expression, range, field:)
+        @field = field
+        @range = range
+        @star = expression == "*"
+        @values = expression.split(",").flat_map { |term| parse_term(term) }.uniq.sort
+      end
+
+      def star? = @star
+
+      def matches?(value) = @values.include?(value)
+
+      # -> Integer | nil: the smallest accepted value >= start (nil when none).
+      def at_or_after(start) = @values.find { |v| v >= start }
+
+      private
+
+      def parse_term(term)
+        head, step = term.include?("/") ? term.split("/", 2) : [term, nil]
+        step = parse_step(step) if step
+        base = parse_base(head)
+        base = base.each_with_index.filter_map { |v, i| v if (i % step).zero? } if step
+        base.each { |v| validate(v) }
+      end
+
+      def parse_step(raw)
+        n = Integer(raw)
+        raise Insika::ValidationError, "cron #{@field} step must be a positive integer, got #{raw.inspect}" unless n.positive?
+
+        n
+      rescue ArgumentError
+        raise Insika::ValidationError,
+              "cron #{@field} step must be a positive integer, got #{raw.inspect}"
+      end
+
+      def parse_base(head)
+        if head.empty? || head == "?" || head == "*"
+          @range.to_a
+        elsif head.include?("-")
+          lo, hi = head.split("-", 2).map { |s| value(s) }
+          raise Insika::ValidationError, "cron #{@field} range reversed: #{head.inspect}" if lo > hi
+
+          (lo..hi).to_a
+        else
+          [value(head)]
+        end
+      end
+
+      def value(raw)
+        v = Integer(raw)
+        v = 0 if @field == :dow && v == 7 # Sunday, the standard second spelling
+        v
+      rescue ArgumentError
+        raise Insika::ValidationError,
+              "cron #{@field} has an unparseable value: #{raw.inspect}"
+      end
+
+      def validate(v)
+        return if @range.cover?(v)
+
+        raise Insika::ValidationError,
+              "cron #{@field} value #{v} out of range (#{@range.inspect})"
+      end
+    end
+
+    attr_reader :expression
+
+    def initialize(expression)
+      @expression = expression.to_s.strip
+      fields = @expression.split(/\s+/)
+      if fields.size != 5
+        raise Insika::ValidationError,
+              "cron expression must have 5 fields (minute hour dom month dow), " \
+              "got #{fields.size}: #{@expression.inspect}"
+      end
+
+      minute, hour, dom, month, dow = fields
+      @minute = Field.new(minute, 0..59, field: :minute)
+      @hour = Field.new(hour, 0..23, field: :hour)
+      @dom = Field.new(dom, 1..31, field: :dom)
+      @month = Field.new(month, 1..12, field: :month)
+      @dow = Field.new(dow, 0..6, field: :dow)
+      freeze
+    end
+
+    # -> Time (UTC) | nil: the first instant strictly after `time` whose
+    # wall-clock in `tz` matches. nil = the expression cannot fire within 400y.
+    def next_after(time, tz: "Etc/UTC")
+      Timezone.in_zone(tz, time) do
+        local = time.getlocal
+        cur = Cursor.new(local.year, local.month, local.day, local.hour, local.min)
+        advance_minute!(cur) # strictly after `time`
+        limit = cur.y + 400
+        while cur.y <= limit
+          if @month.matches?(cur.mo) && day_match?(cur)
+            if @hour.matches?(cur.h) && (mm = @minute.at_or_after(cur.mi))
+              return Time.local(cur.y, cur.mo, cur.d, cur.h, mm)
+            end
+
+            nh = @hour.at_or_after(cur.h + 1)
+            if nh && (mm = @minute.at_or_after(0))
+              return Time.local(cur.y, cur.mo, cur.d, nh, mm)
+            end
+          end
+          advance_day!(cur)
+          cur.h = 0
+          cur.mi = 0
+        end
+        nil
+      end
+    end
+
+    private
+
+    # A date matches when a restricted day-of-month OR day-of-week accepts it
+    # (standard cron); a bare "*" on one side drops that side.
+    def day_match?(cur)
+      dom = @dom.matches?(cur.d)
+      dow = @dow.matches?(Time.utc(cur.y, cur.mo, cur.d).wday)
+      if @dom.star? && @dow.star?
+        true
+      elsif @dom.star?
+        dow
+      elsif @dow.star?
+        dom
+      else
+        dom || dow
+      end
+    end
+
+    Cursor = Struct.new(:y, :mo, :d, :h, :mi)
+
+    def advance_minute!(cur)
+      cur.mi += 1
+      if cur.mi > 59
+        cur.mi = 0
+        cur.h += 1
+        advance_day!(cur) if cur.h > 23
+      end
+    end
+
+    def advance_day!(cur)
+      cur.d += 1
+      return if cur.d <= days_in_month(cur.y, cur.mo)
+
+      cur.d = 1
+      cur.mo += 1
+      if cur.mo > 12
+        cur.mo = 1
+        cur.y += 1
+      end
+    end
+
+    def days_in_month(y, mo)
+      return 29 if mo == 2 && leap?(y)
+      return 28 if mo == 2
+
+      MONTHS_31.include?(mo) ? 31 : 30
+    end
+
+    def leap?(y)
+      y % 4 == 0 && (y % 100 != 0 || y % 400 == 0)
+    end
+  end
+end