jw-automator 3.1.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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).
 
+## [4.0.0] - 2025-11-19
+
+### Breaking Changes
+
+-   **Smart Default `catchUpWindow` Behavior**: The default behavior for `catchUpWindow` has fundamentally changed. Instead of defaulting to `"unlimited"`, it now defaults based on action type:
+    -   For recurring actions, it defaults to the recurrence interval duration.
+    -   For one-time actions, it defaults to `0` (no catch-up).
+    -   **Impact:** Users relying on the previous `"unlimited"` default for actions where `catchUpWindow` was not explicitly set will experience different behavior.
+-   **Invalid `repeat.type` is now a Fatal Error**: Providing a missing or invalid `repeat.type` (e.g., a typo) will now throw a hard `Error` immediately when the action is added or updated.
+    -   **Impact:** Previously, this would be defensively coerced to `'day'` with an `error` event. Code relying on this coercion will now crash.
+-   **Coercion Events changed from `error` to `warning`**: All defensive coercions (e.g., invalid `repeat.interval`, negative `catchUpWindow`, invalid `repeat.limit`) now emit a `warning` event instead of an `error` event.
+    -   **Impact:** Users listening for `automator.on('error', ...)` to catch these specific coercion notifications will need to update their code to listen for `automator.on('warning', ...)` instead.
+
+### Added
+
+-   **`warning` Event Type**: A new event type, `warning`, has been introduced for non-fatal data coercions and corrections during action validation.
+-   **Smart `catchUpWindow` Defaults**: Actions now automatically infer a sensible `catchUpWindow` default based on whether they are one-time (default `0`) or recurring (default to recurrence interval duration).
+
+### Changed
+
+-   The "Defensive Validation" strategy has been refined to distinguish between fatal configuration errors and non-fatal coercions, using `Error` throws for the former and `warning` events for the latter.
+
+## [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 (Initial Implementation)**: Implemented "Fail loudly, run defensively" philosophy with various coercions and `error` events for invalid inputs. This initial strategy was further refined in v4.0.0, which introduced a dedicated `warning` event and stricter validation for `repeat.type`.
+
+### 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

@@ -1,4 +1,4 @@
-# 📚 **jw-automator v3**
+# 📚 **jw-automator v4**
 
 ### A resilient, local-time, 1-second precision automation scheduler for Node.js
 
@@ -8,7 +8,7 @@
 
 ## ⭐️ Overview
 
-**jw-automator** is a robust automation engine designed for small devices, home automation hubs, personal servers, and Node.js environments where **correctness, resilience, and local-time behavior** matter more than millisecond precision.
+**jw-automator** is a robust automation engine designed for small devices, home automation hubs, personal servers, and Node.js environments where **correctness, resilience, and local-time behavior** matter more than millisecond precision. Version 4 introduces enhanced defensive defaults and clearer error handling, making it even more predictable and robust.
 
 Where traditional cron falls short — missed executions, poor DST handling, limited recurrence, lack of catch-up semantics — **jw-automator** provides a predictable, human-centric scheduling model:
 
@@ -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,37 @@ This avoids cron's silent-but-surprising behaviors.
 
 ---
 
-### 4. **Resilient Offline Catch-Up**
+### 4. **Resilient Offline Catch-Up with Smart Defaults**
 
-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. Automator v4 introduces **smart defaults** that infer the desired behavior based on your action's type, making the system more robust and predictable out-of-the-box.
 
-```js
-unBuffered: false   // default: catch up missed executions
-unBuffered: true    // skip missed executions
-```
+**`catchUpWindow` Behavior:**
+
+*   **Explicitly Set (milliseconds or `"unlimited"`):** Your explicit `catchUpWindow` value always takes precedence.
+    *   `catchUpWindow: "unlimited"`: Catch up ALL missed executions.
+    *   `catchUpWindow: 0`: Skip ALL missed executions (real-time only).
+    *   `catchUpWindow: 5000`: Catch up if missed by ≤5 seconds, skip if older.
+*   **Smart Default (Recurring Actions):** If not specified, `catchUpWindow` defaults to the **duration of the action's recurrence interval**.
+    *   Example: A `repeat: { type: 'hour', interval: 1 }` action will default to a 1-hour `catchUpWindow`. If missed by less than an hour, it runs. If missed by more, it fast-forwards to the next scheduled interval.
+*   **Smart Default (One-Time Actions):** If not specified and the action has no `repeat` property, `catchUpWindow` defaults to **`0`**.
+    *   Example: A one-time task scheduled for 2:00 AM that's missed due to downtime will not run when the server comes back online later.
 
