Skip to content

Document Hyperkernel error handling and recovery#13

Draft
hnordt wants to merge 1 commit into
mainfrom
agent/document-error-handling-and-recovery
Draft

Document Hyperkernel error handling and recovery#13
hnordt wants to merge 1 commit into
mainfrom
agent/document-error-handling-and-recovery

Conversation

@hnordt

@hnordt hnordt commented Jul 27, 2026

Copy link
Copy Markdown
Owner

Summary

  • add Draft design record 0005 for predictable error handling and recovery across the Kernel, Extension, and Experience layers
  • distinguish expected command rejections from exceptional operational and integrity failures
  • require custom errors built on platform primitives, stable codes, preserved causes, and JSDoc @throws contracts
  • define the boundaries that own translation, rollback, retry, reconciliation, process containment, and user presentation
  • separate committed command state from projection and external-effect outcomes so uncertainty never causes unsafe duplicate work
  • require locally contained, actionable error UI with safe retry when possible, dismissal, preserved context, and no full-page refresh
  • index the new record in docs/design/README.md

Why

Error handling is a primary reliability and trust requirement for Hyperkernel. The existing architecture defines command, event, projection, and external-effect failure behavior in several places, but it does not yet provide one cross-layer contract for exception semantics, catch ownership, retry safety, public failure descriptors, and resilient UI recovery.

This record makes those decisions explicit while preserving the distinction between target architecture and the current early implementation.

Impact

This PR changes documentation only. It does not implement custom errors, retry orchestration, transport failure descriptors, initialization boundaries, or error UI. Future implementation work must still be classified and verified according to its Kernel, Extension, or Experience risk, and Kernel changes continue to require experienced human review.

Validation

  • npm run lint
  • git diff --check origin/main...HEAD

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant