card-api.gts

import Modifier from 'ember-modifier';
import GlimmerComponent from '@glimmer/component';
import { isEqual } from 'lodash-es';
import { WatchedArray, rawArrayValues } from './watched-array';
import {
  BoxelInput,
  BrokenLinkTemplate,
  CopyButton,
  type BrokenLinkFormat,
} from '@cardstack/boxel-ui/components';
import {
  markdownEscape,
  type MenuItemOptions,
  not,
} from '@cardstack/boxel-ui/helpers';
import {
  getBoxComponent,
  type BoxComponent,
  CardCrudFunctionsConsumer,
  DefaultFormatsConsumer,
} from './field-component';
import { getContainsManyComponent } from './contains-many-component';
import { LinksToEditor } from './links-to-editor';
import { getLinksToManyComponent } from './links-to-many-component';
import {
  assertIsSerializerName,
  baseRef,
  CardContextName,
  CardError,
  CodeRef,
  ToolContext,
  Deferred,
  byteStreamToUint8Array,
  fields,
  fieldSerializer,
  fieldsUntracked,
  formats,
  getAncestor,
  getMenuItems,
  getField,
  getSerializer,
  humanReadable,
  identifyCard,
  inferContentType,
  isBaseInstance,
  isCardError,
  isCardInstance as _isCardInstance,
  isCardResource,
  isFileMetaResource,
  isFileDef,
  isField,
  isFieldInstance,
  isRelationship,
  loadCardDef,
  loadCardDocument,
  Loader,
  localId,
  LocalPath,
  meta,
  primitive,
  realmURL,
  relativeTo,
  SingleCardDocument,
  uuidv4,
  NumberSerializer,
  type Format,
  type Meta,
  type CardFields,
  type Relationship,
  type ResourceID,
  type LooseCardResource,
  type LooseSingleCardDocument,
  type CardDocument,
  type CardResourceMeta,
  type ResolvedCodeRef,
  type getCard,
  type getCards,
  type getCardCollection,
  type Store,
  type SearchResultsComponentSignature,
  type ErrorEntry,
  type Query,
  type QueryWithInterpolations,
  type QueryResultsMeta,
  type SerializedError,
  FileMetaResourceType,
  CardResourceType,
  loadFileMetaDocument,
  CardResource,
  LooseLinkableResource,
  LooseSingleResourceDocument,
  shouldTrackRuntimeModuleGraph,
  shouldTrackRuntimeRelationship,
  trackRuntimeFileDependency,
  trackRuntimeInstanceDependency,
  trackRuntimeModuleDependency,
  runtimeNonQueryDependencyContext,
  runtimeQueryDependencyContext,
  type RuntimeDependencyTrackingContext,
  rri,
  resolveRRIReference,
  type RealmResourceIdentifier,
  type VirtualNetwork,
  isDirectIndexedFieldKey,
  cardTypeName,
} from '@cardstack/runtime-common';
import {
  captureQueryFieldSeedData,
  ensureQueryFieldSearchResource,
  peekQueryFieldSearchResource,
  validateRelationshipQuery,
} from './query-field-support';
import { isSavedInstance } from './-private';
import type { ComponentLike } from '@glint/template';
import { initSharedState } from './shared-state';
import DefaultFittedTemplate from './default-templates/fitted';
import DefaultEmbeddedTemplate from './default-templates/embedded';
import DefaultCardDefTemplate from './default-templates/isolated-and-edit';
import DefaultAtomViewTemplate from './default-templates/atom';
import DefaultHeadTemplate from './default-templates/head';
import MissingTemplate from './default-templates/missing-template';
import FieldDefEditTemplate from './default-templates/field-edit';
import MarkdownTemplate from './default-templates/markdown';
import DefaultMarkdownFallbackTemplate from './default-templates/markdown-fallback';
import { markdownImage } from './markdown-helpers';
import FileDefEditTemplate from './default-templates/file-def-edit';
import FileDefAtomTemplate from './default-templates/file-def-atom';
import FileDefEmbeddedTemplate from './default-templates/file-def-embedded';
import FileDefFittedTemplate from './default-templates/file-def-fitted';
import FileDefIsolatedTemplate from './default-templates/file-def-isolated';
import ImageDefAtomTemplate from './default-templates/image-def-atom';
import ImageDefEmbeddedTemplate from './default-templates/image-def-embedded';
import ImageDefFittedTemplate from './default-templates/image-def-fitted';
import ImageDefIsolatedTemplate from './default-templates/image-def-isolated';
import CaptionsIcon from '@cardstack/boxel-icons/captions';
import FileIcon from '@cardstack/boxel-icons/file';
import ImageIcon from '@cardstack/boxel-icons/image';
import LetterCaseIcon from '@cardstack/boxel-icons/letter-case';
import MarkdownIcon from '@cardstack/boxel-icons/align-box-left-middle';
import RectangleEllipsisIcon from '@cardstack/boxel-icons/rectangle-ellipsis';
import TextAreaIcon from '@cardstack/boxel-icons/align-left';
import ThemeIcon from '@cardstack/boxel-icons/palette';
import ImportIcon from '@cardstack/boxel-icons/import';
import FilePencilIcon from '@cardstack/boxel-icons/file-pencil';
import WandIcon from '@cardstack/boxel-icons/wand';
import HashIcon from '@cardstack/boxel-icons/hash';
// normalizeEnumOptions used by enum moved to packages/base/enum.gts
import PatchThemeTool from '@cardstack/boxel-host/commands/patch-theme';
import CopyAndEditTool from '@cardstack/boxel-host/commands/copy-and-edit';
import { md5 } from 'super-fast-md5';

import {
  callSerializeHook,
  cardClassFromResource,
  deserialize,
  makeMetaForField,
  makeRelativeURL,
  serialize,
  serializeCard,
  serializeCardResource,
  serializeFileDef,
  resourceFrom,
  type DeserializeOpts,
  type JSONAPIResource,
  type JSONAPISingleResourceDocument,
  type SerializeOpts,
  getCardMeta,
} from './card-serialization';
import {
  assertScalar,
  beginComputePass,
  endComputePass,
  entangleWithCardTracking,
  getBrokenLinks,
  getDataBucket,
  getFieldDescription,
  getFieldOverrides,
  getFields,
  getRelationshipMembershipState,
  getter,
  registerRelationshipProbe,
  relationshipStateForEntry,
  readFieldLoadingSignal,
  bumpFieldLoadingSignal,
  isArrayOfCardOrField,
  isCard,
  isCardOrField,
  isLinkError,
  isLinkNotFound,
  isNonPresentLink,
  isNotLoadedValue,
  markAuthoredEmptyLink,
  notifyCardTracking,
  peekAtField,
  propagateRealmContext,
  realmContext,
  setFieldDescription,
  setRealmContextOnField,
  type BrokenLinkFinding,
  type ComputePassSnapshot,
  type LinkErrorValue,
  type LinkNotFoundValue,
  type NotLoadedValue,
  type RelationshipStatus,
  type RelationshipState,
} from './field-support';
import { TextInputValidator } from './text-input-validator';
import { type GetMenuItemParams, getDefaultCardMenuItems } from './menu-items';
import { getDefaultFileMenuItems } from './file-menu-items';
import {
  LinkableDocument,
  SingleFileMetaDocument,
} from '@cardstack/runtime-common/document-types';
import type { MarkdownEmbedChooser } from '@cardstack/runtime-common/bfm-card-references';
import type { FileMetaResource } from '@cardstack/runtime-common';

export const BULK_GENERATED_ITEM_COUNT = 3;

interface CardOrFieldTypeIconSignature {
  Element: SVGSVGElement;
}

export type CardOrFieldTypeIcon = ComponentLike<CardOrFieldTypeIconSignature>;

export {
  beginComputePass,
  endComputePass,
  deserialize,
  getBrokenLinks,
  getCardMeta,
  getDataBucket,
  getFieldDescription,
  getFields,
  getRelationshipMembershipState,
  isNonPresentLink,
  peekAtField,
  isCard,
  isField,
  isFileDef,
  localId,
  meta,
  primitive,
  realmURL,
  relativeTo,
  serialize,
  serializeCard,
  serializeFileDef,
  ensureQueryFieldSearchResource,
  getStore,
  type BoxComponent,
  type BrokenLinkFinding,
  type ComputePassSnapshot,
  type DeserializeOpts,
  type GetMenuItemParams,
  type JSONAPISingleResourceDocument,
  type RelationshipStatus,
  type RelationshipState,
  type ResourceID,
  type SerializeOpts,
};

export const useIndexBasedKey = Symbol.for('cardstack-use-index-based-key');
export const fieldDecorator = Symbol.for('cardstack-field-decorator');
export const queryableValue = Symbol.for('cardstack-queryable-value');
export const formatQuery = Symbol.for('cardstack-format-query');
export const realmInfo = Symbol.for('cardstack-realm-info');
export const emptyValue = Symbol.for('cardstack-empty-value');

export type BaseInstanceType<T extends BaseDefConstructor> = T extends {
  [primitive]: infer P;
}
  ? P
  : InstanceType<T>;

// this is expressing the idea that the fields of a
// card may contain undefined, but even when that's
// true all the symbols and the `constructor` property
// can still be relied on.
type PartialFields<T> = {
  [Property in keyof T]: Property extends symbol
    ? T[Property]
    : Property extends 'constructor'
      ? T[Property]
      : T[Property] | undefined;
};

export type PartialBaseInstanceType<T extends BaseDefConstructor> = T extends {
  [primitive]: infer P;
}
  ? P | null
  : PartialFields<InstanceType<T>> & {
      [fields]: Record<string, BaseDefConstructor>;
      [fieldsUntracked]: Record<string, BaseDefConstructor>;
    };
export type FieldsTypeFor<T extends BaseDef> = {
  [Field in keyof T]: BoxComponent &
    (T[Field] extends ArrayLike<unknown>
      ? BoxComponent[]
      : T[Field] extends BaseDef
        ? FieldsTypeFor<T[Field]>
        : unknown);
};
export { formats, type Format };
export type FieldType = 'contains' | 'containsMany' | 'linksTo' | 'linksToMany';
// Opaque configuration passed to field format components and validators
export type FieldConfiguration = Record<string, any>;
// Configuration may be provided as a static object or a function of the parent instance
export type ConfigurationInput<T> =
  | FieldConfiguration
  | ((this: Readonly<T>) => FieldConfiguration | undefined);
export type FieldFormats = {
  ['fieldDef']: Format;
  ['cardDef']: Format;
};
type Setter = (value: any) => void;

export type SerializedFile<Extra extends object = {}> = {
  sourceUrl: string;
  url: string;
  name: string;
  contentType: string;
  contentHash?: string;
  contentSize?: number;
} & Extra;

export type ByteStream = ReadableStream<Uint8Array> | Uint8Array;

// Declares which links a field makes searchable — i.e. which linked cards are
// pulled into the search doc rather than left as a bare `{ id }` reference.
// `searchable` only ever governs links: a contained value is always included
// once its owner is in the doc, so `searchable` never decides whether a
// contained field appears. `true` makes the immediate ("self") link
// searchable; a dotted path makes a deeper (n+1) link searchable, routed from
// this field's target through its links — naming intermediate contained
// fields as segments to reach a link beneath them; an array combines routes.
// Omitted leaves the link as `{ id }` only. On a `contains`/`containsMany`
// field (whose value is always present) a path is therefore only meaningful to
// make a link reached *through* that contained value searchable.
export type Searchable = true | string | string[];

interface Options {
  computeVia?: () => unknown;
  description?: string;
  // Names which links this field makes searchable. See `Searchable`.
  searchable?: Searchable;
  // Optional: per-usage configuration provider merged with FieldDef-level configuration
  configuration?: ConfigurationInput<any>;
}

interface RelationshipOptions extends Options {
  query?: QueryWithInterpolations;
}

export interface CardContext<T extends CardDef = CardDef> {
  toolContext?: ToolContext;
  // Pre-rename spelling of `toolContext`. Realm content reads
  // `@context.commandContext`; populated with the same value until no
  // deployed content references it.
  commandContext?: ToolContext;
  cardComponentModifier?: typeof Modifier<{
    Args: {
      Named: {
        card?: CardDef;
        cardId?: string;
        format: Format | 'data';
        fieldType: FieldType | undefined;
        fieldName: string | undefined;
      };
    };
  }>;
  // The search rendering surface: renders the heterogeneous `entry`
  // stream for an `entry`-rooted query — prerendered HTML inert (hydrated
  // lazily) or a live card — so a card author renders results without ever
  // branching on prerendered-vs-live. Supersedes `prerenderedCardSearchComponent`.
  searchResultsComponent: typeof GlimmerComponent<SearchResultsComponentSignature>;
  getCard: getCard<T>;
  getCards: getCards;
  getCardCollection: getCardCollection;
  store: Store;
  // Host bridge for the markdown editor's embed chooser. Provided by
  // operator-mode; absent in contexts with no chooser modal (prerender,
  // freestyle), so consumers guard on it.
  markdownEmbedChooser?: MarkdownEmbedChooser;
  // Optional runtime mode/submode hints used by cards that render differently per context.
  mode?: 'host' | 'operator';
  submode?: 'interact' | 'code' | 'host';
}

export interface FieldConstructor<T> {
  cardThunk: () => T;
  computeVia: undefined | (() => unknown);
  declaredCardThunk?: () => T;
  isPolymorphic?: true;
  searchable?: Searchable;
  name: string;
  queryDefinition?: QueryWithInterpolations;
}

type CardChangeSubscriber = (
  instance: BaseDef,
  fieldName: string,
  fieldValue: any,
) => void;

const stores = initSharedState(
  'stores',
  () => new WeakMap<BaseDef, CardStore>(),
);
const subscribers = initSharedState(
  'subscribers',
  () => new WeakMap<BaseDef, Set<CardChangeSubscriber>>(),
);
const subscriberConsumer = initSharedState(
  'subscriberConsumer',
  () => new WeakMap<BaseDef, { fieldOrCard: BaseDef; fieldName: string }>(),
);
const inflightLinkLoads = initSharedState(
  'inflightLinkLoads',
  () => new WeakMap<CardDef, Map<string, Promise<unknown>>>(),
);

export function instanceOf(instance: BaseDef, clazz: typeof BaseDef): boolean {
  let instanceClazz: typeof BaseDef | null = instance.constructor;
  let codeRefInstance: CodeRef | undefined;
  let codeRefClazz = identifyCard(clazz);
  if (!codeRefClazz) {
    return instance instanceof (clazz as any);
  }
  do {
    codeRefInstance = instanceClazz ? identifyCard(instanceClazz) : undefined;
    if (isEqual(codeRefInstance, codeRefClazz)) {
      return true;
    }
    instanceClazz = instanceClazz ? (getAncestor(instanceClazz) ?? null) : null;
  } while (codeRefInstance && !isEqual(codeRefInstance, baseRef));
  return false;
}

class Logger {
  private promises: Promise<any>[] = [];

  // TODO this doesn't look like it's used anymore. in the past this was used to
  // keep track of async when eagerly running computes after a property had been set.
  // consider removing this.
  log(promise: Promise<any>) {
    this.promises.push(promise);
    // make an effort to resolve the promise at the time it is logged
    (async () => {
      try {
        await promise;
      } catch (e: any) {
        console.error(`encountered error performing recompute on card`, e);
      }
    })();
  }

  async flush() {
    let results = await Promise.allSettled(this.promises);
    for (let result of results) {
      if (result.status === 'rejected') {
        console.error(`Promise rejected`, result.reason);
        if (result.reason instanceof Error) {
          console.error(result.reason.stack);
        }
      }
    }
  }
}

let logger = new Logger();
export async function flushLogs() {
  await logger.flush();
}

export interface StoreSearchResource<T extends CardDef | FileDef = CardDef> {
  readonly instances: T[];
  readonly instancesByRealm: { realm: string; cards: T[] }[];
  readonly isLoading: boolean;
  readonly meta: QueryResultsMeta;
  readonly errors?: ErrorEntry[];
}

export type GetSearchResourceFuncOpts = {
  isLive?: boolean;
  doWhileRefreshing?: (() => void) | undefined;
  dependencyTracking?: RuntimeDependencyTrackingContext;
  seed?: {
    cards: CardDef[];
    searchURL?: string;
    realms?: string[];
    queryErrors?: Array<{
      realm: string;
      type: string;
      message: string;
      status?: number;
    }>;
    // IDs the parent doc named in `relationships.{field}.data`. Used
    // by the SearchResource when `cards` is empty and the parent
    // skipped query-backed expansion — the resource loads each ID by
    // URL instead of running a live re-query.
    cardURLs?: string[];
  };
};
export type GetSearchResourceFunc<T extends CardDef | FileDef = CardDef> = (
  parent: object,
  getQuery: () => Query | undefined,
  getRealms?: () => string[] | undefined,
  opts?: GetSearchResourceFuncOpts,
) => StoreSearchResource<T>;

export interface CardStore {
  // Resolve a (possibly relative or RRI) reference to a real, fetchable URL.
  // Stores expose URL-resolution capability — never the VirtualNetwork object
  // itself — so card code can satisfy boundaries that require a real URL (an
  // `<img src>`, `new URL(...)`) without holding the network. Returns
  // undefined when the reference can't be resolved (no network available, or
  // an unresolvable reference) so callers can degrade to URL math.
  resolveURL(reference: string, base?: string): URL | undefined;
  getCard(url: string): CardDef | undefined;
  getFileMeta(url: string): FileDef | undefined;
  setCard(url: string, instance: CardDef): void;
  setFileMeta(url: string, instance: FileDef): void;
  setCardNonTracked(id: string, instance: CardDef): void;
  setFileMetaNonTracked(id: string, instance: FileDef): void;
  makeTracked(id: string): void;
  // `untracked` opts out of the store's load-generation tracking: safe only
  // for a caller that awaits this promise inline and folds the resolved
  // document into its own output, so the load-settle machinery (which exists
  // to catch loads fired and abandoned by field getters) has nothing to wait
  // for. The searchable generator's targeted link loads use this — it lets a
  // walk whose targets all resolve immediately read as settled without a
  // confirmation pass. Stores that don't implement the option simply keep
  // tracking, which costs an extra settle pass and nothing else.
  loadCardDocument(
    url: string,
    opts?: {
      dependencyTrackingContext?: RuntimeDependencyTrackingContext;
      untracked?: true;
    },
  ): Promise<SingleCardDocument | CardError>;
  loadFileMetaDocument(
    url: string,
    opts?: {
      dependencyTrackingContext?: RuntimeDependencyTrackingContext;
      untracked?: true;
    },
  ): Promise<SingleFileMetaDocument | CardError>;
  trackLoad(load: Promise<unknown>): void;
  loaded(): Promise<void>;
  // CS-10872: optional diagnostic hooks used by the prerenderer's
  // render-timeout error path to populate "what the render was
  // waiting on". Stores that don't implement them (e.g. older test
  // doubles) simply won't contribute a queryLoadsInFlight section.
  trackQueryLoad?(
    load: Promise<unknown>,
    meta: QueryLoadMeta,
  ): (() => void) | void;
  queryLoadsInFlight?(): QueryLoadInfo[];
  // Per-URL ageMs for currently-in-flight linked-field / file-meta
  // loads. Mirrors the `cardDocsInFlight` string getter but carries
  // "how long has this URL been loading".
  cardDocLoadsInFlight?(): Array<{ url: string; ageMs: number }>;
  fileMetaDocLoadsInFlight?(): Array<{ url: string; ageMs: number }>;
  // Bounded top-N history of completed slow loads. Survives beyond
  // the in-flight window so the post-timeout capture can see which
  // individual queries / linked fields dominated wall time even if
  // they completed just before the timer fired.
  recentCardDocLoads?(): Array<{ url: string; ms: number }>;
  recentFileMetaLoads?(): Array<{ url: string; ms: number }>;
  recentQueryLoads?(): Array<{ meta: QueryLoadMeta; ms: number }>;
  getSearchResource: GetSearchResourceFunc;
}

export interface QueryLoadMeta {
  // Free-form label so operators can tell "a query-field resolution"
  // apart from "a standalone search". See SearchResource.
  source: string;
  query?: unknown;
  realms?: string[];
  cardId?: string;
  fieldName?: string;
}

export interface QueryLoadInfo extends QueryLoadMeta {
  ageMs: number;
}

export interface Field<
  CardT extends BaseDefConstructor = BaseDefConstructor,
  SearchT = any,
> {
  card: CardT;
  name: string;
  fieldType: FieldType;
  computeVia: undefined | (() => unknown);
  // Optional per-usage configuration stored on the field descriptor
  configuration?: ConfigurationInput<any>;
  // Declarative relationship query definition, if provided
  queryDefinition?: QueryWithInterpolations;
  captureQueryFieldSeedData?(
    instance: BaseDef,
    value: any,
    resource: LooseCardResource,
  ): void;
  isPolymorphic?: true;
  // The links this field makes searchable. This descriptor is the source of
  // truth; `getFieldDefinitions` mirrors it (raw) into the cached
  // `FieldDefinition` for the loaderless query compiler and definition-build
  // validation. See `Searchable`.
  searchable?: Searchable;
  serialize(
    value: any,
    doc: JSONAPISingleResourceDocument,
    visited: Set<string>,
    opts?: SerializeOpts,
  ): JSONAPIResource;
  deserialize(
    value: any,
    doc: LooseSingleCardDocument | CardDocument,
    relationships: JSONAPIResource['relationships'] | undefined,
    fieldMeta: CardFields[string] | undefined,
    store: CardStore | undefined,
    instancePromise: Promise<BaseDef>,
    loadedValue: any,
    relativeTo: RealmResourceIdentifier | URL | undefined,
    opts?: DeserializeOpts,
  ): Promise<any>;
  emptyValue(instance: BaseDef): any;
  validate(instance: BaseDef, value: any): void;
  component(model: Box<BaseDef>): BoxComponent;
  getter(instance: BaseDef): BaseInstanceType<CardT> | undefined;
  queryableValue(value: any, stack: BaseDef[]): SearchT;
}

function cardTypeFor(
  field: Field<typeof BaseDef>,
  boxedElement?: Box<BaseDef>,
  overrides?: () => Map<string, typeof BaseDef> | undefined,
): typeof BaseDef {
  let override: typeof BaseDef | undefined;
  if (overrides) {
    let valueKey = `${field.name}${
      boxedElement ? '.' + boxedElement.name : ''
    }`;
    override = boxedElement?.value ? overrides()?.get(valueKey) : undefined;
  } else {
    override =
      boxedElement?.value && typeof boxedElement.value === 'object'
        ? getFieldOverrides(boxedElement.value)?.get(field.name)
        : undefined;
  }
  if (primitive in field.card) {
    return override ?? field.card;
  }
  if (boxedElement === undefined || boxedElement.value == null) {
    return field.card;
  }
  return Reflect.getPrototypeOf(boxedElement.value)!
    .constructor as typeof BaseDef;
}

function assertNoDeserializeOverride(cardClass: typeof BaseDef) {
  if (
    !(primitive in cardClass) &&
    Object.prototype.hasOwnProperty.call(cardClass, deserialize)
  ) {
    throw new Error(
      `${cardClass.name} overrides [deserialize] directly. Composite fields must use a registered fieldSerializer instead.`,
    );
  }
}

class ContainsMany<FieldT extends FieldDefConstructor> implements Field<
  FieldT,
  any[] | null
> {
  readonly fieldType = 'containsMany';
  private cardThunk: () => FieldT;
  readonly computeVia: undefined | (() => unknown);
  readonly name: string;
  readonly description: string | undefined;
  readonly isPolymorphic: undefined | true;
  readonly searchable: Searchable | undefined;
  configuration: ConfigurationInput<any> | undefined;
  constructor({
    cardThunk,
    computeVia,
    name,
    isPolymorphic,
    searchable,
  }: FieldConstructor<FieldT>) {
    this.cardThunk = cardThunk;
    this.computeVia = computeVia;
    this.name = name;
    this.isPolymorphic = isPolymorphic;
    this.searchable = searchable;
  }

  get card(): FieldT {
    return this.cardThunk();
  }

  getter(instance: BaseDef): BaseInstanceType<FieldT> | undefined {
    let deserialized = getDataBucket(instance);
    entangleWithCardTracking(instance);
    let maybeNotLoaded = deserialized.get(this.name);
    // a not loaded error can blow up thru a computed containsMany field that consumes a link
    if (isNotLoadedValue(maybeNotLoaded)) {
      lazilyLoadLink(instance as CardDef, this, maybeNotLoaded.reference);
      return this.emptyValue(instance) as BaseInstanceType<FieldT>;
    }
    let results = getter(instance, this);
    propagateRealmContext(results, instance);
    return results;
  }

  queryableValue(instances: any[] | null, stack: BaseDef[]): any[] | null {
    if (instances === null || instances.length === 0) {
      // we intentionally use a "null" to represent an empty plural field as
      // this is a limitation to SQLite's json_tree() function when trying to match
      // plural fields that are empty
      return null;
    }

    // Need to replace the WatchedArray proxy with an actual array because the
    // WatchedArray proxy is not structuredClone-able, and hence cannot be
    // communicated over the postMessage boundary between worker and DOM.
    // TODO: can this be simplified since we don't have the worker anymore?
    let results = [...instances]
      .map((instance) => {
        return this.card[queryableValue](instance, stack);
      })
      .filter((i) => i != null);
    return results.length === 0 ? null : results;
  }

  serialize(
    values: BaseInstanceType<FieldT>[] | NotLoadedValue,
    doc: JSONAPISingleResourceDocument,
    _visited: Set<string>,
    opts?: SerializeOpts,
  ): JSONAPIResource {
    // this can be a not loaded value happen when the containsMany is a
    // computed that consumes a linkTo field that is not loaded
    if (isNotLoadedValue(values)) {
      return { attributes: {} };
    }
    let serialized =
      values === null
        ? null
        : values.map((value) =>
            callSerializeHook(this.card, value, doc, undefined, opts),
          );
    if (primitive in this.card) {
      if (opts?.overrides) {
        let meta: Partial<Meta> = {};
        if (Array.isArray(serialized)) {
          for (let [index] of serialized.entries()) {
            let fieldName = `${this.name}.${index}`;
            let override = opts.overrides.get(fieldName);
            if (!override) {
              continue;
            }
            meta.fields = meta.fields ?? {};
            meta.fields[fieldName] = {
              adoptsFrom: identifyCard(
                override,
                opts?.useAbsoluteURL ? undefined : opts?.maybeRelativeReference,
              ),
            };
          }
        }
        return {
          attributes: {
            [this.name]: serialized,
          },
          meta,
        };
      } else {
        return {
          attributes: {
            [this.name]: serialized,
          },
        };
      }
    } else {
      let relationships: Record<string, Relationship> = {};
      let serialized =
        values === null
          ? null
          : values.map((value, index) => {
              let resource: JSONAPISingleResourceDocument['data'] =
                callSerializeHook(this.card, value, doc, undefined, opts);
              if (resource.relationships) {
                for (let [fieldName, relationship] of Object.entries(
                  resource.relationships as Record<string, Relationship>,
                )) {
                  relationships[`${this.name}.${index}.${fieldName}`] =
                    relationship; // warning side-effect
                }
              }
              if (this.card === Reflect.getPrototypeOf(value)!.constructor) {
                // when our implementation matches the default we don't need to include
                // meta.adoptsFrom
                delete resource.meta?.adoptsFrom;
              }
              if (resource.meta && Object.keys(resource.meta).length === 0) {
                delete resource.meta;
              }
              return resource;
            });

      let result: JSONAPIResource = {
        attributes: {
          [this.name]:
            serialized === null
              ? null
              : serialized.map((resource) => resource.attributes),
        },
      };
      if (Object.keys(relationships).length > 0) {
        result.relationships = relationships;
      }

      if (serialized && serialized.some((resource) => resource.meta)) {
        result.meta = {
          fields: {
            [this.name]: serialized.map((resource) => resource.meta ?? {}),
          },
        };
      }

      return result;
    }
  }

  async deserialize(
    value: any[],
    doc: CardDocument,
    relationships: JSONAPIResource['relationships'] | undefined,
    fieldMeta: CardFields[string] | undefined,
    store: CardStore,
    instancePromise: Promise<BaseDef>,
    _loadedValue: any,
    relativeTo: RealmResourceIdentifier | URL | undefined,
    opts: DeserializeOpts,
  ): Promise<BaseInstanceType<FieldT>[] | null> {
    if (value == null) {
      return null;
    }
    if (!Array.isArray(value)) {
      throw new Error(`Expected array for field value ${this.name}`);
    }
    if (fieldMeta && !Array.isArray(fieldMeta)) {
      throw new Error(
        `fieldMeta for contains-many field '${
          this.name
        }' is not an array: ${JSON.stringify(fieldMeta, null, 2)}`,
      );
    }
    let metas: Partial<Meta>[] = fieldMeta ?? [];
    return new WatchedArray(
      (prevArrayValue, arrayValue) =>
        instancePromise.then((instance) => {
          applySubscribersToInstanceValue(
            instance,
            this,
            prevArrayValue,
            arrayValue,
          );
          notifySubscribers(instance, field.name, arrayValue);
          notifyCardTracking(instance);
        }),
      await Promise.all(
        value.map(async (entry, index) => {
          if (primitive in this.card) {
            if (fieldSerializer in this.card) {
              assertIsSerializerName(this.card[fieldSerializer]);
              let serializer = getSerializer(this.card[fieldSerializer]);
              return serializer.deserialize<FieldT>(
                entry,
                relativeTo,
                doc,
                store,
                opts,
              );
            }
            return entry;
          } else {
            if (fieldSerializer in this.card) {
              assertIsSerializerName(this.card[fieldSerializer]);
              let serializer = getSerializer(this.card[fieldSerializer]);
              entry = await serializer.deserialize(
                entry,
                relativeTo,
                doc,
                store,
                opts,
              );
            }
            let meta = metas[index];
            let resource: LooseCardResource = {
              attributes: entry,
              meta: makeMetaForField(meta, this.name, this.card),
            };
            if (relationships) {
              resource.relationships = Object.fromEntries(
                Object.entries(relationships)
                  .filter(([fieldName]) =>
                    fieldName.startsWith(`${this.name}.`),
                  )
                  .map(([fieldName, relationship]) => {
                    let relName = `${this.name}.${index}`;
                    return [
                      fieldName.startsWith(`${relName}.`)
                        ? fieldName.substring(relName.length + 1)
                        : fieldName,
                      relationship,
                    ];
                  }),
              );
            }
            let cardClass = await cardClassFromResource(
              resource,
              this.card,
              relativeTo,
            );
            assertNoDeserializeOverride(cardClass);
            return cardClass[deserialize](
              resource,
              relativeTo,
              doc,
              store,
              opts,
            );
          }
        }),
      ),
    );
  }

  emptyValue(instance: BaseDef) {
    return new WatchedArray((oldValue, value) => {
      applySubscribersToInstanceValue(
        instance,
        this,
        oldValue as BaseDef[],
        value as BaseDef[],
      );
      notifySubscribers(instance, this.name, value);
      notifyCardTracking(instance);
    });
  }

  validate(instance: BaseDef, values: any[] | null) {
    if (values && !Array.isArray(values)) {
      throw new Error(
        `field validation error: Expected array for field value of field '${this.name}'`,
      );
    }
    if (values == null) {
      return values;
    }

    if (!(primitive in this.card)) {
      for (let [index, item] of values.entries()) {
        if (item != null && !instanceOf(item, this.card)) {
          throw new Error(
            `field validation error: tried set instance of ${values.constructor.name} at index ${index} of field '${this.name}' but it is not an instance of ${this.card.name}`,
          );
        }
      }
    }

    return new WatchedArray((oldValue, value) => {
      applySubscribersToInstanceValue(
        instance,
        this,
        oldValue as BaseDef[],
        value as BaseDef[],
      );
      notifySubscribers(instance, this.name, value);
      notifyCardTracking(instance);
    }, values);
  }

  component(model: Box<BaseDef>): BoxComponent {
    let fieldName = this.name as keyof BaseDef;
    let arrayField = model.field(
      fieldName,
      useIndexBasedKey in this.card,
    ) as unknown as Box<BaseDef[]>;

    return getContainsManyComponent({
      model,
      arrayField,
      field: this,
      cardTypeFor,
    });
  }
}

class Contains<CardT extends FieldDefConstructor> implements Field<CardT, any> {
  readonly fieldType = 'contains';
  private cardThunk: () => CardT;
  readonly computeVia: undefined | (() => unknown);
  readonly name: string;
  readonly description: string | undefined;
  readonly isPolymorphic: undefined | true;
  readonly searchable: Searchable | undefined;
  configuration: ConfigurationInput<any> | undefined;
  constructor({
    cardThunk,
    computeVia,
    name,
    isPolymorphic,
    searchable,
  }: FieldConstructor<CardT>) {
    this.cardThunk = cardThunk;
    this.computeVia = computeVia;
    this.name = name;
    this.isPolymorphic = isPolymorphic;
    this.searchable = searchable;
  }

  get card(): CardT {
    return this.cardThunk();
  }

  getter(instance: BaseDef): BaseInstanceType<CardT> | undefined {
    let deserialized = getDataBucket(instance);
    entangleWithCardTracking(instance);
    let maybeNotLoaded = deserialized.get(this.name);
    // a not loaded error can blow up thru a computed contains field that consumes a link
    if (isNotLoadedValue(maybeNotLoaded)) {
      lazilyLoadLink(instance as CardDef, this, maybeNotLoaded.reference);
      return undefined;
    }
    let value = getter(instance, this);
    propagateRealmContext(value, instance);
    return value;
  }

  queryableValue(instance: any, stack: BaseDef[]): any {
    if (primitive in this.card) {
      let result = this.card[queryableValue](instance, stack);
      assertScalar(result, this.card);
      return result;
    }
    if (instance == null) {
      return null;
    }
    return this.card[queryableValue](instance, stack);
  }

  serialize(
    value: InstanceType<CardT> | NotLoadedValue,
    doc: JSONAPISingleResourceDocument,
    _visited: Set<string>,
    opts?: SerializeOpts,
  ): JSONAPIResource {
    // this can be a not loaded value happen when the contains is a
    // computed that consumes a linkTo field that is not loaded
    if (isNotLoadedValue(value)) {
      return { attributes: {} };
    }

    if (primitive in this.card) {
      let serialized: JSONAPISingleResourceDocument['data'] & {
        meta: Record<string, any>;
      } = callSerializeHook(this.card, value, doc, undefined, opts);
      if (this.isPolymorphic) {
        return {
          attributes: { [this.name]: serialized },
          meta: {
            fields: {
              [this.name]: {
                adoptsFrom: identifyCard(
                  this.card,
                  opts?.useAbsoluteURL
                    ? undefined
                    : opts?.maybeRelativeReference,
                ),
              },
            },
          },
        };
      } else {
        return { attributes: { [this.name]: serialized } };
      }
    } else {
      let serialized: JSONAPISingleResourceDocument['data'] & {
        meta: Record<string, any>;
      } = callSerializeHook(this.card, value, doc);
      let resource: JSONAPIResource = {
        attributes: {
          [this.name]: serialized?.attributes,
        },
      };
      if (serialized == null) {
        return resource;
      }
      if (serialized.relationships) {
        resource.relationships = {};
        for (let [fieldName, relationship] of Object.entries(
          serialized.relationships as Record<string, Relationship>,
        )) {
          resource.relationships[`${this.name}.${fieldName}`] = relationship;
        }
      }

      if (
        this.card === Reflect.getPrototypeOf(value)!.constructor &&
        !this.isPolymorphic
      ) {
        // when our implementation matches the default we don't need to include
        // meta.adoptsFrom
        delete serialized.meta.adoptsFrom;
      }

      if (Object.keys(serialized.meta).length > 0) {
        resource.meta = {
          fields: { [this.name]: serialized.meta },
        };
      }
      return resource;
    }
  }

  async deserialize(
    value: any,
    doc: CardDocument,
    relationships: JSONAPIResource['relationships'] | undefined,
    fieldMeta: CardFields[string] | undefined,
    store: CardStore,
    _instancePromise: Promise<BaseDef>,
    _loadedValue: any,
    relativeTo: RealmResourceIdentifier | URL | undefined,
    opts: DeserializeOpts,
  ): Promise<BaseInstanceType<CardT>> {
    if (primitive in this.card) {
      if (fieldSerializer in this.card) {
        assertIsSerializerName(this.card[fieldSerializer]);
        let serializer = getSerializer(this.card[fieldSerializer]);
        return serializer.deserialize(value, relativeTo, doc, store, opts);
      }
      return value;
    }
    if (fieldSerializer in this.card) {
      assertIsSerializerName(this.card[fieldSerializer]);
      let serializer = getSerializer(this.card[fieldSerializer]);
      value = await serializer.deserialize(value, relativeTo, doc, store, opts);
    }
    if (fieldMeta && Array.isArray(fieldMeta)) {
      throw new Error(
        `fieldMeta for contains field '${
          this.name
        }' is an array: ${JSON.stringify(fieldMeta, null, 2)}`,
      );
    }
    let meta: Partial<Meta> | undefined = fieldMeta;
    let resource: LooseCardResource = {
      attributes: value,
      meta: makeMetaForField(meta, this.name, this.card),
    };
    if (relationships) {
      resource.relationships = Object.fromEntries(
        Object.entries(relationships)
          .filter(([fieldName]) => fieldName.startsWith(`${this.name}.`))
          .map(([fieldName, relationship]) => [
            fieldName.startsWith(`${this.name}.`)
              ? fieldName.substring(this.name.length + 1)
              : fieldName,
            relationship,
          ]),
      );
    }
    let cardClass = await cardClassFromResource(
      resource,
      this.card,
      relativeTo,
    );
    assertNoDeserializeOverride(cardClass);
    return cardClass[deserialize](resource, relativeTo, doc, store, opts);
  }

  emptyValue(_instance: BaseDef) {
    if (primitive in this.card) {
      return this.card[emptyValue];
    } else {
      return new this.card();
    }
  }

  validate(_instance: BaseDef, value: any) {
    if (!(primitive in this.card)) {
      let expectedCard = this.card;
      if (value != null && !instanceOf(value, expectedCard)) {
        throw new Error(
          `field validation error: tried set instance of ${value.constructor.name} as field '${this.name}' but it is not an instance of ${expectedCard.name}`,
        );
      }
    }
    return value;
  }

  component(model: Box<BaseDef>): BoxComponent {
    return fieldComponent(this, model);
  }
}

// Wire fragment for a non-present link — the union of not-loaded and the
// terminal link-error / link-not-found sentinels. All three serialize to the
// identical not-loaded shape: the broken reference is preserved as a
// relationship link (with no errorDoc or discriminator) so a save→reload cycle
// reconstructs the state from the live target rather than persisting transient
// failure data. Shared by the singular and plural linksTo serializers so the
// two paths cannot drift.
function serializeNonPresentLink(
  reference: string,
  relationshipType: string,
  opts?: SerializeOpts,
): Relationship {
  return {
    links: { self: makeRelativeURL(reference, opts) },
    data: { type: relationshipType, id: reference },
  };
}

class LinksTo<CardT extends LinkableDefConstructor> implements Field<CardT> {
  readonly fieldType = 'linksTo';
  private cardThunk: () => CardT;
  private declaredCardThunk: () => CardT;
  readonly computeVia: undefined | (() => unknown);
  readonly name: string;
  readonly description: string | undefined;
  readonly isPolymorphic: undefined | true;
  readonly searchable: Searchable | undefined;
  readonly configuration?: ConfigurationInput<any>;
  readonly queryDefinition?: QueryWithInterpolations;
  constructor({
    cardThunk,
    declaredCardThunk,
    computeVia,
    name,
    isPolymorphic,
    searchable,
    queryDefinition,
  }: FieldConstructor<CardT>) {
    this.cardThunk = cardThunk;
    this.declaredCardThunk = declaredCardThunk ?? cardThunk;
    this.computeVia = computeVia;
    this.name = name;
    this.isPolymorphic = isPolymorphic;
    this.searchable = searchable;
    this.queryDefinition = queryDefinition;
  }

  get card(): CardT {
    return this.cardThunk();
  }

  get declaredCardResolver(): () => CardT {
    return this.declaredCardThunk;
  }

  getter(instance: CardDef): BaseInstanceType<CardT> | undefined {
    let deserialized = getDataBucket(instance);
    entangleWithCardTracking(instance);

    if (this.queryDefinition) {
      let dependencyTrackingContext = runtimeQueryDependencyContext({
        queryField: this.name,
        consumer: instance.id,
        source: 'card-api:linksTo:getter',
      });
      let searchResource = ensureQueryFieldSearchResource(
        getStore(instance),
        instance,
        this,
        dependencyTrackingContext,
      );
      // `ensureQueryFieldSearchResource` mirrors the resource's error state
      // into the bucket. The recognition pattern mirrors the declared
      // `linksTo` path above — a terminal `link-error` / `link-not-found`
      // sentinel surfaces as `undefined`, and `getRelationshipMembershipState` is the
      // structured read.
      let bucketEntry = deserialized.get(this.name);
      if (isLinkError(bucketEntry) || isLinkNotFound(bucketEntry)) {
        return undefined;
      }
      let records = (searchResource as any)?.instances ?? ([] as any[]);
      let value = (records as any[])[0] as BaseInstanceType<CardT> | undefined;
      trackRuntimeRelationshipDependency(
        value,
        this.card,
        dependencyTrackingContext,
      );
      return value;
    }

    let maybeNotLoaded = deserialized.get(this.name);
    if (isNotLoadedValue(maybeNotLoaded)) {
      lazilyLoadLink(instance, this, maybeNotLoaded.reference);
      return undefined;
    }
    // link-error / link-not-found are terminal failure states planted by
    // lazilyLoadLink. They surface to userland as `undefined` (the same shape a
    // not-loaded link produces) and are NOT retried — re-reading must not kick
    // off another fetch. `getRelationshipMembershipState` is the only way to observe the
    // structured failure from outside this module.
    if (isLinkError(maybeNotLoaded) || isLinkNotFound(maybeNotLoaded)) {
      return undefined;
    }
    let value = getter(instance, this);
    trackRuntimeRelationshipDependency(value, this.card);
    // An unset linksTo falls through to LinksTo.emptyValue() which returns
    // `null`; the userland contract is that every non-present state — including
    // not-set — surfaces as `undefined`, so all four non-present discriminants
    // collapse to one nullish shape.
    return value ?? undefined;
  }

  queryableValue(instance: any, stack: CardDef[]): any {
    if (primitive in this.card) {
      throw new Error(
        `the linksTo field '${this.name}' contains a primitive card '${this.card.name}'`,
      );
    }
    if (instance == null) {
      return null;
    }
    // A terminal sentinel queries by its reference, the same as a not-loaded
    // link — the broken reference is preserved in the search doc.
    if (isNonPresentLink(instance)) {
      return { id: instance.reference };
    }
    return this.card[queryableValue](instance, stack);
  }

  serialize(
    value: InstanceType<CardT> | NotLoadedValue,
    doc: JSONAPISingleResourceDocument,
    visited: Set<string>,
    opts?: SerializeOpts,
  ) {
    let relationshipType = isFileDef(this.card)
      ? FileMetaResourceType
      : CardResourceType;
    // A terminal sentinel (link-error / link-not-found) serializes the same way
    // a not-loaded link does — the reference is preserved as a relationship
    // link so a save→reload cycle keeps the broken reference rather than
    // silently dropping it.
    if (isNonPresentLink(value)) {
      return {
        relationships: {
          [this.name]: serializeNonPresentLink(
            value.reference,
            relationshipType,
            opts,
          ),
        },
      };
    }
    if (value == null) {
      return {
        relationships: {
          [this.name]: {
            links: { self: null },
          },
        },
      };
    }
    if (isFileDef(this.card) && !value.id) {
      throw new Error(
        `linksTo field '${this.name}' cannot serialize a FileDef without an id`,
      );
    }
    if (visited.has(value.id)) {
      return {
        relationships: {
          [this.name]: {
            links: {
              self: makeRelativeURL(value.id, opts),
            },
            data: { type: relationshipType, id: value.id },
          },
        },
      };
    }
    if (visited.has((value as CardDef)[localId])) {
      return {
        relationships: {
          [this.name]: {
            data: { type: relationshipType, lid: (value as CardDef)[localId] },
          },
        },
      };
    }

    visited.add(value.id ?? (value as CardDef)[localId]);

    let serialized = callSerializeHook(this.card, value, doc, visited, opts) as
      | (JSONAPIResource & { id: string; type: string })
      | null;
    if (serialized) {
      let resource: JSONAPIResource = {
        relationships: {
          [this.name]: {
            ...(value.id
              ? {
                  links: {
                    self: makeRelativeURL(value.id, opts),
                  },
                  data: { type: relationshipType, id: value.id },
                }
              : {
                  data: {
                    type: relationshipType,
                    lid: (value as CardDef)[localId],
                  },
                }),
          },
        },
      };
      if (
        (!(doc.included ?? []).find((r) => 'id' in r && r.id === value.id) &&
          doc.data.id !== value.id) ||
        (!value.id &&
          !(doc.included ?? []).find(
            (r) => 'lid' in r && r.lid === (value as CardDef)[localId],
          ) &&
          doc.data.lid !== (value as CardDef)[localId])
      ) {
        doc.included = doc.included ?? [];
        doc.included.push(serialized);
      }
      return resource;
    }
    return {
      relationships: {
        [this.name]: {
          links: { self: null },
        },
      },
    };
  }

  async deserialize(
    value: any,
    doc: CardDocument,
    _relationships: undefined,
    _fieldMeta: undefined,
    store: CardStore,
    _instancePromise: Promise<CardDef>,
    loadedValue: any,
    relativeTo: RealmResourceIdentifier | URL | undefined,
    opts: DeserializeOpts,
  ): Promise<BaseInstanceType<CardT> | null | NotLoadedValue> {
    if (!isRelationship(value)) {
      throw new Error(
        `linkTo field '${
          this.name
        }' cannot deserialize non-relationship value ${JSON.stringify(value)}`,
      );
    }
    if (Array.isArray(value.data)) {
      throw new Error(
        `linksTo field '${this.name}' cannot deserialize a list of resource ids`,
      );
    }
    let resourceId =
      value.data && 'id' in value.data ? value.data?.id : undefined;
    let reference = value.links?.self ?? resourceId;
    if (reference == null || reference === '') {
      return null;
    }
    let href = resolveRef(reference, relativeTo);
    let cachedInstance = isFileDef(this.card)
      ? store.getFileMeta(href)
      : store.getCard(href);
    if (cachedInstance && instanceOf(cachedInstance, this.card)) {
      cachedInstance[isSavedInstance] = true;
      return cachedInstance as BaseInstanceType<CardT>;
    }
    //links.self is used to tell the consumer of this payload how to get the resource via HTTP. data.id is used to tell the
    //consumer of this payload how to get the resource from the side loaded included bucket. we need to strictly only
    //consider data.id when calling the resourceFrom() function (which actually loads the resource out of the included
    //bucket). we should never used links.self as part of that consideration. If there is a missing data.id in the resource entity
    //that means that the serialization is incorrect and is not JSON-API compliant.
    let resource =
      resourceId != null ? resourceFrom(doc, resourceId) : undefined;
    if (!resource) {
      if (loadedValue !== undefined) {
        return loadedValue;
      }
      return {
        type: 'not-loaded',
        reference,
      };
    }

    let clazz = await cardClassFromResource(resource, this.card, relativeTo);
    let deserialized = await clazz[deserialize](
      resource,
      relativeTo,
      doc,
      store,
      opts,
    );
    if ('isSavedInstance' in deserialized) {
      (deserialized as CardDef)[isSavedInstance] = true;
    }
    return deserialized as BaseInstanceType<CardT>;
  }

  emptyValue(_instance: CardDef) {
    return null;
  }

  validate(_instance: CardDef, value: any) {
    // we can't actually place this in the constructor since that would break cards whose field type is themselves
    // so the next opportunity we have to test this scenario is during field assignment
    if (primitive in this.card) {
      throw new Error(
        `field validation error: the linksTo field '${this.name}' contains a primitive card '${this.card.name}'`,
      );
    }
    if (value) {
      if (isNonPresentLink(value)) {
        return value;
      }
      if (isFileDef(this.card) && !value.id) {
        throw new Error(
          `field validation error: the linksTo field '${this.name}' cannot reference a FileDef without an id`,
        );
      }
      if (!instanceOf(value, this.card)) {
        console.warn(
          'linksTo instance mismatch',
          JSON.stringify({
            expected: identifyCard(this.card),
            actual: identifyCard(value.constructor as typeof BaseDef),
          }),
        );
        throw new Error(
          `field validation error: tried set ${value.constructor.name} as field '${this.name}' but it is not an instance of ${this.card.name}`,
        );
      }
    }
    return value;
  }

  captureQueryFieldSeedData(
    instance: BaseDef,
    value: CardDef,
    resource: LooseCardResource,
  ) {
    if (this.queryDefinition) {
      captureQueryFieldSeedData(
        instance,
        this.name,
        value ? [value] : [],
        resource,
      );
    }
  }

