From 3e9b246b1daf1a6eaaacb6bad33381100754b83d Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Tue, 20 Jan 2026 17:45:28 -0500
Subject: [PATCH] Basic ability to choose a file for a linksTo(FileDef) field

- Improves cache invalidation when linked-to files haven't been indexed yet
---
 packages/base/card-api.gts                    | 11 +--
 packages/base/links-to-editor.gts             | 13 ++-
 packages/base/links-to-many-component.gts     |  9 +-
 .../operator-mode/choose-file-modal.gts       | 18 ++--
 packages/host/app/services/store.ts           | 26 ++++++
 .../acceptance/interact-submode-test.gts      | 52 ++++++++++-
 .../tests/helpers/interact-submode-setup.gts  | 38 ++++++--
 .../components/card-basics-test.gts           | 11 +--
 .../host/tests/integration/realm-test.gts     | 42 +++++++++
 .../host/tests/integration/store-test.gts     | 31 +++++++
 packages/runtime-common/document.ts           |  9 +-
 packages/runtime-common/error.ts              |  2 +-
 packages/runtime-common/file-def-map.ts       | 38 ++++++++
 packages/runtime-common/index-runner.ts       | 38 +-------
 packages/runtime-common/index.ts              |  7 ++
 .../runtime-common/realm-index-updater.ts     | 11 +++
 packages/runtime-common/realm.ts              | 88 ++-----------------
 17 files changed, 280 insertions(+), 164 deletions(-)
 create mode 100644 packages/runtime-common/file-def-map.ts

diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
index 273c39401e..1711c68fcc 100644
--- a/packages/base/card-api.gts
+++ b/packages/base/card-api.gts
@@ -1318,9 +1318,8 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
       format: Format | undefined,
       defaultFormat: Format,
       isComputed: boolean,
