docs(quick-260610-i4x): plan/summary/verification + STATE row (node-cron→setInterval, Verified)

2026-06-10 13:09:09 -04:00
parent d9efbc1060
commit 914197f848
4 changed files with 318 additions and 0 deletions
@@ -148,6 +148,7 @@ Recent decisions affecting current work:
 | 260610-cr8 | Adopt drizzle generate+migrate workflow, retire db:push on MariaDB — removed db:push script + repointed deployment.md to migrate with anti-push warning; dry-verified no destructive diff | 2026-06-10 | 1a95d81 | Verified | [260610-cr8-adopt-drizzle-generate-migrate-workflow-](./quick/260610-cr8-adopt-drizzle-generate-migrate-workflow-/) |
 | 260610-czd | Fix docs/deployment.md local-dev command — added "Running locally (host-side, no Docker)" subsection with correct env-sourced two-terminal run command (Phase 2 UAT gap) | 2026-06-10 | 39e2ee0 |  | [260610-czd-fix-docs-deployment-md-local-dev-command](./quick/260610-czd-fix-docs-deployment-md-local-dev-command/) |
 | 260610-hbu | Phase 5 reminder scheduler resilience (UAT Test 1 gap) — catch-up scan `(now, now+16min]` + per-uid exactly-once dedup so a missed/late cron tick no longer drops a reminder; lead-accurate body; also fixes pre-existing cross-tick double-fire. 10/10 reminder tests pass | 2026-06-10 | 19d92c6 | Verified | [260610-hbu-make-phase-5-reminder-scheduler-resilien](./quick/260610-hbu-make-phase-5-reminder-scheduler-resilien/) |
 | 260610-i4x | Replace node-cron with setInterval in all 3 broker workers (poller/outbox/reminder) — node-cron 4.2.1 skipped EVERY scheduled execution in the long-running API process ("missed execution" each tick), so reminders/poll/outbox never fired on schedule. setInterval fires reliably (verified). 91 broker tests pass | 2026-06-10 | d9efbc1 | Verified | [260610-i4x-replace-node-cron-with-setinterval-in-ba](./quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/) |
 ## Deferred Items
@@ -0,0 +1,164 @@
 ---
 phase: quick-260610-i4x
 plan: 01
 type: execute
 wave: 1
 depends_on: []
 files_modified:
  - apps/api/src/broker/poller.ts
  - apps/api/src/broker/outboxWorker.ts
  - apps/api/src/broker/reminderScheduler.ts
 autonomous: true
 requirements:
  - QUICK-i4x
 must_haves:
  truths:
    - "The three background workers schedule their callbacks with setInterval, not node-cron schedule()"
    - "No worker file imports node-cron"
    - "runPoll / runOutboxDrain / runReminderCheck callback bodies are unchanged (still .catch-wrapped)"
    - "Interval timings are preserved: poller 5 min, outbox 15 s, reminder 1 min"
    - "apps/api typechecks clean and the broker unit tests still pass"
  artifacts:
    - path: "apps/api/src/broker/poller.ts"
      provides: "startBrokerPoller scheduling runPoll via setInterval(5min)"
      contains: "setInterval"
    - path: "apps/api/src/broker/outboxWorker.ts"
      provides: "startOutboxWorker scheduling runOutboxDrain via setInterval(15s)"
      contains: "setInterval"
    - path: "apps/api/src/broker/reminderScheduler.ts"
      provides: "startReminderScheduler scheduling runReminderCheck via setInterval(1min)"
      contains: "setInterval"
  key_links:
    - from: "apps/api/src/broker/poller.ts"
      to: "runPoll"
      via: "setInterval(cb, 5 * 60 * 1000)"
      pattern: "setInterval\\("
    - from: "apps/api/src/broker/outboxWorker.ts"
      to: "runOutboxDrain"
      via: "setInterval(cb, 15 * 1000)"
      pattern: "setInterval\\("
    - from: "apps/api/src/broker/reminderScheduler.ts"
      to: "runReminderCheck"
      via: "setInterval(cb, 60 * 1000)"
      pattern: "setInterval\\("
 ---
 <objective>
 Replace the node-cron `schedule()` scheduling mechanism with `setInterval` in the three
 background worker `start*` functions so scheduled tasks actually fire in the long-running
 API process.
 Purpose: node-cron 4.2.1 silently skips scheduled executions in the long-lived server
 process — the orchestrator proved this live against the running prod container (continuous
 `[NODE-CRON][WARN] missed execution` at every tick while CPU sat at 0.15%; a plain
 `setInterval(…,1000)` in the SAME container fired 8/8 ticks, and a FRESH node-cron process
 fired 8/8 — only the long-lived process misbehaves). Net effect: the CalDAV poller, the
 outbox drain, and the reminder scan never fire on schedule. They only ran when triggered
 manually during debugging.
 Output: Three worker files where `startBrokerPoller`, `startOutboxWorker`, and
 `startReminderScheduler` schedule their existing callbacks with `setInterval` at the same
 intervals, with the now-unused `node-cron` import removed and stale doc comments updated.
 </objective>
 <execution_context>
@$HOME/.claude/gsd-core/workflows/execute-plan.md
 </execution_context>
 <context>
@./CLAUDE.md
 # The three worker files — only the start* functions and their doc comments change.
 # Do NOT modify runPoll / runOutboxDrain / runReminderCheck logic.
@apps/api/src/broker/poller.ts
@apps/api/src/broker/outboxWorker.ts
@apps/api/src/broker/reminderScheduler.ts
 </context>
 <tasks>
 <task type="auto">
  <name>Task 1: Swap node-cron schedule() for setInterval in the three worker start* functions</name>
  <files>apps/api/src/broker/poller.ts, apps/api/src/broker/outboxWorker.ts, apps/api/src/broker/reminderScheduler.ts</files>
  <action>
 In each of the three files, replace the node-cron scheduling call inside the start* function
 with a setInterval call, keeping the callback body EXACTLY as written (it already wraps the
 run function in `.catch(...)`). Then remove the now-unused `import { schedule } from 'node-cron'`
 line from each file. Do NOT touch runPoll / runOutboxDrain / runReminderCheck, the constants,
 helpers, or any other code. Do NOT touch index.ts, package.json, or the lockfile — the start*
 function names and signatures are unchanged so index.ts keeps working as-is.
 Exact mapping (interval in ms = the cron cadence; setInterval fires after the first interval,
 same first-run timing as the old cron — do NOT add an immediate kick, that is out of scope):
 - poller.ts `startBrokerPoller`: change `schedule('*/5 * * * *', () => { ... })` to
  `setInterval(() => { ... }, 5 * 60 * 1000)` — keep the same arrow-function callback body
  (the `runPoll().catch(...)` block).
 - outboxWorker.ts `startOutboxWorker`: change `schedule('*/15 * * * * *', () => { ... })` to
  `setInterval(() => { ... }, 15 * 1000)` — keep the same `runOutboxDrain().catch(...)` body.
 - reminderScheduler.ts `startReminderScheduler`: change `schedule('* * * * *', () => { ... })`
  to `setInterval(() => { ... }, 60 * 1000)` — keep the same `runReminderCheck().catch(...)` body.
 Do NOT call `.unref()` on the returned Timer — we WANT the interval to keep the event loop
 alive (same effect as cron kept the process alive). Storing the returned Timer handle in a
 module-level variable is acceptable if cleaner, but not required — fire-and-forget matches the
 current pattern (the workers run for the process lifetime).
 Update the now-stale doc comments that reference node-cron so they describe setInterval, keeping
 the WHY. Specifically:
  - poller.ts: the file-header line "runs every 5 minutes via node-cron", the
    "startBrokerPoller wraps it in node-cron's 5-minute schedule." line, the
    "Source: https://github.com/node-cron/node-cron ..." source line, and the
    "Starts the 5-minute background polling schedule." block.
  - outboxWorker.ts: "startOutboxWorker wraps it in a 15-second node-cron schedule." and the
    "Source: https://github.com/node-cron/node-cron (v4 stable)" line, plus the
    "Starts the 15-second background outbox drain schedule." block.
  - reminderScheduler.ts: the file-header "Fires every minute via node-cron." line and the
    "Start the 1-minute reminder scan schedule." block comment ("keeps the cron out of the test
    process" → setInterval phrasing).
 Each updated comment must briefly state the WHY (node-cron 4.2.1 skipped scheduled executions
 in the long-running server process, so scheduling uses setInterval instead). Keep edits brief —
 do not rewrite the surrounding decision/threat-mitigation prose. Leave the `node-cron` dependency
 in package.json (now unused, harmless); it is removable later but removing it now risks lockfile
 drift and is out of scope for this tight change.
  </action>
  <verify>
    <automated>cd /home/luc/Projects/familysync && ! grep -rn "node-cron" apps/api/src/broker/poller.ts apps/api/src/broker/outboxWorker.ts apps/api/src/broker/reminderScheduler.ts | grep -v '^\s*[0-9]*:.*//' ; grep -c "setInterval" apps/api/src/broker/poller.ts apps/api/src/broker/outboxWorker.ts apps/api/src/broker/reminderScheduler.ts</automated>
    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api typecheck</automated>
    <automated>cd /home/luc/Projects/familysync && pnpm --filter @familysync/api exec vitest run tests/broker/</automated>
  </verify>
  <done>
 All three files import setInterval-based scheduling with no remaining `import { schedule } from 'node-cron'`;
 each start* function calls setInterval at the correct interval (poller 300000 ms, outbox 15000 ms,
 reminder 60000 ms) with its original callback body intact; `pnpm --filter @familysync/api typecheck`
 exits 0; and `pnpm --filter @familysync/api exec vitest run tests/broker/` reports all broker tests
 green (runPoll / runOutboxDrain / runReminderCheck behavior unchanged).
  </done>
 </task>
 </tasks>
 <verification>
 - No `import { schedule } from 'node-cron'` remains in any of the three worker files.
 - `grep setInterval` matches in all three files (one per start* function).
 - runPoll / runOutboxDrain / runReminderCheck logic is byte-for-byte unchanged (only doc
  comments and the scheduling call were touched).
 - `pnpm --filter @familysync/api typecheck` exits 0.
 - `pnpm --filter @familysync/api exec vitest run tests/broker/` passes (crypto, expand, outboxWorker,
  poller, reminderScheduler, sync, vevent, write). Do NOT run the full suite — it has ~68 pre-existing
  DB-integration failures unrelated to this change (MariaDB host port not exposed in prod-compose).
 - index.ts, package.json, and the lockfile are untouched.
 </verification>
 <success_criteria>
 The three background workers schedule their callbacks via setInterval at the original intervals
 (5 min / 15 s / 1 min), node-cron is no longer imported in src/broker, the apps/api typecheck is
 clean, and the broker unit tests still pass — so in the long-running API process the poller, outbox
 drain, and reminder scan will now actually fire on schedule.
 </success_criteria>
 <output>
 Create `.planning/quick/260610-i4x-replace-node-cron-with-setinterval-in-ba/260610-i4x-SUMMARY.md` when done.
 </output>
@@ -0,0 +1,80 @@
 ---
 phase: quick-260610-i4x
 plan: "01"
 subsystem: broker
 tags: [scheduler, setInterval, node-cron, fix]
 dependency_graph:
  requires: []
  provides: [reliable-broker-scheduling]
  affects: [broker/poller, broker/outboxWorker, broker/reminderScheduler]
 tech_stack:
  added: []
  patterns: [setInterval-based-scheduling]
 key_files:
  created: []
  modified:
    - apps/api/src/broker/poller.ts
    - apps/api/src/broker/outboxWorker.ts
    - apps/api/src/broker/reminderScheduler.ts
 decisions:
  - "Use setInterval for broker worker scheduling: node-cron 4.2.1 silently skipped executions in the long-running API process; setInterval is reliable in the same process"
 metrics:
  completed: "2026-06-10"
 ---
 # Quick Task 260610-i4x: Replace node-cron with setInterval in Broker Workers Summary
 **One-liner:** Replaced `node-cron` `schedule()` calls with `setInterval` (300 s / 15 s / 60 s) in all three broker worker `start*` functions so scheduled tasks actually fire in the long-running API process.
 ## Tasks Completed
 | Task | Name | Commit | Files |
 |------|------|--------|-------|
 | 1 | Swap node-cron schedule() for setInterval in the three worker start* functions | d9efbc1 | poller.ts, outboxWorker.ts, reminderScheduler.ts |
 ## Changes Made
 ### apps/api/src/broker/poller.ts
 - Removed `import { schedule } from 'node-cron'`
 - `startBrokerPoller`: `schedule('*/5 * * * *', cb)` → `setInterval(cb, 5 * 60 * 1000)`
 - Updated file-header and JSDoc comments to reference setInterval and document the WHY
 ### apps/api/src/broker/outboxWorker.ts
 - Removed `import { schedule } from 'node-cron'`
 - `startOutboxWorker`: `schedule('*/15 * * * * *', cb)` → `setInterval(cb, 15 * 1000)`
 - Updated header comment and scheduler JSDoc
 ### apps/api/src/broker/reminderScheduler.ts
 - Removed `import { schedule } from 'node-cron'`
 - `startReminderScheduler`: `schedule('* * * * *', cb)` → `setInterval(cb, 60 * 1000)`
 - Updated file-header "Fires every minute" line and scheduler JSDoc
 Callback bodies (the `.catch`-wrapped `runPoll` / `runOutboxDrain` / `runReminderCheck` calls) are byte-for-byte unchanged. No `.unref()` added — intervals intentionally keep the event loop alive.
 ## Verification Results
 - `! grep -rn "import.*node-cron" apps/api/src/broker/`: exits 1 (no matches) — all imports removed
 - `pnpm --filter @familysync/api typecheck`: **exit 0** — clean
 - `pnpm --filter @familysync/api exec vitest run tests/broker/`: **8 test files passed, 91 tests passed**
 ## Deviations from Plan
 None — plan executed exactly as written.
 ## Known Stubs
 None.
 ## Threat Flags
 None — no new network surface, auth paths, file access, or schema changes introduced.
 ## Self-Check: PASSED
 - [x] `apps/api/src/broker/poller.ts` modified — confirmed
 - [x] `apps/api/src/broker/outboxWorker.ts` modified — confirmed
 - [x] `apps/api/src/broker/reminderScheduler.ts` modified — confirmed
 - [x] Commit d9efbc1 exists on branch gsd/v1.0-milestone
 - [x] No `import { schedule } from 'node-cron'` in any of the three files
 - [x] typecheck: exit 0
 - [x] broker tests: 8 files / 91 tests — all green
@@ -0,0 +1,73 @@
 ---
 phase: quick-260610-i4x
 verified: 2026-06-10T17:08:30Z
 status: passed
 score: 5/5 must-haves verified
 ---
 # Quick Task 260610-i4x: Verification Report
 **Task Goal:** Replace node-cron with setInterval in the three background workers (poller, outboxWorker, reminderScheduler) so scheduled tasks fire in the long-running process.
 **Verified:** 2026-06-10T17:08:30Z
 **Status:** passed
 **Re-verification:** No — initial verification
 ## Goal Achievement
 ### Observable Truths
 | # | Truth | Status | Evidence |
 |---|-------|--------|----------|
 | 1 | The three background workers schedule their callbacks with setInterval, not node-cron schedule() | VERIFIED | Each start* function contains `setInterval(()=>{…}, N)` at lines poller.ts:96, outboxWorker.ts:758, reminderScheduler.ts:210. Zero `schedule(` calls remain in any of the three files. |
 | 2 | No worker file imports node-cron | VERIFIED | All remaining `node-cron` text is inside JSDoc block comments (WHY context). `grep -n "import.*node-cron"` returns no matches. Commit d9efbc1 stat confirms only 3 files changed. |
 | 3 | runPoll / runOutboxDrain / runReminderCheck callback bodies are unchanged (still .catch-wrapped) | VERIFIED | poller.ts:97 `runPoll().catch(...)`, outboxWorker.ts:759 `runOutboxDrain().catch(...)`, reminderScheduler.ts:211 `runReminderCheck().catch(...)` — identical catch wrappers present. |
 | 4 | Interval timings are preserved: poller 5 min, outbox 15 s, reminder 1 min | VERIFIED | poller.ts:100 `5 * 60 * 1000` (300000 ms), outboxWorker.ts:762 `15 * 1000` (15000 ms), reminderScheduler.ts:214 `60 * 1000` (60000 ms). |
 | 5 | apps/api typechecks clean and the broker unit tests still pass | VERIFIED | `pnpm --filter @familysync/api typecheck` exited 0 (no output). `pnpm --filter @familysync/api exec vitest run tests/broker/` reported 8 test files passed, 91 tests passed. |
 **Score:** 5/5 truths verified
 ### Required Artifacts
 | Artifact | Expected | Status | Details |
 |----------|----------|--------|---------|
 | `apps/api/src/broker/poller.ts` | startBrokerPoller scheduling runPoll via setInterval(5min) | VERIFIED | setInterval at line 96, `5 * 60 * 1000` at line 100, `runPoll().catch(...)` callback |
 | `apps/api/src/broker/outboxWorker.ts` | startOutboxWorker scheduling runOutboxDrain via setInterval(15s) | VERIFIED | setInterval at line 758, `15 * 1000` at line 762, `runOutboxDrain().catch(...)` callback |
 | `apps/api/src/broker/reminderScheduler.ts` | startReminderScheduler scheduling runReminderCheck via setInterval(1min) | VERIFIED | setInterval at line 210, `60 * 1000` at line 214, `runReminderCheck().catch(...)` callback |
 ### Key Link Verification
 | From | To | Via | Status | Details |
 |------|----|-----|--------|---------|
 | `apps/api/src/broker/poller.ts` | runPoll | `setInterval(cb, 5 * 60 * 1000)` | VERIFIED | Line 96-100 in startBrokerPoller |
 | `apps/api/src/broker/outboxWorker.ts` | runOutboxDrain | `setInterval(cb, 15 * 1000)` | VERIFIED | Line 758-762 in startOutboxWorker |
 | `apps/api/src/broker/reminderScheduler.ts` | runReminderCheck | `setInterval(cb, 60 * 1000)` | VERIFIED | Line 210-214 in startReminderScheduler |
 ### Behavioral Spot-Checks
 | Behavior | Command | Result | Status |
 |----------|---------|--------|--------|
 | TypeScript compiles clean | `pnpm --filter @familysync/api typecheck` | exit 0, no output | PASS |
 | Broker unit tests pass | `pnpm --filter @familysync/api exec vitest run tests/broker/` | 8 files / 91 tests passed | PASS |
 ### Scope Containment
 | Check | Result |
 |-------|--------|
 | Commit d9efbc1 touches only 3 files | VERIFIED — git show stat: outboxWorker.ts, poller.ts, reminderScheduler.ts only |
 | index.ts not modified | VERIFIED — not in commit stat |
 | package.json not modified | VERIFIED — not in commit stat |
 | pnpm-lock.yaml not modified | VERIFIED — not in commit stat |
 | No `.unref()` added | VERIFIED — grep returns no matches in any of the three files |
 ### Anti-Patterns Found
 None. All node-cron mentions are in block comments providing WHY context, not imports or calls.
 ### Human Verification Required
 None.
 ---
 _Verified: 2026-06-10T17:08:30Z_
 _Verifier: Claude (gsd-verifier)_