sinapse-ai 1.6.1 → 1.7.0

package/.claude/rules/documentation-first.md

@@ -103,7 +103,7 @@ complexity_score ≥ 16 (COMPLEX class) → run Spec Pipeline FIRST
 
 | User says | Classification | What the framework does |
 |---|---|---|
-| "criar um site pra meu cliente Vascularte" | `site` | Invokes `greenfield-ui.yaml` (5-agent Phase 1) |
+| "criar um site pra meu cliente Acme" | `site` | Invokes `greenfield-ui.yaml` (5-agent Phase 1) |
 | "monta uma plataforma SaaS de gestão" | `saas` (COMPLEX) | Spec Pipeline → then `greenfield-fullstack.yaml` |
 | "API de cobrança Asaas" | `api` | Invokes `greenfield-service.yaml` |
 | "corrige o botão verde da home" | `fix` | SDC YOLO direct |

package/.sinapse-ai/core/config/merge-utils.js

@@ -50,6 +50,14 @@ function deepMerge(target, source) {
   const result = { ...target };
 
   for (const [key, value] of Object.entries(source)) {
+    // Defense-in-depth: block prototype-pollution keys (CWE-1321).
+    // The {...target} spread already neutralizes this today, but an explicit
+    // deny-list prevents a future refactor from reintroducing the vulnerability
+    // via untrusted config (YAML/JSON).
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      continue;
+    }
+
     // Handle +append modifier for arrays
     if (key.endsWith('+append')) {
       const baseKey = key.slice(0, -7); // Remove '+append'

package/.sinapse-ai/core/errors/constants.js

@@ -0,0 +1,147 @@
+/**
+ * core/errors/constants.js — SINAPSE typed error constants.
+ *
+ * SNPS_* typed error codes with SINAPSE branding.
+ *
+ * ErrorCategory / ErrorSeverity are the closed enums consumed across the
+ * framework. DEFAULT_ERROR_CODE is the fallback code used when a thrown value
+ * carries no recognizable code.
+ */
+
+const ErrorCategory = Object.freeze({
+  CONFIGURATION: 'configuration',
+  VALIDATION: 'validation',
+  FILESYSTEM: 'filesystem',
+  NETWORK: 'network',
+  REGISTRY: 'registry',
+  ORCHESTRATION: 'orchestration',
+  SYNAPSE: 'synapse',
+  EXECUTION: 'execution',
+  PERMISSION: 'permission',
+  EXTERNAL_EXECUTOR: 'external_executor',
+  UNKNOWN: 'unknown',
+});
+
+const ErrorSeverity = Object.freeze({
+  CRITICAL: 'critical',
+  ERROR: 'error',
+  WARNING: 'warning',
+  INFO: 'info',
+});
+
+const DEFAULT_ERROR_CODE = 'SNPS_UNKNOWN_ERROR';
+
+const CORE_ERROR_DEFINITIONS = Object.freeze([
+  {
+    code: DEFAULT_ERROR_CODE,
+    category: ErrorCategory.UNKNOWN,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    userMessage: 'An unexpected SINAPSE core error occurred.',
+    recovery: ['Review the error metadata and retry if the operation is safe to repeat.'],
+  },
+  {
+    code: 'SNPS_CONFIGURATION_INVALID',
+    category: ErrorCategory.CONFIGURATION,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    userMessage: 'SINAPSE configuration is invalid.',
+    recovery: ['Validate the active SINAPSE configuration and retry.'],
+  },
+  {
+    code: 'SNPS_VALIDATION_FAILED',
+    category: ErrorCategory.VALIDATION,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    userMessage: 'SINAPSE validation failed.',
+    recovery: ['Review validation errors and correct the invalid input.'],
+  },
+  {
+    code: 'SNPS_FILESYSTEM_ERROR',
+    category: ErrorCategory.FILESYSTEM,
+    severity: ErrorSeverity.ERROR,
+    retryable: true,
+    userMessage: 'A filesystem operation failed.',
+    recovery: ['Check path existence, permissions, and disk availability.'],
+  },
+  {
+    code: 'SNPS_PERMISSION_DENIED',
+    category: ErrorCategory.PERMISSION,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    exitCode: 13,
+    userMessage: 'The operation does not have the required permissions.',
+    recovery: ['Grant the required permission or run the command in an authorized context.'],
+  },
+  {
+    code: 'SNPS_NETWORK_ERROR',
+    category: ErrorCategory.NETWORK,
+    severity: ErrorSeverity.ERROR,
+    retryable: true,
+    userMessage: 'A network operation failed.',
+    recovery: ['Check connectivity and retry the operation.'],
+  },
+  {
+    code: 'SNPS_REGISTRY_LOAD_FAILED',
+    category: ErrorCategory.REGISTRY,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    userMessage: 'SINAPSE could not load a registry.',
+    recovery: ['Validate registry file syntax and path configuration.'],
+  },
+  {
+    code: 'SNPS_REGISTRY_WRITE_FAILED',
+    category: ErrorCategory.REGISTRY,
+    severity: ErrorSeverity.ERROR,
+    retryable: true,
+    userMessage: 'SINAPSE could not write a registry.',
+    recovery: ['Check registry path permissions and retry.'],
+  },
+  {
+    code: 'SNPS_ORCHESTRATION_FAILED',
+    category: ErrorCategory.ORCHESTRATION,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    userMessage: 'SINAPSE orchestration failed.',
+    recovery: ['Review orchestration metadata and the active workflow state.'],
+  },
+  {
+    code: 'SNPS_SYNAPSE_LAYER_FAILED',
+    category: ErrorCategory.SYNAPSE,
+    severity: ErrorSeverity.WARNING,
+    retryable: true,
+    userMessage: 'A Synapse layer failed while processing context.',
+    recovery: ['Review layer metadata and continue with graceful degradation when possible.'],
+  },
+  {
+    code: 'SNPS_EXECUTION_FAILED',
+    category: ErrorCategory.EXECUTION,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    userMessage: 'SINAPSE execution failed.',
+    recovery: ['Review execution logs and retry after correcting the failure cause.'],
+  },
+  {
+    code: 'SNPS_EXTERNAL_EXECUTOR_FAILED',
+    category: ErrorCategory.EXTERNAL_EXECUTOR,
+    severity: ErrorSeverity.ERROR,
+    retryable: true,
+    userMessage: 'An external executor failed.',
+    recovery: ['Review external executor logs and retry if the command is idempotent.'],
+  },
+  {
+    code: 'SNPS_PERSISTENCE_DEGRADED',
+    category: ErrorCategory.FILESYSTEM,
+    severity: ErrorSeverity.WARNING,
+    retryable: true,
+    userMessage: 'SINAPSE persistence degraded and continued in memory.',
+    recovery: ['Check persistence path permissions and available disk space.'],
+  },
+]);
+
+module.exports = {
+  ErrorCategory,
+  ErrorSeverity,
+  DEFAULT_ERROR_CODE,
+  CORE_ERROR_DEFINITIONS,
+};

package/.sinapse-ai/core/errors/error-registry.js

@@ -0,0 +1,176 @@
+/**
+ * core/errors/error-registry.js — SINAPSE error definition registry.
+ *
+ * SINAPSE-branded error registry; code regex is [A-Z0-9_]+, so SNPS_* codes
+ * validate. The Pro-tier registry (pro-error-registry.js) is intentionally
+ * not included.
+ *
+ * The registry maps an error code → frozen definition (category, severity,
+ * retryable, userMessage, recovery, optional exitCode). Lookups never throw:
+ * unknown codes fall back to the UNKNOWN definition flagged unregistered.
+ */
+
+const {
+  ErrorCategory,
+  ErrorSeverity,
+  DEFAULT_ERROR_CODE,
+  CORE_ERROR_DEFINITIONS,
+} = require('./constants');
+const {
+  cloneMetadataValue,
+  deepMerge,
+  hasOwn,
+  isPlainObject,
+  normalizeErrorCode,
+  normalizeRecovery,
+} = require('./utils');
+
+const VALID_CATEGORIES = new Set(Object.values(ErrorCategory));
+const VALID_SEVERITIES = new Set(Object.values(ErrorSeverity));
+
+function freezeDefinition(definition) {
+  return Object.freeze({
+    ...definition,
+    metadata: Object.freeze(cloneMetadataValue(definition.metadata || {})),
+    recovery: Object.freeze([...(definition.recovery || [])]),
+  });
+}
+
+function createUnknownDefinition(code = DEFAULT_ERROR_CODE) {
+  return freezeDefinition({
+    code,
+    category: ErrorCategory.UNKNOWN,
+    severity: ErrorSeverity.ERROR,
+    retryable: false,
+    userMessage: 'An unexpected SINAPSE core error occurred.',
+    recovery: ['Review the error metadata and retry if the operation is safe to repeat.'],
+    metadata: code === DEFAULT_ERROR_CODE ? {} : { registry: { registered: false } },
+  });
+}
+
+class ErrorRegistry {
+  constructor(definitions = CORE_ERROR_DEFINITIONS) {
+    this._entries = new Map();
+    this.registerMany(definitions);
+
+    if (!this.has(DEFAULT_ERROR_CODE)) {
+      this.register(createUnknownDefinition());
+    }
+  }
+
+  registerMany(definitions) {
+    if (Array.isArray(definitions)) {
+      definitions.forEach((definition) => this.register(definition));
+      return this;
+    }
+
+    if (isPlainObject(definitions)) {
+      Object.values(definitions).forEach((definition) => this.register(definition));
+      return this;
+    }
+
+    throw new TypeError('ErrorRegistry definitions must be an array or object');
+  }
+
+  register(definition) {
+    const normalized = this._normalizeDefinition(definition);
+
+    if (this._entries.has(normalized.code)) {
+      throw new Error(`Duplicate SINAPSE error code: ${normalized.code}`);
+    }
+
+    this._entries.set(normalized.code, freezeDefinition(normalized));
+    return this;
+  }
+
+  lookup(code) {
+    const normalizedCode = normalizeErrorCode(code) || DEFAULT_ERROR_CODE;
+    const found = this._entries.get(normalizedCode);
+
+    if (found) {
+      return found;
+    }
+
+    const fallback = this._entries.get(DEFAULT_ERROR_CODE) || createUnknownDefinition();
+    return freezeDefinition({
+      ...fallback,
+      code: normalizedCode,
+      metadata: deepMerge(fallback.metadata, { registry: { registered: false } }),
+    });
+  }
+
+  has(code) {
+    const normalizedCode = normalizeErrorCode(code);
+    return Boolean(normalizedCode && this._entries.has(normalizedCode));
+  }
+
+  list() {
+    return Array.from(this._entries.values()).sort((left, right) => left.code.localeCompare(right.code));
+  }
+
+  get size() {
+    return this._entries.size;
+  }
+
+  assertUnique() {
+    const codes = this.list().map((definition) => definition.code);
+    const unique = new Set(codes);
+
+    if (codes.length !== unique.size) {
+      throw new Error('ErrorRegistry contains duplicate error codes');
+    }
+
+    return true;
+  }
+
+  _normalizeDefinition(definition) {
+    if (!isPlainObject(definition)) {
+      throw new TypeError('Error definition must be a plain object');
+    }
+
+    const code = normalizeErrorCode(definition.code);
+    if (!code) {
+      throw new Error('Error definition requires a non-empty code');
+    }
+
+    if (!/^[A-Z0-9_]+$/.test(code)) {
+      throw new Error(`Invalid SINAPSE error code: ${code}`);
+    }
+
+    const category = definition.category || ErrorCategory.UNKNOWN;
+    if (!VALID_CATEGORIES.has(category)) {
+      throw new Error(`Invalid error category for ${code}: ${category}`);
+    }
+
+    const severity = definition.severity || ErrorSeverity.ERROR;
+    if (!VALID_SEVERITIES.has(severity)) {
+      throw new Error(`Invalid error severity for ${code}: ${severity}`);
+    }
+
+    const normalized = {
+      code,
+      category,
+      severity,
+      retryable: Boolean(definition.retryable),
+      userMessage: definition.userMessage || definition.message || code,
+      recovery: normalizeRecovery(definition.recovery),
+      metadata: isPlainObject(definition.metadata) ? cloneMetadataValue(definition.metadata) : {},
+    };
+
+    if (hasOwn(definition, 'exitCode') && definition.exitCode !== undefined) {
+      if (!Number.isInteger(definition.exitCode) || definition.exitCode < 0) {
+        throw new Error(`Invalid exitCode for ${code}: ${definition.exitCode}`);
+      }
+      normalized.exitCode = definition.exitCode;
+    }
+
+    return normalized;
+  }
+}
+
+const defaultErrorRegistry = new ErrorRegistry(CORE_ERROR_DEFINITIONS);
+
+module.exports = {
+  ErrorRegistry,
+  defaultErrorRegistry,
+};

package/.sinapse-ai/core/errors/index.js

@@ -0,0 +1,50 @@
+/**
+ * core/errors/index.js — barrel for the SINAPSE typed-error module.
+ *
+ * SINAPSE-branded barrel. This is the FOUNDATION module: downstream modules consume it via
+ *   const { SinapseError, normalizeError, serializeError } = require('../errors');
+ *
+ * Public API exported here:
+ *   - SinapseError              error class (code/category/severity/retryable/recovery/exitCode)
+ *   - ErrorRegistry             registry class for custom error definition sets
+ *   - ErrorCategory             frozen category enum
+ *   - ErrorSeverity             frozen severity enum
+ *   - DEFAULT_ERROR_CODE        'SNPS_UNKNOWN_ERROR'
+ *   - CORE_ERROR_DEFINITIONS    frozen array of built-in SNPS_* definitions
+ *   - defaultErrorRegistry      singleton registry (core definitions loaded)
+ *   - isSinapseError(value)     duck-typed instanceof check
+ *   - normalizeError(err, opts) envelope any thrown value into a SinapseError
+ *   - serializeError(err, opts) JSON-safe envelope (stack redacted in prod)
+ *   - sanitizeValue(value)      cycle-safe value sanitizer
+ *   - shouldExposeErrorStack    stack-exposure policy predicate
+ *   - deepMerge / isPlainObject / normalizeErrorCode  shared helpers
+ */
+
+const {
+  ErrorCategory,
+  ErrorSeverity,
+  DEFAULT_ERROR_CODE,
+  CORE_ERROR_DEFINITIONS,
+} = require('./constants');
+const { ErrorRegistry, defaultErrorRegistry } = require('./error-registry');
+const { SinapseError, isSinapseError, normalizeError } = require('./sinapse-error');
+const { shouldExposeErrorStack, sanitizeValue, serializeError } = require('./serializer');
+const { deepMerge, isPlainObject, normalizeErrorCode } = require('./utils');
+
+module.exports = {
+  SinapseError,
+  ErrorRegistry,
+  ErrorCategory,
+  ErrorSeverity,
+  DEFAULT_ERROR_CODE,
+  CORE_ERROR_DEFINITIONS,
+  defaultErrorRegistry,
+  isSinapseError,
+  normalizeError,
+  serializeError,
+  sanitizeValue,
+  shouldExposeErrorStack,
+  deepMerge,
+  isPlainObject,
+  normalizeErrorCode,
+};

package/.sinapse-ai/core/errors/serializer.js

@@ -0,0 +1,147 @@
+/**
+ * core/errors/serializer.js — JSON-safe error serialization for SINAPSE.
+ *
+ * SINAPSE-branded serializer with one ADDITIVE, defensive hardening on stack exposure:
+ * stacks are NEVER exposed when NODE_ENV === 'production' unless the caller
+ * explicitly passes `includeStack: true`. This prevents leaking internal stack
+ * traces to users in production (security: do not leak implementation detail).
+ *
+ * `sanitizeValue` lives in ./utils (cycle-safe via WeakSet). Here we inject the
+ * local `serializeError` into it so nested Error values get the full typed
+ * envelope. We re-export `sanitizeValue` so the module's public surface is
+ * unchanged from the original (index barrel still exports it from here too).
+ */
+
+const { DEFAULT_ERROR_CODE } = require('./constants');
+const { hasOwn, sanitizeValue: sanitizeValueBase } = require('./utils');
+
+const STACK_TRUTHY_FLAGS = ['1', 'true', 'yes', 'on'];
+
+function isProductionEnv() {
+  return String(process.env.NODE_ENV || '').toLowerCase() === 'production';
+}
+
+/**
+ * Decide whether an error stack may be included in serialized output.
+ *
+ * Precedence:
+ *   1. options.includeStack === true  → always expose (explicit caller intent)
+ *   2. options.includeStack === false → never expose
+ *   3. NODE_ENV === 'production'       → NEVER expose (additive prod guard)
+ *   4. otherwise → expose only if a debug flag is set
+ *      (SINAPSE_DEBUG | DEBUG_ERROR_STACKS | DEBUG_STACKS)
+ */
+function shouldExposeErrorStack(options = {}) {
+  if (options.includeStack === true) {
+    return true;
+  }
+
+  if (options.includeStack === false) {
+    return false;
+  }
+
+  // Additive defensive guard: in production, never auto-expose stacks.
+  if (isProductionEnv()) {
+    return false;
+  }
+
+  const stackFlag =
+    process.env.SINAPSE_DEBUG ||
+    process.env.DEBUG_ERROR_STACKS ||
+    process.env.DEBUG_STACKS ||
+    '';
+
+  return STACK_TRUTHY_FLAGS.includes(String(stackFlag).toLowerCase());
+}
+
+function sanitizeValue(value, seen = new WeakSet(), options = {}) {
+  // Inject serializeError so nested Error values produce the full envelope.
+  return sanitizeValueBase(value, seen, options, serializeError);
+}
+
+function serializeError(error, options = {}, seen = new WeakSet()) {
+  if (!(error instanceof Error)) {
+    return sanitizeValue(error, seen, options);
+  }
+
+  if (seen.has(error)) {
+    return '[Circular]';
+  }
+
+  seen.add(error);
+
+  try {
+    const serialized = {
+      name: error.name || 'Error',
+      message: error.message || '',
+      stack: shouldExposeErrorStack(options) ? error.stack : '[redacted]',
+    };
+
+    if (error.code) {
+      serialized.code = error.code;
+    }
+
+    if (error.isSinapseError || error.name === 'SinapseError') {
+      serialized.code = error.code || DEFAULT_ERROR_CODE;
+      serialized.category = error.category;
+      serialized.severity = error.severity;
+      serialized.retryable = Boolean(error.retryable);
+
+      if (hasOwn(error, 'exitCode')) {
+        serialized.exitCode = error.exitCode;
+      }
+
+      if (error.userMessage) {
+        serialized.userMessage = error.userMessage;
+      }
+
+      if (Array.isArray(error.recovery)) {
+        serialized.recovery = [...error.recovery];
+      }
+
+      serialized.metadata = sanitizeValue(error.metadata || {}, seen, options);
+    }
+
+    if (error.cause !== undefined) {
+      serialized.cause = error.cause instanceof Error
+        ? serializeError(error.cause, options, seen)
+        : sanitizeValue(error.cause, seen, options);
+    }
+
+    for (const key of Object.getOwnPropertyNames(error)) {
+      if ([
+        'name',
+        'message',
+        'stack',
+        'code',
+        'category',
+        'severity',
+        'retryable',
+        'exitCode',
+        'metadata',
+        'cause',
+        'userMessage',
+        'recovery',
+        'isSinapseError',
+      ].includes(key)) {
+        continue;
+      }
+
+      try {
+        serialized[key] = sanitizeValue(error[key], seen, options);
+      } catch (serializationError) {
+        serialized[key] = `[Unserializable: ${serializationError.message}]`;
+      }
+    }
+
+    return serialized;
+  } finally {
+    seen.delete(error);
+  }
+}
+
+module.exports = {
+  shouldExposeErrorStack,
+  sanitizeValue,
+  serializeError,
+};

package/.sinapse-ai/core/errors/sinapse-error.js

@@ -0,0 +1,144 @@
+/**
+ * core/errors/sinapse-error.js — the SinapseError class + normalizeError.
+ *
+ * SinapseError class + normalizeError with SINAPSE branding.
+ *
+ * SinapseError extends Error and carries the typed fields the framework relies
+ * on: code, category, severity, retryable, recovery, exitCode (+ userMessage,
+ * metadata, cause). normalizeError envelopes any thrown value (raw Error,
+ * existing SinapseError, or non-Error) into a SinapseError without losing
+ * context. Serialization is delegated to ./serializer (no duplicated logic).
+ */
+
+const { DEFAULT_ERROR_CODE } = require('./constants');
+const { defaultErrorRegistry } = require('./error-registry');
+const { serializeError } = require('./serializer');
+const { deepMerge, hasOwn, isPlainObject, normalizeErrorCode } = require('./utils');
+
+class SinapseError extends Error {
+  constructor(message, options = {}) {
+    const code = normalizeErrorCode(options.code) || DEFAULT_ERROR_CODE;
+    const registry = options.registry || defaultErrorRegistry;
+    const definition = registry.lookup(code);
+    const finalMessage = message || options.message || definition.userMessage || code;
+
+    if (hasOwn(options, 'cause')) {
+      super(finalMessage, { cause: options.cause });
+    } else {
+      super(finalMessage);
+    }
+
+    this.name = 'SinapseError';
+    this.code = code;
+    this.category = options.category || definition.category;
+    this.severity = options.severity || definition.severity;
+    this.retryable = hasOwn(options, 'retryable') ? Boolean(options.retryable) : Boolean(definition.retryable);
+    this.userMessage = options.userMessage || definition.userMessage;
+    this.recovery = Array.isArray(options.recovery) ? [...options.recovery] : [...(definition.recovery || [])];
+    this.metadata = deepMerge(definition.metadata || {}, options.metadata || {});
+    this.isSinapseError = true;
+
+    if (hasOwn(options, 'exitCode')) {
+      this.exitCode = options.exitCode;
+    } else if (hasOwn(definition, 'exitCode')) {
+      this.exitCode = definition.exitCode;
+    }
+
+    if (hasOwn(options, 'cause')) {
+      this.cause = options.cause;
+    }
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, SinapseError);
+    }
+  }
+
+  toJSON(options = {}) {
+    return serializeError(this, options);
+  }
+}
+
+function isSinapseError(value) {
+  return value instanceof SinapseError || Boolean(value && value.isSinapseError === true);
+}
+
+function collectErrorOwnProperties(error) {
+  if (!(error instanceof Error)) {
+    return {};
+  }
+
+  return Object.getOwnPropertyNames(error).reduce((properties, key) => {
+    if (['name', 'message', 'stack', 'cause'].includes(key)) {
+      return properties;
+    }
+
+    properties[key] = error[key];
+    return properties;
+  }, {});
+}
+
+function normalizeError(error, overrides = {}) {
+  if (isSinapseError(error)) {
+    if (!overrides || Object.keys(overrides).length === 0) {
+      return error;
+    }
+
+    return new SinapseError(overrides.message || error.message, {
+      code: overrides.code || error.code,
+      category: overrides.category || error.category,
+      severity: overrides.severity || error.severity,
+      retryable: hasOwn(overrides, 'retryable') ? overrides.retryable : error.retryable,
+      exitCode: hasOwn(overrides, 'exitCode') ? overrides.exitCode : error.exitCode,
+      userMessage: overrides.userMessage || error.userMessage,
+      recovery: overrides.recovery || error.recovery,
+      metadata: deepMerge(error.metadata || {}, overrides.metadata || {}),
+      cause: hasOwn(overrides, 'cause') ? overrides.cause : error.cause,
+      registry: overrides.registry,
+    });
+  }
+
+  if (error instanceof Error) {
+    const ownProperties = collectErrorOwnProperties(error);
+    const metadata = deepMerge(
+      {
+        originalError: {
+          name: error.name || 'Error',
+        },
+      },
+      Object.keys(ownProperties).length > 0 ? { originalError: { properties: ownProperties } } : {},
+      isPlainObject(overrides.metadata) ? overrides.metadata : {},
+    );
+
+    return new SinapseError(overrides.message || error.message, {
+      code: overrides.code || error.code || DEFAULT_ERROR_CODE,
+      category: overrides.category,
+      severity: overrides.severity,
+      retryable: overrides.retryable,
+      exitCode: overrides.exitCode,
+      userMessage: overrides.userMessage,
+      recovery: overrides.recovery,
+      metadata,
+      cause: hasOwn(overrides, 'cause') ? overrides.cause : error,
+      registry: overrides.registry,
+    });
+  }
+
+  return new SinapseError(overrides.message || String(error), {
+    code: overrides.code || DEFAULT_ERROR_CODE,
+    category: overrides.category,
+    severity: overrides.severity,
+    retryable: overrides.retryable,
+    exitCode: overrides.exitCode,
+    userMessage: overrides.userMessage,
+    recovery: overrides.recovery,
+    metadata: deepMerge({ originalValue: { type: typeof error } }, overrides.metadata || {}),
+    cause: overrides.cause,
+    registry: overrides.registry,
+  });
+}
+
+module.exports = {
+  SinapseError,
+  isSinapseError,
+  normalizeError,
+};