  component(model: Box<CardDef>): BoxComponent {
    let isComputed = !!this.computeVia || !!this.queryDefinition;
    let fieldName = this.name as keyof CardDef;
    let linksToField = this;
    let getInnerModel = () => {
      let innerModel = model.field(fieldName);
      return innerModel as unknown as Box<CardDef | null>;
    };
    let isFileDefField = isFileDef(linksToField.card);
    function shouldRenderEditor(
      format: Format | undefined,
      defaultFormat: Format,
      isComputed: boolean,
    ) {
      return (format ?? defaultFormat) === 'edit' && !isComputed;
    }
    function getChildFormat(
      format: Format | undefined,
      defaultFormat: Format,
      model: Box<FieldDef>,
      isFileDefField: boolean,
    ) {
      let effectiveFormat = format ?? defaultFormat;
      if (
        effectiveFormat === 'edit' &&
        (('isCardDef' in model.value.constructor &&
          model.value.constructor.isCardDef) ||
          isFileDefField)
      ) {
        return 'fitted';
      }
      return effectiveFormat;
    }
    return class LinksToComponent extends GlimmerComponent<{
      Element: HTMLElement;
      Args: {
        Named: {
          format?: Format;
          displayContainer?: boolean;
          typeConstraint?: ResolvedCodeRef;
          lockConsumingRealm?: boolean;
          consumingRealm?: URL;
        };
      };
      Blocks: {};
    }> {
      <template>
        <CardCrudFunctionsConsumer as |cardCrudFunctions|>
          <DefaultFormatsConsumer as |defaultFormats|>
            {{#let (brokenSingularLink model linksToField.name) as |broken|}}
              {{#if
                (shouldRenderEditor @format defaultFormats.cardDef isComputed)
              }}
                <LinksToEditor
                  @model={{(getInnerModel)}}
                  @field={{linksToField}}
                  @brokenLink={{broken}}
                  @typeConstraint={{@typeConstraint}}
                  @lockConsumingRealm={{@lockConsumingRealm}}
                  @consumingRealm={{@consumingRealm}}
                  @createCard={{cardCrudFunctions.createCard}}
                  ...attributes
                />
              {{else if broken}}
                <BrokenLinkTemplate
                  @brokenUrl={{broken.reference}}
                  @errorDoc={{broken.errorDoc}}
                  @state={{broken.kind}}
                  @format={{brokenLinkFormat @format defaultFormats.cardDef}}
                  @displayName={{cardTypeName broken.reference}}
                  @viewCard={{cardCrudFunctions.viewCard}}
                  ...attributes
                />
              {{else}}
                {{#let (fieldComponent linksToField model) as |FieldComponent|}}
                  <FieldComponent
                    @format={{getChildFormat
                      @format
                      defaultFormats.cardDef
                      model
                      isFileDefField
                    }}
                    @displayContainer={{@displayContainer}}
                    ...attributes
                  />
                {{/let}}
              {{/if}}
            {{/let}}
          </DefaultFormatsConsumer>
        </CardCrudFunctionsConsumer>
      </template>
    };
  }
}

class LinksToMany<FieldT extends LinkableDefConstructor> implements Field<
  FieldT,
  any[] | null
> {
  readonly fieldType = 'linksToMany';
  private cardThunk: () => FieldT;
  private declaredCardThunk: () => FieldT;
  private declaredCardCache: FieldT | undefined;
  readonly computeVia: undefined | (() => unknown);
  readonly name: string;
  readonly isPolymorphic: undefined | true;
  readonly searchable: Searchable | undefined;
  readonly configuration?: ConfigurationInput<any>;
  readonly queryDefinition?: QueryWithInterpolations;
  constructor({
    cardThunk,
    declaredCardThunk,
    computeVia,
    name,
    isPolymorphic,
    searchable,
    queryDefinition,
  }: FieldConstructor<FieldT>) {
    this.cardThunk = cardThunk;
    this.declaredCardThunk = declaredCardThunk ?? cardThunk;
    this.computeVia = computeVia;
    this.name = name;
    this.isPolymorphic = isPolymorphic;
    this.searchable = searchable;
    this.queryDefinition = queryDefinition;
  }

  get card(): FieldT {
    return this.cardThunk();
  }

  private get declaredCard(): FieldT {
    if (!this.declaredCardCache) {
      this.declaredCardCache = this.declaredCardThunk();
    }
    return this.declaredCardCache;
  }

  get declaredCardResolver(): () => FieldT {
    return this.declaredCardThunk;
  }

  getter(instance: CardDef): BaseInstanceType<FieldT> {
    entangleWithCardTracking(instance);
    if (this.computeVia) {
      return getter(instance, this);
    }

    let deserialized = getDataBucket(instance);

    if (this.queryDefinition) {
      let dependencyTrackingContext = runtimeQueryDependencyContext({
        queryField: this.name,
        consumer: instance.id,
        source: 'card-api:linksToMany:getter',
      });
      let searchResource = ensureQueryFieldSearchResource(
        getStore(instance),
        instance,
        this,
        dependencyTrackingContext,
      )!;
      // Resource-level failure: `ensureQueryFieldSearchResource` plants a
      // single whole-field sentinel in the bucket (the search fails as a
      // unit, not per element). The empty array hands callers a usable
      // shape; the structured failure surfaces through `getRelationshipMembershipState`.
      let bucketEntry = deserialized.get(this.name);
      if (isLinkError(bucketEntry) || isLinkNotFound(bucketEntry)) {
        // DIAGNOSTIC LOGGING (CS-11221) — remove after CI passes.
        console.error(
          '[CS-11221 DIAG] linksToMany getter returning emptyValue (bucket sentinel)',
          {
            fieldName: this.name,
            ownerType: instance?.constructor?.name,
            sentinelType: (bucketEntry as { type?: string })?.type,
          },
        );
        return this.emptyValue(instance) as BaseInstanceType<FieldT>;
      }
      let records = searchResource.instances ?? ([] as any[]);
      trackRuntimeRelationshipDependencies(
        records,
        this.card,
        dependencyTrackingContext,
      );
      return records as BaseInstanceType<FieldT>;
    }

    // Non-query fields
    let value = deserialized.get(this.name);

    if (!value) {
      value = this.emptyValue(instance);
      deserialized.set(this.name, value);
    }

    if (isNotLoadedValue(value)) {
      value = this.emptyValue(instance);
      deserialized.set(this.name, value);
      lazilyLoadLink(instance, this, value.reference, { value });
      return this.emptyValue(instance) as BaseInstanceType<FieldT>;
    }

    // A whole-field terminal sentinel (a computed linksToMany that consumes an
    // upstream link which resolved to an error / not-found) is terminal: surface
    // an empty array to userland and do NOT retrigger the loader. Per-slot
    // terminal sentinels living inside the array are handled below — they are
    // simply skipped by the not-loaded retrigger scan.
    if (isLinkError(value) || isLinkNotFound(value)) {
      return this.emptyValue(instance) as BaseInstanceType<FieldT>;
    }

    if (!Array.isArray(value)) {
      throw new Error(
        `LinksToMany field '${
          this.name
        }' expected array but got ${typeof value}`,
      );
    }

    // Sentinels live in the backing array, but the WatchedArray hides them from
    // userland per-slot access (`arr[i]` is `Card | undefined`). Scan the raw
    // backing array — not the hiding proxy — so the not-loaded slots are still
    // visible to kick off their lazy load.
    let rawEntries = rawArrayValues(value);
    let hasNotLoaded = false;
    for (let entry of rawEntries) {
      if (isNotLoadedValue(entry)) {
        hasNotLoaded = true;
        break;
      }
    }
    if (hasNotLoaded) {
      // Each not-loaded sentinel stays in place so the lazy loader can swap it
      // for the resolved card (success) or a terminal error/not-found sentinel
      // (failure). The array identity never changes, so Glimmer re-renders on
      // the in-place swap. A failed slot becomes terminal and surfaces as
      // `undefined` per-slot — `getRelationshipMembershipState` is the only way to read its
      // structured failure state.
      for (let entry of rawEntries) {
        if (isNotLoadedValue(entry) && !(entry as any).loading) {
          lazilyLoadLink(instance, this, entry.reference, { value });
          (entry as any).loading = true;
        }
      }
    }

    trackRuntimeRelationshipDependencies(rawEntries, this.card);
    return value as BaseInstanceType<FieldT>;
  }

  queryableValue(instances: any[] | null, stack: CardDef[]): any[] | null {
    // A whole-field sentinel (a query-field whose search resource errored, or
    // a computed `linksToMany` that consumes an unresolved upstream link)
    // arrives here as a single LinkErrorValue / LinkNotFoundValue / NotLoaded
    // object — NOT an array. Without this guard, the `[...instances]` spread
    // below would throw `instances is not iterable`, the render would fail,
    // and the indexer would classify the consumer as instance-error — the
    // exact cascade the field-getter side of the tolerance machine avoids.
    // Treat a non-present whole-field sentinel as an empty plural for index
    // purposes; the broken reference is preserved on the wire via the
    // serializer (`relationships.{field}` carries the sentinel's `reference`),
    // and `getRelationshipMembershipState` is the structured read surface for the failure
    // state outside the index.
    if (isNonPresentLink(instances)) {
      return null;
    }
    if (instances === null || instances.length === 0) {
      // we intentionally use a "null" to represent an empty plural field as
      // this is a limitation to SQLite's json_tree() function when trying to match
      // plural fields that are empty
      return null;
    }

    // Read the raw backing array (not the hiding proxy) so a broken slot still
    // serializes its reference into the queryable value rather than dropping out
    // as `undefined`. Replacing the WatchedArray proxy with a plain array also
    // keeps the result structuredClone-able for the postMessage boundary.
    let results = rawArrayValues(instances)
      .map((instance) => {
        if (instance == null) {
          return null;
        }
        if (primitive in instance) {
          throw new Error(
            `the linksToMany field '${this.name}' contains a primitive card '${instance.name}'`,
          );
        }
        if (isNonPresentLink(instance)) {
          return { id: instance.reference };
        }
        return this.card[queryableValue](instance, stack);
      })
      .filter((i) => i != null);
    return results.length === 0 ? null : results;
  }

  serialize(
    values: BaseInstanceType<FieldT>[] | null | NotLoadedValue | undefined,
    doc: JSONAPISingleResourceDocument,
    visited: Set<string>,
    opts?: SerializeOpts,
  ) {
    // Check for skip-serialization marker for computed fields that can't be computed
    if (
      values &&
      typeof values === 'object' &&
      'type' in values &&
      (values as any).type === 'skip-serialization'
    ) {
      return { relationships: {} };
    }

    // this can be a not loaded value happen when the linksToMany is a
    // computed that consumes a linkTo field that is not loaded (or a terminal
    // error / not-found sentinel surfacing through the same computed path)
    if (isNonPresentLink(values)) {
      return { relationships: {} };
    }

    if (values == null || values.length === 0) {
      return {
        relationships: {
          [this.name]: {
            links: { self: null },
          },
        },
      };
    }

    if (!Array.isArray(values)) {
      throw new Error(`Expected array for field value ${this.name}`);
    }

    let relationshipType = isFileDef(this.card)
      ? FileMetaResourceType
      : CardResourceType;
    let relationships: Record<string, Relationship> = {};
    // Iterate the raw backing array so broken slots serialize their reference
    // through `serializeNonPresentLink` instead of collapsing to `data: null`.
    rawArrayValues(values).forEach((value, i) => {
      if (value == null) {
        relationships[`${this.name}\.${i}`] = {
          links: {
            self: null,
          },
          data: null,
        };
        return;
      }
      if (isNonPresentLink(value)) {
        relationships[`${this.name}\.${i}`] = serializeNonPresentLink(
          value.reference,
          relationshipType,
          opts,
        );
        return;
      }
      if (isFileDef(this.card) && !value.id) {
        throw new Error(
          `linksToMany field '${this.name}' cannot serialize a FileDef without an id`,
        );
      }
      if (visited.has(value.id)) {
        relationships[`${this.name}\.${i}`] = {
          links: {
            self: makeRelativeURL(value.id, opts),
          },
          data: { type: relationshipType, id: value.id },
        };
        return;
      }
      if (visited.has((value as CardDef)[localId])) {
        relationships[`${this.name}\.${i}`] = {
          data: { type: relationshipType, lid: (value as CardDef)[localId] },
        };
        return;
      }

      visited.add(value.id ?? (value as CardDef)[localId]);
      let serialized: JSONAPIResource & ResourceID = callSerializeHook(
        this.card,
        value,
        doc,
        visited,
        opts,
      );
      if (serialized.meta && Object.keys(serialized.meta).length === 0) {
        delete serialized.meta;
      }
      if (
        (!(doc.included ?? []).find((r) => 'id' in r && r.id === value.id) &&
          doc.data.id !== value.id) ||
        (!value.id &&
          !(doc.included ?? []).find(
            (r) => 'lid' in r && r.lid === (value as CardDef)[localId],
          ) &&
          doc.data.lid !== (value as CardDef)[localId])
      ) {
        doc.included = doc.included ?? [];
        doc.included.push(serialized);
      }

      relationships[`${this.name}\.${i}`] = {
        ...(value.id
          ? {
              links: {
                self: makeRelativeURL(value.id, opts),
              },
              data: { type: relationshipType, id: value.id },
            }
          : {
              data: {
                type: relationshipType,
                lid: (value as CardDef)[localId],
              },
            }),
      };
    });

    return { relationships };
  }

  async deserialize(
    values: any,
    doc: CardDocument,
    _relationships: undefined,
    _fieldMeta: undefined,
    store: CardStore,
    instancePromise: Promise<BaseDef>,
    loadedValues: any,
    relativeTo: RealmResourceIdentifier | URL | undefined,
    opts: DeserializeOpts,
  ): Promise<(BaseInstanceType<FieldT> | NotLoadedValue)[]> {
    let relationships: Relationship[];
    if (Array.isArray(values)) {
      relationships = values;
    } else {
      if (!isRelationship(values)) {
        throw new Error(
          `linksToMany field '${
            this.name
          }' cannot deserialize non-relationship value ${JSON.stringify(
            values,
          )}`,
        );
      }
      if (!Array.isArray(values.data)) {
        // A `{ links: { self: null } }` relationship (no `data` array) is an
        // authored empty — no members. Fall through with an empty relationship
        // list so the shared WatchedArray path below wraps (and tags) it the
        // same as an empty `{ data: [] }`: a mutable, reactive backing array,
        // not a bare `[]` (which would hand a later push/splice a plain array
        // and skip the WatchedArray subscriber).
        relationships = [];
      } else {
        relationships = values.data.map((entry) => ({
          links: {
            self: entry && 'id' in entry ? (entry.id ?? null) : null,
          },
          data: entry,
        }));
      }
    }

    let resources: Promise<BaseInstanceType<FieldT> | NotLoadedValue>[] =
      relationships.map(async (value: Relationship) => {
        if (!isRelationship(value)) {
          throw new Error(
            `linksToMany field '${
              this.name
            }' cannot deserialize non-relationship value ${JSON.stringify(
              value,
            )}`,
          );
        }
        if (Array.isArray(value.data)) {
          throw new Error(
            `linksToMany field '${this.name}' cannot deserialize a list of resource ids`,
          );
        }
        // links.self is used to tell the consumer of this payload how to get the resource via HTTP.
        // data.id is used to tell the consumer how to find the resource in the included bucket.
        // Prefer data.id for resourceFrom(), and fall back to links.self when data.id is missing
        let resourceId =
          value.data && 'id' in value.data ? value.data?.id : undefined;
        let reference = value.links?.self ?? resourceId;
        if (reference == null) {
          return null;
        }
        let normalizedReference = resolveRef(reference, relativeTo);
        let cachedInstance = isFileDef(this.card)
          ? store.getFileMeta(normalizedReference)
          : store.getCard(normalizedReference);

        if (cachedInstance && instanceOf(cachedInstance, this.card)) {
          cachedInstance[isSavedInstance] = true;
          return cachedInstance;
        }
        if (!resourceId) {
          resourceId = normalizedReference;
        }
        if (loadedValues && Array.isArray(loadedValues)) {
          let loadedValue = loadedValues.find(
            (v) => isCardOrField(v) && 'id' in v && v.id === resourceId,
          );
          if (loadedValue) {
            return loadedValue;
          }
        }
        let resource = resourceFrom(doc, resourceId);
        if (!resource && reference !== normalizedReference) {
          resource = resourceFrom(doc, reference);
        }
        if (!resource) {
          return {
            type: 'not-loaded',
            reference,
          };
        }
        let clazz = await cardClassFromResource(
          resource,
          this.card,
          relativeTo,
        );
        let deserialized = await clazz[deserialize](
          resource,
          relativeTo,
          doc,
          store,
          opts,
        );
        if ('isSavedInstance' in deserialized) {
          (deserialized as CardDef)[isSavedInstance] = true;
        }
        return deserialized;
      });

    let resolved = await Promise.all(resources);
    let watched = new WatchedArray(
      (oldValue, value) =>
        instancePromise.then((instance) => {
          applySubscribersToInstanceValue(
            instance,
            this,
            oldValue as BaseDef[],
            value as BaseDef[],
          );
          notifySubscribers(instance, this.name, value);
          notifyCardTracking(instance);
        }),
      resolved,
      { hideSlot: isNonPresentLink },
    );
    // An authored-empty plural relationship (`{ data: [] }` or
    // `{ links: { self: null } }` in the source) deserializes to an empty
    // array — tag it authored so serialization keeps it as `{ self: null }`
    // rather than dropping it like a never-set link. A computed field's
    // emptiness is derived, never authored, so it is never tagged.
    if (resolved.length === 0 && !this.computeVia) {
      markAuthoredEmptyLink(watched);
    }
    return watched;
  }

  emptyValue(instance: BaseDef) {
    return new WatchedArray(
      (oldValue, value) => {
        applySubscribersToInstanceValue(
          instance,
          this,
          oldValue as BaseDef[],
          value as BaseDef[],
        );
        notifySubscribers(instance, this.name, value);
        notifyCardTracking(instance);
      },
      [],
      { hideSlot: isNonPresentLink },
    );
  }

  validate(instance: BaseDef, values: any[] | null) {
    if (primitive in this.card) {
      throw new Error(
        `field validation error: the linksToMany field '${this.name}' contains a primitive card '${this.card.name}'`,
      );
    }

    if (values == null) {
      return values;
    }

    if (!Array.isArray(values)) {
      throw new Error(
        `field validation error: Expected array for field value of field '${this.name}'`,
      );
    }

    let expectedCard = this.declaredCard;
    for (let value of values) {
      if (
        !isNonPresentLink(value) &&
        value != null &&
        !instanceOf(value, expectedCard)
      ) {
        throw new Error(
          `field validation error: tried set ${value.constructor.name} as field '${this.name}' but it is not an instance of ${expectedCard.name}`,
        );
      }
      if (
        !isNonPresentLink(value) &&
        value != null &&
        isFileDef(expectedCard) &&
        !value.id
      ) {
        throw new Error(
          `field validation error: the linksToMany field '${this.name}' cannot reference a FileDef without an id`,
        );
      }
    }

    return new WatchedArray(
      (oldValue, value) => {
        applySubscribersToInstanceValue(
          instance,
          this,
          oldValue as BaseDef[],
          value as BaseDef[],
        );
        notifySubscribers(instance, this.name, value);
        notifyCardTracking(instance);
      },
      // Read raw so re-assigning a field that already holds broken slots keeps
      // the sentinels in the new backing array rather than baking in `undefined`.
      rawArrayValues(values),
      { hideSlot: isNonPresentLink },
    );
  }

  captureQueryFieldSeedData(
    instance: BaseDef,
    value: CardDef[],
    resource: LooseCardResource,
  ) {
    if (this.queryDefinition) {
      captureQueryFieldSeedData(instance, this.name, value, resource);
    }
  }

  component(model: Box<CardDef>): BoxComponent {
    let fieldName = this.name as keyof BaseDef;
    let arrayField = model.field(
      fieldName,
      useIndexBasedKey in this.card,
    ) as unknown as Box<CardDef[]>;
    return getLinksToManyComponent({
      model,
      arrayField,
      field: this,
      cardTypeFor,
    });
  }
}

// Read the singular `linksTo` relationship state for the field named
// `fieldName` on the card that `model` boxes, returning the state only when it
// is a terminal failure (`error` / `not-found`). Every other kind — including
// `not-loaded` and `not-set`, which the field getter also surfaces as
// `undefined` — yields `undefined` here so the caller falls through to the
// normal render path. `getRelationshipMembershipState` is a pure read (it never retriggers
// `lazilyLoadLink`), so this is the single call per render that distinguishes a
// broken link from an absent one.
function brokenSingularLink(
  model: Box<CardDef>,
  fieldName: string,
): Extract<RelationshipState, { kind: 'error' | 'not-found' }> | undefined {
  let owner = model.value;
  if (owner == null) {
    return undefined;
  }
  let slot = getRelationshipMembershipState(owner, fieldName).membership?.[0];
  if (slot && (slot.kind === 'error' || slot.kind === 'not-found')) {
    return slot;
  }
  return undefined;
}

// The broken-link placeholder stands in for the card that failed to load, so it
// adopts the same footprint the card would have had. The placeholder defines
// only four footprints (`isolated` / `fitted` / `embedded` / `atom`), so every
// other reachable `Format` is mapped to its nearest stand-in rather than cast:
// `edit` collapses to `fitted` (mirroring `getChildFormat`, since a computed
// linksTo can reach the view path in edit format and a card def has no editable
// slot when it can't load); `head` / `metadata` / `markdown` / `form` have no
// dedicated placeholder footprint and fall back to the general-purpose
// `embedded` layout.
export function brokenLinkFormat(
  format: Format | undefined,
  defaultFormat: Format,
): BrokenLinkFormat {
  let effectiveFormat = format ?? defaultFormat;
  switch (effectiveFormat) {
    case 'isolated':
    case 'fitted':
    case 'atom':
    case 'embedded':
      return effectiveFormat;
    case 'edit':
      return 'fitted';
    default:
      return 'embedded';
  }
}

function fieldComponent(
  field: Field<typeof BaseDef>,
  model: Box<BaseDef>,
): BoxComponent {
  let fieldName = field.name as keyof BaseDef;
  let card: typeof BaseDef;
  let override =
    model.value && typeof model.value === 'object'
      ? getFieldOverrides(model.value)?.get(field.name)
      : undefined;

  if (primitive in field.card) {
    card = override ?? field.card;
  } else {
    card =
      (model.value[fieldName]?.constructor as typeof BaseDef) ??
      override ??
      field.card;
  }
  let innerModel = model.field(fieldName) as unknown as Box<BaseDef>;
  return getBoxComponent(card, innerModel, field);
}

interface InternalFieldInitializer {
  setupField(
    name: string,
    ownerPrototype: BaseDef,
  ): {
    enumerable?: boolean;
    get(): unknown;
    set(value: unknown): void;
  };
  description: string | undefined;
}

// our decorators are implemented by Babel, not TypeScript, so they have a
// different signature than Typescript thinks they do.
export const field = function (
  target: BaseDef,
  key: string | symbol,
  { initializer }: { initializer(): any },
) {
  if (typeof key === 'symbol') {
    throw new Error(
      `the @field decorator only supports string field names, not symbols`,
    );
  }
  if (!(target instanceof BaseDef)) {
    throw new Error(
      `the @field decorator can only be used inside classes that extend BaseDef`,
    );
  }
  let init = initializer() as InternalFieldInitializer;
  let descriptor = init.setupField(key, target as BaseDef);
  if (init.description) {
    setFieldDescription(target.constructor, key as string, init.description);
  }
  return descriptor;
} as unknown as PropertyDecorator;
(field as any)[fieldDecorator] = undefined;

export function containsMany<FieldT extends FieldDefConstructor>(
  field: FieldT,
  options?: Options,
): BaseInstanceType<FieldT>[] {
  return {
    setupField(fieldName: string, _ownerPrototype: BaseDef) {
      let { computeVia, searchable } = options ?? {};
      let instance = new ContainsMany({
        cardThunk: cardThunk(field),
        computeVia,
        name: fieldName,
        searchable,
      });
      (instance as any).configuration = options?.configuration;
      return makeDescriptor(instance);
    },
    description: options?.description,
  } satisfies InternalFieldInitializer as any;
}

export function contains<FieldT extends FieldDefConstructor>(
  field: FieldT,
  options?: Options,
): BaseInstanceType<FieldT> {
  return {
    setupField(fieldName: string, _ownerPrototype: BaseDef) {
      let { computeVia, searchable } = options ?? {};
      let instance = new Contains({
        cardThunk: cardThunk(field),
        computeVia,
        name: fieldName,
        searchable,
      });
      (instance as any).configuration = options?.configuration;
      return makeDescriptor(instance);
    },
    description: options?.description,
  } satisfies InternalFieldInitializer as any;
}

export function linksTo<CardT extends LinkableDefConstructor>(
  cardOrThunk: CardT | (() => CardT),
  options?: RelationshipOptions,
): BaseInstanceType<CardT> {
  return {
    setupField(fieldName: string, ownerPrototype: BaseDef) {
      let { computeVia, searchable, query } = options ?? {};
      let fieldCardThunk = cardThunk(cardOrThunk);
      if (query) {
        validateRelationshipQuery(ownerPrototype, fieldName, query);
      }
      let instance = new LinksTo({
        cardThunk: fieldCardThunk,
        declaredCardThunk: fieldCardThunk,
        computeVia,
        name: fieldName,
        searchable,
        queryDefinition: query,
      });
      (instance as any).configuration = options?.configuration;
      return makeDescriptor(instance);
    },
    description: options?.description,
  } satisfies InternalFieldInitializer as any;
}

export function linksToMany<CardT extends LinkableDefConstructor>(
  cardOrThunk: CardT | (() => CardT),
  options?: RelationshipOptions,
): BaseInstanceType<CardT>[] {
  return {
    setupField(fieldName: string, ownerPrototype: BaseDef) {
      let { computeVia, searchable, query } = options ?? {};
      let fieldCardThunk = cardThunk(cardOrThunk);
      if (query) {
        validateRelationshipQuery(ownerPrototype, fieldName, query);
      }
      let instance = new LinksToMany({
        cardThunk: fieldCardThunk,
        declaredCardThunk: fieldCardThunk,
        computeVia,
        name: fieldName,
        searchable,
        queryDefinition: query,
      });
      (instance as any).configuration = options?.configuration;
      return makeDescriptor(instance);
    },
    description: options?.description,
  } satisfies InternalFieldInitializer as any;
}

// (moved below BaseDef & FieldDef declarations)

// TODO: consider making this abstract
export class BaseDef {
  // this is here because CardBase has no public instance methods, so without it
  // typescript considers everything a valid card.
  [isBaseInstance] = true;
  // [relativeTo] actually becomes really important for Card/Field separation. FieldDefs
  // may contain interior fields that have relative links. FieldDef's though have no ID.
  // So we need a [relativeTo] property that derives from the root document ID in order to
  // resolve relative links at the FieldDef level.
  [relativeTo]: RealmResourceIdentifier | URL | undefined = undefined;
  [meta]: CardResourceMeta | undefined = undefined;
  declare ['constructor']: BaseDefConstructor;
  static baseDef: undefined;
  static data?: Record<string, any>; // TODO probably refactor this away all together
  static displayName = 'Base';
  static icon: CardOrFieldTypeIcon;

  static getDisplayName(instance: BaseDef) {
    return instance.constructor.displayName;
  }
  static getIconComponent(instance: BaseDef) {
    return instance.constructor.icon;
  }

  get [realmURL](): URL | undefined {
    return undefined; // override in CardDef, FieldDef
  }

  static [emptyValue]: object | string | number | null | boolean | undefined;

  static [serialize](
    value: any,
    doc: JSONAPISingleResourceDocument,
    visited?: Set<string>,
    opts?: SerializeOpts,
  ): any {
    // note that primitive can only exist in field definition
    if (primitive in this) {
      // primitive cards can override this as need be
      return value;
    } else {
      return serializeCardResource(value, doc, opts, visited);
    }
  }

  static [formatQuery](value: any): any {
    if (primitive in this) {
      return value;
    }
    throw new Error(`Cannot format query value for composite card/field`);
  }

  static [queryableValue](value: any, stack: BaseDef[] = []): any {
    if (primitive in this) {
      if (fieldSerializer in this) {
        assertIsSerializerName(this[fieldSerializer]);
        let serializer = getSerializer(this[fieldSerializer]);
        return serializer.queryableValue(value, stack);
      }
      return value;
    } else {
      if (value == null) {
        return null;
      }
      let valueId = (value as { id?: string }).id;
      // Cycle guard. `stack.includes(value)` alone is object-identity, which
      // misses a logical cycle when the same card is re-entered as a DIFFERENT
      // object instance (re-deserialization / query-resolution producing fresh
      // objects mid-render) — recursing without bound. Also break by id, the
      // same id-based `visited` guard `serialize` uses (`visited.has(value.id)`
      // in the field `serialize` paths), so a fresh-object re-entry degrades to
      // `{ id }` instead of recursing forever.
      if (
        stack.includes(value) ||
        (valueId != null &&
          stack.some((s) => (s as { id?: string }).id === valueId))
      ) {
        return { id: valueId };
      }
      function makeAbsoluteURL(maybeRelativeReference: string) {
        if (!value[relativeTo]) {
          return maybeRelativeReference;
        }
        return resolveRef(maybeRelativeReference, value[relativeTo]);
      }
      return Object.fromEntries(
        Object.entries(
          getFields(value, {
            includeComputeds: true,
            usedLinksToFieldsOnly: true,
          }),
        )
          // A query-backed field is resolved live from a query; the index has no
          // way to invalidate it when matching cards change, so its value in the
          // search doc would always be stale. Skip it entirely rather than
          // traverse (and deep-resolve) the query closure into the doc — the
          // host re-resolves these fields at view time, and the indexer records
          // membership from `relationships.{field}.data` separately.
          .filter(([, field]) => !field?.queryDefinition)
          .map(([fieldName, field]) => {
            let rawValue = peekAtField(value, fieldName);
            if (field?.fieldType === 'linksToMany') {
              return [
                fieldName,
                field
                  .queryableValue(rawValue, [value, ...stack])
                  ?.map((v: any) => {
                    return { ...v, id: makeAbsoluteURL(v.id) };
                  }) ?? null,
              ];
            }
            if (isNonPresentLink(rawValue)) {
              let normalizedId = rawValue.reference;
              if (value[relativeTo]) {
                normalizedId = resolveRef(normalizedId, value[relativeTo]);
              }
              return [fieldName, { id: makeAbsoluteURL(rawValue.reference) }];
            }
            // Reuse the value we already peeked above instead of re-reading
            // through the descriptor — for computed fields the descriptor
            // get path re-invokes `computeVia`, doubling the work for every
            // contains/contains-many/links-to field in the search doc.
            return [
              fieldName,
              getQueryableValue(field!, rawValue, [value, ...stack]),
            ];
          }),
      );
    }
  }

  static async [deserialize]<T extends BaseDefConstructor>(
    this: T,
    data: any,
    relativeTo: RealmResourceIdentifier | URL | undefined,
    doc?: CardDocument,
    store?: CardStore,
    opts?: DeserializeOpts,
  ): Promise<BaseInstanceType<T>> {
    if (primitive in this) {
      return data;
    }
    return _createFromSerialized(this, data, doc, relativeTo, store, opts);
  }

  static getComponent(
    card: BaseDef,
    field?: Field,
    opts?: { componentCodeRef?: CodeRef },
  ) {
    return getComponent(card, field, opts);
  }

  static assignInitialFieldValue(
    instance: BaseDef,
    fieldName: string,
    value: any,
  ) {
    (instance as any)[fieldName] = value;
  }

  constructor(data?: Record<string, any>) {
    if (data !== undefined) {
      for (let [fieldName, value] of Object.entries(data)) {
        this.constructor.assignInitialFieldValue(this, fieldName, value);
      }
    }
  }
}
export class Component<
  CardT extends BaseDefConstructor,
> extends GlimmerComponent<SignatureFor<CardT>> {}

export type CreateCardFn = (
  ref: CodeRef,
  relativeTo: RealmResourceIdentifier | URL | undefined,
  opts?: {
    realmURL?: URL; // the realm to create the card in
    localDir?: LocalPath; // the local directory path within the realm to create the card file
    doc?: LooseSingleCardDocument; // initial data for the card
    cardModeAfterCreation?: Format; // by default, the new card opens in the stack in edit mode
  },
) => Promise<string | undefined>;

export type ViewCardFn = (
  cardOrURL: CardDef | URL | RealmResourceIdentifier,
  format?: Format,
  opts?: {
    type?: 'card' | 'file';
    openCardInRightMostStack?: boolean;
    stackIndex?: number;
    fieldType?: 'linksTo' | 'contains' | 'containsMany' | 'linksToMany';
    fieldName?: string;
    useBaseTemplate?: boolean;
  },
) => void;

export type EditCardFn = (
  card: CardDef,
  opts?: { useBaseTemplate?: boolean },
) => void;

export type SaveCardFn = (id: RealmResourceIdentifier) => void;

export type DeleteCardFn = (cardOrId: CardDef | URL | string) => Promise<void>;

export interface CardCrudFunctions {
  createCard: CreateCardFn;
  saveCard: SaveCardFn;
  editCard: EditCardFn;
  viewCard: ViewCardFn;
  deleteCard: DeleteCardFn;
}

export type BaseDefComponent = ComponentLike<{
  Blocks: {};
  Element: any;
  Args: {
    cardOrField: typeof BaseDef;
    fields: any;
    format: Format;
    model: any;
    set: Setter;
    fieldName: string | undefined;
    context?: CardContext;
    canEdit?: boolean;
    typeConstraint?: ResolvedCodeRef;
    // Resolved, merged field configuration (if applicable)
    configuration?: FieldConfiguration | undefined;
    createCard: CreateCardFn;
    viewCard: ViewCardFn;
    editCard: EditCardFn;
    saveCard: SaveCardFn;
  };
}>;

export class FieldDef extends BaseDef {
  // this changes the shape of the class type FieldDef so that a CardDef
  // class type cannot masquerade as a FieldDef class type
  static isFieldDef = true;
  static displayName = 'Field';
  static icon = RectangleEllipsisIcon;
  [realmContext]?: string;

  get [realmURL](): URL | undefined {
    let realmURLString = this[realmContext];
    return realmURLString ? new URL(realmURLString) : undefined;
  }

  // Optional provider for default configuration, merged with per-usage configuration
  static configuration?: ConfigurationInput<any>;

  static embedded: BaseDefComponent = MissingTemplate;
  static edit: BaseDefComponent = FieldDefEditTemplate;
  static atom: BaseDefComponent = DefaultAtomViewTemplate;
  static fitted: BaseDefComponent = MissingTemplate;
  // Default `markdown` fallback (CS-10784): renders the field's HTML embedded
  // template into a hidden source container, then converts it to markdown via
  // turndown (registered on `globalThis` by `packages/host`). Subclasses can
  // override `static markdown` to author bespoke markdown directly.
  static markdown: BaseDefComponent = DefaultMarkdownFallbackTemplate;
}

export class ReadOnlyField extends FieldDef {
  static [primitive]: string;
  static [useIndexBasedKey]: never;
  static embedded = class Embedded extends Component<typeof this> {
    <template>{{@model}}</template>
  };
  static edit = class Edit extends Component<typeof this> {
    <template>{{@model}}</template>
  };
  // CS-10785: emit plain text, escaped so markdown metacharacters in the
  // raw string (e.g. `*`, `#`, `1.`) don't trigger formatting when the
  // value is interpolated into a surrounding markdown document.
  static markdown = class Markdown extends Component<typeof this> {
    <template>{{markdownEscape @model}}</template>
  };
}

export class StringField extends FieldDef {
  static displayName = 'String';
  static icon = LetterCaseIcon;
  static [primitive]: string;
  static [useIndexBasedKey]: never;
  static embedded = class Embedded extends Component<typeof this> {
    <template>{{@model}}</template>
  };
  static edit = class Edit extends Component<typeof this> {
    <template>
      <BoxelInput
        @value={{@model}}
        @onInput={{@set}}
        @disabled={{not @canEdit}}
      />
    </template>
  };
  static atom = class Atom extends Component<typeof this> {
    <template>{{@model}}</template>
  };
  // CS-10785: plain text, escaped. Same rationale as ReadOnlyField.
  // Explicit `BaseDefComponent` annotation so subclass overrides (e.g.
  // TextAreaField, MarkdownField, MaybeBase64Field) aren't forced to
  // structurally match this inline class shape.
  static markdown: BaseDefComponent = class Markdown extends Component<
    typeof this
  > {
    <template>{{markdownEscape @model}}</template>
  };
}

// TODO: This is a simple workaround until the thumbnailURL is converted into an actual image field
export class MaybeBase64Field extends StringField {
  static embedded = class Embedded extends Component<typeof this> {
    get isBase64() {
      return this.args.model?.startsWith('data:');
    }
    <template>
      {{#if this.isBase64}}
        <em>(Base64 encoded value)</em>
      {{else}}
        {{@model}}
      {{/if}}
    </template>
  };
  static atom = MaybeBase64Field.embedded;
  // CS-10785: suppress embedded base64 payloads from the markdown emission —
  // they're never useful to downstream markdown consumers and would blow up
  // the output size. Non-base64 strings are escaped like a StringField.
  static markdown = class Markdown extends Component<typeof this> {
    get isBase64() {
      return this.args.model?.startsWith('data:');
    }
    get escaped() {
      return markdownEscape(this.args.model);
    }
    <template>
      {{#if this.isBase64}}
        [binary content]
      {{else}}
        {{this.escaped}}
      {{/if}}
    </template>
  };
}

export class TextAreaField extends StringField {
  static displayName = 'TextArea';
  static icon = TextAreaIcon;
  static edit = class Edit extends Component<typeof this> {
    <template>
      <BoxelInput
        class='boxel-text-area'
        @value={{@model}}
        @onInput={{@set}}
        @type='textarea'
        @readonly={{not @canEdit}}
      />
    </template>
  };
  // CS-10785: escape the content and convert single `\n` to a CommonMark
  // hard-break (`  \n`) so a multi-line text area renders as stacked lines
  // rather than collapsing into one paragraph. Empty-line paragraph breaks
  // (`\n\n`) are preserved — the regex touches every newline, producing
  // `  \n  \n`, which is still a valid paragraph separator.
  // Explicit `BaseDefComponent` annotation so subclass overrides (e.g.
  // CSSField) aren't forced to structurally match this inline class shape.
  static markdown: BaseDefComponent = class Markdown extends Component<
    typeof this
  > {
    get escapedWithBreaks() {
      let escaped = markdownEscape(this.args.model);
      return escaped.replace(/\n/g, '  \n');
    }
    <template>{{this.escapedWithBreaks}}</template>
  };
}

// enumField has moved to packages/base/enum.gts

export class CSSField extends TextAreaField {
  static displayName = 'CSS Field';
  static embedded = class Embedded extends Component<typeof this> {
    <template>
      <div class='css-field-container'>
        {{#if @model.length}}
          <CopyButton class='css-field-copy-button' @textToCopy={{@model}} />
        {{/if}}
        <pre class='css-field' data-test-css-field>{{if
            @model
            @model
            '/* No CSS defined */'
          }}</pre>
      </div>
      <style scoped>
        .css-field-container {
          --field-bg: var(--card, var(--boxel-100));
          --field-fg: var(--card-foreground, var(--boxel-dark));
          --field-border: var(
            --border,
            color-mix(in oklab, var(--field-fg) 20%, var(--field-bg))
          );
          position: relative;
        }
        .css-field-copy-button {
          position: absolute;
          top: var(--boxel-sp-xs);
          right: var(--boxel-sp-xs);
        }
        .css-field {
          margin-block: 0;
          padding: var(--boxel-sp);
          background-color: var(--field-bg);
          border: 1px solid var(--field-border);
          border-radius: var(--radius, var(--boxel-border-radius));
          color: var(--field-fg);
          font-family: var(
            --font-mono,
            var(--boxel-monospace-font-family, monospace)
          );
          font-size: var(--boxel-font-size-xs);
          white-space: pre-wrap;
        }
        .css-field::placeholder {
          opacity: 0.5;
        }
      </style>
    </template>
  };
  // CS-10785: emit the CSS in a fenced code block with a `css` info string.
  // The fence is computed as the longest run of backticks in the content
  // plus one (minimum 3), so embedded triple-backtick sequences in CSS
  // content can't prematurely close the block. Content itself is not
  // escaped — inside a fenced block, CommonMark treats it as literal.
  static markdown = class Markdown extends Component<typeof this> {
    get fenced() {
      let value = this.args.model ?? '';
      let longestRun = 0;
      let match = value.match(/`+/g);
      if (match) {
        for (let run of match) {
          if (run.length > longestRun) longestRun = run.length;
        }
      }
      let fence = '`'.repeat(Math.max(3, longestRun + 1));
      return `${fence}css\n${value}\n${fence}`;
    }
    <template>{{this.fenced}}</template>
  };
}

export class MarkdownField extends StringField {
  static displayName = 'Markdown';
  static icon = MarkdownIcon;

  static embedded = class MarkdownViewTemplate extends Component<
    typeof MarkdownField
  > {
    <template><MarkdownTemplate @content={{@model}} /></template>
  };
  static atom = class MarkdownViewTemplate extends Component<
    typeof MarkdownField
  > {
    <template><MarkdownTemplate @content={{@model}} /></template>
  };

  static edit = class Edit extends Component<typeof this> {
    <template>
      <BoxelInput
        class='boxel-text-area'
        @type='textarea'
        @value={{@model}}
        @onInput={{@set}}
        @disabled={{not @canEdit}}
        @readonly={{not @canEdit}}
      />
    </template>
  };
  // CS-10785: raw markdown passthrough. Content is already authored as
  // markdown, so interpolating a value with `#`, `*`, etc. must NOT
  // double-escape. This overrides the StringField inherited `static
  // markdown` to suppress escaping.
  static markdown = class Markdown extends Component<typeof MarkdownField> {
    <template>{{@model}}</template>
  };
}

export function deserializeForUI(value: string | number | null): number | null {
  let validationError = NumberSerializer.validate(value);
  if (validationError) {
    return null;
  }

  return NumberSerializer.deserializeSync(value);
}

export function serializeForUI(val: number | null): string | undefined {
  let serialized = NumberSerializer.serialize(val);
  if (serialized != null) {
    return String(serialized);
  }
  return undefined;
}

export class NumberField extends FieldDef {
  static displayName = 'Number';
  static icon = HashIcon;
  static [primitive]: number;
  static [fieldSerializer] = 'number';
  static [useIndexBasedKey]: never;
  static embedded = class View extends Component<typeof this> {
    <template>{{@model}}</template>
  };
  static atom = this.embedded;

  static edit = class Edit extends Component<typeof this> {
    <template>
      <BoxelInput
        @value={{this.textInputValidator.asString}}
        @onInput={{this.textInputValidator.onInput}}
        @errorMessage={{this.textInputValidator.errorMessage}}
        @state={{if this.textInputValidator.isInvalid 'invalid' 'none'}}
        @disabled={{not @canEdit}}
      />
    </template>

    textInputValidator: TextInputValidator<number> = new TextInputValidator(
      () => this.args.model,
      (inputVal) => this.args.set(inputVal),
      deserializeForUI,
      serializeForUI,
      NumberSerializer.validate,
    );
  };
  // CS-10785: render the number as text. `markdownEscape` handles the null/
  // undefined case (empty string) and also protects against line-start
  // `1.`/`2.` etc. being interpreted as ordered list markers when this
  // value gets interpolated into a larger markdown document.
  static markdown = class Markdown extends Component<typeof this> {
    <template>{{markdownEscape @model}}</template>
  };
}

export interface SerializedFileDef {
  url?: string;
  sourceUrl: string;
  name?: string;
  contentHash?: string;
  contentSize?: number;
  contentType?: string;
  content?: string;
  error?: string;
}

// Throw this error from extractAttributes when the file content doesn't match this FileDef's
// expectations so the extractor can fall back to a superclass/base FileDef.
export class FileContentMismatchError extends Error {
  name = 'FileContentMismatchError';
}

export class FileDef extends BaseDef {
  static displayName = 'File';
  static isFileDef = true;
  static icon = FileIcon;
  [isSavedInstance] = true;

  get [realmURL](): URL | undefined {
    let realmURLString = getCardMeta(this, 'realmURL');
    return realmURLString ? new URL(realmURLString) : undefined;
  }

  static assignInitialFieldValue(
    instance: BaseDef,
    fieldName: string,
    value: any,
  ) {
    if (fieldName === 'id') {
      // Similar to CardDef, set 'id' directly in the deserialized cache
      // to avoid triggering recomputes during instantiation
      let deserialized = getDataBucket(instance);
      deserialized.set('id', value);
    } else {
      super.assignInitialFieldValue(instance, fieldName, value);
    }
  }

  @field id: RealmResourceIdentifier = contains(
    ReadOnlyField,
  ) as unknown as RealmResourceIdentifier;
  @field sourceUrl = contains(StringField);
  @field url = contains(StringField);
  @field name = contains(StringField);
  @field contentType = contains(StringField);
  @field contentHash = contains(StringField);
  @field contentSize = contains(NumberField);

  static embedded: BaseDefComponent = FileDefEmbeddedTemplate;
  static fitted: BaseDefComponent = FileDefFittedTemplate;
  static isolated: BaseDefComponent = FileDefIsolatedTemplate;
  static atom: BaseDefComponent = FileDefAtomTemplate;
  static edit: BaseDefComponent = FileDefEditTemplate;
  // Default `markdown` fallback (CS-10784): inherits from FieldDef but
  // restated explicitly so this class's own slot is set rather than relying on
  // prototype lookup — the format-resolution code reads slots via bracket
  // notation on the resolved class (`(cls as any)[format]`), which traverses
  // the prototype chain, but having an own property keeps subclass overrides
  // less surprising.
  static markdown: BaseDefComponent = DefaultMarkdownFallbackTemplate;

  static async extractAttributes(
    url: string,
    getStream: () => Promise<ByteStream>,
    options: { contentHash?: string; contentSize?: number } = {},
  ): Promise<SerializedFile> {
    let parsed = new URL(url);
    let name = decodeURIComponent(
      parsed.pathname.split('/').pop() ?? parsed.pathname,
    );
    let contentType = inferContentType(name);
    let contentHash: string | undefined = options.contentHash;
    let contentSize: number | undefined = options.contentSize;
    if (!contentHash || contentSize === undefined) {
      let bytes = await byteStreamToUint8Array(await getStream());
      if (!contentHash) {
        try {
          contentHash = md5(bytes);
        } catch {
          contentHash = md5(new TextDecoder().decode(bytes));
        }
      }
      if (contentSize === undefined) {
        contentSize = bytes.byteLength;
      }
    }

    return {
      sourceUrl: url,
      url,
      name,
      contentType,
      contentHash,
      contentSize,
    };
  }

  serialize() {
    return {
      sourceUrl: this.sourceUrl,
      url: this.url,
      name: this.name,
      contentType: this.contentType,
      contentHash: this.contentHash,
      contentSize: this.contentSize,
    };
  }

  [getMenuItems](params: GetMenuItemParams): MenuItemOptions[] {
    return getDefaultFileMenuItems(this, params);
  }
}

export function createFileDef({
  url,
  sourceUrl,
  name,
  contentType,
  contentHash,
  contentSize,
}: SerializedFileDef) {
  return new FileDef({
    url,
    sourceUrl,
    name,
    contentType,
    contentHash,
    contentSize,
  });
}

export { getDefaultFileMenuItems } from './file-menu-items';

export class ImageDef extends FileDef {
  static displayName = 'Image';
  static icon = ImageIcon;
  static acceptTypes = 'image/*';

  @field width = contains(NumberField);
  @field height = contains(NumberField);

  static isolated: BaseDefComponent = ImageDefIsolatedTemplate;
  static atom: BaseDefComponent = ImageDefAtomTemplate;
  static embedded: BaseDefComponent = ImageDefEmbeddedTemplate;
  static fitted: BaseDefComponent = ImageDefFittedTemplate;

  // CS-10787: emit a markdown image reference. If no URL is available we
  // fall back to a placeholder that names the image — useful to downstream
  // consumers (e.g. an LLM ingesting the markdown) without a broken link.
  static markdown: BaseDefComponent = class Markdown extends Component<
    typeof ImageDef
  > {
    get text() {
      let model = this.args.model;
      if (!model) {
        return '';
      }
      let url = model.url ?? model.sourceUrl ?? '';
      let name = model.name ?? '';
      if (!url && !name) {
        return '';
      }
      return markdownImage(name, url);
    }
    <template>{{this.text}}</template>
  };
}

export class CardInfoField extends FieldDef {
  static displayName = 'Card Info';
  @field name = contains(StringField);
  @field summary = contains(StringField);
  @field cardThumbnail = linksTo(() => ImageDef);
  @field cardThumbnailURL = contains(MaybeBase64Field);
  @field theme = linksTo(() => Theme);
  @field notes = contains(MarkdownField);
}

export class CardDef extends BaseDef {
  readonly [localId]: string = uuidv4();
  [isSavedInstance] = false;
  get [fieldsUntracked](): Record<string, typeof BaseDef> | undefined {
    let overrides = getFieldOverrides(this);
    return overrides ? Object.fromEntries(getFieldOverrides(this)) : undefined;
  }
  get [fields](): Record<string, typeof BaseDef> | undefined {
    entangleWithCardTracking(this);
    return this[fieldsUntracked];
  }
  set [fields](overrides: Record<string, typeof BaseDef>) {
    let existingOverrides = getFieldOverrides(this);
    for (let [fieldName, clazz] of Object.entries(overrides)) {
      existingOverrides.set(fieldName, clazz);
    }
    // notify glimmer to rerender this card
    notifyCardTracking(this);
  }
  @field id: RealmResourceIdentifier = contains(
    ReadOnlyField,
  ) as unknown as RealmResourceIdentifier;
  @field cardInfo = contains(CardInfoField);
  @field cardTitle = contains(StringField, {
    computeVia: function (this: CardDef) {
      return this.cardInfo.name?.trim()?.length
        ? this.cardInfo.name
        : `Untitled ${this.constructor.displayName}`;
    },
  });
  @field cardDescription = contains(StringField, {
    computeVia: function (this: CardDef) {
      return this.cardInfo.summary;
    },
  });
  @field cardTheme: InstanceType<typeof Theme> | null = linksTo(() => Theme, {
    computeVia: function (this: CardDef) {
      return this.cardInfo.theme;
    },
  });
  // TODO: this will probably be an image or image url field card when we have it
  // UPDATE: we now have a Base64ImageField card. we can probably refactor this
  // to use it directly now (or wait until a better image field comes along)
  @field cardThumbnailURL = contains(MaybeBase64Field, {
    computeVia: function (this: CardDef) {
      return this.cardInfo.cardThumbnailURL;
    },
  });
  static displayName = 'Card';
  static isCardDef = true;
  static icon = CaptionsIcon;

  static assignInitialFieldValue(
    instance: BaseDef,
    fieldName: string,
    value: any,
  ) {
    if (fieldName === 'id') {
      // TODO: can we eliminate this conditional branch?

      // we need to be careful that we don't trigger the ambient recompute() in our setters
      // when we are instantiating an instance that is placed in the cardStore that has
      // not had it's field values set yet, as computeds may assume dependent fields are
      // available when they are not (e.g. Spec.isPrimitive trying to access its 'ref' field).
      // In this scenario, only the 'id' field is available. The rest of the fields will be
      // filled in later, so just set the 'id' directly in the deserialized cache to avoid
      // triggering the recompute.
      let deserialized = getDataBucket(instance);
      deserialized.set('id', value);
    } else {
      super.assignInitialFieldValue(instance, fieldName, value);
    }
  }

  static embedded: BaseDefComponent = DefaultEmbeddedTemplate;
  static fitted: BaseDefComponent = DefaultFittedTemplate;
  static isolated: BaseDefComponent = DefaultCardDefTemplate;
  static edit: BaseDefComponent = DefaultCardDefTemplate;
  static atom: BaseDefComponent = DefaultAtomViewTemplate;
  static head: BaseDefComponent = DefaultHeadTemplate;
  // Default `markdown` fallback (CS-10784): renders the card's HTML isolated
  // template into a hidden source container, then converts it to markdown via
  // turndown (registered on `globalThis` by `packages/host`). Subclasses can
  // override `static markdown` to author bespoke markdown directly.
  static markdown: BaseDefComponent = DefaultMarkdownFallbackTemplate;

  static get hasCustomEditTemplate(): boolean {
    return this.edit !== CardDef.edit;
  }

  static get hasCustomIsolatedTemplate(): boolean {
    return this.isolated !== CardDef.isolated;
  }

  static prefersWideFormat = false; // whether the card is full-width in the stack
  static headerColor: string | null = null; // set string color value if the stack-item header has a background color

  constructor(
    data?: Record<string, any> & {
      [fields]?: Record<string, BaseDefConstructor>;
    },
  ) {
    super(data);
    if (data && localId in data && typeof data[localId] === 'string') {
      this[localId] = data[localId];
    }
    if (data && fields in data && data[fields]) {
      let overrides = getFieldOverrides(this);
      for (let [fieldName, clazz] of Object.entries(data[fields])) {
        overrides.set(fieldName, clazz);
      }
    }
  }

  get [realmInfo]() {
    return getCardMeta(this, 'realmInfo');
  }

  get [realmURL](): URL | undefined {
    let realmURLString: string | undefined = getCardMeta(this, 'realmURL');
    return realmURLString ? new URL(realmURLString) : undefined;
  }

  [getMenuItems](params: GetMenuItemParams): MenuItemOptions[] {
    return getDefaultCardMenuItems(this, params);
  }
}

export class CssImportField extends StringField {
  static displayName = 'CSS Import';
  static icon = ImportIcon;
}

export class Theme extends CardDef {
  static displayName = 'Theme';
  static icon = ThemeIcon;
  @field cssVariables = contains(CSSField, {
    description:
      'CSS variable definitions that build on shadcn variables (typically for :root and .dark selectors) injected into the CardContainer.',
  });
  @field cssImports = containsMany(CssImportField, {
    description:
      'CSS links (e.g. Google Fonts) imported via the CardContainer.',
  });

  [getMenuItems](params: GetMenuItemParams): MenuItemOptions[] {
    let menuItems = super[getMenuItems](params);
    if (params.menuContext === 'interact' && params.toolContext && this.id) {
      menuItems = [
        ...menuItems,
        {
          label: 'Copy and Edit',
          action: async () => {
            if (!params.toolContext || !this.id) {
              return;
            }
            let cmd = new CopyAndEditTool(params.toolContext);
            await cmd.execute({
              card: this,
            });
          },
          icon: FilePencilIcon,
          disabled: !this.id,
        },
        {
          label: 'Modify Theme via AI',
          action: async () => {
            let cmd = new PatchThemeTool(params.toolContext);
            await cmd.execute({
              cardId: this.id as unknown as string,
            });
          },
          icon: WandIcon,
          disabled: !this.id,
        },
      ];
    }
    return menuItems;
  }
}

export type BaseDefConstructor = typeof BaseDef;
export type CardDefConstructor = typeof CardDef;
export type FieldDefConstructor = typeof FieldDef;
export type FileDefConstructor = typeof FileDef;
export type LinkableDefConstructor = CardDefConstructor | FileDefConstructor;

export function subscribeToChanges(
  fieldOrCard: BaseDef | BaseDef[],
  subscriber: CardChangeSubscriber,
  enclosing?: { fieldOrCard: BaseDef; fieldName: string },
) {
  if (isArrayOfCardOrField(fieldOrCard)) {
    fieldOrCard.forEach((item, i) => {
      subscribeToChanges(
        item,
        subscriber,
        enclosing
          ? {
              fieldOrCard: enclosing.fieldOrCard,
              fieldName: `${enclosing.fieldName}.${i}`,
            }
          : undefined,
      );
    });
    return;
  }

  let changeSubscribers = subscribers.get(fieldOrCard);
  if (changeSubscribers && changeSubscribers.has(subscriber)) {
    return;
  }

  if (!changeSubscribers) {
    changeSubscribers = new Set();
    subscribers.set(fieldOrCard, changeSubscribers);
  }

  changeSubscribers.add(subscriber);
  if (enclosing) {
    subscriberConsumer.set(fieldOrCard, enclosing);
  }

  let fields = getFields(fieldOrCard, {
    usedLinksToFieldsOnly: true,
    includeComputeds: false,
  });
  Object.keys(fields).forEach((fieldName) => {
    let field = getField(fieldOrCard, fieldName) as Field<typeof BaseDef>;
    if (
      field &&
      (field.fieldType === 'contains' || field.fieldType === 'containsMany')
    ) {
      let value = peekAtField(fieldOrCard, fieldName);
      if (isCardOrField(value) || isArrayOfCardOrField(value)) {
        subscribeToChanges(value, subscriber, {
          fieldOrCard: enclosing?.fieldOrCard ?? fieldOrCard,
          fieldName: enclosing?.fieldName
            ? `${enclosing.fieldName}.${fieldName}`
            : fieldName,
        });
      }
    }
  });
}

export function unsubscribeFromChanges(
  fieldOrCard: BaseDef | BaseDef[],
  subscriber: CardChangeSubscriber,
  visited: Set<BaseDef> = new Set(),
) {
  if (isArrayOfCardOrField(fieldOrCard)) {
    fieldOrCard.forEach((item) => {
      unsubscribeFromChanges(item, subscriber);
    });
    return;
  }

  if (visited.has(fieldOrCard)) {
    return;
  }

  visited.add(fieldOrCard);
  let changeSubscribers = subscribers.get(fieldOrCard);
  if (!changeSubscribers) {
    return;
  }
  changeSubscribers.delete(subscriber);

  let fields = getFields(fieldOrCard, {
    usedLinksToFieldsOnly: true,
    includeComputeds: false,
  });
  Object.keys(fields).forEach((fieldName) => {
    let field = getField(fieldOrCard, fieldName) as Field<typeof BaseDef>;
    if (
      field &&
      (field.fieldType === 'contains' || field.fieldType === 'containsMany')
    ) {
      let value = peekAtField(fieldOrCard, fieldName);
      if (isCardOrField(value) || isArrayOfCardOrField(value)) {
        unsubscribeFromChanges(value, subscriber);
      }
    }
  });
}

function applySubscribersToInstanceValue(
  instance: BaseDef,
  field: Field<typeof BaseDef>,
  oldValue: BaseDef | BaseDef[],
  newValue: BaseDef | BaseDef[],
) {
  let changeSubscribers: Set<CardChangeSubscriber> | undefined = undefined;
  if (field.fieldType === 'contains' || field.fieldType === 'containsMany') {
    changeSubscribers = subscribers.get(instance);
  } else if (
    isArrayOfCardOrField(oldValue) &&
    oldValue[0] &&
    subscribers.has(oldValue[0])
  ) {
    changeSubscribers = subscribers.get(oldValue[0]);
  } else if (isCardOrField(oldValue)) {
    changeSubscribers = subscribers.get(oldValue);
  }

  if (!changeSubscribers) {
    return;
  }

  let toArray = function (item: BaseDef | BaseDef[]) {
    if (isCardOrField(item)) {
      return [item];
    } else if (isArrayOfCardOrField(item)) {
      return [...item];
    } else {
      return [];
    }
  };

  let oldItems = toArray(oldValue);
  let newItems = toArray(newValue);

  let addedItems = newItems.filter((item) => !oldItems.includes(item));
  let removedItems = oldItems.filter((item) => !newItems.includes(item));

  addedItems.forEach((item, i) =>
    changeSubscribers!.forEach((subscriber) =>
      subscribeToChanges(item, subscriber, {
        fieldOrCard: instance,
        fieldName: `${field.name}.${i}`,
      }),
    ),
  );

  removedItems.forEach((item) =>
    changeSubscribers!.forEach((subscriber) =>
      unsubscribeFromChanges(item, subscriber),
    ),
  );
}

function lazilyLoadLink(
  instance: CardDef,
  field: Field,
  link: string,
  pluralArgs?: { value: any[] },
) {
  let inflightLoads = inflightLinkLoads.get(instance);
  if (!inflightLoads) {
    inflightLoads = new Map();
    inflightLinkLoads.set(instance, inflightLoads);
  }
  let store = getStore(instance);
  let reference = resolveRef(link, instance.id ?? instance[relativeTo]);
  let key = `${field.name}/${reference}`;
  let promise = inflightLoads.get(key);
  if (promise) {
    store.trackLoad(promise);
    return;
  }
  let deferred = new Deferred<void>();
  inflightLoads.set(key, deferred.promise);
  // Surface the in-flight state to `getRelationshipMembershipState(...).isLoading` observers.
  bumpFieldLoadingSignal(instance, field.name);
  store.trackLoad(
    // we wrap the promise with a catch that will prevent the rejections from bubbling up but
    // not interfere with the original deferred. this prevents QUnit from being really noisy
    // and reporting a "global error" even though that is a normal operating circumstance for
    // the rendering when it encounters an error. the original deferred.promise still
    // rejects as expected for anyone awaiting it, but it won't cause unnecessary noise in QUnit.
    deferred.promise.then(
      () => {},
      () => {},
    ),
  );
  let dependencyTrackingContext = runtimeNonQueryDependencyContext({
    source: 'card-api:lazilyLoadLink',
    consumer: instance.id,
  });
  void (async () => {
    let isFileLink = isFileDef(field.card);
    try {
      let fieldValue: CardDef | FileDef;
      // Inside an indexing render the store is job-scoped: the prerender tab is
      // reset (`render` route `clearCache` -> `store.resetCache()`) on the first
      // render of each indexing job, so every instance in it was deserialized
      // during THIS job, from a realm source that is immutable for the job's
      // life. So an instance already in the store is current — reuse it directly
      // instead of re-fetching its card+source and re-running the full field
      // deserialization on every link edge that points at it. That per-edge
      // redundancy is what makes a densely cross-linked render quadratic (the
      // same target reached through many parents is rebuilt once per parent).
      // The per-consumer dependency is still recorded so invalidation tracks
      // this edge. Gated on BOTH the render flag AND `__boxelJobId`: outside a
      // render (the live app) a link may be stale after invalidation and must
      // reload, and a render with no job id has no job-scoped-store guarantee.
      let inIndexingRender =
        typeof globalThis !== 'undefined' &&
        Boolean((globalThis as any).__boxelRenderContext) &&
        Boolean((globalThis as any).__boxelJobId);
      let reusable = inIndexingRender
        ? isFileLink
          ? store.getFileMeta(reference)
          : store.getCard(reference)
        : undefined;
      // Only reuse an instance that finished deserializing. The job-scoped
      // store also holds partially-built, non-tracked instances: a failed
      // `_updateFromSerialized` leaves its half-built instance behind (the
      // store keeps it so cyclic deserialization can resolve), with
      // `isSavedInstance` still false — it flips true only at the end of a
      // successful deserialize. Reusing such a partial would skip the
      // load/error path that plants the broken-link sentinel and index an
      // incomplete target; falling through re-attempts the load and re-plants
      // the sentinel.
      if (
        reusable &&
        reusable[isSavedInstance] === true &&
        instanceOf(reusable, field.card)
      ) {
        if (isFileLink) {
          trackRuntimeFileDependency(reference, dependencyTrackingContext);
        } else {
          trackRuntimeInstanceDependency(reference, dependencyTrackingContext);
        }
        fieldValue = reusable;
      } else if (isFileLink) {
        let fileMetaDoc = await store.loadFileMetaDocument(reference, {
          dependencyTrackingContext,
        });
        if (isCardError(fileMetaDoc)) {
          let cardError = fileMetaDoc;
          let referenceForDeps = reference;
          cardError.deps = [referenceForDeps];
          throw cardError;
        }
        fieldValue = (await createFromSerialized(
          fileMetaDoc.data,
          fileMetaDoc,
          fileMetaDoc.data.id!,
          { store, dependencyTrackingContext },
        )) as FileDef;
      } else {
        let cardDoc = await store.loadCardDocument(reference, {
          dependencyTrackingContext,
        });
        if (isCardError(cardDoc)) {
          let cardError = cardDoc;
          let referenceForDeps = reference;
          cardError.deps = [referenceForDeps];
          throw cardError;
        }
        fieldValue = (await createFromSerialized(
          cardDoc.data,
          cardDoc,
          cardDoc.data.id!,
          { store, dependencyTrackingContext },
        )) as CardDef;
      }
      if (pluralArgs) {
        let { value } = pluralArgs;
        // Match against the raw backing array (the proxy hides not-loaded
        // sentinels from index access); swap through the proxy so the in-place
        // mutation notifies subscribers and Glimmer re-renders.
        let indices: number[] = [];
        for (let [index, item] of rawArrayValues(value).entries()) {
          if (!isNotLoadedValue(item)) {
            continue;
          }
          let notLoadedRef = resolveRef(
            item.reference,
            instance.id ?? instance[relativeTo],
          );
          if (reference === notLoadedRef) {
            indices.push(index);
          }
        }
        for (let index of indices) {
          value[index] = fieldValue;
        }
      } else {
        (instance as any)[field.name] = fieldValue;
      }
    } catch (e) {
      let error = e as Error;
      let isMissingFile =
        (isCardError(error) && error.status === 404) ||
        (typeof error?.message === 'string' &&
          /not found/i.test(error.message));
      let referenceForMissingFile =
        isFileLink || reference.endsWith('.json')
          ? reference
          : `${reference}.json`;
      let payloadError: Pick<SerializedError, 'status' | 'message'> &
        Partial<Pick<SerializedError, 'title' | 'stack' | 'deps'>> & {
          additionalErrors?: Array<
            Partial<
              Pick<SerializedError, 'title' | 'status' | 'message' | 'stack'>
            >
          >;
        } = {
        title: isMissingFile
          ? 'Link Not Found'
          : (error?.message ?? 'Card Error'),
        status: isMissingFile ? 404 : ((error as any)?.status ?? 500),
        message: isMissingFile
          ? `missing file ${referenceForMissingFile}`
          : (error?.message ?? String(e)),
        stack: error?.stack,
      };
      let deps = new Set<string>([referenceForMissingFile]);
      if (isCardError(error)) {
        for (let dep of error.deps ?? []) {
          deps.add(dep);
        }
        if (error.additionalErrors?.length) {
          payloadError.additionalErrors = error.additionalErrors.map(
            (additionalError) => {
              let normalized = additionalError as Partial<SerializedError>;
              return {
                title: normalized.title,
                status: normalized.status,
                message: normalized.message,
                stack: normalized.stack,
              };
            },
          );
        }
      }
      payloadError.deps = [...deps];

      // Plant a typed sentinel into the data bucket (singular) or the failed
      // array slot(s) (plural), replacing the legacy `field = null` write. The
      // field getter surfaces these as `undefined` to userland — the same
      // surface a not-loaded link produces — and never retriggers the loader
      // for them; `getRelationshipMembershipState` is the only way to read the structured
      // failure from outside this module. HTTP 404 → `link-not-found`, every
      // other failure → `link-error`.
      let errorDoc: SerializedError = {
        ...payloadError,
        additionalErrors: payloadError.additionalErrors ?? null,
      };
      let sentinel: LinkErrorValue | LinkNotFoundValue = isMissingFile
        ? { type: 'link-not-found', reference, errorDoc }
        : { type: 'link-error', reference, errorDoc };
      if (pluralArgs) {
        // Swap the sentinel into the slot(s) whose reference just failed,
        // leaving the WatchedArray identity intact so Glimmer re-renders. We
        // match the same not-loaded entries the success path would have
        // replaced with the loaded card. Match against the raw backing array
        // (the proxy hides sentinels) but write through the proxy to notify.
        let { value } = pluralArgs;
        for (let [index, item] of rawArrayValues(value).entries()) {
          if (!isNotLoadedValue(item)) {
            continue;
          }
          let notLoadedRef = resolveRef(
            item.reference,
            instance.id ?? instance[relativeTo],
          );
          if (reference === notLoadedRef) {
            value[index] = sentinel;
          }
        }
      } else {
        // Mirror `setField`'s notification (minus validate, which rejects a
        // non-card value): write the bucket, notify change subscribers, then
        // card tracking. Without the `notifySubscribers` call, `subscribeToChanges`
        // listeners would observe a successful lazy load but not a failed one.
        getDataBucket(instance).set(field.name, sentinel);
        notifySubscribers(instance, field.name, sentinel);
        notifyCardTracking(instance);
      }
    } finally {
      deferred.fulfill();
      inflightLoads.delete(key);
      if (inflightLoads.size === 0) {
        inflightLinkLoads.delete(instance);
      }
      // The load settled — re-evaluate `getRelationshipMembershipState(...).isLoading`.
      bumpFieldLoadingSignal(instance, field.name);
    }
  })();
}

// Whether a declared `linksTo` / `linksToMany` field has a lazy load in flight
// right now. Pure read of the in-flight load registry — the observe-only signal
// behind `getRelationshipMembershipState(...).isLoading` for declared links. A `not-loaded`
// slot that nothing is fetching is NOT loading.
function hasInflightLoadForField(
  instance: CardDef,
  fieldName: string,
): boolean {
  let loads = inflightLinkLoads.get(instance);
  if (!loads) {
    return false;
  }
  let prefix = `${fieldName}/`;
  for (let key of loads.keys()) {
    if (key.startsWith(prefix)) {
      return true;
    }
  }
  return false;
}

// Supply `getRelationshipMembershipState` with the loading status and query-field membership
// that live above field-support: in-flight link loads (here) and per-field
// search resources (in query-field-support). Observe-only — this never starts a
// load or a search; the template's field getter does that.
registerRelationshipProbe((instance, field) => {
  // Entangle the reading render with the field's loading signal so a deferred
  // bump (load start / settle, or query resource creation) re-evaluates this.
  readFieldLoadingSignal(instance, field.name);
  if (field.queryDefinition) {
    let resource = peekQueryFieldSearchResource(instance, field.name);
    let isLoading = resource?.isLoading ?? false;
    let bucketEntry = getDataBucket(instance).get(field.name);
    let queryMembership: RelationshipState[] | undefined;
    if (isLinkError(bucketEntry) || isLinkNotFound(bucketEntry)) {
      // A search that failed as a unit surfaces one whole-field sentinel —
      // independent of whether a live resource exists (it may have been planted
      // directly), so this takes precedence.
      queryMembership = [relationshipStateForEntry(bucketEntry)];
    } else if (!isLoading && resource) {
      queryMembership = (resource.instances ?? []).map((card) =>
        relationshipStateForEntry(card),
      );
    }
    // Otherwise membership stays undefined: in flight, or never queried.
    return { isLoading, isQueryField: true, queryMembership };
  }
  return {
    isLoading: hasInflightLoadForField(instance, field.name),
    isQueryField: false,
  };
});

// Replace any linksTo / linksToMany bucket entry on `consumer` that points
// to `deletedRef` with a `link-not-found` sentinel, and notify subscribers
// so the placeholder render takes over the slot. Returns true when at
// least one slot was rewritten. The host's store calls this from its
// realm-event handler when an instance is removed: the deleted target's
// loaded card is still hard-referenced by every consumer that has it in
// memory, and without this rewrite the consumer's render stays stale
// until something else forces a re-render. Mirrors the sentinel shape
// `lazilyLoadLink` plants for a 404 — same `link-not-found` discriminator,
// same `errorDoc.status: 404`, same `deps` (both id and `.json` forms) so
// downstream invalidation behaves identically to a real fetch failure.
export function notifyLinksToTargetDeleted(
  consumer: CardDef,
  deletedRef: string,
): boolean {
  let bucket = getDataBucket(consumer);
  let fields = getFields(consumer, { includeComputeds: false });
  let referenceWithJson = deletedRef.endsWith('.json')
    ? deletedRef
    : `${deletedRef}.json`;
  let referenceWithoutJson = deletedRef.replace(/\.json$/, '');
  let buildSentinel = (): LinkNotFoundValue => ({
    type: 'link-not-found',
    reference: referenceWithoutJson,
    errorDoc: {
      title: 'Link Not Found',
      status: 404,
      message: `missing file ${referenceWithJson}`,
      deps: [referenceWithoutJson, referenceWithJson],
      additionalErrors: null,
    } as SerializedError,
  });
  let changed = false;
  for (let [fieldName, field] of Object.entries(fields)) {
    if (!field) {
      continue;
    }
    if (field.fieldType === 'linksTo') {
      let current = bucket.get(fieldName);
      if (
        current &&
        typeof current === 'object' &&
        'id' in current &&
        (current as { id?: unknown }).id === referenceWithoutJson
      ) {
        let sentinel = buildSentinel();
        bucket.set(fieldName, sentinel);
        notifySubscribers(consumer, fieldName, sentinel);
        notifyCardTracking(consumer);
        changed = true;
      }
    } else if (field.fieldType === 'linksToMany') {
      let arr = bucket.get(fieldName);
      if (Array.isArray(arr)) {
        let arrChanged = false;
        for (let [index, item] of arr.entries()) {
          if (
            item &&
            typeof item === 'object' &&
            'id' in item &&
            (item as { id?: unknown }).id === referenceWithoutJson
          ) {
            arr[index] = buildSentinel();
            arrChanged = true;
          }
        }
        if (arrChanged) {
          notifySubscribers(consumer, fieldName, arr);
          notifyCardTracking(consumer);
          changed = true;
        }
      }
    }
  }
  return changed;
}

function trackRuntimeRelationshipDependency(
  value: unknown,
  declaredCard: LinkableDefConstructor,
  dependencyTrackingContext?: RuntimeDependencyTrackingContext,
): void {
  if (!value || isNonPresentLink(value)) {
    return;
  }
  let id = (value as { id?: unknown }).id;
  if (typeof id !== 'string') {
    return;
  }
  if (!shouldTrackRuntimeRelationship(id, dependencyTrackingContext)) {
    // Already tracked this relationship target this session. A linksTo /
    // linksToMany getter runs this on every read, and a dense graph re-reads
    // the same targets combinatorially; a repeat would re-derive the identical
    // instance/file + module-graph node set, so skipping it — and the
    // prototype/identity lookups below — is a pure no-op.
    return;
  }
  if (isFileDef(declaredCard)) {
    trackRuntimeFileDependency(id, dependencyTrackingContext);
    trackRuntimeRelationshipModuleDependencies(
      value,
      dependencyTrackingContext,
    );
    return;
  }
  trackRuntimeInstanceDependency(id, dependencyTrackingContext);
  trackRuntimeRelationshipModuleDependencies(value, dependencyTrackingContext);
}

function trackRuntimeRelationshipDependencies(
  values: unknown[],
  declaredCard: LinkableDefConstructor,
  dependencyTrackingContext?: RuntimeDependencyTrackingContext,
): void {
  for (let value of values) {
    trackRuntimeRelationshipDependency(
      value,
      declaredCard,
      dependencyTrackingContext,
    );
  }
}

function trackRuntimeRelationshipModuleDependencies(
  value: unknown,
  dependencyTrackingContext?: RuntimeDependencyTrackingContext,
): void {
  if (!value || typeof value !== 'object') {
    return;
  }

  let ctor = Reflect.getPrototypeOf(value)?.constructor;
  if (typeof ctor !== 'function') {
    return;
  }

  let identity = Loader.identify(ctor);
  if (!identity) {
    return;
  }

  // This walk repeats once per element of a linksToMany (and again on every
  // getter re-read), but records the identical node set every time, so it only
  // needs to run once per (context, type module) per tracking session. The
  // probe collapses each repeat to a single Set lookup — without it, a
  // linksToMany of N same-typed cards re-tracks the type's entire module graph
  // N times per read, and that per-call tracking overhead dominates aggregate
  // renders.
  if (
    !shouldTrackRuntimeModuleGraph(
      'relationship',
      identity.module,
      dependencyTrackingContext,
    )
  ) {
    return;
  }

  // Loader identities and dependency lists are in canonical RRI form, while
  // the dependency tracker keys module nodes by http(s) URL and drops
  // anything else — so convert at this boundary via the loader's
  // tracking-key form.
  let loader = Loader.getLoaderFor(ctor);
  trackRuntimeModuleDependency(
    loader ? loader.dependencyTrackingKey(identity.module) : identity.module,
    dependencyTrackingContext,
  );
  if (!loader) {
    return;
  }

  for (let dep of loader.getKnownConsumedModules(identity.module)) {
    trackRuntimeModuleDependency(
      loader.dependencyTrackingKey(dep),
      dependencyTrackingContext,
    );
  }
}

export function setId(instance: CardDef, id: RealmResourceIdentifier) {
  let field = getField(instance, 'id');
  if (field) {
    setField(instance, field, id);
  }
}

export function isSaved(instance: CardDef): boolean {
  return instance[isSavedInstance] === true;
}

export function getQueryableValue(
  field: Field<typeof BaseDef>,
  value: any,
  stack?: BaseDef[],
): any;
export function getQueryableValue(
  fieldCard: typeof BaseDef,
  value: any,
  stack?: BaseDef[],
): any;
export function getQueryableValue(
  fieldOrCard: Field<typeof BaseDef> | typeof BaseDef,
  value: any,
  stack: BaseDef[] = [],
): any {
  if ('baseDef' in fieldOrCard) {
    let result = fieldOrCard[queryableValue](value, stack);
    if (primitive in fieldOrCard) {
      assertScalar(result, fieldOrCard);
    }
    return result;
  }
  return fieldOrCard.queryableValue(value, stack);
}

export function formatQueryValue(
  field: Field<typeof BaseDef>,
  queryValue: any,
): any {
  let serializer: ReturnType<typeof getSerializer> | undefined;
  if (primitive in field.card && fieldSerializer in field.card) {
    assertIsSerializerName(field.card[fieldSerializer]);
    serializer = getSerializer(field.card[fieldSerializer]);
  }
  return (
    serializer?.formatQuery?.(queryValue) ?? field.card[formatQuery](queryValue)
  );
}

async function getDeserializedValue<CardT extends BaseDefConstructor>({
  card,
  loadedValue,
  fieldName,
  value,
  resource,
  modelPromise,
  doc,
  store,
  relativeTo,
  opts,
}: {
  card: CardT;
  loadedValue: any;
  fieldName: string;
  value: any;
  resource: LooseCardResource;
  modelPromise: Promise<BaseDef>;
  doc: LooseSingleCardDocument | CardDocument;
  store: CardStore;
  relativeTo: RealmResourceIdentifier | URL | undefined;
  opts?: DeserializeOpts;
}): Promise<any> {
  let field = getField(isCardInstance(value) ? value : card, fieldName);
  if (!field) {
    throw new Error(`could not find field ${fieldName} in card ${card.name}`);
  }
  let result = await field.deserialize(
    value,
    doc,
    resource.relationships,
    resource.meta.fields?.[fieldName],
    store,
    modelPromise,
    loadedValue,
    relativeTo,
    opts,
  );
  return result;
}

// TODO Currently our deserialization process performs 2 tasks that probably
// need to be disentangled:
// 1. convert the data from a wire format to the native format
// 2. absorb async to load computeds
//
// Consider the scenario where the server is providing the client the card JSON,
// in this case the server has already processed the computed, and all we really
// need to do is purely the conversion of the data from the wire format to the
// native format which should be async. Instead our client is re-doing the work
// to calculate the computeds that the server has already done.

// use an interface loader and not the class Loader
export async function createFromSerialized<T extends BaseDefConstructor>(
  resource:
    | LooseLinkableResource<CardResource>
    | LooseLinkableResource<FileMetaResource>,
  doc:
    | LooseSingleResourceDocument<CardResource | FileMetaResource>
    | LinkableDocument,
  relativeTo: RealmResourceIdentifier | URL | undefined,
  opts?: DeserializeOpts & {
    store?: CardStore;
    dependencyTrackingContext?: RuntimeDependencyTrackingContext;
  },
): Promise<BaseInstanceType<T>> {
  let store = opts?.store ?? new FallbackCardStore();
  let localIdValue =
    'lid' in resource && typeof resource.lid === 'string'
      ? resource.lid
      : undefined;
  let defaultContext = runtimeNonQueryDependencyContext({
    source: 'card-api:createFromSerialized',
    consumer: resource.id ?? localIdValue,
    consumerKind: isFileMetaResource(resource) ? 'file' : 'instance',
  });
  let context = opts?.dependencyTrackingContext ?? defaultContext;
  let {
    meta: { adoptsFrom },
  } = resource;
  let card: typeof BaseDef | undefined = await loadCardDef(adoptsFrom, {
    loader: myLoader(),
    relativeTo,
    dependencyTrackingContext: context,
  });
  if (!card) {
    throw new Error(`could not find card: '${humanReadable(adoptsFrom)}'`);
  }

  return card[deserialize](
    resource,
    relativeTo,
    doc as CardDocument,
    store,
    opts,
  ) as BaseInstanceType<T>;
}

export async function updateFromSerialized<T extends BaseDefConstructor>(
  instance: BaseInstanceType<T>,
  doc: LooseSingleCardDocument,
  store = getStore(instance),
  opts?: DeserializeOpts,
): Promise<BaseInstanceType<T>> {
  stores.set(instance, store);
  if (!instance[relativeTo] && doc.data.id) {
    instance[relativeTo] = rri(doc.data.id);
  }

  if (isCardInstance(instance)) {
    if (!instance[meta] && doc.data.meta) {
      instance[meta] = doc.data.meta;
    }
  }
  return await _updateFromSerialized({
    instance,
    resource: doc.data,
    doc,
    store,
    opts,
  });
}

// The typescript `is` type here refuses to work unless it's in this file.
function isCardInstance(instance: any): instance is CardDef {
  return _isCardInstance(instance);
}

async function _createFromSerialized<T extends BaseDefConstructor>(
  card: T,
  data: T extends { [primitive]: infer P } ? P : LooseCardResource,
  doc: LooseSingleCardDocument | CardDocument | undefined,
  _relativeTo: RealmResourceIdentifier | URL | undefined,
  store: CardStore = new FallbackCardStore(),
  opts?: DeserializeOpts,
): Promise<BaseInstanceType<T>> {
  let resource: LooseCardResource | undefined;
  if (isCardResource(data) || isFileMetaResource(data)) {
    resource = data as LooseCardResource;
  }
  if (!resource) {
    let adoptsFrom = identifyCard(card);
    if (!adoptsFrom) {
      throw new Error(
        `bug: could not determine identity for card '${card.name}'`,
      );
    }
    // in this case we are dealing with an empty instance
    resource = { meta: { adoptsFrom } };
  }
  if (!doc) {
    doc = { data: resource };
  }
  let instance: BaseInstanceType<T> | undefined;
  if (resource.id != null || resource.lid != null) {
    let resourceId = (resource.id ?? resource.lid)!;
    let cachedInstance =
      isFileMetaResource(resource) || isFileDef(card)
        ? store.getFileMeta(resourceId)
        : store.getCard(resourceId);
    if (cachedInstance && instanceOf(cachedInstance, card as any)) {
      instance = cachedInstance as BaseInstanceType<T>;
    }
  }
  if (!instance) {
    instance = new card({
      id: resource.id,
      [localId]: resource.lid,
    }) as BaseInstanceType<T>;
    instance[relativeTo] = _relativeTo;
  }
  stores.set(instance, store);
  return await _updateFromSerialized({
    instance,
    resource,
    doc,
    store,
    opts,
  });
}

async function _updateFromSerialized<T extends BaseDefConstructor>({
  instance,
  resource,
  doc,
  store,
  opts,
}: {
  instance: BaseInstanceType<T>;
  resource: LooseCardResource;
  doc: LooseSingleCardDocument | CardDocument;
  store: CardStore;
  opts?: DeserializeOpts;
}): Promise<BaseInstanceType<T>> {
  // because our store uses a tracked map for its identity map all the assembly
  // work that we are doing to deserialize the instance below is "live". so we
  // add the actual instance silently in a non-tracked way and only track it at
  // the very end.
  let card = Reflect.getPrototypeOf(instance)!.constructor as T;
  if (resource.id != null) {
    if (isFileMetaResource(resource) || isFileDef(card)) {
      store.setFileMetaNonTracked(resource.id, instance as FileDef);
    } else {
      store.setCardNonTracked(resource.id, instance as CardDef);
    }
  }
  let deferred = new Deferred<BaseDef>();
  let nonNestedRelationships = Object.fromEntries(
    Object.entries(resource.relationships ?? {}).filter(
      ([fieldName]) => !fieldName.includes('.'),
    ),
  );
  let linksToManyRelationships: Record<string, Relationship[]> = Object.entries(
    resource.relationships ?? {},
  )
    .filter(
      ([fieldName]) =>
        fieldName.split('.').length === 2 &&
        fieldName.split('.')[1].match(/^\d+$/),
    )
    .reduce((result, [fieldName, value]) => {
      let name = fieldName.split('.')[0];
      result[name] = result[name] || [];
      result[name].push(value);
      return result;
    }, Object.create(null));

  let existingOverrides = getFieldOverrides(instance);
  let loadedValues = getDataBucket(instance);
  let instanceRelativeTo: RealmResourceIdentifier | URL | undefined =
    instance[relativeTo] ??
    ('id' in instance && typeof instance.id === 'string'
      ? (instance.id as RealmResourceIdentifier)
      : undefined);

  function getFieldMeta(
    fieldsMeta: CardFields | undefined,
    key: string,
  ): Partial<Meta> | undefined {
    let entry = fieldsMeta?.[key];
    return Array.isArray(entry) ? undefined : entry;
  }

  function getFieldMetaArray(
    fieldsMeta: CardFields | undefined,
    key: string,
  ): Partial<Meta>[] | undefined {
    let entry = fieldsMeta?.[key];
    return Array.isArray(entry) ? entry : undefined;
  }
  function clearIndexedFieldOverrides(fieldName: string): void {
    for (let key of existingOverrides.keys()) {
      if (isDirectIndexedFieldKey(key, fieldName)) {
        existingOverrides.delete(key);
      }
    }
  }
  function isAssignableToField(
    overrideCard: typeof BaseDef,
    fieldCard: typeof BaseDef,
  ): boolean {
    let current: typeof BaseDef | undefined = overrideCard;
    while (current) {
      if (current === fieldCard) {
        return true;
      }
      current = getAncestor(current) ?? undefined;
    }
    return false;
  }

  function applyFieldOverride(
    fieldName: string,
    overrideCard?: typeof BaseDef,
    field?: Field<typeof BaseDef, any>,
  ): boolean {
    if (!overrideCard) {
      return false;
    }
    if (
      field &&
      !isAssignableToField(overrideCard, field.card as typeof BaseDef)
    ) {
      return false;
    }
    if (existingOverrides.get(fieldName) === overrideCard) {
      return false;
    }
    existingOverrides.set(fieldName, overrideCard);
    return true;
  }
  async function setDeserializedFieldOverride(
    fieldName: string,
    resource: LooseCardResource,
    field: Field<typeof BaseDef, any>,
    serializedFieldOverride?: Partial<Meta>,
  ): Promise<boolean> {
    let overrideMeta = serializedFieldOverride;
    if (!overrideMeta) {
      overrideMeta = getFieldMeta(resource.meta?.fields, fieldName);
    }
    if (!overrideMeta || !overrideMeta.adoptsFrom) {
      return false;
    }
    let override = await loadCardDef(overrideMeta.adoptsFrom, {
      loader: myLoader(),
      // Prefer the deserialization context (instanceRelativeTo) so overrides resolve
      // relative to the document we fetched (e.g. catalog/index), then fall back to the resource id.
      relativeTo:
        instanceRelativeTo ?? (resource.id ? rri(resource.id) : undefined),
      dependencyTrackingContext: opts?.dependencyTrackingContext,
    });
    if (!override) {
      return false;
    }
    return applyFieldOverride(fieldName, override, field);
  }

  function applyLinkOverrideFromValue(
    fieldName: string,
    field: Field<typeof BaseDef, any>,
    value: any,
  ): Field<typeof BaseDef, any> {
    let changed = false;
    if (field.fieldType === 'linksTo') {
      if (isCardInstance(value)) {
        changed = applyFieldOverride(
          fieldName,
          value.constructor as typeof BaseDef,
          field,
        );
      }
    } else if (field.fieldType === 'linksToMany') {
      if (Array.isArray(value)) {
        let linked = value.find((entry) => isCardInstance(entry));
        if (linked) {
          changed = applyFieldOverride(
            fieldName,
            linked.constructor as typeof BaseDef,
            field,
          );
        }
      }
    }
    if (changed) {
      return (getField(instance, fieldName) ?? field) as Field<T>;
    }
    return field;
  }

  let values = (await Promise.all(
    Object.entries({
      ...resource.attributes,
      ...nonNestedRelationships,
      ...linksToManyRelationships,
      ...(resource.id !== undefined ? { id: resource.id } : {}),
    }).map(async ([fieldName, value]) => {
      let field = getField(instance, fieldName);
      if (!field) {
        // This happens when the instance has a field that is not in the definition. It can happen when
        // instance or definition is updated and the other is not. In this case we will just ignore the
        // mismatch and try to serialize it anyway so that the client can see still see the instance data
        // and have a chance to fix it so that it adheres to the definition
        return [];
      }
      let resourceMetaFields = resource.meta?.fields;
      let overrideApplied = false;
      if (field.fieldType === 'containsMany') {
        clearIndexedFieldOverrides(fieldName);
        if (primitive in field.card) {
          if (Array.isArray(value)) {
            for (let [index] of value.entries()) {
              let key = `${fieldName}.${index}`;
              overrideApplied =
                (await setDeserializedFieldOverride(
                  key,
                  resource,
                  field,
                  getFieldMeta(resourceMetaFields, key),
                )) || overrideApplied;
            }
          } else {
            overrideApplied =
              (await setDeserializedFieldOverride(
                fieldName,
                resource,
                field,
                getFieldMeta(resourceMetaFields, fieldName),
              )) || overrideApplied;
          }
        } else {
          let metas = getFieldMetaArray(resourceMetaFields, fieldName);
          if (metas) {
            for (let [index, meta] of metas.entries()) {
              overrideApplied =
                (await setDeserializedFieldOverride(
                  `${fieldName}.${index}`,
                  resource,
                  field,
                  meta,
                )) || overrideApplied;
            }
          }
        }
      } else if (field.fieldType === 'contains') {
        overrideApplied =
          (await setDeserializedFieldOverride(
            fieldName,
            resource,
            field,
            getFieldMeta(resourceMetaFields, fieldName),
          )) || overrideApplied;
      }
      if (overrideApplied) {
        field = (getField(instance, fieldName) ?? field) as Field<T>;
      }
      // Prefer the deserialization context ([relativeTo]) when available; fall back to the instance id
      let relativeToVal: RealmResourceIdentifier | URL | undefined =
        instance[relativeTo] ??
        ('id' in instance && typeof instance.id === 'string'
          ? (instance.id as RealmResourceIdentifier)
          : undefined);
      let deserializedValue = await getDeserializedValue({
        card,
        loadedValue: loadedValues.get(fieldName),
        fieldName,
        value,
        resource,
        modelPromise: deferred.promise,
        doc,
        store,
        relativeTo: relativeToVal,
        opts,
      });

      field = applyLinkOverrideFromValue(
        fieldName,
        field,
        deserializedValue,
      ) as Field<T>;
      return [field, deserializedValue];
    }),
  )) as [Field<T>, any][];

  let realmURLString =
    getCardMeta(instance as CardDef, 'realmURL') ?? resource.meta?.realmURL;

  // this block needs to be synchronous
  {
    let wasSaved = false;
    let originalId: string | undefined;
    if (isCardInstance(instance)) {
      wasSaved = instance[isSavedInstance];
      originalId = (instance as CardDef).id; // the instance is a composite card
      instance[isSavedInstance] = false;
    }
    let deserialized = getDataBucket(instance);

    for (let [field, value] of values) {
      if (!field) {
        continue;
      }
      if (field.name === 'id' && wasSaved && originalId !== value) {
        throw new Error(
          `cannot change the id for saved instance ${originalId}`,
        );
      }
      propagateRealmContext(value, realmURLString);
      field.validate(instance, value);

      // Before updating field's value, we also have to make sure
      // the subscribers also subscribes to a new value.
      let existingValue = deserialized.get(field.name as string);
      if (
        isCardOrField(existingValue) ||
        isArrayOfCardOrField(existingValue) ||
        isCardOrField(value) ||
        isArrayOfCardOrField(value)
      ) {
        applySubscribersToInstanceValue(instance, field, existingValue, value);
      }
      deserialized.set(field.name as string, value);
      field.captureQueryFieldSeedData?.(instance, value, resource);
    }

    // assign the realm meta before we compute as computeds may be relying on this
    if (!isFieldInstance(instance) && resource.id != null) {
      (instance as any)[meta] = resource.meta;
    }
    if (realmURLString && isFieldInstance(instance)) {
      setRealmContextOnField(instance, realmURLString);
    }
    notifyCardTracking(instance);
    if (isCardInstance(instance) && resource.id != null) {
      // importantly, we place this synchronously after the assignment of the model's
      // fields, such that subsequent assignment of the id field when the model is
      // saved will throw
      instance[isSavedInstance] = true;
    }
  }

  // now we make the instance "live" after it's all constructed
  if (resource.id != null) {
    store.makeTracked(resource.id);
  }

  deferred.fulfill(instance);
  return instance;
}

export function setCardAsSavedForTest(instance: CardDef, id?: string): void {
  if (id != null) {
    let deserialized = getDataBucket(instance);
    deserialized.set('id', id);
  }
  instance[isSavedInstance] = true;
}

function makeDescriptor<
  CardT extends BaseDefConstructor,
  FieldT extends BaseDefConstructor,
>(field: Field<FieldT>) {
  let descriptor: any = {
    enumerable: true,
  };
  descriptor.get = function (this: BaseInstanceType<CardT>) {
    return field.getter(this);
  };
  if (field.computeVia) {
    descriptor.set = function () {
      // computeds should just no-op when an assignment occurs
    };
  } else {
    descriptor.set = function (this: BaseInstanceType<CardT>, value: any) {
      if (
        (field.card as typeof BaseDef) === ReadOnlyField &&
        isCardInstance(this) &&
        this[isSavedInstance]
      ) {
        throw new Error(
          `cannot assign a value to the field '${
            field.name
          }' on the saved card '${
            (this as any)[field.name]
          }' because it is a read-only field`,
        );
      }
      setField(this, field, value);
    };
  }
  (descriptor.get as any)[isField] = field;
  return descriptor;
}

function setField(instance: BaseDef, field: Field, value: any) {
  propagateRealmContext(value, instance);
  // TODO: refactor validate to not have a return value and accomplish this normalization another way
  value = field.validate(instance, value);
  let deserialized = getDataBucket(instance);
  deserialized.set(field.name, value);
  notifySubscribers(instance, field.name, value);
  notifyCardTracking(instance);
}

function notifySubscribers(
  instance: BaseDef,
  fieldName: string,
  value: any,
  visited = new WeakSet<BaseDef>(),
) {
  if (visited.has(instance)) {
    return;
  }
  visited.add(instance);
  let changeSubscribers = subscribers.get(instance);
  if (changeSubscribers) {
    for (let subscriber of changeSubscribers) {
      subscriber(instance, fieldName, value);
    }
  }
  let consumer = subscriberConsumer.get(instance);
  if (consumer) {
    notifySubscribers(
      consumer.fieldOrCard,
      `${consumer.fieldName}.${fieldName}`,
      value,
      visited,
    );
  }
}

function cardThunk<CardT extends BaseDefConstructor>(
  cardOrThunk: CardT | (() => CardT),
): () => CardT {
  if (!cardOrThunk) {
    throw new Error(
      `cardOrThunk was ${cardOrThunk}. There might be a cyclic dependency in one of your fields.
      Use '() => CardName' format for the fields with the cycle in all related cards.
      e.g.: '@field friend = linksTo(() => Person)'`,
    );
  }
  return (
    'baseDef' in cardOrThunk ? () => cardOrThunk : cardOrThunk
  ) as () => CardT;
}

export type SignatureFor<CardT extends BaseDefConstructor> = {
  Args: {
    model: PartialBaseInstanceType<CardT>;
    fields: FieldsTypeFor<InstanceType<CardT>>;
    set: Setter;
    fieldName: string | undefined;
    context?: CardContext;
    createCard?: CreateCardFn;
    viewCard?: ViewCardFn;
    editCard?: EditCardFn;
    saveCard?: SaveCardFn;
    canEdit?: boolean;
    configuration?: FieldConfiguration | undefined;
  };
};

// Cache top-level BoxComponents by (model, componentCodeRef). CardRenderer's
// `renderedCard` getter runs on every reactive re-render, and without this
// cache it would call `Box.create(model)` + `getBoxComponent(...)` afresh
// each time — producing a brand-new FieldComponent class that Glimmer's
// `<this.renderedCard />` would treat as a new component, remounting the
// entire card tree on every reactive update. Cache key includes the
// codeRef so that toggling `useBaseTemplate` (which threads a different
// codeRef into `getComponent`) still produces a fresh component, since
// the captured `opts` lives in the FieldComponent's closure and can't be
// mutated. Field invocations (field !== undefined) go through `fieldComponent`
// → `Box.field(name)` (already cached on the parent Box), so they bypass
// this cache.
const componentByModel = new WeakMap<object, Map<string, BoxComponent>>();

function codeRefCacheKey(codeRef: CodeRef | undefined): string {
  return codeRef ? JSON.stringify(codeRef) : '';
}

export function getComponent(
  model: BaseDef,
  field?: Field,
  opts?: { componentCodeRef?: CodeRef },
): BoxComponent {
  if (field) {
    return getBoxComponent(
      model.constructor as BaseDefConstructor,
      Box.create(model),
      field,
      opts,
    );
  }
  let perModel = componentByModel.get(model);
  if (!perModel) {
    perModel = new Map();
    componentByModel.set(model, perModel);
  }
  let key = codeRefCacheKey(opts?.componentCodeRef);
  let cached = perModel.get(key);
  if (cached) {
    return cached;
  }
  let boxComponent = getBoxComponent(
    model.constructor as BaseDefConstructor,
    Box.create(model),
    field,
    opts,
  );
  perModel.set(key, boxComponent);
  return boxComponent;
}

export class Box<T> {
  static create<T>(model: T): Box<T> {
    return new Box({ type: 'root', model });
  }

  private state:
    | {
        type: 'root';
        model: any;
      }
    | {
        type: 'derived';
        containingBox: Box<any>;
        fieldName: string;
        useIndexBasedKeys: boolean;
      };

  private constructor(state: Box<T>['state']) {
    this.state = state;
  }

  get value(): T {
    if (this.state.type === 'root') {
      return this.state.model;
    } else {
      return this.state.containingBox.value[this.state.fieldName];
    }
  }

  get name() {
    return this.state.type === 'derived' ? this.state.fieldName : undefined;
  }

  set value(v: T) {
    if (this.state.type === 'root') {
      throw new Error(`can't set topmost model`);
    } else {
      let value = this.state.containingBox.value;
      if (Array.isArray(value)) {
        let index = parseInt(this.state.fieldName);
        if (typeof index !== 'number') {
          throw new Error(
            `Cannot set a value on an array item with non-numeric index '${String(
              this.state.fieldName,
            )}'`,
          );
        }
        this.state.containingBox.value[index] = v;
        return;
      }
      this.state.containingBox.value[this.state.fieldName] = v;
    }
  }

  set = <V extends T>(value: V): void => {
    this.value = value;
  };

  private fieldBoxes = new Map<string, Box<unknown>>();

  field<K extends keyof T>(fieldName: K, useIndexBasedKeys = false): Box<T[K]> {
    let box = this.fieldBoxes.get(fieldName as string);
    if (!box) {
      box = new Box({
        type: 'derived',
        containingBox: this,
        fieldName: fieldName as string,
        useIndexBasedKeys,
      });
      this.fieldBoxes.set(fieldName as string, box);
    }
    return box as Box<T[K]>;
  }

  private prevChildren: Box<ElementType<T>>[] = [];
  private prevValues: ElementType<T>[] = [];

  get children(): Box<ElementType<T>>[] {
    if (this.state.type === 'root') {
      throw new Error('tried to call children() on root box');
    }
    let value = this.value;
    if (value == null) {
      return [];
    }
    if (!Array.isArray(value)) {
      throw new Error(
        `tried to call children() on Boxed non-array value ${value} for ${String(
          this.state.fieldName,
        )}`,
      );
    }

    let { prevChildren, prevValues, state } = this;
    let newChildren: Box<ElementType<T>>[] = value.map((element, index) => {
      let found = prevChildren.find((_oldBox, i) =>
        state.useIndexBasedKeys ? index === i : this.prevValues[i] === element,
      );
      if (found) {
        if (state.useIndexBasedKeys) {
          // note that the underlying box already has the correct value so there
          // is nothing to do in this case. also, we are currently inside a rerender.
          // mutating a watched array in a rerender will spawn another rerender which
          // infinitely recurses.
        } else {
          let toRemoveIndex = prevChildren.indexOf(found);
          prevChildren.splice(toRemoveIndex, 1);
          prevValues.splice(toRemoveIndex, 1);
          if (found.state.type === 'root') {
            throw new Error('bug');
          }
          found.state.fieldName = String(index);
        }
        return found;
      } else {
        return new Box({
          type: 'derived',
          containingBox: this,
          fieldName: String(index),
          useIndexBasedKeys: false,
        });
      }
    });
    this.prevChildren = newChildren;
    this.prevValues = value.slice();
    return newChildren;
  }
}

type ElementType<T> = T extends (infer V)[] ? V : never;

declare module 'ember-provide-consume-context/context-registry' {
  export default interface ContextRegistry {
    [CardContextName]: CardContext;
  }
}

function getStore(instance: BaseDef): CardStore {
  return stores.get(instance as BaseDef) ?? new FallbackCardStore();
}

// Resolve a (possibly relative or RRI) reference to a real, fetchable URL,
// relative to the instance's own location. Card definitions that must hand a
// real URL to a boundary that can't consume canonical RRI (an `<img src>`, the
// AI source-file reader's `new URL(...)`) use this rather than reaching for the
// VirtualNetwork object directly — they get back a URL, not the network itself.
// Resolves through the instance's own store, which may carry realm mappings
// the module loader's network does not (e.g. a card deserialized with an
// explicit store). Returns undefined when none is available, or when the
// reference can't be resolved, so callers can degrade to URL math.
export function resolveInstanceURL(
  instance: CardDef,
  reference: string,
): URL | undefined {
  try {
    return getStore(instance).resolveURL(
      reference,
      instance.id ?? instance[relativeTo],
    );
  } catch {
    return undefined;
  }
}

// Resolve a (possibly relative) reference to its absolute canonical RRI,
// relative to `relativeTo`. Identifiers are canonical RRI by the time they
// reach here, so this is pure form-preserving path math (see
// `resolveRRIReference`) — no VirtualNetwork, no realm-mapping lookup. The
// returned string is used as an opaque store key / "did this resolve?" signal.
// Exported for `searchable.ts`'s search-doc absolutization.
export function resolveRef(
  reference: string,
  relativeTo: RealmResourceIdentifier | URL | undefined,
): string {
  return resolveRRIReference(reference, relativeTo);
}

function myLoader(): Loader {
  // we know this code is always loaded by an instance of our Loader, which sets
  // import.meta.loader.

  // When type-checking realm-server, tsc sees this file and thinks
  // it will be transpiled to CommonJS and so it complains about this line. But
  // this file is always loaded through our loader and always has access to import.meta.
  // @ts-ignore
  return (import.meta as any).loader;
}

class FallbackCardStore implements CardStore {
  #instances: Map<string, CardDef> = new Map();
  #fileMetaInstances: Map<string, FileDef> = new Map();
  #inFlight: Set<Promise<unknown>> = new Set();
  #loadGeneration = 0; // mirrors host store tracking to detect new loads

  #requireVirtualNetwork(): VirtualNetwork {
    let vn = myLoader().getVirtualNetwork();
    if (!vn) {
      throw new Error(
        `FallbackCardStore requires the active Loader to have a VirtualNetwork`,
      );
    }
    return vn;
  }

  resolveURL(reference: string, base?: string): URL | undefined {
    let vn: VirtualNetwork | undefined;
    try {
      vn = myLoader().getVirtualNetwork();
    } catch {
      return undefined;
    }
    if (!vn) {
      return undefined;
    }
    try {
      return vn.resolveURL(reference, base);
    } catch {
      return undefined;
    }
  }

  getCard(id: string) {
    id = id.replace(/\.json$/, '');
    return this.#instances.get(id);
  }
  getFileMeta(id: string) {
    id = id.replace(/\.json$/, '');
    return this.#fileMetaInstances.get(id);
  }
  setCard(id: string, instance: CardDef) {
    id = id.replace(/\.json$/, '');
    return this.#instances.set(id, instance);
  }
  setFileMeta(id: string, instance: FileDef) {
    id = id.replace(/\.json$/, '');
    return this.#fileMetaInstances.set(id, instance);
  }
  setCardNonTracked(id: string, instance: CardDef) {
    id = id.replace(/\.json$/, '');
    return this.#instances.set(id, instance);
  }
  setFileMetaNonTracked(id: string, instance: FileDef) {
    id = id.replace(/\.json$/, '');
    return this.#fileMetaInstances.set(id, instance);
  }
  makeTracked(_id: string) {}
  trackLoad(load: Promise<unknown>) {
    if (this.#inFlight.has(load)) {
      return;
    }
    this.#inFlight.add(load);
    this.#loadGeneration++;
    load.finally(() => {
      this.#inFlight.delete(load);
    });
  }
  async loaded() {
    let observedGeneration = this.#loadGeneration;
    while (true) {
      if (this.#inFlight.size === 0) {
        await Promise.resolve();
      } else {
        let pendingLoads = Array.from(this.#inFlight);
        await Promise.allSettled(pendingLoads);
      }
      if (
        this.#inFlight.size === 0 &&
        this.#loadGeneration === observedGeneration
      ) {
        return;
      }
      observedGeneration = this.#loadGeneration;
    }
  }
  async loadCardDocument(
    url: string,
    opts?: { dependencyTrackingContext?: RuntimeDependencyTrackingContext },
  ) {
    trackRuntimeInstanceDependency(url, opts?.dependencyTrackingContext);
    let promise = loadCardDocument(fetch, url, this.#requireVirtualNetwork());
    this.trackLoad(promise);
    return await promise;
  }

  async loadFileMetaDocument(
    url: string,
    opts?: { dependencyTrackingContext?: RuntimeDependencyTrackingContext },
  ) {
    trackRuntimeFileDependency(url, opts?.dependencyTrackingContext);
    let promise = loadFileMetaDocument(
      fetch,
      url,
      this.#requireVirtualNetwork(),
    );
    this.trackLoad(promise);
    return await promise;
  }

  getSearchResource<T extends CardDef = CardDef>(
    _parent: object,
    _getQuery: () => any,
    _getRealms?: () => string[] | undefined,
    _opts?: any,
  ): StoreSearchResource<T> {
    return {
      instances: [] as T[],
      instancesByRealm: [],
      isLoading: false,
      meta: { page: { total: 0 } },
      errors: undefined,
    } as StoreSearchResource<T>;
  }
}