From bc982536f1a2272806effc930251527c9281f792 Mon Sep 17 00:00:00 2001 From: Ruben Carlo Benante Date: Wed, 8 Jul 2026 19:24:42 -0300 Subject: [PATCH] v1.4 backfill-to-today algorithm, 12-card cap, idempotent spawns; drop dual-path --- Model/RecoRecoModel.php | 134 ++++++++++++++++++++++++++-------------- Plugin.php | 2 +- README.md | 21 +++++-- VERSION | 2 +- 4 files changed, 106 insertions(+), 53 deletions(-) diff --git a/Model/RecoRecoModel.php b/Model/RecoRecoModel.php index 257a073..8e81639 100644 --- a/Model/RecoRecoModel.php +++ b/Model/RecoRecoModel.php @@ -8,15 +8,34 @@ use Kanboard\Model\TaskModel; /** * The RecoReco engine: find enabled templates and spawn their due occurrences. * - * Called by the recoreco:run CLI command. v0.3 handles monthly-by-day and fires everything whose - * fire time has arrived (fire time = occurrence - days_before); v1.0 adds the 4-window cron horizon. + * Called by the recoreco:run CLI command (from cron, or from the identical "Run now" button). One + * run is one pass over every enabled template; running it five times a day instead of four is + * harmless -- see the idempotency note below. * - * Per template: the native-recurrence yield (decision 13), first-run init / manual-edit re-anchor, - * then a catch-up loop that duplicates the card into the target column and advances the cursor. + * Per template there is a SINGLE algorithm (no first-run vs catch-up split): + * + * 1. Yield to native recurrence if the card became native-recurring (decision 13). + * 2. Walk occurrences forward from the cursor (the template due date), collecting every one whose + * fire time (occurrence - days_before) has arrived (before this run's horizon). The first + * occurrence still ahead of the horizon is the "next future" one. + * 3. Cap to the most recent MAX_BACKFILL: if more than that are due (a template set far in the + * past), skip the OLDEST overflow and keep the newest ones -- contiguous, no gap. + * 4. Spawn each kept occurrence into the target column, dated to that occurrence. + * 5. Park the cursor on the next future occurrence and stop. + * + * Idempotency: after a run the cursor sits on a future occurrence, so a second run the same day + * collects nothing. As a belt-and-suspenders guard against a run overlapping cron on the same + * occurrence, spawn() is skipped when a clone for that (template, due) already exists (cloneExists). */ class RecoRecoModel extends Base { - const CATCHUP_CAP = 24; + // Most recent occurrences to actually spawn in one run. A template set far in the past spawns + // these newest ones and skips the older overflow (no gap), rather than flooding the board. + const MAX_BACKFILL = 12; + + // Safety bound on the occurrence walk so a misbehaving calculator can never loop forever + // (1200 monthly steps is a century). + const MAX_ITERATIONS = 1200; private $calc; @@ -43,7 +62,7 @@ class RecoRecoModel extends Base * "ceil now to the next 6h boundary, then +12h", which lands on the four daily runs: * 05:58 -> 18:00, 11:58 -> 00:00, 17:58 -> 06:00, 23:58 -> 12:00. Gives a 12h look-ahead with a * 6h overlap between runs, so a missed run is covered by its neighbour. Past-due occurrences are - * naturally included (their fire time is < now < horizon) -- that is the catch-up. + * naturally included (their fire time is < now < horizon) -- that is the back-fill. * * @param int $now * @return int @@ -79,6 +98,8 @@ class RecoRecoModel extends Base return 0; } + // The anchor defines the recurrence PATTERN (which day-of-month, which weekday ordinal); the + // cursor (the template due date) is our POSITION in that pattern. $anchor = isset($meta['recoreco_anchor']) ? (int) $meta['recoreco_anchor'] : 0; if ($anchor <= 0) { @@ -91,46 +112,83 @@ class RecoRecoModel extends Base // Default off: only keep the duplicate link when explicitly turned on. $linkCopies = isset($meta['recoreco_link_copies']) && $meta['recoreco_link_copies'] == 1; + // Phase 1 -- walk forward from the cursor, collecting every occurrence whose fire time has + // arrived. The loop exits on the first occurrence still ahead of the horizon, which is then + // the "next future" one to park on. $cursor = (int) $task['date_due']; - $synced = isset($meta['recoreco_synced_due']) ? (int) $meta['recoreco_synced_due'] : null; + $due = array(); + $iterations = 0; - if ($synced === null) { - // First run after enabling: place the cursor on the first occurrence. - $cursor = $this->firstCursor($anchor, $frequency, $lastDay, $now); - $this->setDue($task_id, $cursor); - } elseif ($cursor !== $synced) { - // The user hand-edited the due date -> re-anchor to it (a reschedule). - $anchor = $cursor; - $this->taskMetadataModel->save($task_id, array('recoreco_anchor' => $anchor)); - $this->setDue($task_id, $cursor); - } - - // Fire every occurrence whose fire time is before this run's horizon (this includes - // past-due ones -> catch-up), advancing the cursor each time. - $spawned = 0; - $fireTime = $cursor - $daysBefore * 86400; - - while ($fireTime < $horizon && $spawned < self::CATCHUP_CAP) { - $this->spawn($task, $targetColumn); + while ($cursor - $daysBefore * 86400 < $horizon && $iterations < self::MAX_ITERATIONS) { + $due[] = $cursor; $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false); if ($next === null || $next <= $cursor) { - break; + break; // calculator cannot advance -- stop rather than loop } $cursor = $next; - $this->setDue($task_id, $cursor); - $fireTime = $cursor - $daysBefore * 86400; + $iterations++; + } + + $nextFuture = $cursor; + + // Phase 2 -- cap to the most recent MAX_BACKFILL, skipping the oldest overflow (no gap). + $skip = max(0, count($due) - self::MAX_BACKFILL); + $toSpawn = array_slice($due, $skip); + + // Phase 3 -- spawn each kept occurrence, dated to that occurrence. Idempotent: skip any that + // this template has already spawned (survives a run overlapping cron on the same occurrence). + $spawned = 0; + + foreach ($toSpawn as $occurrence) { + if ($this->cloneExists($task_id, $occurrence)) { + continue; + } + + // duplicate() copies the template's date_due onto the clone, so set it to this occurrence + // first, then spawn. + $this->setDue($task_id, $occurrence); + $this->spawn($task, $targetColumn); $spawned++; } + // Phase 4 -- park the cursor on the next future occurrence and stop. + $this->setDue($task_id, $nextFuture); + // Reconcile the duplicate links with the setting (removes both new and old ones when off). $this->syncCloneLinks($task_id, $linkCopies); return $spawned; } + /** + * Has this template already spawned a clone for the given occurrence? A clone records its source + * template (recoreco_source) and carries the occurrence as its due date, so the pair identifies + * it. This makes a repeated or overlapping run idempotent -- an occurrence is never spawned twice. + * + * @param int $template_id + * @param int $due + * @return bool + */ + private function cloneExists($template_id, $due) + { + $clone_ids = $this->db->table('task_has_metadata') + ->eq('name', 'recoreco_source') + ->eq('value', (string) $template_id) + ->findAllByColumn('task_id'); + + if (empty($clone_ids)) { + return false; + } + + return $this->db->table(TaskModel::TABLE) + ->in('id', $clone_ids) + ->eq('date_due', $due) + ->exists(); + } + /** * Reconcile a template's "is a duplicate of" links with the link-copies setting. When off, remove * the links to THIS template's own RecoReco clones (identified by recoreco_source, so manual @@ -154,24 +212,10 @@ class RecoRecoModel extends Base } } - /** - * The first occurrence: respect an explicitly future anchor (the due date the user set) as the - * first one; otherwise jump to the next occurrence on/after now. - */ - private function firstCursor($anchor, $frequency, $lastDay, $now) + private function setDue($task_id, $due) { - if ($anchor >= $now) { - return $anchor; - } - - return $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $now, true); - } - - private function setDue($task_id, $cursor) - { - // Advance the template's due date directly (no task events) + mirror it for edit detection. - $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $cursor)); - $this->taskMetadataModel->save($task_id, array('recoreco_synced_due' => $cursor)); + // Move the template's due date directly (no task events fired). This is the cursor. + $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $due)); } private function spawn(array $template, $targetColumn) diff --git a/Plugin.php b/Plugin.php index 2c585af..119ec60 100644 --- a/Plugin.php +++ b/Plugin.php @@ -55,7 +55,7 @@ class Plugin extends Base public function getPluginVersion() { - return '1.3.0'; + return '1.4.0'; } public function getPluginHomepage() diff --git a/README.md b/README.md index ecd3e19..cef3e5c 100644 --- a/README.md +++ b/README.md @@ -31,15 +31,24 @@ The engine runs from the CLI command `recoreco:run`. Add it to cron **four times ``` (Point the path at your install and run it as the user that owns Kanboard's data.) Each run looks -ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one, and -any occurrence whose time is already past is still caught up. `days before` shifts a copy earlier -within that lead. You can also run it by hand any time: `php cli recoreco:run`. +ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one. + +Each run walks a template forward from its current due date and spawns **every** occurrence whose +fire time has arrived -- so occurrences already in the past are backfilled, not skipped. To avoid +flooding the board when a template was set far in the past, a single run spawns at most the **12 +most recent** due occurrences; any older overflow is skipped (contiguous, no gap) and the template +advances straight to the next future occurrence. `days before` shifts a copy earlier within the +lead. Runs are idempotent: an occurrence is never spawned twice, so running an extra time is safe. + +You can trigger the exact same pass by hand -- either on the CLI (`php cli recoreco:run`) or with +the **Run now** button under **Settings -> RecoReco** (admin only). The button and cron do the +identical thing. ## Status -Working for **monthly by day** (with the last-day rule), driven by cron. The remaining frequencies -(yearly, weekly, daily, monthly by weekday), the recurrence icons, and the FinanceBuddy -installment hand-off arrive in the following versions. +All five frequencies work (yearly, monthly by day, monthly by weekday, weekly, daily) with the +last-day rule, board recurrence icons, backfill with the 12-occurrence cap, the Run-now button, and +the FinanceBuddy installment hand-off. ## Requirements diff --git a/VERSION b/VERSION index 93a562d..12ab6d5 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -RecoReco v1.3 +RecoReco v1.4