refactor(esplifecycle): simplify to node-name API and expand example coverage

Author: zekageri

CHANGELOG.md

@@ -5,31 +5,38 @@ All notable changes to this project will be documented in this file.
 ## [Unreleased]
 
 ### Added
-- ESPStartup-like compatibility APIs: `start()` and `stop()` aliases.
-- `NodeBuilder::parallelSafe(bool)` for fluent startup-style tuning.
-- `LifecycleConfig` parallel controls for all phases:
-  - `enableParallelInit`
-  - `enableParallelDeinit`
-  - `enableParallelReinit`
-- Additional runtime config fields:
-  - `waitTicks`
-  - `workerName`
-  - `workerStackSizeBytes`
-- Direct snapshot APIs:
-  - `LifecycleSnapshot snapshot() const`
-  - `JsonDocument snapshotJson() const`
-- Scope teardown entrypoint:
-  - `LifecycleResult deinitializeByScopeMask(uint32_t scopeMask)`
+- Name-first runtime APIs:
+  - `reinitialize(std::initializer_list<const char*>)`
+  - `reinitialize(const std::vector<const char*>&)`
+  - `deinitialize(std::initializer_list<const char*>)`
+  - `deinitialize(const std::vector<const char*>&)`
+- Name-list based reload listener API:
+  - `startReloadListener(ESPEventBus&, uint16_t, std::function<std::vector<const char*>(void*)>)`
+  - `stopReloadListener()`
+- Extended example suite:
+  - `dependency-closure`
+  - `deferred-readiness`
+  - `parallel-waves`
+  - `failure-policy`
+  - `reload-burst`
 
 ### Changed
-- Scoped teardown now includes transitive dependents of selected scope nodes.
-- Scoped reinit now includes selected nodes, their transitive dependents, and required transitive dependencies.
-- Runtime scheduling now uses deterministic dependency waves for init/deinit/reinit.
-- Parallel execution now supported in init/deinit/reinit waves when enabled.
+- Public lifecycle targeting is now node-name based.
+- Partial deinitialize expands selected nodes with transitive dependents.
+- Partial reinitialize expands selected nodes with dependents and required dependencies.
+- Reload listener now consumes node-name payloads and coalesces deduplicated names.
+
+### Removed
+- `start()` / `stop()` compatibility aliases.
+- Scope-mask-based APIs:
+  - `deinitializeByScopeMask(...)`
+  - `reinitializeByScopeMask(...)`
+  - `reinitializeByNodeNames(...)`
+- Node scope bit tagging API:
+  - `NodeBuilder::reloadScope(...)`
 
 ### Fixed
-- Dependency closure behavior now matches lifecycle correctness requirements for partial reinit.
-- Snapshot metadata now includes phase and last operation/error context for websocket/UI consumers.
+- Error reporting now uses node-focused resolution failures (`UnknownNode`, `NodeResolutionFailed`).
 
 ## [0.1.0] - 2026-03-05
 ### Added

README.md

@@ -1,6 +1,6 @@
 # ESPLifecycle
 