-For example:
+**How it works:**
 
-* 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.
+*   If an action is missed by less than its effective `catchUpWindow`, it executes (recovers from brief glitches or short offline periods).
+*   If missed by more, it's skipped and fast-forwarded to its next future scheduled time (prevents "thundering herds" after extended outages).
+*   The fast-forward optimization uses mathematical projection to instantly advance high-frequency tasks.
 
-This feature is ideal for:
+**Events for Coercion & Validation:**
 
-* Home automation logic ("turn heater off at 9 even if offline")
-* Sensor sampling
-* Data collection pipelines
+*   **`warning` event:** Emitted when `catchUpWindow` or `repeat` properties are syntactically invalid and have been defensively coerced to a sensible default (e.g., negative interval becomes `1`).
+*   **`Error` (thrown):** For fundamental issues like an invalid `repeat.type` (e.g., typo like `'horu'`). This is a fatal error, as the user's intent cannot be reliably determined.
+
+**Backwards compatibility:**
+
+The legacy `unBuffered` property is still supported and maps directly to `catchUpWindow` behavior:
+*   `unBuffered: false` is equivalent to `catchUpWindow: "unlimited"`
+*   `unBuffered: true` is equivalent to `catchUpWindow: 0`
 
 ---
 
@@ -213,6 +227,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.
 
@@ -304,6 +342,7 @@ Listen to events using `automator.on(event, callback)`:
 * `action` - Action executed
 * `update` - Action added/updated/removed
 * `error` - Error occurred
+* `warning` - Non-fatal data coercion or correction occurred
 * `debug` - Debug information
 
 ```js
@@ -413,14 +452,14 @@ 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 (smart default based on action type, or milliseconds number) |
 
 ### Repeat block:
 
@@ -435,7 +474,7 @@ npm run test:coverage
 
 ---
 
-## 🎯 Project Goals (v3)
+## 🎯 Project Goals (v4)
 
 * Deterministic behavior
 * Rock-solid DST handling

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
-# Architecture Overview
+# Architecture Overview (v4)
 
-## jw-automator v3 Architecture
+## jw-automator v4 Architecture
 
 This document describes the internal architecture of jw-automator v3.
 
@@ -244,11 +244,13 @@ Returns event list (state unchanged)
 - **Simulatable**: Preview future schedules
 - **Catch-up**: Process offline gaps identically to real-time
 
-### Why Buffered/UnBuffered?
+### Why `catchUpWindow` (and Legacy Buffered/UnBuffered)?
 
-- **Buffered**: "I want this to happen even if delayed" (e.g., turn heater off)
-- **UnBuffered**: "Only if on-time" (e.g., animations, rate limiting)
-- Both advance the recurrence chain correctly
+The `catchUpWindow` property, supported by the CoreEngine, precisely defines the time window for recovering missed actions.
+
+- **Smart Defaults**: For recurring actions, the `catchUpWindow` defaults to the action's interval (e.g., a 1-hour action has a 1-hour catch-up window). For one-time actions, it defaults to `0` (no catch-up). This prevents "thundering herd" issues by ensuring that actions too old are simply skipped.
+- **Explicit Control**: Users can still set `catchUpWindow` to `0` (skip all missed), a specific millisecond value (tolerate N ms lag), or `"unlimited"` (catch up all, like old buffered behavior).
+- **Legacy `unBuffered`**: The `unBuffered` flag (`true` or `false`) is now a legacy alias for `catchUpWindow: 0` and `catchUpWindow: "unlimited"` respectively. The system transparently maps it.
 
 ---
 

package/docs/MIGRATION.md

@@ -1,18 +1,45 @@
-# Migration Guide: v2 to v3
+# Migration Guide: v3 to v4
 
-This guide helps you migrate from jw-automator v2 to v3.
+This guide helps you migrate from jw-automator v3 to v4.
 
 ---
 
 ## Overview
 
-jw-automator v3 is a **complete clean-room rewrite** with improved semantics, better DST handling, and a cleaner API. While the core concepts remain the same, there are breaking changes from v2.
+jw-automator v4 is a significant refinement of v3's architecture, focusing on making the scheduler's behavior even more predictable and robust out-of-the-box. While v3 represented a complete rewrite, v4 introduces breaking changes by refining default behaviors and error handling for action specifications.
 
-v2 was the widely-deployed production version. v3 represents a ground-up reimplementation that preserves the philosophy while modernizing the architecture.
+v3 was the widely-deployed production version. v4 builds upon that foundation with enhanced predictability.
 
 ---
 
-## Breaking Changes
+## Breaking Changes from v3 to v4
+
+### 1. Default `catchUpWindow` Behavior Changed
+
+**v3:** If `catchUpWindow` was not specified, it defaulted to `"unlimited"` (catch up all missed executions).
+**v4:** If `catchUpWindow` is not specified, it now uses a **smart default** based on the action type:
+-   For **recurring actions**, it defaults to the **duration of the recurrence interval** (e.g., an hourly action gets a 1-hour `catchUpWindow`).
+-   For **one-time actions**, it defaults to **`0`** (skip all missed executions).
+
+**Impact:** User applications that relied on the implicit "unlimited" catch-up for all actions in v3 might now see actions being skipped or fast-forwarded more aggressively. If you desire the old "unlimited" catch-up, you must explicitly set `catchUpWindow: "unlimited"`.
+
+### 2. Invalid `repeat.type` Throws a Fatal Error
+
+**v3:** If `repeat.type` was missing or invalid (e.g., a typo like `'horu'`), Automator would defensively coerce it to `'day'` and emit an `error` event.
+**v4:** An invalid or missing `repeat.type` now throws a hard `Error` immediately.
+
+**Impact:** Code that previously succeeded by silently allowing `repeat.type` coercions will now fail fast, forcing explicit correction. This ensures that the action's intent is never misinterpreted.
+
+### 3. Coercion Events Changed from `error` to `warning`
+
+**v3:** Non-fatal defensive coercions (e.g., an invalid `repeat.interval` being set to `1`, a negative `catchUpWindow` becoming `0`) would emit an `error` event.
+**v4:** These same non-fatal coercions now emit a `warning` event. The `error` event is reserved for more critical issues (e.g., storage failures).
+
+**Impact:** If your application was listening for `automator.on('error', ...)` to catch these coercion notifications, you must now update your event listener to `automator.on('warning', ...)` to continue receiving them.
+
+---
+
+## Breaking Changes from v3 to v4
 
 ### 1. Constructor and Initialization
 
@@ -146,6 +173,20 @@ automator.updateActionByName('Old Name', {
 
 ## New Features in v3
 
+## New Features in v4
+
+### 1. Smart `catchUpWindow` Defaults
+
+The new intelligent default system for `catchUpWindow` means that for most actions, you no longer need to explicitly define this property to get predictable, sensible behavior. It automatically adapts based on whether your action is one-time or recurring.
+
+### 2. Dedicated `warning` Event
+
+A new `warning` event (`automator.on('warning', ...)`) provides a clearer channel for non-fatal feedback about defensive coercions. This allows developers to distinguish between critical runtime errors and minor data corrections.
+
+---
+
+## New Features in v3
+
 ### 1. Simulation
 
 Preview future schedules without running them:
@@ -232,180 +273,47 @@ const automator = new Automator({
 
 ---
 
-## Migration Steps
-
-### Step 1: Update Initialization
-
-Replace your v2 initialization with v3 constructor:
+## Migration Steps (v3 to v4)
 
-```javascript
-// Before
-const automator = require('jw-automator');
-automator.init({ file: './actions.json' });
+### Step 1: Understand Breaking Changes
 
-// After
-const Automator = require('jw-automator');
-const automator = new Automator({
-  storage: Automator.storage.file('./actions.json')
-});
-```
+Thoroughly review the "Breaking Changes from v3 to v4" section above. Identify which changes affect your application.
 
-### Step 2: Update Action Definitions
+### Step 2: Review `catchUpWindow` Usage
 
-Add `dstPolicy` to actions with repeat:
+If your v3 application relied on the implicit "unlimited" catch-up for actions where `catchUpWindow` was not explicitly set, you will need to:
 
-```javascript
-// Before
-automator.addAction({
-  cmd: 'myCmd',
-  date: new Date(),
-  repeat: { type: 'day', interval: 1 }
-});
-
-// After
-automator.addAction({
-  cmd: 'myCmd',
-  date: new Date(),
-  repeat: {
-    type: 'day',
-    interval: 1,
-    dstPolicy: 'once' // Explicitly choose DST behavior
-  }
-});
-```
+-   **Explicitly set `catchUpWindow: "unlimited"`** for those actions if you wish to maintain the old behavior.
+-   Otherwise, understand that these actions will now use the new smart defaults (recurrence interval for recurring, `0` for one-time actions).
 
 ### Step 3: Update Event Listeners
 
-Standardize event names:
+If your application was listening for `automator.on('error', ...)` to catch notifications about defensive coercions (e.g., invalid `repeat.interval`), you must now update your code to listen for `automator.on('warning', ...)` to receive these non-fatal messages.
 
-```javascript
-// Before
-automator.on('actionExecuted', (data) => { ... });
+### Step 4: Correct Invalid `repeat.type` Definitions
 
