feat(core): add error governance contract

[rafaelscosta]

Summary

• Adds the canonical AIOX error governance contract: AIOXError, registry, constants, serializer, and public exports.
• Registers the new error surface in IDS/entity metadata and install manifest.
• Fixes IDS entity ID collision handling so .aiox-core/core/errors/index.js registers as errors-index without overwriting .aiox-core/core/index.js.

Validation

• npm run typecheck PASS
• npm run lint PASS with 0 errors; 114 pre-existing warnings outside this scope
• npm run validate:manifest PASS
• Focused Jest for errors + IDS PASS: 128 tests
• Previously failing related suites PASS individually
• npm test -- --runInBand PASS: 334 suites passed, 11 skipped; 8372 tests passed, 149 skipped. Jest printed the known open-handles warning after the green summary and the process was ended manually after completion.

Refs #701

Summary by CodeRabbit

• New Features

  • Implemented standardized error handling with structured error codes, categories, severity levels, and recovery guidance for improved debugging and error management.
  • Added safe error serialization with automatic stack trace management, circular reference protection, and JSON-safe metadata handling.

• Documentation

  • Added architecture decision record documenting error governance contract and compatibility guarantees.

[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 11:51am

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

This pull request introduces a canonical error-governance contract for aiox-core, implementing AIOXError (an error subclass with standardized metadata), ErrorRegistry (a taxonomy registry with lookups), and serialization utilities that produce JSON-safe, circular-reference-tolerant outputs. The entity registry system is updated to support scoped entity IDs, preventing collisions across categories. Comprehensive tests validate error handling, normalization, serialization, and registry operations.

Changes

Error Governance Contract

Layer / File(s)	Summary
Error Taxonomy .aiox-core/core/errors/constants.js	Defines ErrorCategory and ErrorSeverity enums, DEFAULT_ERROR_CODE, and immutable CORE_ERROR_DEFINITIONS array with structured error metadata.
Error Registry .aiox-core/core/errors/error-registry.js	Implements ErrorRegistry class with frozen definition storage, normalized code lookup, duplicate validation, and a module-level defaultErrorRegistry instance.
Error Class & Normalization .aiox-core/core/errors/aiox-error.js	Defines AIOXError as Error subclass with registry-derived fields, toJSON serialization, isAIOXError detection, and normalizeError for coercing arbitrary inputs into AIOXError instances.
Serialization & Utilities .aiox-core/core/errors/serializer.js, utils.js	Provides shouldExposeErrorStack, sanitizeValue, serializeError (with circular-reference protection and safe JSON conversion), plus isPlainObject, cloneMetadataValue, deepMerge, normalizeErrorCode, normalizeRecovery, and hasOwn helpers.
Public API .aiox-core/core/errors/index.js	Aggregates and re-exports all error-governance building blocks for external consumption.
Entity ID Resolution .aiox-core/development/scripts/populate-entity-registry.js	Introduces toScopedEntityId and resolveEntityId helpers to generate category-scoped entity IDs avoiding collisions across file paths.
Registry Updater Integration .aiox-core/core/ids/registry-updater.js	Updates file create/modify handlers to use resolveEntityId for collision-aware entity ID derivation.
Registry Data .aiox-core/data/entity-registry.yaml	Adds six new core/errors module entries with dependencies, checksums, and verification timestamps; updates module count from 746 to 752.
Install Manifest .aiox-core/install-manifest.yaml	Records SHA256 hashes and metadata for six new error module files; updates file count from 1111 to 1117.
Tests tests/core/errors/*.test.js, tests/core/ids/*	Comprehensive Jest suites validating AIOXError construction/normalization, ErrorRegistry lookup/validation, serializer behavior (stack redaction, circular handling, sanitization), and ID resolution/collision detection.
Architecture & Story docs/architecture/adr/ADR-ERROR-GOVERNANCE-CONTRACT.md, docs/stories/epic-error-governance/*	Documents canonical error surface contract, compatibility rules, epic objectives, acceptance criteria, and completion status.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• [RFC] Error Governance Contract: AIOXError, ErrorRegistry, and incremental migration #701 — This PR directly implements the error-governance contract RFC's proposed AIOXError, ErrorRegistry, serialization, and normalization components at the code level.
• [EPIC-7] Framework Observability & Error Governance Refinement #621 — The additions (AIOXError, ErrorRegistry, circular-safe serialization, metadata cloning utilities, deepMerge) fulfill the Error Governance work described in EPIC-7.

Suggested labels

area: core, type: test, area: docs

Suggested reviewers

• oalanicolas
• Pedrovaleriolopez

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(core): add error governance contract' directly and clearly summarizes the main change—introducing a new error governance system with AIOXError, registry, and related utilities as the primary contribution.
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 feature/issue-701-error-governance-contract

---

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)