@warp-drive/core 5.9.0-alpha.17 → 5.9.0-alpha.19

package/dist/unpkg/dev/graph/-private.js

@@ -55,9 +55,14 @@ function assertValidRelationshipPayload(graph, op) {
     kind
   } = definition;
   if (payload.links) {
-    console.warn(`You pushed a record of type '${type}' with a relationship '${field}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, isAsync || payload.data === null || !!payload.data || state.hasReceivedData, {
-      id: 'ds.store.push-link-for-sync-relationship'
-    });
+    // once JSON_API_CACHE_VALIDATION_ERRORS is active, this warning is instead
+    // the responsibility of the new document validator (see validateResourceRelationships
+    // in warp-drive-packages/json-api/src/-private/validator/1.1/7.2_resource-objects.ts)
+    {
+      console.warn(`You pushed a record of type '${type}' with a relationship '${field}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, isAsync || payload.data === null || !!payload.data || state.hasReceivedData, {
+        id: 'ds.store.push-link-for-sync-relationship'
+      });
+    }
   } else if (payload.data) {
     if (kind === 'belongsTo') {
       (test => {
@@ -748,7 +753,7 @@ let assertInheritedSchema;
       errors.set('type', ` <---- should be '${definition.inverseType}'`);
     }
     if (definition.inverseKind !== meta.kind) {
-      errors.set('type', ` <---- should be '${definition.inverseKind}'`);
+      errors.set('kind', ` <---- should be '${definition.inverseKind}'`);
     }
     if (definition.inverseIsAsync !== meta.options.async) {
       errors.set('async', ` <---- should be ${definition.inverseIsAsync}`);
@@ -759,7 +764,12 @@ let assertInheritedSchema;
     if (definition.key !== meta.options.inverse) {
       errors.set('inverse', ` <---- should be '${definition.key}'`);
     }
-    if (definition.type !== meta.options.as) {
+    // `as` is only meaningful when `definition` itself is polymorphic (i.e. it
+    // points at an abstract type that `meta` is expected to implement). When
+    // `definition` isn't polymorphic, there's no abstract type for `meta` to
+    // declare `as` against, so `meta.options.as` is correctly absent - that's
+    // not an error to report.
+    if (definition.isPolymorphic && definition.type !== meta.options.as) {
       errors.set('as', ` <---- should be '${definition.type}'`);
     }
     return errors;
@@ -798,18 +808,6 @@ let assertInheritedSchema;
 
 `;
   }
-  function metaFrom(definition) {
-    return {
-      name: definition.key,
-      type: definition.type,
-      kind: definition.kind,
-      options: {
-        async: definition.isAsync,
-        polymorphic: definition.isPolymorphic,
-        inverse: definition.inverseKey
-      }
-    };
-  }
   function inverseMetaFrom(definition) {
     return {
       name: definition.inverseKey,
@@ -852,15 +850,18 @@ let assertInheritedSchema;
     });
   }
   assertInheritedSchema = function assertInheritedSchema(definition, type) {
-    const meta1 = metaFrom(definition);
+    // `definition` is the only source of truth we have here - there is no
+    // second, independently-declared schema available to diff it against.
+    // That means the only thing we can actually verify is internal: does
+    // `definition`'s own resolved inverse agree that this relationship is
+    // polymorphic? Every other field of `meta2` below (name/type/kind/async/
+    // inverse) is derived directly from `definition` itself, so comparing
+    // them back to `definition` can never disagree - only the polymorphic
+    // flag is independently meaningful, because `definitionWithPolymorphic`
+    // asserts what it *should* be rather than mirroring what it already is.
     const meta2 = inverseMetaFrom(definition);
-    const errors1 = validateSchema(inverseDefinition(definition), meta1);
     const errors2 = validateSchema(definitionWithPolymorphic(definition), meta2);
-    if (errors2.size === 0 && errors1.size > 0) {
-      throw new Error(`The schema for the relationship '${type}.${definition.key}' is not configured to satisfy '${definition.inverseType}' and thus cannot utilize the '${definition.inverseType}.${definition.key}' relationship to connect with '${definition.type}.${definition.inverseKey}'\n\nIf using this relationship in a polymorphic manner is desired, the relationships schema definition for '${type}' should include:${printSchema(meta1, errors1)}`);
-    } else if (errors1.size > 0) {
-      throw new Error(`The schema for the relationship '${type}.${definition.key}' is not configured to satisfy '${definition.inverseType}' and thus cannot utilize the '${definition.inverseType}.${definition.key}' relationship to connect with '${definition.type}.${definition.inverseKey}'\n\nIf using this relationship in a polymorphic manner is desired, the relationships schema definition for '${type}' should include:${printSchema(meta1, errors1)} and the relationships schema definition for '${definition.type}' should include:${printSchema(meta2, errors2)}`);
-    } else if (errors2.size > 0) {
+    if (errors2.size > 0) {
       throw new Error(`The schema for the relationship '${type}.${definition.key}' satisfies '${definition.inverseType}' but cannot utilize the '${definition.inverseType}.${definition.key}' relationship to connect with '${definition.type}.${definition.inverseKey}' because that relationship is not polymorphic.\n\nIf using this relationship in a polymorphic manner is desired, the relationships schema definition for '${definition.type}' should include:${printSchema(meta2, errors2)}`);
     }
   };
@@ -1355,8 +1356,10 @@ function replaceRelatedRecord(graph, op, isRemote = false) {
   if (op.value === existingState) {
     // if we were empty before but now know we are empty this needs to be true
     state.hasReceivedData = true;
+
     // if this is a remote update we still sync
     if (isRemote) {
+      state.hasReceivedRemoteData = true;
       const {
         localState
       } = relationship;
@@ -1379,6 +1382,15 @@ function replaceRelatedRecord(graph, op, isRemote = false) {
   // update value to the new value
   relationship[prop] = op.value;
   state.hasReceivedData = true;
+  /**
+   * Local mutations never give us additional information about
+   * whether the relationship has received *remote* data. This is
+   * what `getRemoteRelationship` relies on to avoid reflecting
+   * local-only edits.
+   */
+  if (isRemote) {
+    state.hasReceivedRemoteData = true;
+  }
   state.isEmpty = op.value === null;
   state.isStale = false;
   state.hasFailedLoadAttempt = false;
@@ -1890,8 +1902,30 @@ function rollbackRelationship(graph, key, field, relationship) {
   }
 }
 function createState() {
+  {
+    {
+      if (getGlobalConfig().WarpDrive.debug.LOG_GRAPH || globalThis.getWarpDriveRuntimeConfig().debug.LOG_GRAPH) {
+        let hasReceivedData = false;
+        return {
+          get hasReceivedData() {
+            return hasReceivedData;
+          },
+          set hasReceivedData(value) {
+            hasReceivedData = value;
+          },
+          hasReceivedRemoteData: false,
+          isEmpty: true,
+          isStale: false,
+          hasFailedLoadAttempt: false,
+          shouldForceReload: false,
+          hasDematerializedInverse: false
+        };
+      }
+    }
+  }
   return {
     hasReceivedData: false,
+    hasReceivedRemoteData: false,
     isEmpty: true,
     isStale: false,
     hasFailedLoadAttempt: false,
@@ -1996,13 +2030,10 @@ function legacyGetResourceRelationshipData(source, getRemoteState) {
   source.accessed = true;
   let data;
   const payload = {};
-  if (getRemoteState && source.remoteState) {
-    data = source.remoteState;
-  } else if (!getRemoteState && source.localState) {
-    data = source.localState;
-  }
-  if ((getRemoteState && source.remoteState === null || source.localState === null) && source.state.hasReceivedData) {
-    data = null;
+  if (getRemoteState && (source.remoteState || source.state.hasReceivedRemoteData)) {
+    data = source.remoteState ?? null;
+  } else if (!getRemoteState && (source.localState || source.state.hasReceivedData)) {
+    data = source.localState ?? null;
   }
   if (source.links) {
     payload.links = source.links;
@@ -2216,7 +2247,6 @@ function updateRelationshipOperation(graph, op) {
   })(isHasMany(relationship) || isBelongsTo(relationship));
   const {
     definition,
-    state,
     identifier
   } = relationship;
   const {
@@ -2256,23 +2286,6 @@ function updateRelationshipOperation(graph, op) {
         value: payload.data ? graph.store.cacheKeyManager.upgradeIdentifier(payload.data) : null
       }, true);
     }
-  } else if (definition.isAsync === false && !state.hasReceivedData) {
-    hasRelationshipDataProperty = true;
-    if (isCollection) {
-      graph.update({
-        op: 'replaceRelatedRecords',
-        record: identifier,
-        field: op.field,
-        value: []
-      }, true);
-    } else {
-      graph.update({
-        op: 'replaceRelatedRecord',
-        record: identifier,
-        field: op.field,
-        value: null
-      }, true);
-    }
   }
   if (payload.links) {
     const originalLinks = relationship.links;
@@ -2282,9 +2295,10 @@ function updateRelationshipOperation(graph, op) {
       const currentLink = originalLinks && originalLinks.related ? _normalizeLink(originalLinks.related) : null;
       const currentLinkHref = currentLink ? currentLink.href : null;
       if (relatedLink && relatedLink.href && relatedLink.href !== currentLinkHref) {
-        console.warn(`You pushed a record of type '${identifier.type}' with a relationship '${definition.key}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, definition.isAsync || state.hasReceivedData, {
-          id: 'ds.store.push-link-for-sync-relationship'
-        });
+        // Note: the equivalent warning for this case is issued eagerly (and with a more
+        // complete condition, since it also accounts for `payload.data` being present) by
+        // `assertValidRelationshipPayload` in `-utils.ts`, which always runs immediately
+        // before this operation in DEBUG builds. Warning here too would double-warn.
         (test => {
           if (!test) {
             throw new Error(`You have pushed a record of type '${identifier.type}' with '${definition.key}' as a link, but the value of that link is not a string.`);
@@ -2315,6 +2329,7 @@ function updateRelationshipOperation(graph, op) {
     // we don't need to notify here as the update op we pushed in above will notify once
     // membership is in the correct state.
     relationship.state.hasReceivedData = true;
+    relationship.state.hasReceivedRemoteData = true;
     relationship.state.isStale = false;
     relationship.state.hasDematerializedInverse = false;
     relationship.state.isEmpty = relationshipIsEmpty;

package/dist/unpkg/dev/{index-BZRBBa34.js → index-DU_HLpg-.js}

@@ -2,13 +2,13 @@ import { D as Destroy, C as Context, S as SOURCE, a as Checkout, b as Commit } f
 import { d as defineGate, w as withSignalStore, n as notifyInternalSignal, p as peekInternalSignal, a as willSyncFlushWatchers, g as getOrCreateInternalSignal, c as consumeInternalSignal, b as createInternalSignal, A as ARRAY_SIGNAL, S as Signals, e as createSignalDescriptor, f as defineSignal, h as entangleSignal, i as entangleInitiallyStaleSignal, O as OBJECT_SIGNAL, j as createInternalMemo, o as waitFor } from "./-leaked-BohmerbH.js";
 import { EnableHydration, SkipCache, STRUCTURED } from './types/request.js';
 import { isResourceSchema } from './types/schema/fields.js';
+import { setLogging, getRuntimeConfig, setIsMaybeMirage } from './types/runtime.js';
 import { a as cloneResponseProperties, I as IS_CACHE_HANDLER, b as assertValidRequest, e as executeNextHandler, d as getRequestResult, u as upgradePromise, s as setPromiseResult, f as clearRequestResult } from "./future-DUuPqyLj.js";
 import { getOrSetGlobal, setTransient, peekTransient, peekUniversalTransient, setUniversalTransient } from './types/-private.js';
 import { DefaultCachePolicy } from './store.js';
 import { withBrand } from './request.js';
 import { CACHE_OWNER, DEBUG_STALE_CACHE_OWNER, DEBUG_KEY_TYPE, DEBUG_CLIENT_ORIGINATED } from './types/identifier.js';
 import { g as getGlobalConfig } from "./runtime-DGG4CvlW.js";
-import { setLogging, getRuntimeConfig } from './types/runtime.js';
 import { RecordStore, Type } from './types/symbols.js';
 function urlFromLink(link) {
   if (typeof link === 'string') return link;
@@ -6660,11 +6660,32 @@ function getBelongsToField(context) {
 }
 function setBelongsToField(context) {
   const {
+    field,
+    resourceKey,
     store
   } = context;
   const {
-    schema
+    schema,
+    cache
   } = store;
+
+  /**
+   * We currently only allow editing sync belongsTo relationships
+   * in PolarisMode
+   */
+  const isValidPolarisConfig = field.options.linksMode && !field.options.async;
+  if (!context.legacy && isValidPolarisConfig) {
+    const name = context.path.at(-1);
+    cache.mutate({
+      op: 'replaceRelatedRecord',
+      record: resourceKey,
+      field: name,
+      value: getResourceKey(context.value)
+    },
+    // @ts-expect-error
+    true);
+    return true;
+  }
   (test => {
     if (!test) {
       throw new Error(`Can only mutate belongsTo fields when the resource is in legacy mode`);
@@ -6673,6 +6694,12 @@ function setBelongsToField(context) {
   schema._kind('@legacy', 'belongsTo').set(store, context.record, context.resourceKey, context.field, context.value);
   return true;
 }
+function getResourceKey(record) {
+  if (!record) {
+    return null;
+  }
+  return recordIdentifierFor(record);
+}
 function getCollectionField(context) {
   entangleSignal(context.signals, context.record, context.path.at(-1), null);
   (test => {
@@ -7405,6 +7432,17 @@ function setSchemaObjectField(context) {
   // }
   return true;
 }
+
+/**
+ * A ReactiveResource context object passed to
+ * the get/set functions of a field kind implementation.
+ *
+ * This provides all the necessary information for
+ * the field kind to perform its operations.
+ *
+ * @internal
+ */
+
 const DefaultMode = {
   '@hash': {
     get: getHashField,
@@ -7700,6 +7738,9 @@ class ReactiveResource {
         if (prop === Destroy || prop === Checkout) {
           return true;
         }
+        if (prop === identityField?.name) {
+          return true;
+        }
         return fields.has(prop);
       },
       getOwnPropertyDescriptor(target, prop) {
@@ -8198,6 +8239,14 @@ const TypeField = {
     key: 'type'
   }
 };
+const IdentifierField = {
+  type: '@identity',
+  name: '$key',
+  kind: 'derived',
+  options: {
+    key: '^'
+  }
+};
 const DefaultIdentityField = {
   name: 'id',
   kind: '@id'
@@ -8386,6 +8435,7 @@ function withDefaults(schema) {
   // we add TypeField to the beginning so that it will
   // appear right next to the identity field
   schema.fields.unshift(TypeField);
+  schema.fields.unshift(IdentifierField);
   schema.fields.push(ConstructorField);
   return schema;
 }
@@ -8441,6 +8491,90 @@ function registerDerivations(schema) {
   schema.registerDerivation(fromIdentity);
   schema.registerDerivation(_constructor);
 }
+
+/**
+ * A relationship field capable of declaring `options.as`, marking it as a
+ * concrete implementation of an abstract polymorphic type.
+ */
+
+/**
+ * A relationship field contributed to an abstract type's schema, along with
+ * the name of the type that contributed it (either a concrete implementer,
+ * via `options.as`, or the abstract type's own schema), for use in assertion
+ * messages when two contributions disagree on shape.
+ */
+
+/**
+ * Reduces a field to a plain object with a fixed key order, covering every
+ * option any relationship-implementer field can declare, so two fields can
+ * be compared for exact equality via `JSON.stringify` regardless of the key
+ * order the schema author happened to write them in.
+ *
+ * `options.as` is included and is *not* special-cased: every contributor to
+ * a given field name on an abstract type - including the abstract type's
+ * own schema, if it has one - is expected to declare `as` equal to that
+ * abstract type's own name. This is redundant/self-referential for the
+ * abstract type's own schema, but required for consistency: relationship
+ * resolution elsewhere (e.g. `inverse` name-matching) does not itself
+ * validate `as`, so a field with a missing or incorrect `as` can otherwise
+ * be silently pulled into a relationship it never declared it implements.
+ */
+function comparableAbstractFieldShape(field) {
+  const {
+    kind,
+    name,
+    type,
+    sourceKey,
+    options
+  } = field;
+  return {
+    kind,
+    name,
+    type,
+    sourceKey,
+    options: {
+      as: options?.as,
+      async: options?.async,
+      inverse: options?.inverse,
+      polymorphic: options?.polymorphic,
+      linksMode: options?.linksMode,
+      resetOnRemoteUpdate: options?.resetOnRemoteUpdate,
+      arrayExtensions: options?.arrayExtensions
+    }
+  };
+}
+
+/**
+ * Asserts that two contributions to the same field name on an abstract
+ * polymorphic type - whether from two different concrete implementers, or
+ * from an implementer and the abstract type's own schema - declare an
+ * identical shape: `kind`, `type`, and every option, including `as` (which
+ * every contributor, the abstract type's own schema included, must declare
+ * equal to `abstractType`). A mismatch here (e.g. one implementer's field
+ * being a `hasMany` while another's is a `belongsTo`, the two disagreeing on
+ * `inverse`/`async`/`polymorphic`, or one omitting or misdeclaring `as`)
+ * cannot be resolved by picking one side arbitrarily, since that would
+ * silently leave whichever side lost the mismatch pointing at a relationship
+ * whose true shape differs from what its own schema declared.
+ */
+function assertConsistentAbstractFieldShape(abstractType, fieldName, existing, incoming) {
+  // This function exists solely to support the `assert()` call below - there
+  // is no other work here with an effect in production. Since `assert()`'s
+  // own babel-macro stripping only removes the call expression itself, not
+  // the (comparatively expensive, involving `JSON.stringify`) computation of
+  // its arguments, guard the whole body so none of it survives in production
+  // builds, matching how `assertPolymorphicType`/`assertInheritedSchema` and
+  // their call sites are gated in `assert-polymorphic-type.ts`.
+  {
+    const existingShape = comparableAbstractFieldShape(existing.field);
+    const incomingShape = comparableAbstractFieldShape(incoming.field);
+    (test => {
+      if (!test) {
+        throw new Error(`Expected the relationship '${fieldName}' on the abstract polymorphic type '${abstractType}' to be declared identically everywhere it is implemented (including 'options.as', which every contributor - the abstract type's own schema included - must declare equal to '${abstractType}'), but '${existing.source}' declares it as:\n\n${JSON.stringify(existingShape, null, 2)}\n\nwhile '${incoming.source}' declares it as:\n\n${JSON.stringify(incomingShape, null, 2)}\n\nAll concrete implementers of an abstract type - and the abstract type's own schema, if it has one - must declare an identical shape for any relationship field they share.`);
+      }
+    })(JSON.stringify(existingShape) === JSON.stringify(incomingShape));
+  }
+}
 /**
  * Wraps a derivation in a new function with Derivation signature but that looks
  * up the value in the cache before recomputing.
@@ -8480,6 +8614,18 @@ class SchemaService {
 
   /** @internal */
 
+  /**
+   * Tracks, per abstract type, the relationship fields that concrete
+   * implementers have contributed via `options.as`, along with the type
+   * that contributed each one (for assertion messages). This is
+   * independent of whatever schema (synthesized or user-registered)
+   * currently occupies `_schemas` for that type, so that these fields
+   * survive regardless of the order in which the abstract type's
+   * implementers and its own (optional) concrete schema are registered.
+   *
+   * @internal
+   */
+
   /** @internal */
 
   /** @internal */
@@ -8491,6 +8637,7 @@ class SchemaService {
     this._derivations = new Map();
     this._traits = new Map();
     this._modes = new Map();
+    this._abstractImplementerFields = new Map();
     this._extensions = {
       object: new Map(),
       array: new Map()
@@ -8586,6 +8733,7 @@ class SchemaService {
     const fields = new Map();
     const relationships = {};
     const attributes = {};
+    const abstractImplementations = [];
     for (const field of schema.fields) {
       (test => {
         if (!test) {
@@ -8599,6 +8747,31 @@ class SchemaService {
         attributes[field.name] = field;
       } else if (field.kind === 'belongsTo' || field.kind === 'hasMany') {
         relationships[field.name] = field;
+        if (field.options?.as) {
+          abstractImplementations.push(field);
+        }
+      }
+    }
+
+    // This type may already be known as an abstract polymorphic type,
+    // implemented by other concrete types via `options.as`, from before it
+    // ever had a schema of its own (see `_registerAbstractTypeImplementation`).
+    // Carry those previously-contributed fields forward so that registering
+    // a "real" schema for the type - whenever that happens to occur - never
+    // erases the relationships its implementers depend on.
+    const implementerFields = this._abstractImplementerFields.get(schema.type);
+    if (implementerFields) {
+      for (const [name, contribution] of implementerFields) {
+        const ownField = fields.get(name);
+        if (!ownField) {
+          fields.set(name, contribution.field);
+          relationships[name] = contribution.field;
+        } else {
+          assertConsistentAbstractFieldShape(schema.type, name, contribution, {
+            field: ownField,
+            source: schema.type
+          });
+        }
       }
     }
     const cacheFields = null;
@@ -8617,6 +8790,101 @@ class SchemaService {
       internalSchema.cacheFields = getCacheFields(internalSchema);
     }
     this._schemas.set(schema.type, internalSchema);
+
+    // A relationship field's `as` option marks it as a valid concrete
+    // implementer of an abstract polymorphic type (e.g. `as: 'commentable'`).
+    // That abstract type may never be given its own schema by the user - it
+    // may exist only to be implemented by concrete types like this one - or
+    // it may already have (or later receive) a schema of its own, e.g. if it
+    // turns out to also be a real, directly-resolvable resource. Either way,
+    // ensure it has a schema with this field present, so that it behaves
+    // like any other registered resource (`hasResource`, `fields`, etc.)
+    // instead of requiring special-casing wherever abstract relationship
+    // types are resolved.
+    for (const field of abstractImplementations) {
+      this._registerAbstractTypeImplementation(field, schema.type);
+    }
+  }
+
+  /** @internal */
+  _registerAbstractTypeImplementation(field, implementer) {
+    const abstractType = field.options.as;
+    let implementerFields = this._abstractImplementerFields.get(abstractType);
+    if (!implementerFields) {
+      implementerFields = new Map();
+      this._abstractImplementerFields.set(abstractType, implementerFields);
+    }
+
+    // Unlike the original approach this replaced, `as` is *not* stripped here:
+    // the field as synthesized onto the abstract type's own schema keeps
+    // `options.as === abstractType`, redundant/self-referential as that is.
+    // This keeps every contributor - implementers and the abstract type's
+    // own schema alike - declaring the same thing, which is what
+    // `assertConsistentAbstractFieldShape` checks, and it is also what lets
+    // `assertPolymorphicType` (which reads a field's declared `as` off
+    // whatever `schema.fields()` serves for its type) correctly permit the
+    // abstract type itself to be pushed directly into this relationship.
+    const abstractField = {
+      ...field
+    };
+    const contribution = {
+      field: abstractField,
+      source: implementer
+    };
+
+    // all concrete implementations of an abstract type are required to
+    // share the same shape for the field that implements it, so the first
+    // one registered is as good a canonical source as any - but a later,
+    // differently-shaped one is almost certainly a mistake rather than an
+    // intentional override, so we catch it rather than silently ignoring it.
+    const existingImplementer = implementerFields.get(field.name);
+    if (existingImplementer) {
+      {
+        assertConsistentAbstractFieldShape(abstractType, field.name, existingImplementer, contribution);
+      }
+      return;
+    }
+    implementerFields.set(field.name, contribution);
+    let abstractSchema = this._schemas.get(abstractType);
+    if (!abstractSchema) {
+      abstractSchema = {
+        original: {
+          legacy: true,
+          identity: {
+            kind: '@id',
+            name: 'id'
+          },
+          type: abstractType,
+          fields: []
+        },
+        finalized: true,
+        fields: new Map(),
+        cacheFields: new Map(),
+        relationships: {},
+        attributes: {},
+        traits: new Set()
+      };
+      this._schemas.set(abstractType, abstractSchema);
+    }
+    const existingAbstractField = abstractSchema.fields.get(field.name);
+    if (existingAbstractField) {
+      {
+        assertConsistentAbstractFieldShape(abstractType, field.name, {
+          field: existingAbstractField,
+          source: abstractType
+        }, contribution);
+      }
+      return;
+    }
+    abstractSchema.fields.set(field.name, abstractField);
+    abstractSchema.relationships[field.name] = abstractField;
+
+    // If the schema is mid-finalization (traits pending), finalizeResource
+    // will recompute cacheFields from the current `fields` map anyway; avoid
+    // doing so prematurely from a partially-resolved set of fields.
+    if (abstractSchema.finalized) {
+      abstractSchema.cacheFields = getCacheFields(abstractSchema);
+    }
   }
 
   /**
@@ -8875,9 +9143,33 @@ function cloneResponse(response, overrides) {
   const props = cloneResponseProperties(response);
   return new Response(response.body, Object.assign(props, overrides));
 }
+function withDateHeader(response) {
+  const headers = new Headers(response.headers);
+  headers.set('date', new Date().toUTCString());
+  return cloneResponse(response, {
+    headers
+  });
+}
+
+// Detects Mirage (or another Pretender-based fetch mock), whose `Response`
+// may (unlike a spec-compliant `fetch()`, whose Response headers are always
+// immutable) allow header mutation and may not support streaming reads.
+//
+// This is inherently a heuristic - many legitimate tools (APM/monitoring
+// agents, browser extensions, polyfills) also patch `window.fetch`, and can
+// produce false positives. `setWarpDriveIsMaybeMirage(value)` lets an app
+// declare the answer explicitly (`true` or `false`), overriding the
+// heuristic in either direction; leave it unset to keep the default
+// detection. See https://github.com/warp-drive-data/warp-drive/issues/10535
 let IS_MAYBE_MIRAGE = () => false;
 {
-  IS_MAYBE_MIRAGE = () => Boolean(typeof window !== 'undefined' && (window.server?.pretender || window.fetch.toString().replace(/\s+/g, '') !== 'function fetch() { [native code] }'.replace(/\s+/g, '')));
+  IS_MAYBE_MIRAGE = () => {
+    const override = getRuntimeConfig().mirage;
+    if (override !== undefined) {
+      return override;
+    }
+    return Boolean(typeof window !== 'undefined' && (window.server?.pretender || window.fetch.toString().replace(/\s+/g, '') !== 'function fetch() { [native code] }'.replace(/\s+/g, '')));
+  };
 }
 const MUTATION_OPS = new Set(['updateRecord', 'createRecord', 'deleteRecord']);
 const ERROR_STATUS_CODE_FOR = new Map([[400, 'Bad Request'], [401, 'Unauthorized'], [402, 'Payment Required'], [403, 'Forbidden'], [404, 'Not Found'], [405, 'Method Not Allowed'], [406, 'Not Acceptable'], [407, 'Proxy Authentication Required'], [408, 'Request Timeout'], [409, 'Conflict'], [410, 'Gone'], [411, 'Length Required'], [412, 'Precondition Failed'], [413, 'Payload Too Large'], [414, 'URI Too Long'], [415, 'Unsupported Media Type'], [416, 'Range Not Satisfiable'], [417, 'Expectation Failed'], [419, 'Page Expired'], [420, 'Enhance Your Calm'], [421, 'Misdirected Request'], [422, 'Unprocessable Entity'], [423, 'Locked'], [424, 'Failed Dependency'], [425, 'Too Early'], [426, 'Upgrade Required'], [428, 'Precondition Required'], [429, 'Too Many Requests'], [430, 'Request Header Fields Too Large'], [431, 'Request Header Fields Too Large'], [450, 'Blocked By Windows Parental Controls'], [451, 'Unavailable For Legal Reasons'], [500, 'Internal Server Error'], [501, 'Not Implemented'], [502, 'Bad Gateway'], [503, 'Service Unavailable'], [504, 'Gateway Timeout'], [505, 'HTTP Version Not Supported'], [506, 'Variant Also Negotiates'], [507, 'Insufficient Storage'], [508, 'Loop Detected'], [509, 'Bandwidth Limit Exceeded'], [510, 'Not Extended'], [511, 'Network Authentication Required']]);
@@ -8929,13 +9221,15 @@ const Fetch = {
     const isMutationOp = Boolean(op && MUTATION_OPS.has(op));
     if (!isError && !isMutationOp && response.status !== 204 && !response.headers.has('date')) {
       if (IS_MAYBE_MIRAGE()) {
-        response.headers.set('date', new Date().toUTCString());
+        try {
+          response.headers.set('date', new Date().toUTCString());
+        } catch {
+          // IS_MAYBE_MIRAGE() was a false positive, or the mock's headers
+          // are (correctly) immutable - fall back to cloning.
+          response = withDateHeader(response);
+        }
       } else {
-        const headers = new Headers(response.headers);
-        headers.set('date', new Date().toUTCString());
-        response = cloneResponse(response, {
-          headers
-        });
+        response = withDateHeader(response);
       }
     }
     context.setResponse(response);
@@ -9330,6 +9624,12 @@ class RequestManager {
   globalThis.getWarpDriveRuntimeConfig = getRuntimeConfig;
 }
 
+// Mirage (or another Pretender-based fetch mock) may be used outside of a
+// `TESTING` build (e.g. `ember serve` in dev mode), so this override is
+// exposed unconditionally rather than gated to the `TESTING` env.
+// @ts-expect-error adding to globalThis
+globalThis.setWarpDriveIsMaybeMirage = setIsMaybeMirage;
+
 /**
  * Options for setting up a Store instance with `useRecommendedStore`.
  */
@@ -9350,7 +9650,29 @@ class RequestManager {
  */
 function useRecommendedStore(options, StoreKlass = Store) {
   return class AppStore extends StoreKlass {
-    requestManager = new RequestManager().use([...(options.handlers ?? []), Fetch]).useCache(CacheHandler);
+    constructor(createArgs) {
+      super(createArgs);
+      // installed via defineProperty (rather than a class field/accessor) so that
+      // this lazy override of the inherited `requestManager` field does not
+      // conflict with the documented pattern of assigning it directly on
+      // consumer-authored Store subclasses. The setter preserves the ability
+      // to replace `requestManager` outright after construction.
+      let requestManager;
+      Object.defineProperty(this, 'requestManager', {
+        configurable: true,
+        enumerable: true,
+        get: () => {
+          if (!requestManager) {
+            const handlers = typeof options.handlers === 'function' ? options.handlers(this) : options.handlers ?? [];
+            requestManager = new RequestManager().use([...handlers, Fetch]).useCache(CacheHandler);
+          }
+          return requestManager;
+        },
+        set: value => {
+          requestManager = value;
+        }
+      });
+    }
     lifetimes = options.policy ?? new DefaultCachePolicy({
       apiCacheHardExpires: 15 * 60 * 1000,
       // 15 minutes