fix(core): expose master persistence degradation

[rafaelscosta]

Summary

• Adds explicit persistence health state to MasterOrchestrator so failed state saves are visible through status/finalization APIs instead of only a warn log.
• Persists normalized persistence metadata in saved state snapshots and resets the signal after a successful write.
• Covers the failure path with a focused unit test and updates generated governance metadata/manifest.

Issue

Part of #621, specifically the concrete MasterOrchestrator silent-persistence-failure slice.

Validation

• node -c .aiox-core/core/orchestration/master-orchestrator.js
• npm test -- tests/core/master-orchestrator.test.js --runInBand — 57 passed
• npm run generate:manifest
• npm run validate:manifest
• git diff --check

Additional battery already run on this same slice before the final one-line normalized-log adjustment:

• npm run lint — pass, 0 errors / 114 baseline warnings
• npm run typecheck — pass
• node scripts/validate-package-completeness.js — pass, 34/34
• node bin/utils/validate-publish.js — pass, 4199 files in package
• npm test -- --runInBand --forceExit — 330 passed suites, 11 skipped; 8347 passed tests, 149 skipped

Summary by CodeRabbit

• New Features

  • Added state-persistence health reporting: availability flag and last-error details surfaced in status and finalize outputs
  • New public indicators to query persistence availability and any recent persistence error

• Tests

  • Added tests covering persistence write failures, recovery, and status propagation into saved state and status outputs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aiox-core	Ready	Preview, Comment	May 8, 2026 6:29am

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2cce4e79-146b-4936-893f-5780fd7bb8c7

📥 Commits

Reviewing files that changed from the base of the PR and between 9bcfc16 and 9711e07.

📒 Files selected for processing (4)

• .aiox-core/core/orchestration/master-orchestrator.js
• .aiox-core/data/entity-registry.yaml
• .aiox-core/install-manifest.yaml
• tests/core/master-orchestrator.test.js

---

Walkthrough

MasterOrchestrator now tracks persistence health via internal _persistenceAvailable and _persistenceError fields. The saveState() method records success or failure, extends persisted payloads with persistence metadata, and new public accessors (isPersistenceAvailable(), getPersistenceError()) expose this state. The finalize() and getStatus() outputs include persistence health blocks. Test coverage validates persistence failure and recovery scenarios.

Changes

Persistence Health Tracking

Layer / File(s)	Summary
State Initialization .aiox-core/core/orchestration/master-orchestrator.js	Constructor initializes _persistenceAvailable and _persistenceError fields for internal persistence health tracking.
Persistence Tracking in saveState() .aiox-core/core/orchestration/master-orchestrator.js	saveState() writes a persistence block into the persisted state; updates availability and lastError on success; on failure sets availability=false, records error message, and logs a warning.
Finalize Output .aiox-core/core/orchestration/master-orchestrator.js	finalize() output includes a top-level persistence object with current availability and last error.
Status & Public API .aiox-core/core/orchestration/master-orchestrator.js	getStatus() includes persistence; new public methods isPersistenceAvailable() and getPersistenceError() expose the current persistence health.
Test Coverage tests/core/master-orchestrator.test.js	New test simulates a one-time fs.writeJson failure, verifies saveState() returns false and persistence state/error propagate through accessors/status/finalize, then verifies recovery on subsequent successful save.
Registry and Manifest Updates .aiox-core/data/entity-registry.yaml, .aiox-core/install-manifest.yaml	Generated metadata refreshed: registry timestamp/checksums updated; install-manifest regenerated with updated hashes/sizes for changed files.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• SynkraAI/aiox-core#695: Implements the same persistence-availability fields and accessors on a related state-management class.

Suggested reviewers

• Pedrovaleriolopez
• oalanicolas

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(core): expose master persistence degradation' accurately summarizes the main change—adding explicit persistence health state and APIs to surface failed state-save operations in MasterOrchestrator.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devops/issue-621-master-persistence-signal-20260508

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

📊 Coverage Report

Coverage report not available

📈 Full coverage report available in Codecov

---

Generated by PR Automation (Story 6.1)

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/core/master-orchestrator.test.js (1)

291-310: ⚡ Quick win

Add a fail→success recovery assertion for persistence health

This test validates degradation, but it doesn’t verify that a subsequent successful saveState() clears the degraded signal. Add one extra successful save/assert cycle so the reset behavior is locked in.

As per coding guidelines, “Verify test coverage exists for new/modified functions.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/core/master-orchestrator.test.js` around lines 291 - 310, After mocking
fs.writeJson to fail once and asserting degradation, add a recovery step: change
the spy (writeJsonSpy) to resolve successfully for a subsequent call (e.g.,
mockResolvedValueOnce or replace the mock) and invoke orchestrator.saveState()
again, then assert orchestrator.isPersistenceAvailable() is true,
orchestrator.getPersistenceError() is null/empty, and that
orchestrator.getStatus().persistence and orchestrator.finalize().persistence
reflect available: true with no error; keep using the same writeJsonSpy and
restore it in the finally block as before and locate behavior around
orchestrator.saveState(), orchestrator.isPersistenceAvailable(),
orchestrator.getPersistenceError(), getStatus(), and finalize().

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.aiox-core/core/orchestration/master-orchestrator.js:
- Around line 1133-1136: The persisted persistence snapshot is built from
this._persistenceAvailable and this._persistenceError before those flags are
reset after writeJson, so a successful retry can still write a stale {
available: false, lastError: ... } to disk; fix by ensuring the snapshot
reflects the post-save state: either reset/clear this._persistenceAvailable and
this._persistenceError before constructing the persistence object, or
(preferably) only update the persisted snapshot after writeJson succeeds (i.e.,
set persistence.available = true and persistence.lastError = null and then
writeJson), making the change around the writeJson call in
master-orchestrator.js where persistence is assembled and flags are reset.

---

Nitpick comments:
In `@tests/core/master-orchestrator.test.js`:
- Around line 291-310: After mocking fs.writeJson to fail once and asserting
degradation, add a recovery step: change the spy (writeJsonSpy) to resolve
successfully for a subsequent call (e.g., mockResolvedValueOnce or replace the
mock) and invoke orchestrator.saveState() again, then assert
orchestrator.isPersistenceAvailable() is true,
orchestrator.getPersistenceError() is null/empty, and that
orchestrator.getStatus().persistence and orchestrator.finalize().persistence
reflect available: true with no error; keep using the same writeJsonSpy and
restore it in the finally block as before and locate behavior around
orchestrator.saveState(), orchestrator.isPersistenceAvailable(),
orchestrator.getPersistenceError(), getStatus(), and finalize().

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 39f2db55-d09b-4b64-a2cf-6ed6158ed3ca

📥 Commits

Reviewing files that changed from the base of the PR and between a88405c and 9bcfc16.

📒 Files selected for processing (4)

• .aiox-core/core/orchestration/master-orchestrator.js
• .aiox-core/data/entity-registry.yaml
• .aiox-core/install-manifest.yaml
• tests/core/master-orchestrator.test.js