-ESPLifecycle is the ESPToolKit lifecycle orchestrator for deterministic init, deinit, and scoped reinit with ESPStartup-like fluent registration.
+ESPLifecycle is the ESPToolKit lifecycle orchestrator for deterministic init, deinit, and node-targeted reinit.
 
 ## CI / Release / License
 [![CI](https://github.com/ESPToolKit/esp-lifecycle/actions/workflows/ci.yml/badge.svg)](https://github.com/ESPToolKit/esp-lifecycle/actions/workflows/ci.yml)
@@ -9,12 +9,12 @@ ESPLifecycle is the ESPToolKit lifecycle orchestrator for deterministic init, de
 
 ## Features
 - Section-based orchestration with dependency validation (`after` / `before`).
-- Deterministic `initialize()`, `deinitialize()`, `reinitialize*()`.
-- Scoped deinit/reinit closure with dependency correctness.
+- Deterministic `initialize()`, `deinitialize()`, and partial `reinitialize(...)`.
+- Node-name targeted closure with dependency correctness.
 - Optional parallel waves for init, deinit, and reinit.
 - Deferred sections with readiness gates.
 - Snapshot callback + direct `snapshotJson()` helper (ArduinoJson V7).
-- Optional scope listener with 25ms coalescing.
+- Optional reload listener with 25ms coalescing and node-name payload mapping.
 
 ## Installation
 - PlatformIO: add `https://github.com/ESPToolKit/esp-lifecycle.git` to `lib_deps`.
@@ -30,7 +30,7 @@ Dependencies:
 #include <ESPLifecycle.h>
 ```
 
-## Quick Start (ESPStartup-like)
+## Quick Start
 ```cpp
 #include <ESPLifecycle.h>
 #include <ESPWorker.h>
@@ -46,7 +46,6 @@ void setup() {
     cfg.enableParallelInit = true;
     cfg.enableParallelDeinit = true;
     cfg.enableParallelReinit = true;
-    cfg.onReady = []() { Serial.println("ready"); };
 
     lifecycle.configure(cfg);
     lifecycle.init({"core", "network"});
@@ -55,9 +54,11 @@ void setup() {
     lifecycle.addTo("core", "storage", []() { return true; }, []() { return true; });
     lifecycle.addTo("network", "wifi", []() { return true; }, []() { return true; }).after("logger");
 
-    if (!lifecycle.start()) {
-        Serial.println("lifecycle start failed");
-    }
+    (void)lifecycle.build();
+    (void)lifecycle.initialize();
+
+    // Reinitialize logger and everything that depends on it.
+    (void)lifecycle.reinitialize({"logger"});
 }
 ```
 
@@ -71,10 +72,10 @@ lifecycle.section("services")
     );
 ```
 
-## Scope Semantics
-- `deinitializeByScopeMask(mask)` expands to target nodes + transitive dependents.
-- `reinitializeByScopeMask(mask)` expands to target nodes + dependents + required dependencies.
-- `reinitializeByNodeNames(...)` uses the same reinit closure rule.
+## Node-Name Targeting Semantics
+- `deinitialize({"logger"})` expands to selected nodes + transitive dependents.
+- `reinitialize({"logger"})` expands to selected nodes + dependents + required dependencies.
+- `reinitializeAll()` keeps full-graph behavior.
 
 ## Snapshot API
 ```cpp
@@ -92,13 +93,15 @@ serializeJson(json, Serial);
 
 ## Runtime API
 - `LifecycleResult build()`
-- `bool start()` / `void stop()` compatibility aliases
 - `LifecycleResult initialize()`
 - `LifecycleResult deinitialize()`
-- `LifecycleResult deinitializeByScopeMask(uint32_t scopeMask)`
+- `LifecycleResult deinitialize(std::initializer_list<const char*> nodeNames)`
+- `LifecycleResult deinitialize(const std::vector<const char*>& nodeNames)`
 - `LifecycleResult reinitializeAll()`
-- `LifecycleResult reinitializeByScopeMask(uint32_t scopeMask)`
-- `LifecycleResult reinitializeByNodeNames(const std::vector<const char*>& nodeNames)`
+- `LifecycleResult reinitialize(std::initializer_list<const char*> nodeNames)`
+- `LifecycleResult reinitialize(const std::vector<const char*>& nodeNames)`
+- `bool startReloadListener(ESPEventBus&, uint16_t, std::function<std::vector<const char*>(void*)>)`
+- `void stopReloadListener()`
 - `LifecycleSnapshot snapshot() const`
 - `JsonDocument snapshotJson() const`
 
@@ -109,15 +112,14 @@ serializeJson(json, Serial);
 - `continueTeardownOnFailure=false` stops at first teardown failure.
 - Busy transitions return `LifecycleErrorCode::Busy`.
 
-## Migration from ESPStartup
-- `start()` exists as compatibility alias.
-- `stop()` maps to `deinitialize()`.
-- Each node must provide `init` and `teardown` callbacks.
-- Parallel config now exists for all phases.
-
 ## Examples
 - `examples/basic-startup`
 - `examples/scoped-reload`
+- `examples/dependency-closure` - demonstrates dependent closure for partial deinit/reinit.
+- `examples/deferred-readiness` - deferred section gate using readiness callbacks.
+- `examples/parallel-waves` - parallel init/deinit/reinit wave behavior.
+- `examples/failure-policy` - rollback and teardown failure policy behavior.
+- `examples/reload-burst` - listener burst coalescing and deduplicated node-name reloads.
 
 ## License
 MIT - see [LICENSE.md](LICENSE.md).

examples/basic-startup/basic-startup.ino

@@ -26,8 +26,15 @@ void setup() {
     lifecycle.addTo("core", "storage", []() { return true; }, []() { return true; });
     lifecycle.addTo("network", "wifi", []() { return true; }, []() { return true; }).after("storage");
 
-    if( !lifecycle.start() ){
-        Serial.println("start failed");
+    LifecycleResult buildResult = lifecycle.build();
+    if( !buildResult.ok ){
+        Serial.println("build failed");
+        return;
+    }
+
+    LifecycleResult initResult = lifecycle.initialize();
+    if( !initResult.ok ){
+        Serial.println("initialize failed");
         return;
     }
 
@@ -36,7 +43,7 @@ void setup() {
     Serial.println();
 
     delay(1000);
-    lifecycle.stop();
+    (void)lifecycle.deinitialize({"logger"});
 }
 
 void loop() {

examples/deferred-readiness/deferred-readiness.ino

@@ -0,0 +1,62 @@
+#include <Arduino.h>
+#include <ESPLifecycle.h>
+#include <ESPWorker.h>
+
+ESPWorker worker;
+ESPLifecycle lifecycle;
+
+bool initCore() {
+    Serial.println("init core");
+    return true;
+}
+
+bool initCloud() {
+    Serial.println("init cloud");
+    return true;
+}
+
+bool deinitCore() {
+    Serial.println("deinit core");
+    return true;
+}
+
+bool deinitCloud() {
+    Serial.println("deinit cloud");
+    return true;
+}
+
+bool cloudReady() {
+    return millis() > 4000;
+}
+
+void waitForReady(TickType_t waitTicks) {
+    (void)waitTicks;
+    delay(250);
+}
+
+void setup() {
+    Serial.begin(115200);
+
+    worker.init(ESPWorker::Config{});
+
+    LifecycleConfig config{};
+    config.worker = &worker;
+    config.onReady = []() { Serial.println("all sections ready"); };
+
+    lifecycle.configure(config);
+    lifecycle.init({"core", "cloud"});
+
+    lifecycle.section("cloud")
+        .mode(LifecycleSectionMode::Deferred)
+        .readiness(cloudReady, waitForReady);
+
+    lifecycle.addTo("core", "core-init", initCore, deinitCore);
+    lifecycle.addTo("cloud", "cloud-sync", initCloud, deinitCloud).after("core-init");
+
+    (void)lifecycle.build();
+    (void)lifecycle.initialize();
+}
+
+void loop() {
+    delay(500);
+}

examples/dependency-closure/dependency-closure.ino

@@ -0,0 +1,84 @@
+#include <Arduino.h>
+#include <ESPLifecycle.h>
+#include <ESPWorker.h>
+
+ESPWorker worker;
+ESPLifecycle lifecycle;
+
+static bool loggerReady = false;
+static bool wifiReady = false;
+static bool apiReady = false;
+
+bool initLogger() {
+    loggerReady = true;
+    Serial.println("init logger");
+    return true;
+}
+
+bool initWifi() {
+    if( !loggerReady ){
+        return false;
+    }
+    wifiReady = true;
+    Serial.println("init wifi");
+    return true;
+}
+
+bool initApi() {
+    if( !wifiReady ){
+        return false;
+    }
+    apiReady = true;
+    Serial.println("init api");
+    return true;
+}
+
+bool deinitLogger() {
+    loggerReady = false;
+    Serial.println("deinit logger");
+    return true;
+}
+
+bool deinitWifi() {
+    wifiReady = false;
+    Serial.println("deinit wifi");
+    return true;
+}
+
+bool deinitApi() {
+    apiReady = false;
+    Serial.println("deinit api");
+    return true;
+}
+
+void setup() {
+    Serial.begin(115200);
+
+    worker.init(ESPWorker::Config{});
+
+    LifecycleConfig config{};
+    config.worker = &worker;
+    config.enableParallelInit = false;
+    config.enableParallelDeinit = false;
+    config.enableParallelReinit = false;
+
+    lifecycle.configure(config);
+    lifecycle.init({"core", "network", "services"});
+
+    lifecycle.addTo("core", "logger", initLogger, deinitLogger);
+    lifecycle.addTo("network", "wifi", initWifi, deinitWifi).after("logger");
+    lifecycle.addTo("services", "api", initApi, deinitApi).after("wifi");
+
+    (void)lifecycle.build();
+    (void)lifecycle.initialize();
+
+    Serial.println("Reinitialize logger -> expects wifi+api closure");
+    (void)lifecycle.reinitialize({"logger"});
+
+    Serial.println("Deinitialize logger -> expects wifi+api teardown");
+    (void)lifecycle.deinitialize({"logger"});
+}
+
+void loop() {
+    delay(500);
+}