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
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
1 participant
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).kernel-error.tsto@metamask/kernel-errorswithKernelErrorCodetypes,KERNEL_ERROR_PATTERNregex, andisKernelError/getKernelErrorCode/isFatalKernelErrordetection utilitiesmakeKernelErrorandmakeFatalKernelErrorhelpers tokernel-marshal.ts, importing shared types from@metamask/kernel-errorsNote: 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 (
kernel-error.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 rejection wire format for multiple kernel promise failures from ad-hoc strings/errors to structured
[KERNEL:*]Error messages, which may break vat code that inspects rejection values. Touches core message routing, remote handling, vat termination, and syscall fatal-error reporting paths.Overview
Standardizes errors surfaced to vat-land as promise rejections by introducing a machine-readable kernel error message format: expected errors as
[KERNEL:<CODE>] <detail>and fatal errors as[KERNEL:VAT_FATAL:<CODE>] <detail>.Adds
@metamask/kernel-errorsutilities and types (KernelErrorCode,KERNEL_ERROR_PATTERN,isKernelError,getKernelErrorCode,isFatalKernelError) plus tests, and updateskernel-marshalwithmakeKernelError/makeFatalKernelError(deprecatingmakeError).Migrates key kernel rejection sites (
KernelRouter,RemoteManager,VatHandle,VatSyscall,KernelServiceManager) to emit these coded errors and updates integration/unit tests to assert against the new[KERNEL:...]strings (including removing peerId details from some remote-connection-loss messages).Written by Cursor Bugbot for commit 3b6db98. This will update automatically on new commits. Configure here.