cardstack · backspace · May 14, 2026 · May 14, 2026 · May 15, 2026 · May 19, 2026
diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
@@ -2356,7 +2356,7 @@ export type EditCardFn = (
   opts?: { useBaseTemplate?: boolean },
 ) => void;
 
-export type SaveCardFn = (id: string) => void;
+export type SaveCardFn = (id: RealmResourceIdentifier) => void;
 
 export type DeleteCardFn = (cardOrId: CardDef | URL | string) => Promise<void>;
 
@@ -2740,7 +2740,9 @@ export class FileDef extends BaseDef {
     }
   }
 
-  @field id = contains(ReadOnlyField);
+  @field id: RealmResourceIdentifier = contains(
+    ReadOnlyField,
+  ) as unknown as RealmResourceIdentifier;
   @field sourceUrl = contains(StringField);
   @field url = contains(StringField);
   @field name = contains(StringField);
@@ -2900,7 +2902,9 @@ export class CardDef extends BaseDef {
     // notify glimmer to rerender this card
     notifyCardTracking(this);
   }
-  @field id = contains(ReadOnlyField);
+  @field id: RealmResourceIdentifier = contains(
+    ReadOnlyField,
+  ) as unknown as RealmResourceIdentifier;
   @field cardInfo = contains(CardInfoField);
   @field cardTitle = contains(StringField, {
     computeVia: function (this: CardDef) {
@@ -3462,7 +3466,7 @@ function trackRuntimeRelationshipModuleDependencies(
   }
 }
 
-export function setId(instance: CardDef, id: string) {
+export function setId(instance: CardDef, id: RealmResourceIdentifier) {
   let field = getField(instance, 'id');
   if (field) {
     setField(instance, field, id);

diff --git a/packages/base/matrix-event.gts b/packages/base/matrix-event.gts
@@ -27,6 +27,7 @@ import {
   CodeRef,
   APP_BOXEL_LLM_MODE,
   type LLMMode,
+  type RealmResourceIdentifier,
 } from '@cardstack/runtime-common';
 import { type SerializedFile } from './file-api';
 
@@ -191,7 +192,7 @@ export interface BoxelErrorForContext {
 
 export interface BoxelContext {
   agentId?: string;
-  openCardIds?: string[];
+  openCardIds?: RealmResourceIdentifier[];
   realmUrl?: string;
   realmPermissions?: {
     canRead: boolean;
@@ -210,7 +211,7 @@ export interface BoxelContext {
     currentFile?: string;
     moduleInspectorPanel?: string;
     previewPanelSelection?: {
-      cardId: string;
+      cardId: RealmResourceIdentifier;
       format: string;
     };
     selectedCodeRef?: CodeRef;

diff --git a/packages/catalog-realm/commands/collect-submission-files.ts b/packages/catalog-realm/commands/collect-submission-files.ts
@@ -9,6 +9,7 @@ import {
   planModuleInstall,
   type ListingPathResolver,
   type LooseSingleCardDocument,
+  type RealmResourceIdentifier,
   type Relationship,
 } from '@cardstack/runtime-common';
 import type { CopyInstanceMeta } from '@cardstack/runtime-common/catalog';
@@ -310,11 +311,11 @@ export default class CollectSubmissionFilesCommand extends Command<
     let getCardCommand = new GetCardCommand(this.commandContext);
     let serializeCardCommand = new SerializeCardCommand(this.commandContext);
 
-    const instancesById = new Map<string, CardDef>();
-    const visited = new Set<string>();
-    const queue: string[] = instances
+    const instancesById = new Map<RealmResourceIdentifier, CardDef>();
+    const visited = new Set<RealmResourceIdentifier>();
+    const queue: RealmResourceIdentifier[] = instances
       .map((instance) => instance.id)
-      .filter((id): id is string => typeof id === 'string');
+      .filter((id): id is RealmResourceIdentifier => typeof id === 'string');
 
     while (queue.length > 0) {
       const id = queue.shift();

diff --git a/packages/catalog-realm/crm-app/components/base-task-planner.gts b/packages/catalog-realm/crm-app/components/base-task-planner.gts
@@ -85,7 +85,6 @@ export type FilterType = 'status' | 'assignee';
 
 // Type definitions for the card structure
 export interface TaskCard extends CardDef {
-  id: string;
   status?: {
     label: string;
     index: number;

diff --git a/packages/catalog-realm/sprint-planner/components/base-task-planner.gts b/packages/catalog-realm/sprint-planner/components/base-task-planner.gts
@@ -85,7 +85,6 @@ export type FilterType = 'status' | 'assignee';
 
 // Type definitions for the card structure
 export interface TaskCard extends CardDef {
-  id: string;
   status?: {
     label: string;
     index: number;

diff --git a/packages/experiments-realm/components/base-task-planner.gts b/packages/experiments-realm/components/base-task-planner.gts
@@ -85,7 +85,6 @@ export type FilterType = 'status' | 'assignee';
 
 // Type definitions for the card structure
 export interface TaskCard extends CardDef {
-  id: string;
   status?: {
     label: string;
     index: number;

diff --git a/packages/host/app/commands/listing-install.ts b/packages/host/app/commands/listing-install.ts
@@ -11,6 +11,7 @@ import {
   PlanBuilder,
   extractRelationshipIds,
   type Relationship,
+  type RealmResourceIdentifier,
 } from '@cardstack/runtime-common';
 import { logger } from '@cardstack/runtime-common';
 import type { CopyInstanceMeta } from '@cardstack/runtime-common/catalog';
@@ -162,11 +163,11 @@ export default class ListingInstallCommand extends HostBaseCommand<
 
   // Walk relationships by fetching linked cards and enqueueing their ids.
   private async expandInstances(instances: CardDef[]): Promise<CardDef[]> {
-    let instancesById = new Map<string, CardDef>();
-    let visited = new Set<string>();
-    let queue: string[] = instances
+    let instancesById = new Map<RealmResourceIdentifier, CardDef>();
+    let visited = new Set<RealmResourceIdentifier>();
+    let queue: RealmResourceIdentifier[] = instances
       .map((instance) => instance.id)
-      .filter((id): id is string => typeof id === 'string');
+      .filter((id): id is RealmResourceIdentifier => typeof id === 'string');
 
     // - Queue of ids to traverse; visited prevents duplicate relationship ids.
     // - Each loop extracts relationship ids and enqueues them, so we descend

diff --git a/packages/host/app/commands/open-create-listing-modal.ts b/packages/host/app/commands/open-create-listing-modal.ts
@@ -1,6 +1,9 @@
 import { service } from '@ember/service';
 
-import { isFieldDef } from '@cardstack/runtime-common';
+import {
+  isFieldDef,
+  type RealmResourceIdentifier,
+} from '@cardstack/runtime-common';
 import { loadCardDef } from '@cardstack/runtime-common/code-ref';
 
 import type * as BaseCommandModule from 'https://cardstack.com/base/command';
@@ -42,7 +45,7 @@ export default class OpenCreateListingModalCommand extends HostBaseCommand<
     this.operatorModeStateService.showCreateListingModal({
       codeRef: input.codeRef,
       targetRealm: input.targetRealm,
-      openCardIds: input.openCardIds,
+      openCardIds: input.openCardIds as RealmResourceIdentifier[] | undefined,
       declarationKind,
     });
   }

diff --git a/packages/host/app/commands/show-card.ts b/packages/host/app/commands/show-card.ts
@@ -78,7 +78,7 @@ export default class ShowCardCommand extends HostBaseCommand<
       }
       this.playgroundPanelService.persistSelections(
         internalKeyFor(cardDefRef, undefined),
-        input.cardId,
+        rri(input.cardId),
         (input.format as Format) || 'isolated',
         undefined,
       );

diff --git a/packages/host/app/commands/update-playground-selection.ts b/packages/host/app/commands/update-playground-selection.ts
@@ -1,5 +1,7 @@
 import { service } from '@ember/service';
 
+import { rri } from '@cardstack/runtime-common';
+
 import type { Format } from 'https://cardstack.com/base/card-api';
 import type * as BaseCommandModule from 'https://cardstack.com/base/command';
 
@@ -27,7 +29,7 @@ export default class UpdatePlaygroundSelectionCommand extends HostBaseCommand<
   ): Promise<undefined> {
     this.playgroundPanelService.persistSelections(
       input.moduleId,
-      input.cardId,
+      rri(input.cardId),
       input.format as Format,
       input.fieldIndex,
     );

diff --git a/packages/host/app/components/matrix/room.gts b/packages/host/app/components/matrix/room.gts
@@ -36,7 +36,10 @@ import {
 } from '@cardstack/boxel-ui/components';
 import { and, eq, not } from '@cardstack/boxel-ui/helpers';
 
-import type { ResolvedCodeRef } from '@cardstack/runtime-common';
+import type {
+  RealmResourceIdentifier,
+  ResolvedCodeRef,
+} from '@cardstack/runtime-common';
 import {
   baseFileRef,
   formattedError,
@@ -1608,7 +1611,7 @@ export default class Room extends Component<Signature> {
       let openCardIds = new Set([
         ...(this.operatorModeStateService.getOpenCardIds() || []),
         ...this.autoAttachedCardIds,
-      ]);
+      ]) as Set<RealmResourceIdentifier>;
       let context =
         await this.operatorModeStateService.getSummaryForAIBot(openCardIds);
       try {

diff --git a/packages/host/app/components/operator-mode/code-submode/module-inspector.gts b/packages/host/app/components/operator-mode/code-submode/module-inspector.gts
@@ -411,7 +411,7 @@ export default class ModuleInspector extends Component<ModuleInspectorSignature>
       this.selectedDeclarationAsCodeRef,
       undefined,
     );
-    const cardId = id.replace(/\.json$/, '');
+    const cardId = rri(id.replace(/\.json$/, ''));
 
     const selections = window.localStorage.getItem(PlaygroundSelections);
     let existingFormat: Format = isField ? 'embedded' : 'isolated';

diff --git a/packages/host/app/components/operator-mode/code-submode/playground/playground-panel.gts b/packages/host/app/components/operator-mode/code-submode/playground/playground-panel.gts
@@ -703,7 +703,7 @@ export default class PlaygroundPanel extends Component<Signature> {
 
     this.playgroundPanelService.persistSelections(
       this.moduleId,
-      trimJsonExtension(selectedCardId),
+      rri(trimJsonExtension(selectedCardId)),
       selectedFormat,
       index, // `undefined` means we are previewing a card instances. fields MUST have a corresponding index
       // based on their position on their spec's containedExamples field. otherwise, it means that we are previewing

diff --git a/packages/host/app/components/operator-mode/workspace-chooser/workspace.gts b/packages/host/app/components/operator-mode/workspace-chooser/workspace.gts
@@ -34,7 +34,6 @@ import {
   hasExecutableExtension,
   RealmPaths,
   ri,
-  rri,
   SupportedMimeType,
 } from '@cardstack/runtime-common';
 
@@ -995,7 +994,7 @@ export default class Workspace extends Component<Signature> {
         this.operatorModeStateService.realmURL === this.args.realmURL ||
         this.operatorModeStateService
           .getOpenCardIds()
-          .some((cardId) => realmPath.inRealm(rri(cardId))) ||
+          .some((cardId) => realmPath.inRealm(cardId)) ||
         this.operatorModeStateService.codePathString?.startsWith(
           this.args.realmURL,
         );

diff --git a/packages/host/app/lib/gc-card-store.ts b/packages/host/app/lib/gc-card-store.ts
@@ -11,6 +11,7 @@ import {
   localId as localIdSymbol,
   loadCardDocument,
   loadFileMetaDocument,
+  rri,
   trackRuntimeFileDependency,
   trackRuntimeInstanceDependency,
   logger,
@@ -794,7 +795,7 @@ export default class CardStoreWithGarbageCollection implements CardStore {
         localId = remoteId.split('/').pop()!;
         item = bucket.get(localId) ?? silentBucket.get(localId);
         if (item && type === 'instance' && isCardOrFileInstance(item)) {
-          item.id = remoteId;
+          item.id = rri(remoteId);
         }
       }
     }

diff --git a/packages/host/app/resources/search.ts b/packages/host/app/resources/search.ts
@@ -25,7 +25,6 @@ import {
   buildQueryParamValue,
   parseSearchURL,
   ri,
-  rri,
   RealmPaths,
   runtimeDependencyContextWithSource,
 } from '@cardstack/runtime-common';
@@ -304,7 +303,7 @@ export class SearchResource<
       .map((realm) => {
         let realmPath = new RealmPaths(ri(realm));
         let cards = this.instances.filter((card) =>
-          realmPath.inRealm(rri(card.id)),
+          realmPath.inRealm(card.id),
         );
         return { realm, cards };
       })

diff --git a/packages/host/app/services/operator-mode-state-service.ts b/packages/host/app/services/operator-mode-state-service.ts
@@ -80,7 +80,7 @@ import type IndexController from '../controllers';
 export interface CreateListingModalPayload {
   codeRef: CodeRef;
   targetRealm: string;
-  openCardIds?: string[];
+  openCardIds?: RealmResourceIdentifier[];
   declarationKind: 'card' | 'field';
 }
 
@@ -687,15 +687,15 @@ export default class OperatorModeStateService extends Service {
     return undefined;
   }
 
-  getOpenCardIds(): string[] {
+  getOpenCardIds(): RealmResourceIdentifier[] {
     if (this._state.submode === Submodes.Code) {
-      let openCardsInCodeMode = [];
+      let openCardsInCodeMode: RealmResourceIdentifier[] = [];
       if (this.playgroundPanelSelection) {
         openCardsInCodeMode.push(this.playgroundPanelSelection.cardId);
       }
       // Alternatively we may simply be looking at a card in code mode
       if (this.isViewingCardInCodeMode) {
-        let cardId = this.codePathString!.replace(/\.json$/, '');
+        let cardId = rri(this.codePathString!.replace(/\.json$/, ''));
         if (!openCardsInCodeMode.includes(cardId)) {
           openCardsInCodeMode.push(cardId);
         }
@@ -706,7 +706,7 @@ export default class OperatorModeStateService extends Service {
       return this.topMostStackItems()
         .filter((stackItem: StackItem) => stackItem)
         .map((stackItem: StackItem) => stackItem.id)
-        .filter(Boolean) as string[];
+        .filter(Boolean) as RealmResourceIdentifier[];
     }
   }
 
@@ -820,8 +820,10 @@ export default class OperatorModeStateService extends Service {
     return undefined;
   }
 
-  get codePathString() {
-    return this._state.codePath?.toString();
+  get codePathString(): RealmResourceIdentifier | undefined {
+    return this._state.codePath?.toString() as
+      | RealmResourceIdentifier
+      | undefined;
   }
 
   onFileSelected = async (entryPath: LocalPath) => {
@@ -1460,7 +1462,9 @@ export default class OperatorModeStateService extends Service {
   }
 
   async getSummaryForAIBot(
-    openCardIdsSet: Set<string> = new Set([...this.getOpenCardIds()]),
+    openCardIdsSet: Set<RealmResourceIdentifier> = new Set([
+      ...this.getOpenCardIds(),
+    ]),
   ): Promise<BoxelContext> {
     let codeMode: BoxelContext['codeMode'] = undefined;
     if (this._state.workspaceChooserOpened) {
@@ -1506,7 +1510,7 @@ export default class OperatorModeStateService extends Service {
       if (this.isViewingCardInCodeMode) {
         codeMode.moduleInspectorPanel = 'preview';
         codeMode.previewPanelSelection = {
-          cardId: this.codePathString!.replace(/\.json$/, ''),
+          cardId: rri(this.codePathString!.replace(/\.json$/, '')),
           format: this.currentViewingFormat ?? 'isolated',
         };
       } else {
@@ -1554,7 +1558,9 @@ export default class OperatorModeStateService extends Service {
     return result;
   }
 
-  private makeRemoteIdsList(ids: (string | undefined)[]) {
+  private makeRemoteIdsList(
+    ids: (RealmResourceIdentifier | undefined)[],
+  ): RealmResourceIdentifier[] {
     return ids
       .map((id) => {
         if (!id) {
@@ -1574,7 +1580,7 @@ export default class OperatorModeStateService extends Service {
         }
         return id;
       })
-      .filter(Boolean) as string[];
+      .filter(Boolean) as RealmResourceIdentifier[];
   }
 }
 

diff --git a/packages/host/app/services/playground-panel-service.ts b/packages/host/app/services/playground-panel-service.ts
@@ -8,7 +8,12 @@ import { task } from 'ember-concurrency';
 import window from 'ember-window-mock';
 import { TrackedObject } from 'tracked-built-ins';
 
-import { isCardInstance, localId, isLocalId } from '@cardstack/runtime-common';
+import {
+  isCardInstance,
+  localId,
+  isLocalId,
+  type RealmResourceIdentifier,
+} from '@cardstack/runtime-common';
 
 import { PlaygroundSelections } from '@cardstack/host/utils/local-storage-keys';
 
@@ -26,7 +31,7 @@ import type ResetService from './reset';
 import type StoreService from './store';
 
 export interface PlaygroundSelection {
-  cardId: string; // for fields, this is their corresponding spec card's id, since fields do not have a card id
+  cardId: RealmResourceIdentifier; // for fields, this is their corresponding spec card's id, since fields do not have a card id
   format: Format; // default is 'isolated' for cards, 'embedded' for fields
   fieldIndex?: number;
   /* fieldIndex `undefined` means we are previewing a card instances. fields MUST have a corresponding index
@@ -73,7 +78,7 @@ export default class PlaygroundPanelService extends Service {
 
   persistSelections = (
     moduleId: string,
-    cardId: string,
+    cardId: RealmResourceIdentifier,
     format: Format,
     fieldIndex: number | undefined,
   ) => {