Harden Phase for v0.1.0 release

.github/workflows/ci.yml

@@ -24,19 +24,45 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Audit production sources
+        shell: bash
         run: |
           if grep -RInE '(^|[^[:alnum:]_])throw([^[:alnum:]_]|$)|std::abort[[:space:]]*\(' src; then
             echo "Embedded safety audit failed"
             exit 1
           fi
-          if grep -RInE '#include[[:space:]]+[<"](Fresh|Pulse|Signal|Tempo|Trace|Worker|Vault|Link|Courier|Flow|Lingo)\\.h[>"]' src; then
+          if grep -RInE '#include[[:space:]]+[<"](Fresh|Pulse|Signal|Tempo|Trace|Worker|Vault|Link|Courier|Flow|Lingo)\.h[>"]' src; then
             echo "Embedded safety audit failed: Phase must not depend on other ZekStack libraries"
             exit 1
           fi
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            python3 scripts/check_release_version.py --tag "$GITHUB_REF_NAME"
+          else
+            python3 scripts/check_release_version.py
+          fi
 
-  build-examples:
+  host-tests:
     runs-on: ubuntu-latest
     needs: source-audit
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build host tests
+        run: |
+          g++ -std=c++20 -pthread -Wall -Wextra -Werror \
+            -Itests/host/stubs -Isrc \
+            src/Phase.cpp \
+            tests/host/semaphore_stubs.cpp \
+            tests/host/task_stubs.cpp \
+            tests/host/test_phase.cpp \
+            -o phase-host-tests
+
+      - name: Run host tests
+        run: ./phase-host-tests
+
+  build-examples:
+    runs-on: ubuntu-latest
+    needs: [source-audit, host-tests]
     strategy:
       fail-fast: false
       matrix:
@@ -81,45 +107,9 @@ jobs:
             fi
           done
 
-  release:
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: [source-audit, build-examples, arduino-cli]
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-
-      - name: Generate release changelog
-        run: |
-          python3 scripts/generate_release_changelog.py \
-            --target-ref "${GITHUB_REF_NAME}" \
-            --tag-name "${GITHUB_REF_NAME}" \
-            --output "release-changelog.md"
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: ${{ github.ref_name }}
-          target_commitish: ${{ github.sha }}
-          draft: false
-          prerelease: ${{ contains(github.ref_name, '-') }}
-          generate_release_notes: false
-          body_path: release-changelog.md
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
   arduino-cli:
     runs-on: ubuntu-latest
-    needs: source-audit
+    needs: [source-audit, host-tests]
     strategy:
       fail-fast: false
       matrix:
@@ -177,3 +167,39 @@ jobs:
                 "$d"
             fi
           done
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [source-audit, host-tests, build-examples, arduino-cli]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Generate release changelog
+        run: |
+          python3 scripts/generate_release_changelog.py \
+            --target-ref "${GITHUB_REF_NAME}" \
+            --tag-name "${GITHUB_REF_NAME}" \
+            --output "release-changelog.md"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          target_commitish: ${{ github.sha }}
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          generate_release_notes: false
+          body_path: release-changelog.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -93,9 +93,12 @@ void loop() {
 * `pause()` is async and takes effect before the next lifecycle action or group-condition poll.
 * Callback timeout checks happen after the callback returns.
 * Group condition polling timeouts are enforced by the Phase task.
-* Registration closes after `start()`.
-* The destructor waits for the Phase task to end. If user lifecycle code never returns, destruction can block forever.
-* Phase uses bounded node and dependency counts, but registration currently uses dynamic allocation through `std::vector`, `std::string`, and `std::function`. Register nodes during setup before runtime work starts.
+* Registration closes after a successful `start()` request.
+* `stop()`, `pause()`, and `resume()` may be called from Phase callbacks. `end()` must be called from another task and returns `Busy` when called from the Phase task.
+* The destructor waits for the Phase task to stop using its internal state. Destruction from a Phase callback is deferred safely until the worker exits.
+* Registration and graph preparation use `std::vector`, `std::string`, and `std::function`. Node storage, dependency indexes, and lifecycle order are preallocated before the worker starts; lifecycle execution does not allocate.
+* `PhaseChange` string pointers are valid for the complete callback invocation. Event messages and pause reasons are copied into bounded internal snapshots and may be truncated to 191 characters.
+* Stop/deinit failures are best-effort and are reported through `onChange()` while remaining cleanup continues.
 * Phase does not depend on other ZekStack libraries.
 
 ## Examples
@@ -154,7 +157,7 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | PSRAM | Optional for task stacks when ESP-IDF support is available |
 | Dependencies | none |
 | Exceptions | Not used |
-| Status | Early-stage `0.0.1` |
+| Status | `0.1.0` release candidate |
 
 ## Configuration
 

library.json

@@ -1,6 +1,6 @@
 {
   "name": "Phase",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Async application lifecycle orchestration library for ESP32.",
   "keywords": [
     "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Phase
-version=0.0.1
+version=0.1.0
 author=zekageri
 maintainer=zekageri
 sentence=Application lifecycle orchestration library for ESP32.

scripts/check_release_version.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+from pathlib import Path
+
+
+def properties_version(path: Path) -> str:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.startswith("version="):
+            return line.split("=", 1)[1].strip()
+    raise SystemExit(f"version is missing from {path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--tag", default="")
+    args = parser.parse_args()
+
+    json_version = json.loads(Path("library.json").read_text(encoding="utf-8"))["version"]
+    properties = properties_version(Path("library.properties"))
+    if json_version != properties:
+        raise SystemExit(
+            f"manifest version mismatch: library.json={json_version}, library.properties={properties}"
+        )
+
+    if args.tag:
+        expected = args.tag[1:] if args.tag.startswith("v") else args.tag
+        if json_version != expected:
+            raise SystemExit(f"tag {args.tag} does not match manifest version {json_version}")
+
+    print(f"Phase release metadata is consistent: {json_version}")
+
+
+if __name__ == "__main__":
+    main()