refactor(ocap-kernel): branded kernel identifiers with runtime validation (#917)

Fixes #809 

## Summary
- Add branded string types (`VatId`, `RemoteId`, `KRef`, `VRef`, `RRef`,
`SubclusterId`, `GCAction`, etc.) for kernel identifiers with runtime
validators (`isX`/`insistX`)
- Split `Message` into `KernelMessage` (kernel-space, KRef slots) and
`EndpointMessage` (endpoint-space, ERef slots)
- Remove public `kv` from `KernelStore` API, replace with typed accessor
methods
- Add `KernelOneResolution` type for kernel-space promise resolutions
- Add `KernelSyscallObject` discriminated union type for kernel-space
syscalls, removing casts from `VatSyscall`
- Add `makeGCAction` factory with runtime validation
- Remove redundant interior runtime validation where branded types
enforce correctness at compile time
- Tighten function signatures throughout OCAP URL redemption chain and
`kslot`/`makeStandinPromise` to use `KRef`
- Validate `coerceEndpointMessage` with `EndpointMessageStruct` at the
liveslots boundary
- Fix `getOwner` to handle `'kernel'` owner without throwing EndpointId
validation failure
- Document branded type trust model (types.ts header, store README)
- Add comprehensive tests for all ref validators and assertion functions

## TODO

- `kernel-ui` type safety is not fully addressed by this PR, and will be
implemented in a follow-up
- While the API of the kernel store is type safe, it is only type safe
by an established convention of `writeX(value: X): void` / `readX(): X`
pairs that use the same db keys internally. If we want to make the store
actually type safe, we would have to establish some kind of compile-time
mapping between db keys and value types. This may or may not be worth
the trouble, and we defer this decision to the future.

## Test plan
- [x] `yarn workspace @MetaMask/ocap-kernel lint:fix` passes
- [x] `yarn workspace @MetaMask/ocap-kernel build` passes
- [x] `yarn workspace @MetaMask/ocap-kernel test:dev:quiet` passes
- [x] `yarn workspace @metamask/kernel-node-runtime test:e2e:ci` passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches core kernel routing/queueing, remote comms, and persistence
access patterns; while largely type-safety refactors, signature changes
and reduced runtime checks could surface as behavioral regressions at
boundaries (RPC/liveslots/remotes) if any call sites or stored data
violate the new invariants.
> 
> **Overview**
> **Branded kernel identifiers are enforced end-to-end.** This
introduces branded string types (e.g., `KRef`, `VatId`, `SubclusterId`)
with `is*`/`insist*` validators, and updates kernel/public RPC APIs
(e.g., `queueMessage`, `issueOcapURL`, `terminateSubcluster`) and UI
call sites to use these types.
> 
> **Message and resolution types are split and tightened.** `Message` is
separated into `KernelMessage` vs `EndpointMessage`, promise resolution
flows switch to kernel-space types, and the
queue/router/service-manager/remotes paths are updated accordingly
(including narrowed `kslot`/`krefOf` behavior).
> 
> **Raw KV access is removed from `KernelStore`.** `KernelStore.kv` is
no longer exposed; consumers/tests now use typed accessors for
initialization state, kernel-service krefs, remote identity values, and
known relay storage (with added validation on relay parsing).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
812f5bf. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rekmarks

packages/kernel-store/src/sqlite/nodejs.ts

@@ -108,9 +108,11 @@ function makeKVStore(db: Database): KVStore {
   }
 
   return {
-    get: (key) => kvGet(key, false),
+    get: <Value extends string = string>(key: string) =>
+      kvGet(key, false) as Value | undefined,
     getNextKey: kvGetNextKey,
-    getRequired: (key) => kvGet(key, true) as string,
+    getRequired: <Value extends string = string>(key: string) =>
+      kvGet(key, true) as Value,
     set: kvSet,
     delete: kvDelete,
   };

packages/kernel-store/src/sqlite/wasm.ts

@@ -137,9 +137,11 @@ function makeKVStore(db: Database, logger?: Logger): KVStore {
   }
 
   return {
-    get: (key) => kvGet(key, false),
+    get: <Value extends string = string>(key: string) =>
+      kvGet(key, false) as Value | undefined,
     getNextKey: kvGetNextKey,
-    getRequired: (key) => kvGet(key, true) as string,
+    getRequired: <Value extends string = string>(key: string) =>
+      kvGet(key, true) as Value,
     set: kvSet,
     delete: kvDelete,
   };

packages/kernel-store/src/types.ts

@@ -1,6 +1,6 @@
 export type KVStore = {
-  get(key: string): string | undefined;
-  getRequired(key: string): string;
+  get<Value extends string = string>(key: string): Value | undefined;
+  getRequired<Value extends string = string>(key: string): Value;
   getNextKey(previousKey: string): string | undefined;
   set(key: string, value: string): void;
   delete(key: string): void;

packages/kernel-test/src/persistence.test.ts

@@ -1,7 +1,7 @@
 import type { CapData } from '@endo/marshal';
 import { makeSQLKernelDatabase } from '@metamask/kernel-store/sqlite/nodejs';
 import { waitUntilQuiescent } from '@metamask/kernel-utils';
-import { kunser, makeKernelStore } from '@metamask/ocap-kernel';
+import { kunser } from '@metamask/ocap-kernel';
 import { unlink } from 'node:fs/promises';
 import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 
@@ -153,7 +153,7 @@ describe('persistent storage', { timeout: 20_000 }, () => {
 
   it('handles messages in queue after kernel restart', async () => {
     const database1 = await makeSQLKernelDatabase({ dbFilename: databasePath });
-    const kernelStore1 = makeKernelStore(database1);
+    const kv1 = database1.kernelKVStore;
     const kernel1 = await makeKernel(
       database1,
       false,
@@ -168,31 +168,31 @@ describe('persistent storage', { timeout: 20_000 }, () => {
     const result1 = await kernel1.queueMessage(v1Root, 'resume', []);
     expect(kunser(result1)).toBe('Counter incremented to: 2');
     // Enqueue a send message into the database
-    kernelStore1.kv.set('queue.run.head', '4');
-    kernelStore1.kv.set('nextPromiseId', '4');
-    kernelStore1.kv.set(`${v1Root}.refCount`, '3,3');
-    kernelStore1.kv.set('queue.kp3.head', '1');
-    kernelStore1.kv.set('queue.kp3.tail', '1');
-    kernelStore1.kv.set('kp3.state', 'unresolved');
-    kernelStore1.kv.set('kp3.subscribers', '[]');
-    kernelStore1.kv.set('kp3.refCount', '2');
-    kernelStore1.kv.set(
+    kv1.set('queue.run.head', '4');
+    kv1.set('nextPromiseId', '4');
+    kv1.set(`${v1Root}.refCount`, '3,3');
+    kv1.set('queue.kp3.head', '1');
+    kv1.set('queue.kp3.tail', '1');
+    kv1.set('kp3.state', 'unresolved');
+    kv1.set('kp3.subscribers', '[]');
+    kv1.set('kp3.refCount', '2');
+    kv1.set(
       'queue.run.3',
       `{"type":"send","target":"${v1Root}","message":{"methargs":{"body":"#[\\"resume\\",[]]","slots":[]},"result":"kp3"}}`,
     );
     await kernel1.stop();
     // Open a fresh connection to verify the message is in the database
     const database2 = await makeSQLKernelDatabase({ dbFilename: databasePath });
-    const kernelStore2 = makeKernelStore(database2);
-    expect(kernelStore2.kv.get('queue.run.3')).toBeDefined();
+    const kv2 = database2.kernelKVStore;
+    expect(kv2.get('queue.run.3')).toBeDefined();
     // restart the kernel
     const kernel2 = await makeKernel(
       database2,
       false,
       logger.logger.subLogger({ tags: ['test'] }),
     );
     // verify that the run queue is empty
-    expect(kernelStore2.kv.get('queue.run.3')).toBeUndefined();
+    expect(kv2.get('queue.run.3')).toBeUndefined();
     // verify that the message is processed and the counter is incremented
     const result2 = await kernel2.queueMessage(v1Root, 'resume', []);
     expect(kunser(result2)).toBe('Counter incremented to: 4');

packages/kernel-ui/src/components/SendMessageForm.tsx

@@ -9,6 +9,7 @@ import {
   TextColor,
 } from '@metamask/design-system-react';
 import { stringify } from '@metamask/kernel-utils';
+import type { KRef } from '@metamask/ocap-kernel';
 import type { Json } from '@metamask/utils';
 import { useState, useMemo } from 'react';
 
@@ -68,7 +69,7 @@ export const SendMessageForm: React.FC = () => {
       .then(async (args) =>
         callKernelMethod({
           method: 'queueMessage',
-          params: [target, method, args],
+          params: [target as KRef, method, args],
         }),
       )
       .then((response) => {

packages/kernel-ui/src/components/SubclusterAccordion.tsx

@@ -7,6 +7,7 @@ import {
   TextVariant,
 } from '@metamask/design-system-react';
 import { stringify } from '@metamask/kernel-utils';
+import type { SubclusterId, VatId } from '@metamask/ocap-kernel';
 import { useMemo, useState } from 'react';
 
 import type { VatRecord } from '../types.ts';
@@ -15,13 +16,13 @@ import { Modal } from './shared/Modal.tsx';
 import { VatTable } from './VatTable.tsx';
 
 export const SubclusterAccordion: React.FC<{
-  id: string;
+  id: SubclusterId;
   vats: VatRecord[];
   config: unknown;
-  onPingVat: (id: string) => void;
-  onRestartVat: (id: string) => void;
-  onTerminateVat: (id: string) => void;
-  onTerminateSubcluster: (id: string) => void;
+  onPingVat: (id: VatId) => void;
+  onRestartVat: (id: VatId) => void;
+  onTerminateVat: (id: VatId) => void;
+  onTerminateSubcluster: (id: SubclusterId) => void;
 }> = ({
   id,
   vats,

packages/kernel-ui/src/components/VatTable.tsx

@@ -5,6 +5,7 @@ import {
   IconName,
   ButtonIcon,
 } from '@metamask/design-system-react';
+import type { VatId } from '@metamask/ocap-kernel';
 
 import type { VatRecord } from '../types.ts';
 import {
@@ -17,9 +18,9 @@ import {
 
 export const VatTable: React.FC<{
   vats: VatRecord[];
-  onPingVat: (id: string) => void;
-  onRestartVat: (id: string) => void;
-  onTerminateVat: (id: string) => void;
+  onPingVat: (id: VatId) => void;
+  onRestartVat: (id: VatId) => void;
+  onTerminateVat: (id: VatId) => void;
 }> = ({ vats, onPingVat, onRestartVat, onTerminateVat }) => {
   if (vats.length === 0) {
     return null;

packages/kernel-ui/src/hooks/useVats.ts

@@ -2,6 +2,7 @@ import { stringify } from '@metamask/kernel-utils';
 import type {
   VatConfig,
   VatId,
+  SubclusterId,
   Subcluster,
   KernelStatus,
 } from '@metamask/ocap-kernel';
@@ -45,7 +46,7 @@ export const useVats = (): {
   pingVat: (id: VatId) => void;
   restartVat: (id: VatId) => void;
   terminateVat: (id: VatId) => void;
-  terminateSubcluster: (id: string) => void;
+  terminateSubcluster: (id: SubclusterId) => void;
   hasVats: boolean;
 } => {
   const { callKernelMethod, status, logMessage } = usePanelContext();
@@ -120,7 +121,7 @@ export const useVats = (): {
   );
 
   const terminateSubcluster = useCallback(
-    (id: string) => {
+    (id: SubclusterId) => {
       callKernelMethod({
         method: 'terminateSubcluster',
         params: { id },

packages/kernel-ui/src/services/db-parser.ts

@@ -1,3 +1,5 @@
+import type { KRef } from '@metamask/ocap-kernel';
+
 import type {
   ObjectRegistry,
   VatSnapshot,
@@ -22,8 +24,8 @@ export function parseObjectRegistry(
   const kpValueRaw: Record<string, { body: string; slots: string[] }> = {};
   const vatConfigs: Record<string, { name: string; bundleSpec: string }> = {};
   // C-lists
-  const objCList: { vat: string; kref: string; eref: string }[] = [];
-  const prmCList: { vat: string; kref: string; eref: string }[] = [];
+  const objCList: { vat: string; kref: KRef; eref: string }[] = [];
+  const prmCList: { vat: string; kref: KRef; eref: string }[] = [];
 
   let gcActions = '';
   let reapQueue = '';
@@ -78,7 +80,7 @@ export function parseObjectRegistry(
       matches[1] &&
         objCList.push({
           vat: matches[1] ?? '',
-          kref: matches[2] ?? '',
+          kref: (matches[2] ?? '') as KRef,
           eref: value.replace(/^R\s*/u, ''),
         });
       continue;
@@ -87,7 +89,7 @@ export function parseObjectRegistry(
       matches[1] &&
         prmCList.push({
           vat: matches[1] ?? '',
-          kref: matches[2] ?? '',
+          kref: (matches[2] ?? '') as KRef,
           eref: value.replace(/^R\s*/u, ''),
         });
       continue;
@@ -112,7 +114,11 @@ export function parseObjectRegistry(
   // Helper to resolve slots
   const resolveSlot = (kref: string): SlotInfo => {
     const entry = objCList.find((item) => item.kref === kref);
-    return { kref, eref: entry?.eref ?? null, vat: entry?.vat ?? null };
+    return {
+      kref: kref as KRef,
+      eref: entry?.eref ?? null,
+      vat: entry?.vat ?? null,
+    };
   };
 
   // 3) Populate objects

packages/kernel-ui/src/types.ts

@@ -1,11 +1,11 @@
-import type { VatId } from '@metamask/ocap-kernel';
+import type { KRef, SubclusterId, VatId } from '@metamask/ocap-kernel';
 
 export type VatRecord = {
   id: VatId;
   source: string;
   parameters: string;
   creationOptions: string;
-  subclusterId: string;
+  subclusterId: SubclusterId;
 };
 
 /**
@@ -37,7 +37,7 @@ export type VatSnapshot = {
 };
 
 export type ObjectBinding = {
-  kref: string;
+  kref: KRef;
   eref: string;
   refCount: string;
 };
@@ -52,7 +52,7 @@ export type ObjectBindingWithTargets = {
 } & ObjectBinding;
 
 export type PromiseBinding = {
-  kref: string;
+  kref: KRef;
   eref: string;
   state: string;
   value: { body: string; slots: SlotInfo[] };
@@ -67,7 +67,7 @@ export type PromiseBindingWithTargets = {
 } & PromiseBinding;
 
 export type SlotInfo = {
-  kref: string;
+  kref: KRef;
   eref: string | null;
   vat: string | null;
 };