-      isFileDef: boolean,
     ) {
-      return (format ?? defaultFormat) === 'edit' && !isComputed && !isFileDef;
+      return (format ?? defaultFormat) === 'edit' && !isComputed;
     }
     function getChildFormat(
       format: Format | undefined,
@@ -1354,9 +1353,7 @@ class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
         <CardCrudFunctionsConsumer as |cardCrudFunctions|>
           <DefaultFormatsConsumer as |defaultFormats|>
             {{#if
-              (shouldRenderEditor
-                @format defaultFormats.cardDef isComputed isFileDef
-              )
+              (shouldRenderEditor @format defaultFormats.cardDef isComputed)
             }}
               <LinksToEditor
                 @model={{(getInnerModel)}}
@@ -2859,6 +2856,10 @@ function lazilyLoadLink(
       if (isCardError(error) && error.deps?.length) {
         payloadError.deps = [...new Set(error.deps)];
       }
+      if (isMissingFile) {
+        let missingDep = isFileLink ? reference : referenceForMissingFile;
+        payloadError.deps = [...new Set([...(payloadError.deps ?? []), missingDep])];
+      }
       let payload = JSON.stringify({
         type: 'error',
         error: payloadError,
diff --git a/packages/base/links-to-editor.gts b/packages/base/links-to-editor.gts
index d451f07b60..16409ae136 100644
--- a/packages/base/links-to-editor.gts
+++ b/packages/base/links-to-editor.gts
@@ -10,16 +10,17 @@ import {
   getBoxComponent,
 } from './field-component';
 import {
-  type CardDef,
   type BaseDef,
   type Box,
   type Field,
   type CardContext,
   type LinkableDefConstructor,
   CreateCardFn,
+  isFileDefConstructor,
 } from './card-api';
 import {
   chooseCard,
+  chooseFile,
   baseCardRef,
   identifyCard,
   CardContextName,
@@ -37,7 +38,7 @@ import { hash } from '@ember/helper';
 interface Signature {
   Element: HTMLElement;
   Args: {
-    model: Box<CardDef | null>;
+    model: Box<BaseDef | null>;
     field: Field<LinkableDefConstructor>;
     typeConstraint?: ResolvedCodeRef;
     createCard?: CreateCardFn;
@@ -166,6 +167,14 @@ export class LinksToEditor extends GlimmerComponent<Signature> {
   }
 
   private chooseCard = restartableTask(async () => {
+    if (isFileDefConstructor(this.args.field.card as typeof BaseDef)) {
+      let file = await chooseFile();
+      if (file) {
+        this.args.model.value = file;
+      }
+      return;
+    }
+
     let type = identifyCard(this.args.field.card) ?? baseCardRef;
     if (this.args.typeConstraint) {
       type = await getNarrowestType(this.args.typeConstraint, type, myLoader());
diff --git a/packages/base/links-to-many-component.gts b/packages/base/links-to-many-component.gts
index 2a6b173fd2..438c2017be 100644
--- a/packages/base/links-to-many-component.gts
+++ b/packages/base/links-to-many-component.gts
@@ -482,9 +482,8 @@ function shouldRenderEditor(
   format: Format | undefined,
   defaultFormat: Format,
   isComputed: boolean,
-  isFileDef: boolean,
 ) {
-  return (format ?? defaultFormat) === 'edit' && !isComputed && !isFileDef;
+  return (format ?? defaultFormat) === 'edit' && !isComputed;
 }
 const componentCache = initSharedState(
   'linksToManyComponentCache',
@@ -519,11 +518,7 @@ export function getLinksToManyComponent({
   let linksToManyComponent = class LinksToManyComponent extends GlimmerComponent<BoxComponentSignature> {
     <template>
       <DefaultFormatsConsumer as |defaultFormats|>
-        {{#if
-          (shouldRenderEditor
-            @format defaultFormats.cardDef isComputed isFileDef
-          )
-        }}
+        {{#if (shouldRenderEditor @format defaultFormats.cardDef isComputed)}}
           <LinksToManyEditor
             @model={{model}}
             @arrayField={{arrayField}}
diff --git a/packages/host/app/components/operator-mode/choose-file-modal.gts b/packages/host/app/components/operator-mode/choose-file-modal.gts
index 8374016328..231a99086a 100644
--- a/packages/host/app/components/operator-mode/choose-file-modal.gts
+++ b/packages/host/app/components/operator-mode/choose-file-modal.gts
@@ -20,14 +20,14 @@ import {
   Deferred,
   RealmPaths,
   type LocalPath,
+  isCardErrorJSONAPI,
 } from '@cardstack/runtime-common';
 
 import ModalContainer from '@cardstack/host/components/modal-container';
 
-import type MatrixService from '@cardstack/host/services/matrix-service';
 import type OperatorModeStateService from '@cardstack/host/services/operator-mode-state-service';
-
 import type RealmService from '@cardstack/host/services/realm';
+import type StoreService from '@cardstack/host/services/store';
 
 import type { FileDef } from 'https://cardstack.com/base/file-api';
 
@@ -44,7 +44,7 @@ export default class ChooseFileModal extends Component<Signature> {
 
   @service private declare operatorModeStateService: OperatorModeStateService;
   @service private declare realm: RealmService;
-  @service private declare matrixService: MatrixService;
+  @service private declare store: StoreService;
 
   constructor(owner: Owner, args: Signature['Args']) {
     super(owner, args);
@@ -72,13 +72,15 @@ export default class ChooseFileModal extends Component<Signature> {
   }
 
   @action
-  private pick(path: LocalPath | undefined) {
+  private async pick(path: LocalPath | undefined) {
     if (this.deferred && this.selectedRealm && path) {
       let fileURL = new RealmPaths(this.selectedRealm.url).fileURL(path);
-      let file = this.matrixService.fileAPI.createFileDef({
-        sourceUrl: fileURL.toString(),
-        name: fileURL.toString().split('/').pop()!,
-      });
+      let file = await this.store.getFileMeta<FileDef>(fileURL.href);
+      if (isCardErrorJSONAPI(file)) {
+        throw new Error(
+          `choose-file-modal: failed to load file meta for ${fileURL.href}`,
+        );
+      }
       this.deferred.fulfill(file);
     }
 
diff --git a/packages/host/app/services/store.ts b/packages/host/app/services/store.ts
index 319c8b2000..36f534e1bf 100644
--- a/packages/host/app/services/store.ts
+++ b/packages/host/app/services/store.ts
@@ -52,6 +52,7 @@ import {
 
 import type { CardDef, BaseDef } from 'https://cardstack.com/base/card-api';
 import type * as CardAPI from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 
 import type { RealmEventContent } from 'https://cardstack.com/base/matrix-event';
 
@@ -377,6 +378,31 @@ export default class StoreService extends Service implements StoreInterface {
     return await this.getInstance<T>({ idOrDoc: id });
   }
 
+  async getFileMeta<T extends FileDef>(
+    url: string,
+  ): Promise<T | CardErrorJSONAPI> {
+    return await this.withTestWaiters(async () => {
+      try {
+        let fileMetaDoc = await this.store.loadFileMetaDocument(url);
+        if (isCardError(fileMetaDoc)) {
+          throw fileMetaDoc;
+        }
+        let api = await this.cardService.getAPI();
+        let fileInstance = await api.createFromSerialized(
+          fileMetaDoc.data,
+          fileMetaDoc,
+          fileMetaDoc.data.id ? new URL(fileMetaDoc.data.id) : new URL(url),
+          { store: this.store },
+        );
+        this.setIdentityContext(fileInstance as unknown as CardDef);
+        return fileInstance as unknown as T;
+      } catch (error: any) {
+        let errorResponse = processCardError(url, error);
+        return errorResponse.errors[0];
+      }
+    });
+  }
+
   // Bypass cached state and fetch from source of truth
   async getWithoutCache<T extends CardDef>(
     id: string,
diff --git a/packages/host/tests/acceptance/interact-submode-test.gts b/packages/host/tests/acceptance/interact-submode-test.gts
index f089f925eb..b26e0a6d50 100644
--- a/packages/host/tests/acceptance/interact-submode-test.gts
+++ b/packages/host/tests/acceptance/interact-submode-test.gts
@@ -6,6 +6,7 @@ import {
   typeIn,
   triggerKeyEvent,
   settled,
+  waitFor,
 } from '@ember/test-helpers';
 
 import { triggerEvent } from '@ember/test-helpers';
@@ -511,7 +512,7 @@ module('Acceptance | interact submode tests', function (hooks) {
     });
 
     test('clicking a linked file opens it as a new isolated stack item', async function (assert) {
-      let fileId = `${testRealmURL}FileLinkCard/notes.txt`;
+      let fileId = `${testRealmURL}FileLinkCard/notes.md`;
       await visitOperatorMode({
         stacks: [
           [
@@ -549,6 +550,55 @@ module('Acceptance | interact submode tests', function (hooks) {
       });
     });
 
+    test('can link a file via the chooser and index the update', async function (assert) {
+      let cardId = `${testRealmURL}FileLinkCard/empty`;
+      await visitOperatorMode({
+        stacks: [
+          [
+            {
+              id: cardId,
+              format: 'edit',
+            },
+          ],
+        ],
+      });
+
+      let messageService = getService('message-service');
+      let receivedEventDeferred = new Deferred<IncrementalIndexEventContent>();
+      messageService.listenerCallbacks.get(testRealmURL)!.push((ev) => {
+        if (
+          ev.eventName === 'index' &&
+          ev.indexType === 'incremental-index-initiation'
+        ) {
+          return; // ignore the index initiation event
+        }
+        if (ev.eventName === 'index' && ev.indexType === 'incremental') {
+          receivedEventDeferred.fulfill(ev as IncrementalIndexEventContent);
+        }
+      });
+
+      await click(
+        `[data-test-links-to-editor="attachment"] [data-test-add-new="attachment"]`,
+      );
+      await waitFor('[data-test-file="README.md"]');
+      await click('[data-test-file="README.md"]');
+      await click('[data-test-choose-file-modal-add-button]');
+
+      await click('[data-test-edit-button]');
+
+      assert
+        .dom(
+          `[data-test-stack-card="${cardId}"] [data-test-file-link-attachment]`,
+        )
+        .includesText('Hello World', 'linked file is rendered');
+
+      let indexEvent = await receivedEventDeferred.promise;
+      assert.ok(
+        indexEvent.invalidations.includes(cardId),
+        'indexing invalidates the edited card',
+      );
+    });
+
     test('can save mutated card without having opened in stack', async function (assert) {
       await visitOperatorMode({
         stacks: [
diff --git a/packages/host/tests/helpers/interact-submode-setup.gts b/packages/host/tests/helpers/interact-submode-setup.gts
index 6cc37ea5f1..4c0986b3a4 100644
--- a/packages/host/tests/helpers/interact-submode-setup.gts
+++ b/packages/host/tests/helpers/interact-submode-setup.gts
@@ -56,12 +56,12 @@ export function setupInteractSubmodeTests(
     let string: typeof import('https://cardstack.com/base/string');
     let spec: typeof import('https://cardstack.com/base/spec');
     let cardsGrid: typeof import('https://cardstack.com/base/cards-grid');
-    let fileApi: typeof import('https://cardstack.com/base/file-api');
+    let markdownFileDef: typeof import('https://cardstack.com/base/markdown-file-def');
     cardApi = await loader.import(`${baseRealm.url}card-api`);
     string = await loader.import(`${baseRealm.url}string`);
     spec = await loader.import(`${baseRealm.url}spec`);
     cardsGrid = await loader.import(`${baseRealm.url}cards-grid`);
-    fileApi = await loader.import(`${baseRealm.url}file-api`);
+    markdownFileDef = await loader.import(`${baseRealm.url}markdown-file-def`);
 
     let {
       field,
@@ -76,7 +76,7 @@ export function setupInteractSubmodeTests(
     let { default: StringField } = string;
     let { Spec } = spec;
     let { CardsGrid } = cardsGrid;
-    let { FileDef } = fileApi;
+    let { MarkdownDef } = markdownFileDef;
 
     class Pet extends CardDef {
       static displayName = 'Pet';
@@ -245,7 +245,7 @@ export function setupInteractSubmodeTests(
     class FileLinkCard extends CardDef {
       static displayName = 'File Link Card';
       @field title = contains(StringField);
-      @field attachment = linksTo(FileDef);
+      @field attachment = linksTo(MarkdownDef);
 
       static isolated = class Isolated extends Component<typeof this> {
         <template>
@@ -313,8 +313,8 @@ export function setupInteractSubmodeTests(
         'personnel.gts': { Personnel },
         'pet.gts': { Pet, Puppy },
         'shipping-info.gts': { ShippingInfo },
-        'README.txt': `Hello World`,
-        'FileLinkCard/notes.txt': 'Hello from a file link',
+        'README.md': `# Hello World`,
+        'FileLinkCard/notes.md': '# Hello from a file link',
         'person-entry.json': new Spec({
           cardTitle: 'Person Card',
           cardDescription: 'Spec for Person Card',
@@ -392,11 +392,11 @@ export function setupInteractSubmodeTests(
             relationships: {
               attachment: {
                 links: {
-                  self: './notes.txt',
+                  self: './notes.md',
                 },
                 data: {
                   type: 'file-meta',
-                  id: './notes.txt',
+                  id: `${testRealmURL}FileLinkCard/notes.md`,
                 },
               },
             },
@@ -408,6 +408,28 @@ export function setupInteractSubmodeTests(
             },
           },
         },
+        'FileLinkCard/empty.json': {
+          data: {
+            type: 'card',
+            attributes: {
+              title: 'Empty linked file',
+            },
+            relationships: {
+              attachment: {
+                links: {
+                  self: null,
+                },
+                data: null,
+              },
+            },
+            meta: {
+              adoptsFrom: {
+                module: '../file-link-card',
+                name: 'FileLinkCard',
+              },
+            },
+          },
+        },
         'Puppy/marco.json': new Puppy({ name: 'Marco', age: '5 months' }),
         'grid.json': new CardsGrid(),
         'index.json': new CardsGrid(),
diff --git a/packages/host/tests/integration/components/card-basics-test.gts b/packages/host/tests/integration/components/card-basics-test.gts
index 3137a4c7e5..a9a07ec8ac 100644
--- a/packages/host/tests/integration/components/card-basics-test.gts
+++ b/packages/host/tests/integration/components/card-basics-test.gts
@@ -385,7 +385,7 @@ module('Integration | card-basics', function (hooks) {
       assert.true(instanceOf(new ExteriorField(), FieldDef));
     });
 
-    test('linksTo FileDef renders without editor controls in edit format', async function (assert) {
+    test('linksTo FileDef renders editor controls in edit format', async function (assert) {
       class ImageDef extends FileDef {
         static fitted = class Fitted extends Component<typeof this> {
           <template>
@@ -420,13 +420,13 @@ module('Integration | card-basics', function (hooks) {
 
       assert
         .dom('[data-test-links-to-editor="hero"]')
-        .doesNotExist('FileDef links should not show linksTo editor UI');
+        .exists('FileDef links shows linksTo editor UI');
       assert
         .dom('[data-test-image-def]')
         .hasText('hero.png', 'FileDef uses delegated fitted view');
     });
 
-    test('linksToMany FileDef renders without editor controls in edit format', async function (assert) {
+    test('linksToMany FileDef renders editor controls in edit format', async function (assert) {
       class ImageDef extends FileDef {
         static fitted = class Fitted extends Component<typeof this> {
           <template>
@@ -468,10 +468,7 @@ module('Integration | card-basics', function (hooks) {
 
       assert
         .dom('[data-test-links-to-many="attachments"]')
-        .doesNotExist('FileDef links should not show linksToMany editor UI');
-      assert
-        .dom('[data-test-plural-view-field="attachments"]')
-        .exists('FileDef links render via the plural view');
+        .exists('FileDef links shows linksToMany editor UI');
       assert
         .dom('[data-test-image-def]')
         .exists(
diff --git a/packages/host/tests/integration/realm-test.gts b/packages/host/tests/integration/realm-test.gts
index 6d9f6c517f..c88421f957 100644
--- a/packages/host/tests/integration/realm-test.gts
+++ b/packages/host/tests/integration/realm-test.gts
@@ -2958,6 +2958,48 @@ module('Integration | realm', function (hooks) {
     assert.strictEqual(response.status, 404, 'file no longer exists');
   });
 
+  test('realm can delete a file asset via card source', async function (assert) {
+    let { realm } = await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'notes.md': '# Notes\n\nhello\n',
+      },
+    });
+
+    let response = await handle(
+      realm,
+      new Request(`${testRealmURL}notes.md`, {
+        headers: {
+          Accept: 'application/vnd.card+source',
+        },
+      }),
+    );
+    assert.strictEqual(response.status, 200, 'file exists');
+
+    response = await handle(
+      realm,
+      new Request(`${testRealmURL}notes.md`, {
+        method: 'DELETE',
+        headers: {
+          Accept: 'application/vnd.card+source',
+        },
+      }),
+    );
+    await realm.flushUpdateEvents();
+
+    assert.strictEqual(response.status, 204, 'file is deleted');
+
+    response = await handle(
+      realm,
+      new Request(`${testRealmURL}notes.md`, {
+        headers: {
+          Accept: 'application/vnd.card+source',
+        },
+      }),
+    );
+    assert.strictEqual(response.status, 404, 'file no longer exists');
+  });
+
   test('realm can serve compiled js file when requested without file extension ', async function (assert) {
     let { realm } = await setupIntegrationTestRealm({
       mockMatrixUtils,
diff --git a/packages/host/tests/integration/store-test.gts b/packages/host/tests/integration/store-test.gts
index 17ca742c3d..49d02c8658 100644
--- a/packages/host/tests/integration/store-test.gts
+++ b/packages/host/tests/integration/store-test.gts
@@ -15,6 +15,7 @@ import { module, test } from 'qunit';
 
 import {
   isCardInstance,
+  isCardErrorJSONAPI,
   baseRealm,
   localId,
   baseCardRef,
@@ -38,6 +39,7 @@ import type { CardErrorJSONAPI } from '@cardstack/host/services/store';
 
 import type { CardDef as CardDefType } from 'https://cardstack.com/base/card-api';
 import type * as CardAPI from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 import type { RealmEventContent } from 'https://cardstack.com/base/matrix-event';
 
 import {
@@ -1180,6 +1182,35 @@ module('Integration | Store', function (hooks) {
     );
   });
 
+  test('getFileMeta loads file meta for executable files', async function (assert) {
+    let fileMeta = await storeService.getFileMeta<FileDef>(
+      `${testRealmURL}person.gts`,
+    );
+    assert.false(
+      isCardErrorJSONAPI(fileMeta),
+      'file meta result is not an error',
+    );
+    assert.false(
+      isCardInstance(fileMeta),
+      'file meta result is not a card instance',
+    );
+    assert.strictEqual(
+      (fileMeta as any).id,
+      `${testRealmURL}person.gts`,
+      'file meta id is set',
+    );
+    assert.strictEqual(
+      (fileMeta as any).name,
+      'person.gts',
+      'file meta name is set',
+    );
+    assert.strictEqual(
+      (fileMeta as any).contentType,
+      'text/typescript+glimmer',
+      'file meta content type is inferred',
+    );
+  });
+
   test<TestContextWithSave>('can skip waiting for the save when patching an instance', async function (assert) {
     assert.expect(4);
 
diff --git a/packages/runtime-common/document.ts b/packages/runtime-common/document.ts
index 750855e1d6..ab97f11c2d 100644
--- a/packages/runtime-common/document.ts
+++ b/packages/runtime-common/document.ts
@@ -17,13 +17,8 @@ async function loadDocumentWithRequest(
   requestURL.searchParams.set('noCache', 'true');
   try {
     response = await fetch(requestURL.href, {
-      // there is a bunch of realm meta that is missing when we load a document
-      // in this manner (card-src/file-meta), hopefully that does not come back
-      // to bite us. loading a document in this manner is useful because it
-      // allows us to handle an index that is being built: where the document
-      // you are loading might not have been added to the index yet. this
-      // allows us to remove the visit() function when crawling the links of
-      // documents being indexed and not finding the document yet in the index.
+      // We bypass cache so callers see authoritative 404s from the server,
+      // which are handled the same way as card lookups.
       headers: {
         Accept: accept,
       },
diff --git a/packages/runtime-common/error.ts b/packages/runtime-common/error.ts
index 3b4a6ea5b3..f893aae943 100644
--- a/packages/runtime-common/error.ts
+++ b/packages/runtime-common/error.ts
@@ -269,7 +269,7 @@ export class CardError extends Error implements SerializedError {
 }
 
 export function isCardErrorJSONAPI(err: any): err is CardErrorJSONAPI {
-  return (
+  return !!(
     err != null &&
     typeof err === 'object' &&
     err.status &&
diff --git a/packages/runtime-common/file-def-map.ts b/packages/runtime-common/file-def-map.ts
new file mode 100644
index 0000000000..76f1cd82e3
--- /dev/null
+++ b/packages/runtime-common/file-def-map.ts
@@ -0,0 +1,38 @@
+import { baseRealm, type ResolvedCodeRef } from './index';
+
+export const FILEDEF_CODE_REF_BY_EXTENSION: Record<string, ResolvedCodeRef> = {
+  // TODO: Replace with realm metadata configuration.
+  '.markdown': {
+    module: `${baseRealm.url}markdown-file-def`,
+    name: 'MarkdownDef',
+  },
+  '.md': {
+    module: `${baseRealm.url}markdown-file-def`,
+    name: 'MarkdownDef',
+  },
+  '.mismatch': { module: './filedef-mismatch', name: 'FileDef' },
+};
+
+export const BASE_FILE_DEF_CODE_REF: ResolvedCodeRef = {
+  module: `${baseRealm.url}file-api`,
+  name: 'FileDef',
+};
+
+export function resolveFileDefCodeRef(fileURL: URL): ResolvedCodeRef {
+  let name = fileURL.pathname.split('/').pop() ?? '';
+  let dot = name.lastIndexOf('.');
+  let extension = dot === -1 ? '' : name.slice(dot).toLowerCase();
+  let mapping = extension
+    ? FILEDEF_CODE_REF_BY_EXTENSION[extension]
+    : undefined;
+  if (!mapping) {
+    return BASE_FILE_DEF_CODE_REF;
+  }
+  if (mapping.module.includes('://')) {
+    return mapping;
+  }
+  return {
+    ...mapping,
+    module: new URL(mapping.module, fileURL).href,
+  };
+}
diff --git a/packages/runtime-common/index-runner.ts b/packages/runtime-common/index-runner.ts
index 61424ebb08..9dc2ad816a 100644
--- a/packages/runtime-common/index-runner.ts
+++ b/packages/runtime-common/index-runner.ts
@@ -36,9 +36,9 @@ import {
   type LocalPath,
   type Reader,
   type Stats,
-  baseRealm,
   internalKeyFor,
 } from './index';
+import { BASE_FILE_DEF_CODE_REF, resolveFileDefCodeRef } from './file-def-map';
 import { inferContentType } from './infer-content-type';
 import {
   CardError,
@@ -47,42 +47,6 @@ import {
   type SerializedError,
 } from './error';
 
-const FILEDEF_CODE_REF_BY_EXTENSION: Record<string, ResolvedCodeRef> = {
-  // TODO: Replace with realm metadata configuration.
-  '.markdown': {
-    module: `${baseRealm.url}markdown-file-def`,
-    name: 'MarkdownDef',
-  },
-  '.md': {
-    module: `${baseRealm.url}markdown-file-def`,
-    name: 'MarkdownDef',
-  },
-  '.mismatch': { module: './filedef-mismatch', name: 'FileDef' },
-};
-const BASE_FILE_DEF_CODE_REF: ResolvedCodeRef = {
-  module: `${baseRealm.url}file-api`,
-  name: 'FileDef',
-};
-
-function resolveFileDefCodeRef(fileURL: URL): ResolvedCodeRef {
-  let name = fileURL.pathname.split('/').pop() ?? '';
-  let dot = name.lastIndexOf('.');
-  let extension = dot === -1 ? '' : name.slice(dot).toLowerCase();
-  let mapping = extension
-    ? FILEDEF_CODE_REF_BY_EXTENSION[extension]
-    : undefined;
-  if (!mapping) {
-    return BASE_FILE_DEF_CODE_REF;
-  }
-  if (mapping.module.includes('://')) {
-    return mapping;
-  }
-  return {
-    ...mapping,
-    module: new URL(mapping.module, fileURL).href,
-  };
-}
-
 function canonicalURL(url: string, relativeTo?: string): string {
   try {
     let parsed = new URL(url, relativeTo);
diff --git a/packages/runtime-common/index.ts b/packages/runtime-common/index.ts
index 9953a43ea7..70c56e0b07 100644
--- a/packages/runtime-common/index.ts
+++ b/packages/runtime-common/index.ts
@@ -297,6 +297,7 @@ import type {
   FieldDef,
   BaseDef,
 } from 'https://cardstack.com/base/card-api';
+import type { FileDef } from 'https://cardstack.com/base/file-api';
 import type * as CardAPI from 'https://cardstack.com/base/card-api';
 import type { RealmInfo } from './realm';
 import type { PrerenderedCard, QueryResultsMeta } from './index-query-engine';
@@ -464,6 +465,7 @@ export interface Store {
   peekLive<T extends CardDef>(id: string): T | CardErrorJSONAPI | undefined;
   peekError(id: string): CardErrorJSONAPI | undefined;
   get<T extends CardDef>(id: string): Promise<T | CardErrorJSONAPI>;
+  getFileMeta<T extends FileDef>(url: string): Promise<T | CardErrorJSONAPI>;
   delete(id: string): Promise<void>;
   patch<T extends CardDef>(
     id: string,
@@ -658,5 +660,10 @@ export function isBrowserTestEnv() {
   return typeof window !== 'undefined' && Boolean((globalThis as any).QUnit);
 }
 
+export {
+  BASE_FILE_DEF_CODE_REF,
+  FILEDEF_CODE_REF_BY_EXTENSION,
+  resolveFileDefCodeRef,
+} from './file-def-map';
 export * from './prerendered-card-search';
 export { DEFAULT_LLM_ID_TO_NAME } from './matrix-constants';
diff --git a/packages/runtime-common/realm-index-updater.ts b/packages/runtime-common/realm-index-updater.ts
index 665a1d1d32..2790073636 100644
--- a/packages/runtime-common/realm-index-updater.ts
+++ b/packages/runtime-common/realm-index-updater.ts
@@ -37,6 +37,7 @@ export class RealmIndexUpdater {
   #indexWriter: IndexWriter;
   #queue: QueuePublisher;
   #indexingDeferred: Deferred<void> | undefined;
+  #isIndexing = false;
 
   constructor({
     realm,
@@ -82,11 +83,16 @@ export class RealmIndexUpdater {
     return this.#indexingDeferred?.promise;
   }
 
+  get isIndexing() {
+    return this.#isIndexing;
+  }
+
   // TODO consider triggering realm events for invalidations now that we can
   // calculate fine grained invalidations for from-scratch indexing by passing
   // in an onInvalidation callback
   async fullIndex(priority = systemInitiatedPriority) {
     this.#indexingDeferred = new Deferred<void>();
+    this.#isIndexing = true;
     let startedAt = performance.now();
     try {
       let args: FromScratchArgs = {
@@ -121,6 +127,7 @@ export class RealmIndexUpdater {
       this.#log.error(`Error running from-scratch-index: ${e.message}`);
     } finally {
       this.#indexingDeferred.fulfill();
+      this.#isIndexing = false;
     }
   }
 
@@ -133,6 +140,7 @@ export class RealmIndexUpdater {
     },
   ): Promise<void> {
     this.#indexingDeferred = new Deferred<void>();
+    this.#isIndexing = true;
     try {
       let args: IncrementalArgs = {
         urls: urls.map((u) => u.href),
@@ -162,6 +170,7 @@ export class RealmIndexUpdater {
       throw e;
     } finally {
       this.#indexingDeferred.fulfill();
+      this.#isIndexing = false;
     }
   }
 
@@ -170,6 +179,7 @@ export class RealmIndexUpdater {
     onInvalidation?: (invalidatedURLs: URL[]) => Promise<void>,
   ): Promise<void> {
     this.#indexingDeferred = new Deferred<void>();
+    this.#isIndexing = true;
     try {
       let args: CopyArgs = {
         realmURL: this.#realm.url,
@@ -194,6 +204,7 @@ export class RealmIndexUpdater {
       throw e;
     } finally {
       this.#indexingDeferred.fulfill();
+      this.#isIndexing = false;
     }
   }
 
diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts
index ad233b1829..91407d7afa 100644
--- a/packages/runtime-common/realm.ts
+++ b/packages/runtime-common/realm.ts
@@ -64,6 +64,7 @@ import {
   type PrerenderedHtmlFormat,
   codeRefFromInternalKey,
   codeRefWithAbsoluteURL,
+  resolveFileDefCodeRef,
   userInitiatedPriority,
   systemInitiatedPriority,
   userIdFromUsername,
@@ -187,10 +188,6 @@ const CACHE_HIT_VALUE = 'hit';
 const CACHE_MISS_VALUE = 'miss';
 const MODULE_ETAG_VARIANT = 'module';
 const SOURCE_ETAG_VARIANT = 'source';
-const FILE_DEF_CODE_REF: ResolvedCodeRef = {
-  module: `${baseRealm.url}file-api`,
-  name: 'FileDef',
-};
 export const FILE_META_RESERVED_KEYS = new Set([
   'name',
   'url',
@@ -624,11 +621,7 @@ export class Realm {
         SupportedMimeType.CardJson,
         this.patchCardInstance.bind(this),
       )
-      .delete(
-        '/|/.+(?<!.json)',
-        SupportedMimeType.CardJson,
-        this.removeCard.bind(this),
-      )
+      .delete('/|/.+', SupportedMimeType.CardJson, this.removeCard.bind(this))
       .post(
         '/.*',
         SupportedMimeType.CardSource,
@@ -1453,16 +1446,6 @@ export class Realm {
       if (!isLocal) {
         await this.checkPermission(request, requestContext, requiredPermission);
       }
-      let acceptedMimeType = extractSupportedMimeType(
-        request.headers.get('Accept') as unknown as null | string | [string],
-      );
-      if (
-        acceptedMimeType === SupportedMimeType.CardJson &&
-        ['POST', 'PATCH', 'PUT', 'DELETE'].includes(request.method) &&
-        (await this.openFileForMetadata(localPath))
-      ) {
-        return methodNotAllowed(request, requestContext);
-      }
       if (!this.#realmIndexQueryEngine) {
         return systemError({
           requestContext,
@@ -2132,62 +2115,9 @@ export class Realm {
     if (!localPath || localPath.startsWith('_')) {
       return undefined;
     }
-    if (localPath.endsWith('.json')) {
-      return undefined;
-    }
     return this.#adapter.openFile(localPath);
   }
 
-  private async fileMetaDocument(
-    requestContext: RequestContext,
-    localPath: LocalPath,
-    contentType: SupportedMimeType = SupportedMimeType.CardJson,
-  ): Promise<Response | undefined> {
-    let fileRef = await this.openFileForMetadata(localPath);
-    if (!fileRef) {
-      return undefined;
-    }
-    let fileURL = this.paths.fileURL(localPath).href;
-    let name = localPath.split('/').pop() ?? localPath;
-    let inferredContentType = inferContentType(name);
-    let createdAt = await this.getCreatedTime(localPath);
-    let realmInfo = await this.parseRealmInfo();
-    let contentHash =
-      (this.#dbAdapter
-        ? await getContentHash(this.#dbAdapter, this.url, localPath)
-        : undefined) ?? (await computeContentHashFromRef(fileRef));
-    let doc: SingleFileMetaDocument = {
-      data: {
-        type: 'file-meta',
-        id: fileURL,
-        attributes: {
-          name,
-          url: fileURL,
-          sourceUrl: fileURL,
-          contentType: inferredContentType,
-          contentHash,
-          lastModified: fileRef.lastModified,
-          createdAt: createdAt ?? fileRef.lastModified,
-        },
-        meta: {
-          adoptsFrom: FILE_DEF_CODE_REF,
-          realmInfo,
-          realmURL: this.url,
-        },
-        links: { self: fileURL },
-      },
-    };
-    return createResponse({
-      body: JSON.stringify(doc, null, 2),
-      init: {
-        headers: {
-          'content-type': contentType,
-        },
-      },
-      requestContext,
-    });
-  }
-
   private async fileMetaDocumentFromIndex(
     requestContext: RequestContext,
     localPath: LocalPath,
@@ -2209,7 +2139,7 @@ export class Realm {
       codeRefFromInternalKey(fileEntry.types?.[0]) ??
       (isCodeRef(fileEntry.resource?.meta?.adoptsFrom)
         ? fileEntry.resource?.meta?.adoptsFrom
-        : FILE_DEF_CODE_REF);
+        : resolveFileDefCodeRef(new URL(fileURL)));
     let resourceAttributes =
       (fileEntry as IndexedFile).resource?.attributes ?? {};
     let baseAttributes = {
@@ -2272,8 +2202,12 @@ export class Realm {
     if (localPath === '') {
       localPath = 'index';
     }
+    let queryOpts = this.#realmIndexUpdater.isIndexing
+      ? { useWorkInProgressIndex: true }
+      : undefined;
     let fileEntry = await this.#realmIndexQueryEngine.file(
       this.paths.fileURL(localPath),
+      queryOpts,
     );
     if (fileEntry) {
       return await this.fileMetaDocumentFromIndex(
@@ -2282,14 +2216,6 @@ export class Realm {
         fileEntry,
       );
     }
-    let fileResponse = await this.fileMetaDocument(
-      requestContext,
-      localPath,
-      SupportedMimeType.FileMeta,
-    );
-    if (fileResponse) {
-      return fileResponse;
-    }
     return notFound(request, requestContext);
   }