jw-automator 3.2.0 → 4.0.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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
@@ -23,15 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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)
+- **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
 

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:
 
@@ -139,35 +139,37 @@ This avoids cron's silent-but-surprising behaviors.
 
 ---
 
-### 4. **Resilient Offline Catch-Up with Time Windows**
+### 4. **Resilient Offline Catch-Up with Smart Defaults**
 
-When the device is offline or delayed, you can control exactly how far back to catch up using the `catchUpWindow` property:
+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
-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
-```
+**`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.
 
 **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
+*   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.
 
-**Example scenarios:**
+**Events for Coercion & Validation:**
 
-* **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
+*   **`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 fully supported:
-```js
-unBuffered: false   // equivalent to catchUpWindow: "unlimited"
-unBuffered: true    // equivalent to catchUpWindow: 0
-```
+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`
 
 ---
 
@@ -340,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
@@ -456,8 +459,7 @@ npm run test:coverage
 | `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`)           |
+| `catchUpWindow` | Time window for catching up missed executions (smart default based on action type, or milliseconds number) |
 
 ### Repeat block:
 
@@ -472,7 +474,7 @@ npm run test:coverage
 
 ---
 
-## 🎯 Project Goals (v3)
+## 🎯 Project Goals (v4)
 
 * Deterministic behavior
 * Rock-solid DST handling
@@ -493,6 +495,6 @@ MIT
 
 ## ❤️ Acknowledgments
 
-jw-automator v3 is a ground-up rethinking of the original jw-automator library, preserving the spirit while strengthening the foundations.
+jw-automator v4 is a ground-up rethinking of the original jw-automator library, preserving the spirit while strengthening the foundations.
 
 If you're building automation logic and want predictable, human-friendly scheduling that survives the real world — **welcome.**

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
 
 ---
 

package/docs/defensive-defaults.md

