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

.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()

.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()

.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()

.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()

.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()

.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()

.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()