-// After
-automator.on('action', (event) => { ... });
-```
-
-### Step 4: Update API Calls
-
-Use new method names:
-
-```javascript
-// Before
-automator.removeAction(id);
-
-// After
-automator.removeActionByID(id);
-```
-
-### Step 5: Test DST Behavior
-
-Review actions that run during DST transitions and set appropriate `dstPolicy`:
-
-- `'once'` - Run only the first occurrence during fall-back (recommended default)
-- `'twice'` - Run both occurrences during fall-back
-
-### Step 6: Leverage New Features
-
-Consider using:
-- `getActionsInRange()` for calendar previews
-- `describeAction()` for debugging
-- Custom storage adapters for database persistence
-- Update events for logging changes
+If your application previously used actions with invalid or missing `repeat.type` values that were silently corrected in v3, you must now explicitly fix these `repeat.type` values. Failure to do so will result in a hard `Error` when the action is added or updated in v4.
 
 ---
 
 ## Compatibility Notes
 
-### What's the Same
+### What's the Same (v3 to v4)
 
-- **Core concept**: Schedule actions with recurrence
-- **Recurrence types**: second, minute, hour, day, week, month, year
-- **Local time**: Still operates in local time
-- **Buffered/unbuffered**: Still supported (as `unBuffered` flag)
-- **Function registration**: Still use `addFunction()`
+-   **Core concepts**: Schedule actions with recurrence
+-   **Recurrence types**: `second`, `minute`, `hour`, `day`, `week`, `month`, `year`
+-   **Local time**: Still operates in local time
+-   **API methods**: Names and signatures of `addAction()`, `updateActionByID()`, etc., remain the same.
+-   **Function registration**: Still use `addFunction()`
+-   **Legacy `unBuffered`**: Still supported as an alias, mapping to `catchUpWindow`.
 
-### What's Different
+### What's Different (v3 to v4)
 
-- **Constructor**: Now uses `new Automator()`
-- **Storage**: Explicitly configured
-- **DST**: Explicit policy required
-- **Events**: Standardized names and payloads
-- **API**: More consistent naming (`ByID`, `ByName`)
-- **IDs**: Auto-generated, not user-provided
-- **State**: Better separation of spec vs. state
-
----
-
-## Example: Complete Migration
-
-**v2 Code:**
-```javascript
-const automator = require('jw-automator');
-automator.init({ file: './actions.json' });
-
-automator.addFunction('turnLightOn', () => {
-  console.log('Light on');
-});
-
-automator.addAction({
-  cmd: 'turnLightOn',
-  date: new Date('2025-05-01T07:00:00'),
-  repeat: { type: 'day', interval: 1 }
-});
-
-automator.start();
-```
-
-**v3 Code:**
-```javascript
-const Automator = require('jw-automator');
-
-const automator = new Automator({
-  storage: Automator.storage.file('./actions.json')
-});
-
-automator.addFunction('turnLightOn', () => {
-  console.log('Light on');
-});
-
-automator.addAction({
-  name: 'Morning Lights',
-  cmd: 'turnLightOn',
-  date: new Date('2025-05-01T07:00:00'),
-  unBuffered: false,
-  repeat: {
-    type: 'day',
-    interval: 1,
-    dstPolicy: 'once'
-  }
-});
-
-automator.start();
-```
+-   **`catchUpWindow` Default Behavior**: Now smart and context-aware, instead of always `"unlimited"`.
+-   **`repeat.type` Validation**: Invalid types now throw a fatal `Error`.
+-   **Event Handling**: Coercions now emit `warning` events instead of `error` events.
+-   **Defensive Defaults Philosophy**: More refined and explicit.
 
 ---
 
 ## Getting Help
-
-If you encounter issues during migration:
-
-1. Check the [README](../README.md) for full API documentation
-2. Review the [Architecture](./ARCHITECTURE.md) for design understanding
-3. Run the examples in the `examples/` directory
-4. File an issue on GitHub
-
----
-
-## Why Rewrite?
-
-v3 addresses several issues from v2:
-
-- **Infinite loops**: Better safety guards
-- **DST bugs**: Explicit, predictable handling
-- **Catch-up logic**: More reliable offline behavior
-- **Testability**: Deterministic core engine
-- **Maintainability**: Cleaner architecture
-- **Extensibility**: Pluggable storage, better API
-
-The rewrite provides a solid foundation for long-term reliability.

package/docs/QUICKSTART.md

@@ -1,6 +1,6 @@
 # Quick Start Guide
 
-Get up and running with jw-automator v3 in 5 minutes.
+Get up and running with jw-automator v4 in 5 minutes.
 
 ---
 
@@ -137,36 +137,53 @@ automator.addAction({
 
 ---
 
-## Buffered vs UnBuffered
+## Offline Catch-Up with `catchUpWindow`
 
-### Buffered (Default) - Catch Up Missed Events
+Automator v4 manages offline catch-up using the `catchUpWindow` property, which has smart defaults for predictable behavior.
+
+### Smart Defaults for `catchUpWindow`
+
+-   **Recurring Actions:** If `catchUpWindow` is not specified, it defaults to the **duration of the action's recurrence interval**. This ensures short delays are recovered, but long outages don't cause a "thundering herd."
+-   **One-Time Actions:** If `catchUpWindow` is not specified and the action has no `repeat` property, it defaults to **`0`** (skip if missed).
+
+### Explicit Control
+
+You can explicitly set `catchUpWindow`:
+
+-   `catchUpWindow: "unlimited"`: Catch up ALL missed executions.
+-   `catchUpWindow: 0`: Skip ALL missed executions (real-time only).
+-   `catchUpWindow: 5000`: Catch up if missed by ≤5 seconds, skip if older.
+
+#### Example: Critical Task (unlimited catch-up)
 
 ```javascript
 automator.addAction({
   name: 'Critical Task',
   cmd: 'criticalTask',
   date: new Date('2025-05-01T10:00:00'),
-  unBuffered: false, // Execute even if delayed
+  catchUpWindow: "unlimited", // Execute all missed, even if offline for long
   repeat: { type: 'hour', interval: 1 }
 });
 ```
 
 If the system is offline from 10:00 to 13:00, it will execute the 10:00, 11:00, and 12:00 occurrences when it comes back online.
 
-### UnBuffered - Skip Missed Events
+#### Example: Animation Frame (skip missed)
 
 ```javascript
 automator.addAction({
   name: 'Animation Frame',
   cmd: 'updateAnimation',
   date: new Date(),
-  unBuffered: true, // Only run if on time
+  catchUpWindow: 0, // Only run if on time
   repeat: { type: 'second', interval: 1 }
 });
 ```
 
 If the system is delayed, it won't execute missed animation frames.
 
+**Legacy `unBuffered`**: The `unBuffered` property is still supported as a direct alias for `catchUpWindow` for backwards compatibility: `unBuffered: false` maps to `catchUpWindow: "unlimited"`, and `unBuffered: true` maps to `catchUpWindow: 0`.
+
 ---
 
 ## Simulation
@@ -249,6 +266,11 @@ automator.on('update', (event) => {
 automator.on('error', (event) => {
   console.error('Error:', event.message);
 });
+
+// Warnings (non-fatal coercions/corrections)
+automator.on('warning', (event) => {
+  console.warn('Warning:', event.message);
+});
 ```
 
 ---
@@ -349,7 +371,7 @@ process.on('SIGINT', () => {
 - Read the full [README](../README.md)
 - Check out [examples](../examples/)
 - Review [Architecture](./ARCHITECTURE.md)
-- See [Migration Guide](./MIGRATION.md) if upgrading from v1
+- See [Migration Guide](./MIGRATION.md) if upgrading from v3
 
 ---