Skip to content

Add branded types for kernel identifier strings #809

@rekmarks

Description

@rekmarks

Summary

The kernel uses several string types to identify various entities (subclusters, vats, krefs, etc.). These are currently just type aliases for string, which makes them interchangeable at compile time even though they represent semantically different values.

Current State

In packages/ocap-kernel/src/types.ts:

  • VatId = string
  • RemoteId = string
  • SubclusterId = string
  • KRef, VRef, RRef = string

Proposed Change

Add TypeScript branded types to prevent accidental misuse of identifier types.

Benefits

  1. Type Safety: Prevents accidentally passing a VatId where a SubclusterId is expected
  2. Self-Documenting: Makes API contracts clearer
  3. Compile-Time Checks: Catches errors without runtime overhead

Considerations

  • Need factory functions or type assertions to create branded values
  • Existing validation functions (isVatId, isSubclusterId, etc.) would serve as type guards
  • May require updates throughout the codebase where these types are used

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions