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

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions