feat(kernel-errors): standardize kernel errors observable in vat-land#913
Open
feat(kernel-errors): standardize kernel errors observable in vat-land#913
Conversation
Introduce a machine-readable error format for kernel errors surfaced to vats as promise rejections: `[KERNEL:<CODE>] detail` for expected errors and `[KERNEL:FATAL:<CODE>] detail` for fatal ones. - Add `kernel-error.ts` to `@metamask/kernel-errors` with `ExpectedKernelErrorCode`, `FatalKernelErrorCode`, `KernelErrorCode` types, `KERNEL_ERROR_PATTERN` regex, and `isKernelError`, `getKernelErrorCode`, `isFatalKernelError` detection utilities - Add `makeKernelError` and `makeFatalKernelError` to `kernel-marshal.ts`, importing the shared types from `@metamask/kernel-errors` - Migrate all 17+ error sites in KernelRouter, RemoteManager, VatHandle, VatSyscall, and KernelServiceManager to the new helpers - Update all affected test assertions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Fatal kernel errors terminate the offending vat, not the kernel itself. Rename the infix from FATAL to VAT_FATAL to reflect this: `[KERNEL:VAT_FATAL:<CODE>] detail`. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Import FatalKernelErrorCode in VatSyscall.ts instead of inline union - Add unit tests for makeKernelError and makeFatalKernelError with round-trip verification through kernel-errors detection utilities Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Coverage Report
File Coverage
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Contributor
|
Formalizing these errors seems good, but why not use the existing |
sirtimid
reviewed
Apr 2, 2026
sirtimid
reviewed
Apr 2, 2026
sirtimid
reviewed
Apr 2, 2026
- Rename kernel-error.ts to vat-observable-errors.ts to clarify that these are errors observed by vat code as promise rejections, distinct from the kernel-side error classes and stream error marshalling - Migrate last makeError call in VatHandle.ts to makeFatalKernelError - Remove makeError (no remaining callers) - Rewrite README to delineate the three error categories and explain why they exist as separate systems Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Member
Author
|
@grypez re: "why not use existing custom error classes", see: https://github.com/MetaMask/ocap-kernel/pull/913/changes#diff-264f75c66df4821245bc8352e848930024d74de093347c608e2ca5cc750926d4 |
- Add ENDPOINT_UNREACHABLE and DELIVERY_FAILED test cases to KernelRouter tests - Tighten OBJECT_DELETED and BAD_PROMISE_RESOLUTION assertions from expect.anything() to check for specific error codes - Verify CONNECTION_LOST in handleRemoteGiveUp rejection payload - Verify PEER_RESTARTED in handleIncarnationChange rejection payload Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Kernel errors surfaced to vats as promise rejections previously had no consistent format — some were plain strings, some Error objects, with no way for vat code to programmatically identify or categorize them.
This PR introduces a machine-readable error format:
[KERNEL:<CODE>] detailfor expected errors (vat code can handle gracefully) and[KERNEL:VAT_FATAL:<CODE>] detailfor fatal errors (vat gets terminated).vat-observable-errors.tsto@metamask/kernel-errorswithKernelErrorCodetypes,KERNEL_ERROR_PATTERNregex, andisKernelError/getKernelErrorCode/isFatalKernelErrordetection utilitiesmakeKernelErrorandmakeFatalKernelErrorhelpers tokernel-marshal.ts, importing shared types from@metamask/kernel-errorsmakeError(no remaining callers)@metamask/kernel-errorsREADME to delineate the three distinct error categories in the package (error classes, stream marshalling, vat-observable error codes) and explain why they exist as separate systemsNote: Four sites previously used
kser('string')which serialized a plain string as the rejection value. These now usemakeKernelError(...)which serializes an Error object. This is an intentional wire-format change — vat code that deserialized the rejection and checkedtypeof reason === 'string'would need updating.Testing
New unit tests cover the detection utilities (
vat-observable-errors.test.ts) and factory functions (kernel-marshal.test.ts), including round-trip verification through the@metamask/kernel-errorsdetection utilities. All existing unit tests in@metamask/ocap-kerneland integration tests in@ocap/kernel-testpass with updated assertions matching the new[KERNEL:*]format.Note
Medium Risk
Changes the wire format of promise rejections visible to vats (many string/opaque errors become serialized
Errors with[KERNEL:*]prefixes), which may break downstream error handling and affects multiple kernel routing/termination paths.Overview
Standardizes vat-observable kernel promise rejections to a machine-readable message format: expected errors as
[KERNEL:<CODE>] ...and fatal errors as[KERNEL:VAT_FATAL:<CODE>] ....Adds
@metamask/kernel-errorsutilities and types (KernelErrorCode,KERNEL_ERROR_PATTERN,isKernelError,getKernelErrorCode,isFatalKernelError) plus tests, and updates docs to clearly separate error-class vs stream-marshalling vs vat-observable error domains.Migrates kernel sites that surface errors to vats (
KernelRouter,RemoteManager,KernelServiceManager,VatHandle,VatSyscall) to use newmakeKernelError/makeFatalKernelErrorhelpers (replacing ad-hockser('string')/kser(Error)), introduces new explicit codes likeOBJECT_REVOKED,OBJECT_DELETED,BAD_PROMISE_RESOLUTION,ENDPOINT_UNREACHABLE,CONNECTION_LOST,PEER_RESTARTED,VAT_TERMINATED,DELIVERY_FAILED, and updates unit/e2e assertions accordingly.Written by Cursor Bugbot for commit 9538b10. This will update automatically on new commits. Configure here.