jw-automator 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to jw-automator will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2025-11-18
+
+### Added
+
+- **`seed()` Method**: New bootstrapping method that runs initialization logic only when the database is empty
+  - Solves the "Bootstrapping Problem" by safely initializing actions without resetting schedules on restart
+  - Returns `true` if seeding ran, `false` if skipped
+  - Automatically saves state after seeding
+  - Perfect for system tasks that should be added once but preserved forever
+
+- **`catchUpWindow` Property**: Time-based validity window for missed executions (replaces binary buffered/unBuffered)
+  - `catchUpWindow: "unlimited"` - Catch up ALL missed executions (like old `unBuffered: false`)
+  - `catchUpWindow: 0` - Skip ALL missed executions (like old `unBuffered: true`)
+  - `catchUpWindow: 5000` - Hybrid: tolerate 5s lag, skip if offline for hours
+  - Solves the "Thundering Herd Problem" by preventing thousands of queued executions after long downtime
+  - Fast-forward optimization uses mathematical projection to instantly advance high-frequency tasks
+  - Uses `"unlimited"` string literal instead of `Infinity` for clean JSON serialization
+
+- **Defensive Validation**: "Fail loudly, run defensively" philosophy
+  - Invalid `repeat.type` → defaults to `'day'` with ERROR event
+  - Invalid `repeat.interval` → coerced to `Math.max(1, Math.floor(value))` with ERROR event
+  - Invalid `repeat.limit` → defaults to `null` (unlimited) with ERROR event
+  - Invalid `repeat.endDate` → ignored with ERROR event
+  - Invalid `catchUpWindow` → defaults to `"unlimited"` with ERROR event
+  - Negative `catchUpWindow` → coerced to `0` with ERROR event
+  - Missing `date` → defaults to 5 seconds from now with DEBUG event
+  - Unregistered commands → emit DEBUG event, keep trying (never remove action)
+
+### Changed
+
+- **Backwards Compatibility**: `unBuffered` property is now a maintained alias that maps to `catchUpWindow`
+  - `unBuffered: true` → `catchUpWindow: 0`
+  - `unBuffered: false` → `catchUpWindow: "unlimited"`
+  - `catchUpWindow: Infinity` → automatically coerced to `"unlimited"` with DEBUG event
+  - Both properties supported indefinitely with zero breaking changes
+  - `catchUpWindow` takes precedence if both are specified
+
+### Improved
+
+- Clean JSON serialization: `"unlimited"` is a string, no special JSON handling required
+- Enhanced action validation with comprehensive error/debug event emissions
+- All invalid values coerced to sensible defaults - system keeps running
+- Updated action loading to normalize `catchUpWindow` for backwards compatibility
+- Comprehensive test coverage for both new features and defensive validation
+- Updated examples to demonstrate `seed()` and `catchUpWindow` usage
+- Updated documentation with detailed usage patterns and migration guidance
+
 ## [3.0.0] - 2025-11-17
 
 ### Added (v3 Complete Rewrite)

package/README.md

@@ -58,20 +58,22 @@ automator.addFunction('turnLightOn', function(payload) {
   console.log('Turning light on');
 });
 
-// Add an action
-automator.addAction({
-  name: 'Morning Lights',
-  cmd: 'turnLightOn',
-  date: new Date('2025-05-01T07:00:00'),
-  payload: null,
-  unBuffered: false,
-  repeat: {
-    type: 'day',
-    interval: 1,
-    limit: null,
-    endDate: null,
-    dstPolicy: 'once'
-  }
+// Seed initial actions (runs only on first use)
+automator.seed((auto) => {
+  auto.addAction({
+    name: 'Morning Lights',
+    cmd: 'turnLightOn',
+    date: new Date('2025-05-01T07:00:00'),
+    payload: null,
+    catchUpWindow: 60000, // Tolerate 1 minute of lag
+    repeat: {
+      type: 'day',
+      interval: 1,
+      limit: null,
+      endDate: null,
+      dstPolicy: 'once'
+    }
+  });
 });
 
 // Start the scheduler
@@ -137,25 +139,35 @@ This avoids cron's silent-but-surprising behaviors.
 
 ---
 
-### 4. **Resilient Offline Catch-Up**
+### 4. **Resilient Offline Catch-Up with Time Windows**
 
-If the device is offline or delayed (e.g., blocked by CPU load):
+When the device is offline or delayed, you can control exactly how far back to catch up using the `catchUpWindow` property:
 
 ```js
-unBuffered: false   // default: catch up missed executions
-unBuffered: true    // skip missed executions
+catchUpWindow: "unlimited"  // Catch up ALL missed executions (default)
+catchUpWindow: 0            // Skip ALL missed executions (real-time only)
+catchUpWindow: 5000         // Catch up if missed by ≤5 seconds, skip if older
 ```
 
-For example:
+**How it works:**
+
+* If an action is missed by less than `catchUpWindow` milliseconds, it executes (recovers from brief glitches)
+* If missed by more than `catchUpWindow`, it's skipped and fast-forwarded (prevents thundering herd)
+* The fast-forward optimization uses mathematical projection to instantly advance high-frequency tasks
+
+**Example scenarios:**
 
-* A job scheduled at 09:00 will still run when the device restarts at 10:00 (if buffered).
-* A sequence of per-second readings will "compress" naturally after a delay.
+* **Billing tasks:** `catchUpWindow: "unlimited"` - Never miss a charge
+* **Real-time alerts:** `catchUpWindow: 0` - Only relevant "now"
+* **Sensor readings:** `catchUpWindow: 5000` - Tolerate 5s lag, skip if system was down for hours
 
-This feature is ideal for:
+**Backwards compatibility:**
 
-* Home automation logic ("turn heater off at 9 even if offline")
-* Sensor sampling
-* Data collection pipelines
+The legacy `unBuffered` property is still fully supported:
+```js
+unBuffered: false   // equivalent to catchUpWindow: "unlimited"
+unBuffered: true    // equivalent to catchUpWindow: 0
+```
 
 ---
 
@@ -213,6 +225,30 @@ Options:
 
 ### Methods
 
+#### `seed(callback)`
+Seed the automator with initial actions. Runs only when the database is empty (first use).
+
+**Returns:** `boolean` - `true` if seeding ran, `false` if skipped
+
+```js
+automator.seed((auto) => {
+  auto.addAction({
+    name: 'Daily Report',
+    cmd: 'generateReport',
+    date: new Date('2025-01-01T09:00:00'),
+    catchUpWindow: "unlimited",
+    repeat: { type: 'day', interval: 1 }
+  });
+});
+```
+
+**Why use seed()?**
+
+* Solves the bootstrapping problem: safely initialize actions without resetting the schedule on every restart
+* Preserves user-modified schedules perfectly
+* Runs initialization logic only once in the application lifecycle
+* Automatically saves state after seeding
+
 #### `start()`
 Start the scheduler.
 
@@ -257,6 +293,15 @@ automator.updateActionByID(1, {
 });
 ```
 
+#### `updateActionByName(name, updates)`
+Update all actions with the given name. Returns the number of actions updated.
+
+```js
+automator.updateActionByName('My Action', {
+  payload: { newData: 'newValue' }
+});
+```
+
 #### `removeActionByID(id)`
 Remove an action by ID.
 
@@ -404,14 +449,15 @@ npm run test:coverage
 
 ### Top-level action fields:
 
-| Field        | Description                                       |
-| ------------ | ------------------------------------------------- |
-| `id`         | Unique internal identifier (auto-generated)       |
-| `name`       | User label (optional)                             |
-| `cmd`        | Name of registered function to execute            |
-| `payload`    | Data passed to the command                        |
-| `date`       | Next scheduled run time (local `Date`)            |
-| `unBuffered` | Skip missed events (`true`) or catch up (`false`) |
+| Field           | Description                                                           |
+| --------------- | --------------------------------------------------------------------- |
+| `id`            | Unique internal identifier (auto-generated)                          |
+| `name`          | User label (optional)                                                |
+| `cmd`           | Name of registered function to execute                               |
+| `payload`       | Data passed to the command                                           |
+| `date`          | Next scheduled run time (local `Date`)                               |
+| `catchUpWindow` | Time window for catching up missed executions (default: `"unlimited"`, or milliseconds number) |
+| `unBuffered`    | Legacy: Skip missed events (`true`) or catch up (`false`)           |
 
 ### Repeat block:
 

package/docs/ARCHITECTURE.md

@@ -156,7 +156,7 @@ setTimeout(() => tick(), wait);
 - Event emission
 
 **Key APIs**:
-- Action management: `addAction`, `updateActionByID`, `removeActionByID`, etc.
+- Action management: `addAction`, `updateActionByID`, `updateActionByName`, `removeActionByID`, etc.
 - Function registration: `addFunction`, `removeFunction`
 - Introspection: `getActions`, `describeAction`, `getActionsInRange`
 - Lifecycle: `start`, `stop`

package/docs/MIGRATION.md

@@ -136,6 +136,10 @@ automator.updateActionByID(id, {
   name: 'New Name',
   repeat: { type: 'hour', interval: 2 }
 });
+
+automator.updateActionByName('Old Name', {
+  name: 'New Name'
+});
 ```
 
 ---

package/docs/QUICKSTART.md

@@ -269,10 +269,16 @@ const id = automator.addAction({
 ### Update
 
 ```javascript
+// By ID
 automator.updateActionByID(id, {
   name: 'Updated Task',
   repeat: { type: 'hour', interval: 2 }
 });
+
+// By name
+automator.updateActionByName('My Task', {
+  payload: { updated: true }
+});
 ```
 
 ### Remove

package/examples/basic-example.js

@@ -50,51 +50,54 @@ automator.on('error', (event) => {
   console.error('Error:', event.message);
 });
 
-// Add actions
-
-// 1. Every 10 seconds - demo message
-automator.addAction({
-  name: 'Demo Message',
-  cmd: 'logMessage',
-  date: new Date(Date.now() + 5000), // Start in 5 seconds
-  payload: { message: 'This is a recurring message every 10 seconds' },
-  unBuffered: false,
-  repeat: {
-    type: 'second',
-    interval: 10,
-    limit: 6, // Run 6 times then stop
-    dstPolicy: 'once'
-  }
-});
-
-// 2. Daily morning routine at 7:00 AM
-automator.addAction({
-  name: 'Morning Routine',
-  cmd: 'morningRoutine',
-  date: new Date(new Date().setHours(7, 0, 0, 0)),
-  unBuffered: false,
-  repeat: {
-    type: 'day',
-    interval: 1,
-    dstPolicy: 'once'
-  }
-});
-
-// 3. Weekly backup every Sunday at 2:00 AM
-const nextSunday = new Date();
-nextSunday.setDate(nextSunday.getDate() + (7 - nextSunday.getDay()) % 7);
-nextSunday.setHours(2, 0, 0, 0);
-
-automator.addAction({
-  name: 'Weekly Backup',
-  cmd: 'weeklyBackup',
-  date: nextSunday,
-  unBuffered: false,
-  repeat: {
-    type: 'week',
-    interval: 1,
-    dstPolicy: 'once'
-  }
+// Seed initial actions (runs only on first use)
+automator.seed((auto) => {
+  console.log('Seeding initial actions...\n');
+
+  // 1. Every 10 seconds - demo message
+  auto.addAction({
+    name: 'Demo Message',
+    cmd: 'logMessage',
+    date: new Date(Date.now() + 5000), // Start in 5 seconds
+    payload: { message: 'This is a recurring message every 10 seconds' },
+    catchUpWindow: 30000, // Tolerate 30 seconds of lag
+    repeat: {
+      type: 'second',
+      interval: 10,
+      limit: 6, // Run 6 times then stop
+      dstPolicy: 'once'
+    }
+  });
+
+  // 2. Daily morning routine at 7:00 AM
+  auto.addAction({
+    name: 'Morning Routine',
+    cmd: 'morningRoutine',
+    date: new Date(new Date().setHours(7, 0, 0, 0)),
+    catchUpWindow: "unlimited", // Never miss a morning routine
+    repeat: {
+      type: 'day',
+      interval: 1,
+      dstPolicy: 'once'
+    }
+  });
+
+  // 3. Weekly backup every Sunday at 2:00 AM
+  const nextSunday = new Date();
+  nextSunday.setDate(nextSunday.getDate() + (7 - nextSunday.getDay()) % 7);
+  nextSunday.setHours(2, 0, 0, 0);
+
+  auto.addAction({
+    name: 'Weekly Backup',
+    cmd: 'weeklyBackup',
+    date: nextSunday,
+    catchUpWindow: "unlimited", // Always run backups, even if delayed
+    repeat: {
+      type: 'week',
+      interval: 1,
+      dstPolicy: 'once'
+    }
+  });
 });
 
 // Demonstrate simulation - what will happen in the next 24 hours?

package/examples/seed-example.js

@@ -0,0 +1,147 @@
+/**
+ * Seed Example - jw-automator v3
+ *
+ * Demonstrates the seed() method and catchUpWindow property.
+ * This example shows how to bootstrap a persistent scheduler that:
+ * - Initializes actions only on first run
+ * - Preserves user-modified schedules on subsequent runs
+ * - Uses catchUpWindow for smart catch-up behavior
+ */
+
+const Automator = require('../index');
+const fs = require('fs');
+
+// Storage file path
+const STORAGE_FILE = './seed-example-actions.json';
+
+// Clean up old storage file for demo purposes
+if (fs.existsSync(STORAGE_FILE)) {
+  console.log('Note: Removing existing storage file for clean demo');
+  fs.unlinkSync(STORAGE_FILE);
+}
+
+// Create automator with file-based persistence
+const automator = new Automator({
+  storage: Automator.storage.file(STORAGE_FILE),
+  autoSave: true,
+  saveInterval: 3000
+});
+
+// Register command functions
+automator.addFunction('criticalTask', function(payload, event) {
+  console.log(`[CRITICAL] ${payload.message}`);
+  console.log(`  Scheduled: ${event.scheduledTime.toLocaleTimeString()}`);
+  console.log(`  Executed: ${event.actualTime.toLocaleTimeString()}`);
+  console.log(`  Execution #${event.count + 1}`);
+});
+
+automator.addFunction('realtimeAlert', function(payload, event) {
+  console.log(`[REALTIME] ${payload.message}`);
+  console.log(`  Only executes if "now" - skips if missed`);
+});
+
+automator.addFunction('flexibleTask', function(payload, event) {
+  const lag = event.actualTime - event.scheduledTime;
+  console.log(`[FLEXIBLE] ${payload.message}`);
+  console.log(`  Lag: ${lag}ms (tolerates up to 5 seconds)`);
+});
+
+// Listen to events
+automator.on('ready', () => {
+  console.log('\n=== Automator Ready ===');
+  console.log(`Actions loaded: ${automator.getActions().length}`);
+});
+
+// SEED: Initialize actions (runs only on first use)
+const didSeed = automator.seed((auto) => {
+  console.log('\n=== SEEDING: First Run Detected ===');
+  console.log('Creating initial system tasks...\n');
+
+  // Task 1: Critical billing task - NEVER miss an execution
+  auto.addAction({
+    name: 'Billing Task',
+    cmd: 'criticalTask',
+    date: new Date(Date.now() + 2000),
+    payload: { message: 'Process billing (catchUpWindow: "unlimited")' },
+    catchUpWindow: "unlimited", // Catch up ALL missed executions
+    repeat: {
+      type: 'second',
+      interval: 10,
+      limit: 3
+    }
+  });
+
+  // Task 2: Real-time alert - only relevant "now"
+  auto.addAction({
+    name: 'Realtime Alert',
+    cmd: 'realtimeAlert',
+    date: new Date(Date.now() + 5000),
+    payload: { message: 'Temperature spike detected!' },
+    catchUpWindow: 0, // Skip ALL missed executions
+    repeat: {
+      type: 'second',
+      interval: 15,
+      limit: 3
+    }
+  });
+
+  // Task 3: Flexible sensor reading - tolerate brief lag
+  auto.addAction({
+    name: 'Sensor Reading',
+    cmd: 'flexibleTask',
+    date: new Date(Date.now() + 8000),
+    payload: { message: 'Read temperature sensor' },
+    catchUpWindow: 5000, // Tolerate up to 5 seconds of lag
+    repeat: {
+      type: 'second',
+      interval: 12,
+      limit: 3
+    }
+  });
+
+  console.log('✅ Initial tasks created!\n');
+});
+
+if (didSeed) {
+  console.log('✨ Seeding completed - tasks initialized for the first time');
+} else {
+  console.log('⏭️  Seeding skipped - existing schedule preserved');
+}
+
+console.log('\n=== Current Schedule ===');
+automator.getActions().forEach((action) => {
+  console.log(`\n${action.name}:`);
+  console.log(`  catchUpWindow: ${action.catchUpWindow === "unlimited" ? '"unlimited"' : action.catchUpWindow + 'ms'}`);
+  console.log(`  Next run: ${action.date.toLocaleTimeString()}`);
+  console.log(`  Executions so far: ${action.count}`);
+});
+
+console.log('\n=== Starting Scheduler ===\n');
+automator.start();
+
+// Simulate a brief delay after 15 seconds to demonstrate catch-up behavior
+setTimeout(() => {
+  console.log('\n⏸️  Simulating 3-second system pause...\n');
+  const start = Date.now();
+  while (Date.now() - start < 3000) {
+    // Block the event loop
+  }
+  console.log('▶️  Resumed! Watch how different catchUpWindow values behave:\n');
+}, 15000);
+
+// Auto-stop after 40 seconds
+setTimeout(() => {
+  console.log('\n=== Shutting Down ===');
+  automator.stop();
+  console.log('\n💡 Tip: Run this example again to see seeding skipped!');
+  console.log(`Storage file: ${STORAGE_FILE}`);
+  console.log('Goodbye!\n');
+  process.exit(0);
+}, 40000);
+
+// Graceful shutdown on Ctrl+C
+process.on('SIGINT', () => {
+  console.log('\n\nShutting down...');
+  automator.stop();
+  process.exit(0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jw-automator",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "A resilient, local-time, 1-second precision automation scheduler for Node.js",
   "main": "index.js",
   "files": [

package/src/Automator.js

@@ -35,6 +35,33 @@ class Automator {
     this._loadState();
   }
 
+  /**
+   * Seed the automator with initial actions (runs only on first use)
+   *
+   * @param {Function} callback - Function to execute when database is empty
+   * @returns {boolean} - True if seeding ran, false if skipped
+   */
+  seed(callback) {
+    if (typeof callback !== 'function') {
+      throw new Error('seed() requires a callback function');
+    }
+
+    const state = this.host.getState();
+
+    // Check if already populated
+    if (state.actions && state.actions.length > 0) {
+      return false;
+    }
+
+    // Execute seeding callback
+    callback(this);
+
+    // Immediately save the seeded state
+    this._saveState();
+
+    return true;
+  }
+
   /**
    * Start the automator
    */
@@ -83,17 +110,33 @@ class Automator {
    * Add an action
    */
   addAction(actionSpec) {
-    // Validate action
+    // Validate action (includes defensive coercion)
     this._validateAction(actionSpec);
 
+    // Normalize catchUpWindow (handles backwards compatibility with unBuffered)
+    const catchUpWindow = this._normalizeCatchUpWindow(actionSpec);
+
+    // Defensive: Default missing date to 5 seconds from now
+    let startDate;
+    if (!actionSpec.date) {
+      startDate = new Date(Date.now() + 5000);
+      this._emit('debug', {
+        type: 'debug',
+        message: 'No date provided - defaulting to 5 seconds from now'
+      });
+    } else {
+      startDate = new Date(actionSpec.date);
+    }
+
     // Create action with state
     const action = {
       id: this.nextId++,
       name: actionSpec.name || null,
       cmd: actionSpec.cmd,
       payload: actionSpec.payload !== undefined ? actionSpec.payload : null,
-      date: actionSpec.date ? new Date(actionSpec.date) : new Date(),
-      unBuffered: actionSpec.unBuffered || false,
+      date: startDate,
+      unBuffered: actionSpec.unBuffered !== undefined ? actionSpec.unBuffered : false,
+      catchUpWindow: catchUpWindow,
       repeat: actionSpec.repeat ? { ...actionSpec.repeat } : null,
       count: 0
     };
@@ -130,7 +173,7 @@ class Automator {
     }
 
     // Update allowed fields
-    const allowedUpdates = ['name', 'cmd', 'payload', 'date', 'unBuffered', 'repeat', 'count'];
+    const allowedUpdates = ['name', 'cmd', 'payload', 'date', 'unBuffered', 'catchUpWindow', 'repeat', 'count'];
 
     for (const key of allowedUpdates) {
       if (key in updates) {
@@ -147,6 +190,14 @@ class Automator {
       }
     }
 
+    // Re-normalize catchUpWindow if unBuffered or catchUpWindow was updated
+    if ('unBuffered' in updates || 'catchUpWindow' in updates) {
+      action.catchUpWindow = this._normalizeCatchUpWindow({
+        catchUpWindow: action.catchUpWindow,
+        unBuffered: action.unBuffered
+      });
+    }
+
     this._emit('update', {
       type: 'update',
       operation: 'update',
@@ -159,6 +210,61 @@ class Automator {
     }
   }
 
+  /**
+   * Update actions by name
+   */
+  updateActionByName(name, updates) {
+    const state = this.host.getState();
+    const toUpdate = state.actions.filter(a => a.name === name);
+
+    if (toUpdate.length === 0) {
+      // For consistency with removeActionByName, we could throw an error.
+      // However, it might be more convenient to simply return 0.
+      // Let's return 0 for now.
+      return 0;
+    }
+
+    const allowedUpdates = ['cmd', 'payload', 'date', 'unBuffered', 'catchUpWindow', 'repeat', 'count'];
+
+    for (const action of toUpdate) {
+      for (const key of allowedUpdates) {
+        if (key in updates) {
+          if (key === 'date' && updates[key]) {
+            action[key] = new Date(updates[key]);
+          } else if (key === 'repeat' && updates[key]) {
+            action[key] = { ...action.repeat, ...updates[key] };
+            if (!action[key].dstPolicy) {
+              action[key].dstPolicy = 'once';
+            }
+          } else {
+            action[key] = updates[key];
+          }
+        }
+      }
+
+      // Re-normalize catchUpWindow if unBuffered or catchUpWindow was updated
+      if ('unBuffered' in updates || 'catchUpWindow' in updates) {
+        action.catchUpWindow = this._normalizeCatchUpWindow({
+          catchUpWindow: action.catchUpWindow,
+          unBuffered: action.unBuffered
+        });
+      }
+
+      this._emit('update', {
+        type: 'update',
+        operation: 'update',
+        actionId: action.id,
+        action: { ...action }
+      });
+    }
+
+    if (this.options.autoSave) {
+      this._saveState();
+    }
+
+    return toUpdate.length;
+  }
+
   /**
    * Remove action by ID
    */
@@ -216,12 +322,31 @@ class Automator {
     return toRemove.length;
   }
 
+  /**
+   * Deep clone an action
+   */
+  _cloneAction(action) {
+    const cloned = { ...action };
+
+    // Deep copy nested objects
+    if (action.repeat) {
+      cloned.repeat = { ...action.repeat };
+    }
+
+    // Clone Date objects properly
+    if (action.date) {
+      cloned.date = new Date(action.date);
+    }
+
+    return cloned;
+  }
+
   /**
    * Get all actions (deep copy)
    */
   getActions() {
     const state = this.host.getState();
-    return JSON.parse(JSON.stringify(state.actions));
+    return state.actions.map(a => this._cloneAction(a));
   }
 
   /**
@@ -231,7 +356,7 @@ class Automator {
     const state = this.host.getState();
     return state.actions
       .filter(a => a.name === name)
-      .map(a => JSON.parse(JSON.stringify(a)));
+      .map(a => this._cloneAction(a));
   }
 
   /**
@@ -240,7 +365,7 @@ class Automator {
   getActionByID(id) {
     const state = this.host.getState();
     const action = state.actions.find(a => a.id === id);
-    return action ? JSON.parse(JSON.stringify(action)) : null;
+    return action ? this._cloneAction(action) : null;
   }
 
   /**
@@ -346,13 +471,21 @@ class Automator {
   _loadState() {
     try {
       const state = this.options.storage.load();
-      this.host.setState(state);
 
-      // Update nextId to be higher than any existing ID
+      // Normalize catchUpWindow for existing actions (for backwards compatibility)
       if (state.actions && state.actions.length > 0) {
+        state.actions = state.actions.map(action => ({
+          ...action,
+          catchUpWindow: action.catchUpWindow !== undefined
+            ? action.catchUpWindow
+            : this._normalizeCatchUpWindow(action)
+        }));
+
         const maxId = Math.max(...state.actions.map(a => a.id || 0));
         this.nextId = maxId + 1;
       }
+
+      this.host.setState(state);
     } catch (error) {
       this._emit('error', {
         type: 'error',
@@ -392,7 +525,45 @@ class Automator {
   }
 
   /**
-   * Validate action specification
+   * Normalize catchUpWindow property (handles backwards compatibility with unBuffered)
+   *
+   * Priority:
+   * 1. catchUpWindow specified → normalize it (coerce Infinity to "unlimited" if needed)
+   * 2. unBuffered specified → convert to catchUpWindow equivalent
+   * 3. Neither specified → default to "unlimited" (catch up everything)
+   *
+   * @param {Object} spec - Action specification
+   * @returns {string|number} - Normalized catchUpWindow value ("unlimited" or milliseconds)
+   */
+  _normalizeCatchUpWindow(spec) {
+    // New property takes precedence
+    if (spec.catchUpWindow !== undefined) {
+      // Coerce Infinity to "unlimited" (backwards compatibility)
+      if (spec.catchUpWindow === Infinity) {
+        this._emit('debug', {
+          type: 'debug',
+          message: 'Coercing catchUpWindow: Infinity → "unlimited"'
+        });
+        return "unlimited";
+      }
+      return spec.catchUpWindow;
+    }
+
+    // Backwards compatibility mapping
+    if (spec.unBuffered !== undefined) {
+      return spec.unBuffered ? 0 : "unlimited";
+    }
+
+    // Default: catch up everything (current buffered behavior)
+    return "unlimited";
+  }
+
+  /**
+   * Validate and normalize action specification
+   * Philosophy: "Fail loudly, run defensively"
+   * - Emit ERROR events for serious issues but coerce to reasonable defaults
+   * - Emit DEBUG events for auto-corrections
+   * - Never silently fail
    */
   _validateAction(action) {
     if (!action.cmd) {
@@ -401,16 +572,91 @@ class Automator {
 
     if (action.repeat) {
       const validTypes = ['second', 'minute', 'hour', 'day', 'weekday', 'weekend', 'week', 'month', 'year'];
-      if (!validTypes.includes(action.repeat.type)) {
-        throw new Error(`Invalid repeat type: ${action.repeat.type}`);
+
+      // Defensive: Coerce invalid repeat.type to 'day' with ERROR event
+      if (!action.repeat.type || !validTypes.includes(action.repeat.type)) {
+        this._emit('error', {
+          type: 'error',
+          message: `Invalid repeat.type "${action.repeat.type}" - defaulting to "day"`,
+          actionSpec: action
+        });
+        action.repeat.type = 'day';
       }
 
-      if (action.repeat.interval !== undefined && action.repeat.interval < 1) {
-        throw new Error('Repeat interval must be >= 1');
+      // Defensive: Coerce invalid interval to Math.max(1, Math.floor(value))
+      if (action.repeat.interval !== undefined) {
+        const original = action.repeat.interval;
+        const coerced = Math.max(1, Math.floor(original));
+        if (original !== coerced) {
+          this._emit('error', {
+            type: 'error',
+            message: `Invalid repeat.interval ${original} - coerced to ${coerced}`,
+            actionSpec: action
+          });
+          action.repeat.interval = coerced;
+        }
       }
 
+      // Defensive: Validate dstPolicy
       if (action.repeat.dstPolicy && !['once', 'twice'].includes(action.repeat.dstPolicy)) {
-        throw new Error('DST policy must be "once" or "twice"');
+        this._emit('error', {
+          type: 'error',
+          message: `Invalid dstPolicy "${action.repeat.dstPolicy}" - defaulting to "once"`,
+          actionSpec: action
+        });
+        action.repeat.dstPolicy = 'once';
+      }
+
+      // Defensive: Coerce invalid repeat.limit to null (unlimited) with ERROR event
+      if (action.repeat.limit !== undefined && action.repeat.limit !== null) {
+        if (typeof action.repeat.limit !== 'number' || action.repeat.limit < 1) {
+          this._emit('error', {
+            type: 'error',
+            message: `Invalid repeat.limit ${action.repeat.limit} - defaulting to null (unlimited)`,
+            actionSpec: action
+          });
+          action.repeat.limit = null;
+        }
+      }
+
+      // Defensive: Validate repeat.endDate
+      if (action.repeat.endDate !== undefined && action.repeat.endDate !== null) {
+        try {
+          new Date(action.repeat.endDate);
+        } catch (e) {
+          this._emit('error', {
+            type: 'error',
+            message: `Invalid repeat.endDate - ignoring`,
+            actionSpec: action
+          });
+          action.repeat.endDate = null;
+        }
+      }
+    }
+
+    // Defensive: Validate catchUpWindow if provided
+    if (action.catchUpWindow !== undefined) {
+      const isValidString = action.catchUpWindow === "unlimited";
+      const isNumber = typeof action.catchUpWindow === 'number';
+      const isInfinity = action.catchUpWindow === Infinity; // Allow for backwards compatibility
+
+      // Coerce negative numbers to 0 FIRST
+      if (isNumber && action.catchUpWindow < 0) {
+        this._emit('error', {
+          type: 'error',
+          message: `Negative catchUpWindow ${action.catchUpWindow} - coerced to 0`,
+          actionSpec: action
+        });
+        action.catchUpWindow = 0;
+      }
+      // Then validate it's a valid value
+      else if (!isValidString && !isNumber && !isInfinity) {
+        this._emit('error', {
+          type: 'error',
+          message: `Invalid catchUpWindow "${action.catchUpWindow}" - defaulting to "unlimited"`,
+          actionSpec: action
+        });
+        action.catchUpWindow = "unlimited";
       }
     }
   }

package/src/core/CoreEngine.js

@@ -52,14 +52,47 @@ class CoreEngine {
       let iterationCount = 0;
       let currentNextRun = nextRun;
 
+      // Get catchUpWindow (defaults to "unlimited" for backwards compatibility)
+      const catchUpWindow = action.catchUpWindow !== undefined ? action.catchUpWindow : "unlimited";
+
+      // Fast-forward optimization: if we're far outside the catch-up window,
+      // jump directly to near the current time using mathematical projection
+      if (catchUpWindow !== "unlimited" && action.repeat) {
+        const lag = now.getTime() - currentNextRun.getTime();
+
+        if (lag > catchUpWindow * 2) {
+          // We're deep in the "Dead Zone" - use fast-forward
+          const fastForwardResult = this._fastForwardAction(action, now, catchUpWindow);
+
+          if (fastForwardResult) {
+            currentNextRun = fastForwardResult.nextRun;
+            action.date = currentNextRun;
+            action.count = fastForwardResult.count;
+
+            // After fast-forward, if still outside window, just advance without executing
+            if (currentNextRun <= now) {
+              const finalLag = now.getTime() - currentNextRun.getTime();
+              if (finalLag > catchUpWindow) {
+                // Still outside window after fast-forward, skip to next viable occurrence
+                this._advanceAction(action);
+                currentNextRun = action.date ? new Date(action.date) : null;
+              }
+            }
+          }
+        }
+      }
+
       while (currentNextRun <= now && iterationCount < maxIterations) {
         iterationCount++;
 
-        // Determine if we should execute this occurrence
-        // UnBuffered: only execute if this is the actual current tick (not catching up)
-        // Buffered: execute all missed occurrences
+        const lag = now.getTime() - currentNextRun.getTime();
+
+        // Determine if we should execute this occurrence based on catchUpWindow
         const isInCurrentTick = currentNextRun > lastTick && currentNextRun <= now;
-        const shouldExecute = action.unBuffered ? isInCurrentTick : true;
+        const isWithinWindow = catchUpWindow === "unlimited" || lag <= catchUpWindow;
+
+        // Legacy unBuffered behavior (maps to catchUpWindow: 0 or Infinity)
+        const shouldExecute = isWithinWindow;
 
         if (shouldExecute) {
           const event = this._executeAction(action, currentNextRun);
@@ -168,6 +201,77 @@ class CoreEngine {
     }
   }
 
+  /**
+   * Fast-forward an action to near the current time using mathematical projection
+   * This avoids iterating through thousands/millions of occurrences for high-frequency tasks
+   *
+   * @param {Object} action - The action to fast-forward
+   * @param {Date} now - Current time
+   * @param {number} catchUpWindow - The catch-up window in milliseconds
+   * @returns {Object|null} - { nextRun, count } or null if not applicable
+   */
+  static _fastForwardAction(action, now, catchUpWindow) {
+    if (!action.repeat || !action.date) {
+      return null;
+    }
+
+    const { type, interval = 1 } = action.repeat;
+    const currentTime = new Date(action.date);
+    const lag = now.getTime() - currentTime.getTime();
+
+    // Only applicable for simple time-based recurrence (not weekday/weekend)
+    let stepMilliseconds = 0;
+
+    switch (type) {
+      case 'second':
+        stepMilliseconds = interval * 1000;
+        break;
+      case 'minute':
+        stepMilliseconds = interval * 60 * 1000;
+        break;
+      case 'hour':
+        stepMilliseconds = interval * 60 * 60 * 1000;
+        break;
+      case 'day':
+        stepMilliseconds = interval * 24 * 60 * 60 * 1000;
+        break;
+      case 'week':
+        stepMilliseconds = interval * 7 * 24 * 60 * 60 * 1000;
+        break;
+      default:
+        // Complex recurrence (weekday, weekend, month, year) - can't fast-forward easily
+        return null;
+    }
+
+    if (stepMilliseconds === 0) {
+      return null;
+    }
+
+    // Calculate how many steps we can skip
+    // We want to jump to just before the catch-up window starts
+    const targetLag = catchUpWindow;
+    const timeToSkip = lag - targetLag;
+
+    if (timeToSkip <= 0) {
+      return null;
+    }
+
+    const stepsToSkip = Math.floor(timeToSkip / stepMilliseconds);
+
+    if (stepsToSkip <= 0) {
+      return null;
+    }
+
+    // Project forward
+    const newTime = new Date(currentTime.getTime() + (stepsToSkip * stepMilliseconds));
+    const newCount = (action.count || 0) + stepsToSkip;
+
+    return {
+      nextRun: newTime,
+      count: newCount
+    };
+  }
+
   /**
    * Simulate actions in a time range without mutating state
    */