@@ -0,0 +1,65 @@
+# Automator Defensive Defaults Strategy
+
+The Automator's design philosophy for handling action specifications is **"Fail loudly, run defensively."**
+
+The goal is to maximize system robustness. Rather than rejecting an action with minor errors or missing properties, the Automator will make reasonable, "defensive" assumptions to coerce the action into a valid, runnable state.
+
+However, these corrections are never silent. Whenever a default is applied or a value is coerced due to invalid input, the Automator emits either a `warning` or `debug` event. This ensures that the developer is always aware of any assumptions the system has made on their behalf.
+
+---
+
+### Property Default and Coercion Rules
+
+The following rules are applied when an action is added via `addAction()` or updated via `updateAction...()`.
+
+#### **`cmd`**
+- **Rule:** An action without a command is not runnable.
+- **Behavior:** Throws a hard `Error` if missing. This is the primary exception to the "run defensively" rule, as the action's intent cannot be determined.
+
+#### **`date`** (Start Time)
+- **Rule:** An action needs a starting time.
+- **Default:** If `date` is not provided, it defaults to **5 seconds in the future** from the time it was added.
+- **Event:** `debug`
+
+#### **`catchUpWindow`** (Smart Default)
+- **Philosophy:** The default catch-up behavior should match the user's likely intent for "server busy" vs. "server offline" scenarios. Explicit settings always take priority.
+- **Priority Rules:**
+  1.  **Explicit `catchUpWindow`:** If the property is present, it is used.
+      - `Infinity` is coerced to `"unlimited"`.
+      - Negative numbers are coerced to `0`.
+      - Invalid strings or other types are coerced to `"unlimited"`.
+      - A `warning` event is emitted for any coercion.
+  2.  **Legacy `unBuffered`:** If `catchUpWindow` is absent but the legacy `unBuffered` property is present, it is mapped for backwards compatibility:
+      - `unBuffered: true` maps to `catchUpWindow: 0` (no catch-up).
+      - `unBuffered: false` maps to `catchUpWindow: "unlimited"`.
+  3.  **Smart Default (Recurring):** If the action has a `repeat` property, `catchUpWindow` defaults to the **duration of the repeat interval** (e.g., an hourly action gets a 1-hour catch-up window).
+  4.  **Smart Default (One-Time):** If the action does not have a `repeat` property, `catchUpWindow` defaults to **`0`** (no catch-up).
+
+---
+
+### Recurrence Rules (`repeat.*`)
+
+#### **`repeat.type`**
+- **Rule:** The recurrence `type` is fundamental to the action's behavior and must be a valid string (e.g., 'hour', 'day', 'week').
+- **Behavior:** Throws a hard `Error` if missing or invalid. Unlike other properties, the ambiguity of an invalid type is considered a fatal error, as the user's intent cannot be safely determined.
+
+#### **`repeat.interval`**
+- **Rule:** The interval must be a positive integer.
+- **Default:** If `undefined`, it is `1`. If defined but invalid (e.g., `0`, `-5`, `2.5`), it is coerced to a valid integer via `Math.max(1, Math.floor(value))`.
+- **Event:** `warning` (if a value was changed).
+
+#### **`repeat.limit`**
+- **Rule:** The execution limit must be a number greater than or equal to 1.
+- **Default:** If invalid (e.g., `0`, `-10`, `'foo'`), it is coerced to `null` (unlimited).
+- **Event:** `warning`
+
+#### **`repeat.endDate`**
+- **Rule:** The end date must be a valid date representation.
+-
+- **Default:** If invalid, it is coerced to `null` (no end date).
+- **Event:** `warning`
+
+#### **`repeat.dstPolicy`**
+- **Rule:** The DST "fall back" policy must be either `'once'` or `'twice'`.
+- **Default:** If missing or invalid, it is coerced to `'once'`.
+- **Event:** `warning` (if an invalid value was provided).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jw-automator",
-  "version": "3.2.0",
-  "description": "A resilient, local-time, 1-second precision automation scheduler for Node.js",
+  "version": "4.0.1",
+  "description": "A resilient, local-time, 1-second precision automation scheduler for Node.js with smart defensive defaults and clear error handling",
   "main": "index.js",
   "files": [
     "src/",

package/src/Automator.js

@@ -1,7 +1,7 @@
 /**
  * Automator.js
  *
- * Main API class for jw-automator v3
+ * Main API class for jw-automator v4
  */
 
 const SchedulerHost = require('./host/SchedulerHost');
@@ -135,7 +135,6 @@ class Automator {
       cmd: actionSpec.cmd,
       payload: actionSpec.payload !== undefined ? actionSpec.payload : null,
       date: startDate,
-      unBuffered: actionSpec.unBuffered !== undefined ? actionSpec.unBuffered : false,
       catchUpWindow: catchUpWindow,
       repeat: actionSpec.repeat ? { ...actionSpec.repeat } : null,
       count: 0
@@ -192,10 +191,8 @@ 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
-      });
+      action.catchUpWindow = this._normalizeCatchUpWindow(action);
+      delete action.unBuffered; // Remove legacy property
     }
 
     this._emit('update', {
@@ -244,10 +241,8 @@ 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
-        });
+        action.catchUpWindow = this._normalizeCatchUpWindow(action);
+        delete action.unBuffered; // Remove legacy property
       }
 
       this._emit('update', {
@@ -409,7 +404,7 @@ class Automator {
     description += `\n  Command: ${action.cmd}`;
     description += `\n  Next run: ${action.date ? action.date.toLocaleString() : 'None'}`;
     description += `\n  Executions: ${action.count}`;
-    description += `\n  Buffered: ${!action.unBuffered}`;
+    description += `\n  Catch-up Window: ${action.catchUpWindow === 'unlimited' ? 'unlimited' : `${action.catchUpWindow}ms`}`;
 
     if (action.repeat) {
       description += `\n  Recurrence: ${action.repeat.type}`;
@@ -472,14 +467,15 @@ class Automator {
     try {
       const state = this.options.storage.load();
 
-      // 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)
-        }));
+        state.actions.forEach(action => {
+          // Set catchUpWindow if missing, using legacy unBuffered if present
+          if (action.catchUpWindow === undefined) {
+            action.catchUpWindow = this._normalizeCatchUpWindow(action);
+          }
+          // Remove legacy property after normalization
+          delete action.unBuffered;
+        });
 
         const maxId = Math.max(...state.actions.map(a => a.id || 0));
         this.nextId = maxId + 1;
@@ -524,6 +520,43 @@ class Automator {
     }, this.options.saveInterval);
   }
 
+
+  /**
+   * Calculate interval in milliseconds from a repeat spec.
+   * Note: Uses approximations for month/year, as this is for a default
+   * catch-up window, not for precise scheduling.
+   *
+   * @param {object} repeat
+   * @returns {number}
+   * @private
+   */
+  _getIntervalMilliseconds(repeat) {
+    const interval = repeat.interval || 1;
+    switch (repeat.type) {
+      case 'second':
+        return interval * 1000;
+      case 'minute':
+        return interval * 60 * 1000;
+      case 'hour':
+        return interval * 60 * 60 * 1000;
+      case 'day':
+      case 'weekday': // Approximated as 1 day for catch-up purposes
+      case 'weekend': // Approximated as 1 day for catch-up purposes
+        return interval * 24 * 60 * 60 * 1000;
+      case 'week':
+        return interval * 7 * 24 * 60 * 60 * 1000;
+      case 'month':
+        // A reasonable approximation for a default is 30 days
+        return interval * 30 * 24 * 60 * 60 * 1000;
+      case 'year':
+        // A reasonable approximation for a default is 365 days
+        return interval * 365 * 24 * 60 * 60 * 1000;
+      default:
+        // Fallback for an invalid type that slipped past validation
+        return 60000; // 1 minute
+    }
+  }
+
   /**
    * Normalize catchUpWindow property (handles backwards compatibility with unBuffered)
    *
@@ -536,7 +569,7 @@ class Automator {
    * @returns {string|number} - Normalized catchUpWindow value ("unlimited" or milliseconds)
    */
   _normalizeCatchUpWindow(spec) {
-    // New property takes precedence
+    // 1. New property takes precedence
     if (spec.catchUpWindow !== undefined) {
       // Coerce Infinity to "unlimited" (backwards compatibility)
       if (spec.catchUpWindow === Infinity) {
@@ -549,13 +582,18 @@ class Automator {
       return spec.catchUpWindow;
     }
 
-    // Backwards compatibility mapping
+    // 2. Backwards compatibility mapping for legacy 'unBuffered'
     if (spec.unBuffered !== undefined) {
       return spec.unBuffered ? 0 : "unlimited";
     }
 
-    // Default: catch up everything (current buffered behavior)
-    return "unlimited";
+    // 3. For recurring actions, default to the interval duration
+    if (spec.repeat) {
+      return this._getIntervalMilliseconds(spec.repeat);
+    }
+
+    // 4. For one-time actions, default to 0 (no catch-up)
+    return 0;
   }
 
   /**
@@ -573,14 +611,9 @@ class Automator {
     if (action.repeat) {
       const validTypes = ['second', 'minute', 'hour', 'day', 'weekday', 'weekend', 'week', 'month', 'year'];
 
-      // Defensive: Coerce invalid repeat.type to 'day' with ERROR event
+      // CRITICAL: An invalid repeat.type is a fatal error, as intent is lost.
       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';
+        throw new Error(`Invalid repeat.type "${action.repeat.type}". Must be one of: ${validTypes.join(', ')}`);
       }
 
       // Defensive: Coerce invalid interval to Math.max(1, Math.floor(value))
@@ -588,8 +621,8 @@ class Automator {
         const original = action.repeat.interval;
         const coerced = Math.max(1, Math.floor(original));
         if (original !== coerced) {
-          this._emit('error', {
-            type: 'error',
+          this._emit('warning', {
+            type: 'warning',
             message: `Invalid repeat.interval ${original} - coerced to ${coerced}`,
             actionSpec: action
           });
@@ -599,19 +632,19 @@ class Automator {
 
       // Defensive: Validate dstPolicy
       if (action.repeat.dstPolicy && !['once', 'twice'].includes(action.repeat.dstPolicy)) {
-        this._emit('error', {
-          type: 'error',
+        this._emit('warning', {
+          type: 'warning',
           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
+      // Defensive: Coerce invalid repeat.limit to null (unlimited) with WARNING 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',
+          this._emit('warning', {
+            type: 'warning',
             message: `Invalid repeat.limit ${action.repeat.limit} - defaulting to null (unlimited)`,
             actionSpec: action
           });
@@ -624,8 +657,8 @@ class Automator {
         try {
           new Date(action.repeat.endDate);
         } catch (e) {
-          this._emit('error', {
-            type: 'error',
+          this._emit('warning', {
+            type: 'warning',
             message: `Invalid repeat.endDate - ignoring`,
             actionSpec: action
           });
@@ -642,8 +675,8 @@ class Automator {
 
       // Coerce negative numbers to 0 FIRST
       if (isNumber && action.catchUpWindow < 0) {
-        this._emit('error', {
-          type: 'error',
+        this._emit('warning', {
+          type: 'warning',
           message: `Negative catchUpWindow ${action.catchUpWindow} - coerced to 0`,
           actionSpec: action
         });
@@ -651,8 +684,8 @@ class Automator {
       }
       // Then validate it's a valid value
       else if (!isValidString && !isNumber && !isInfinity) {
-        this._emit('error', {
-          type: 'error',
+        this._emit('warning', {
+          type: 'warning',
           message: `Invalid catchUpWindow "${action.catchUpWindow}" - defaulting to "unlimited"`,
           actionSpec: action
         });