fix(synapse): surface layer processing errors

[rafaelscosta]

Summary

• Stops SynapseEngine from classifying layer processing failures as plain skips when _safeProcess() swallowed the exception.
• Adds LayerProcessor#getLastError() so graceful degradation still returns null, but the orchestrator can record the layer as error in metrics.
• Adds a direct _safeProcess() exception boundary in SynapseEngine so malformed/custom layers do not crash the pipeline.
• Covers both captured errors and direct _safeProcess() throws in focused Synapse tests.

Issue

Part of #621, specifically the concrete SynapseEngine silent-layer-failure telemetry slice.

Validation

• node -c .aiox-core/core/synapse/engine.js
• node -c .aiox-core/core/synapse/layers/layer-processor.js
• npm test -- tests/synapse/engine.test.js tests/synapse/layer-processor.test.js --runInBand — 59 passed
• npm run generate:manifest
• npm run validate:manifest
• git diff --check
• 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

Note: the IDS pre-push registry hook produced an unsafe local entity-registry collision for generic engine; that generated artifact was not included in this PR.

Summary by CodeRabbit

• New Features

  • Improved per-layer error capture so individual layer failures are recorded and the pipeline continues.
  • Engine now surfaces layer error details into metrics when layers return no result.

• Tests

  • Added tests covering multiple error-capture paths and verifying metrics reflect per-layer failures.

[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:53am

[coderabbitai]

Walkthrough

LayerProcessor now records the last processing error and exposes it via getLastError(). SynapseEngine wraps layer execution to catch throws and, when layers return null/undefined, consults getLastError() to record per-layer errors to metrics. Tests and manifest updated accordingly.

Changes

Error Tracking in Synapse Pipeline Layers

Layer / File(s)	Summary
LayerProcessor Error State .aiox-core/core/synapse/layers/layer-processor.js	LayerProcessor initializes _lastError in the constructor, clears it at _safeProcess() start, sets it to a normalized Error when exceptions occur, and exposes it via new getLastError() method.
SynapseEngine Error Integration .aiox-core/core/synapse/engine.js	Adds getLayerError(layer) helper; wraps layer._safeProcess(context) in try/catch to record thrown exceptions with metrics.errorLayer(). When a layer returns null/undefined, engine queries getLastError() and records it as an error if present, otherwise retains the prior skip behavior.
Tests & Manifest tests/synapse/engine.test.js, tests/synapse/layer-processor.test.js, .aiox-core/install-manifest.yaml	Engine tests add scenarios asserting per-layer error metrics for (1) null return with getLastError() error, (2) _safeProcess throwing, and (3) getLastError() throwing. LayerProcessor tests assert getLastError() captures and clears errors (including a flaky retry). Manifest hashes/sizes updated.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

area: core, area: synapse, type: test

Suggested reviewers

• oalanicolas
• Pedrovaleriolopez

🚥 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(synapse): surface layer processing errors' accurately describes the main objective of this PR—surfacing and properly recording layer processing errors in metrics rather than silently treating them as skips.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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-synapse-layer-error-metrics-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

🤖 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/synapse/engine.js:
- Around line 183-189: The getLayerError function currently calls
layer.getLastError() directly which can throw for malformed/custom layers;
update getLayerError to guard that call with a try/catch around invoking
layer.getLastError (checking typeof as now), return the caught error or a
wrapped Error with context if invocation fails, and otherwise return the
original result or null—ensure you only change getLayerError and keep its
signature so callers of getLayerError (and the process/_safeProcess flow)
receive a safe error object instead of letting exceptions propagate.

🪄 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: 0c9b4b10-27be-4b54-b57b-c21e07a35b40

📥 Commits

Reviewing files that changed from the base of the PR and between 9496767 and bb25433.

📒 Files selected for processing (5)

• .aiox-core/core/synapse/engine.js
• .aiox-core/core/synapse/layers/layer-processor.js
• .aiox-core/install-manifest.yaml
• tests/synapse/engine.test.js
• tests/synapse/layer-processor.test.js

[coderabbitai]

🧹 Nitpick comments (1)

tests/synapse/engine.test.js (1)

352-361: ⚡ Quick win

Add an explicit layers_errored === 0 assertion for the graceful-degradation path.

The three new error-recording tests (lines 399–442) verify the "null + error" paths well. However, the complementary graceful-degradation path — _safeProcess returns null while getLastError() returns null or is absent — has no assertion on layers_errored. The existing "should return empty xml when no results" test (lines 352–361) covers this setup but only asserts on result.xml; it won't catch a regression where null returns are incorrectly classified as errors in metrics.

Given that this PR's core goal is accurate per-layer error telemetry, a false positive in layers_errored would be a direct regression in the new feature.

✅ Suggested assertion addition to the existing test

   test('should return empty xml when no results', async () => {
     // Make all layers return null
     for (const layer of engine.layers) {
       layer._safeProcess = jest.fn(() => null);
     }

     formatter.formatSynapseRules.mockReturnValue('');
     const result = await engine.process('test', {});
     expect(result.xml).toBe('');
+    // Graceful null returns (no getLastError / getLastError returns null) must NOT
+    // be classified as errors — they are silent skips, not telemetry-visible failures.
+    expect(result.metrics.layers_errored).toBe(0);
   });

Also applies to: 399-442

🤖 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/synapse/engine.test.js` around lines 352 - 361, Add an explicit
assertion that no layers were counted as errored when all layers return null:
after calling engine.process in the "should return empty xml when no results"
test, assert that result.metrics.layers_errored === 0 (or the equivalent metrics
field on the returned result). Also add the same assertion to the complementary
graceful-degradation tests that cover the "null + no getLastError()/null" paths
so regressions that treat null returns as errors are caught; locate these tests
by the use of layer._safeProcess mocks and formatter.formatSynapseRules
expectations.

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

Nitpick comments:
In `@tests/synapse/engine.test.js`:
- Around line 352-361: Add an explicit assertion that no layers were counted as
errored when all layers return null: after calling engine.process in the "should
return empty xml when no results" test, assert that
result.metrics.layers_errored === 0 (or the equivalent metrics field on the
returned result). Also add the same assertion to the complementary
graceful-degradation tests that cover the "null + no getLastError()/null" paths
so regressions that treat null returns as errors are caught; locate these tests
by the use of layer._safeProcess mocks and formatter.formatSynapseRules
expectations.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1e2533aa-a058-4b57-81df-f0a71f5a447a

📥 Commits

Reviewing files that changed from the base of the PR and between bb25433 and f890246.

📒 Files selected for processing (3)

• .aiox-core/core/synapse/engine.js
• .aiox-core/install-manifest.yaml
• tests/synapse/engine.test.js

🚧 Files skipped from review as they are similar to previous changes (2)

• .aiox-core/core/synapse/engine.js
• .aiox-core/install-manifest.yaml