@warp-drive-mirror/json-api 5.8.0-alpha.30 → 5.8.0-alpha.34

package/dist/unpkg/dev/index.js

@@ -0,0 +1,3225 @@
+import { graphFor, peekGraph, isBelongsTo } from '@warp-drive-mirror/core/graph/-private';
+import { logGroup, isResourceKey, assertPrivateCapabilities, isRequestKey } from '@warp-drive-mirror/core/store/-private';
+import Fuse from 'fuse.js';
+import jsonToAst from 'json-to-ast';
+import { macroCondition, getGlobalConfig } from '@embroider/macros';
+
+function validateDocumentFields(schema, jsonApiDoc) {
+  const {
+    data,
+    included
+  } = jsonApiDoc;
+  if (data === null) {
+    return;
+  }
+  if (typeof jsonApiDoc.data !== 'object') {
+    throw new Error(`Expected a resource object in the 'data' property in the document provided to the cache, but was ${typeof jsonApiDoc.data}`);
+  }
+  if (Array.isArray(data)) {
+    for (const resource of data) {
+      validateResourceFields(schema, resource, {
+        verifyIncluded: true,
+        included
+      });
+    }
+  } else {
+    validateResourceFields(schema, data, {
+      verifyIncluded: true,
+      included
+    });
+  }
+  if (included) {
+    for (const resource of included) {
+      validateResourceFields(schema, resource, {
+        verifyIncluded: false
+      });
+    }
+  }
+}
+function validateResourceFields(schema, resource, options) {
+  if (!resource.relationships) {
+    return;
+  }
+  const resourceType = resource.type;
+  const fields = schema.fields({
+    type: resource.type
+  });
+  for (const [type, relationshipDoc] of Object.entries(resource.relationships)) {
+    const field = fields.get(type);
+    if (!field) {
+      return;
+    }
+    switch (field.kind) {
+      case 'belongsTo':
+        {
+          if (field.options.linksMode) {
+            validateBelongsToLinksMode(resourceType, field, relationshipDoc, options);
+          }
+          break;
+        }
+      case 'hasMany':
+        {
+          if (field.options.linksMode) {
+            validateHasManyToLinksMode(resourceType, field);
+          }
+          break;
+        }
+    }
+  }
+}
+function validateBelongsToLinksMode(resourceType, field, relationshipDoc, options) {
+  if (field.options.async) {
+    throw new Error(`Cannot fetch ${resourceType}.${field.name} because the field is in linksMode but async is not yet supported`);
+  }
+  if (!relationshipDoc.links?.related) {
+    throw new Error(`Cannot fetch ${resourceType}.${field.name} because the field is in linksMode but the related link is missing`);
+  }
+  const relationshipData = relationshipDoc.data;
+  if (Array.isArray(relationshipData)) {
+    throw new Error(`Cannot fetch ${resourceType}.${field.name} because the relationship data for a belongsTo relationship is unexpectedly an array`);
+  }
+  // Explicitly allow `null`! Missing key or `undefined` are always invalid.
+  if (relationshipData === undefined) {
+    throw new Error(`Cannot fetch ${resourceType}.${field.name} because the field is in linksMode but the relationship data is undefined`);
+  }
+  if (relationshipData === null) {
+    return;
+  }
+  if (!options.verifyIncluded) {
+    return;
+  }
+  const includedDoc = options.included?.find(doc => doc.type === relationshipData.type && doc.id === relationshipData.id);
+  if (!includedDoc) {
+    throw new Error(`Cannot fetch ${resourceType}.${field.name} because the field is in linksMode but the related data is not included`);
+  }
+}
+function validateHasManyToLinksMode(resourceType, field, _relationshipDoc, _options) {
+  if (field.options.async) {
+    throw new Error(`Cannot fetch ${resourceType}.${field.name} because the field is in linksMode but async hasMany is not yet supported`);
+  }
+}
+
+function inspectType(obj) {
+  if (obj === null) {
+    return 'null';
+  }
+  if (Array.isArray(obj)) {
+    return 'array';
+  }
+  if (typeof obj === 'object') {
+    const proto = Object.getPrototypeOf(obj);
+    if (proto === null) {
+      return 'object';
+    }
+    if (proto === Object.prototype) {
+      return 'object';
+    }
+    return `object (${proto.constructor?.name})`;
+  }
+  if (typeof obj === 'function') {
+    return 'function';
+  }
+  if (typeof obj === 'string') {
+    return 'string';
+  }
+  if (typeof obj === 'number') {
+    return 'number';
+  }
+  if (typeof obj === 'boolean') {
+    return 'boolean';
+  }
+  if (typeof obj === 'symbol') {
+    return 'symbol';
+  }
+  if (typeof obj === 'bigint') {
+    return 'bigint';
+  }
+  if (typeof obj === 'undefined') {
+    return 'undefined';
+  }
+  return 'unknown';
+}
+function isSimpleObject(obj) {
+  if (obj === null) {
+    return false;
+  }
+  if (Array.isArray(obj)) {
+    return false;
+  }
+  if (typeof obj !== 'object') {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto === null) {
+    return true;
+  }
+  if (proto === Object.prototype) {
+    return true;
+  }
+  return false;
+}
+const RELATIONSHIP_FIELD_KINDS = ['belongsTo', 'hasMany', 'resource', 'collection'];
+class Reporter {
+  capabilities;
+  contextDocument;
+  errors = [];
+  ast;
+  jsonStr;
+
+  // TODO @runspired make this configurable to consuming apps before
+  // activating by default
+  strict = {
+    linkage: true,
+    unknownType: true,
+    unknownAttribute: true,
+    unknownRelationship: true
+  };
+  constructor(capabilities, doc) {
+    this.capabilities = capabilities;
+    this.contextDocument = doc;
+    this.jsonStr = JSON.stringify(doc.content, null, 2);
+    this.ast = jsonToAst(this.jsonStr, {
+      loc: true
+    });
+  }
+  searchTypes(type) {
+    if (!this._typeFilter) {
+      const allTypes = this.schema.resourceTypes();
+      this._typeFilter = new Fuse(allTypes);
+    }
+    const result = this._typeFilter.search(type);
+    return result;
+  }
+  _fieldFilters = new Map();
+  searchFields(type, field) {
+    if (!this._fieldFilters.has(type)) {
+      const allFields = this.schema.fields({
+        type
+      });
+      const allCacheFields = this.schema.cacheFields?.({
+        type
+      }) ?? allFields;
+      const attrs = Array.from(allCacheFields.values()).filter(isRemoteField).map(v => v.name);
+      this._fieldFilters.set(type, new Fuse(attrs));
+    }
+    const result = this._fieldFilters.get(type).search(field);
+    return result;
+  }
+  get schema() {
+    return this.capabilities.schema;
+  }
+  getLocation(path, kind) {
+    if (path.length === 0) {
+      return this.ast.loc;
+    }
+    let priorNode = this.ast;
+    let node = this.ast;
+    for (const segment of path) {
+      //
+      // handle array paths
+      //
+      if (typeof segment === 'number') {
+        macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+          if (!test) {
+            throw new Error(`Because the segment is a number, expected a node of type Array`);
+          }
+        })(node.type === 'Array') : {};
+        if (node.children && node.children[segment]) {
+          priorNode = node;
+          const childNode = node.children[segment];
+          if (childNode.type === 'Object' || childNode.type === 'Array') {
+            node = childNode;
+          } else {
+            // set to the closest node we can find
+            return node.loc;
+          }
+        } else {
+          // set to the closest node we can find
+          // as we had no children
+          return priorNode.loc;
+        }
+
+        //
+        // handle object paths
+        //
+      } else {
+        macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+          if (!test) {
+            throw new Error(`Because the segment is a string, expected a node of type Object`);
+          }
+        })(node.type === 'Object') : {};
+        const child = node.children.find(childCandidate => {
+          if (childCandidate.type === 'Property') {
+            return childCandidate.key.type === 'Identifier' && childCandidate.key.value === segment;
+          }
+          return false;
+        });
+        if (child) {
+          if (child.value.type === 'Object' || child.value.type === 'Array') {
+            priorNode = node;
+            node = child.value;
+          } else {
+            // set to the closest node we can find
+            return kind === 'key' ? child.key.loc : child.value.loc;
+          }
+        } else {
+          // set to the closest node we can find
+          return priorNode.loc;
+        }
+      }
+    }
+    return node.loc;
+  }
+  error(path, message, kind = 'key') {
+    const loc = this.getLocation(path, kind);
+    this.errors.push({
+      path,
+      message,
+      loc,
+      type: 'error',
+      kind
+    });
+  }
+  warn(path, message, kind = 'key') {
+    const loc = this.getLocation(path, kind);
+    this.errors.push({
+      path,
+      message,
+      loc,
+      type: 'warning',
+      kind
+    });
+  }
+  info(path, message, kind = 'key') {
+    const loc = this.getLocation(path, kind);
+    this.errors.push({
+      path,
+      message,
+      loc,
+      type: 'info',
+      kind
+    });
+  }
+  hasExtension(extensionName) {
+    return REGISTERED_EXTENSIONS.has(extensionName);
+  }
+  getExtension(extensionName) {
+    return REGISTERED_EXTENSIONS.get(extensionName);
+  }
+  report(colorize = true) {
+    const lines = this.jsonStr.split('\n');
+
+    // sort the errors by line, then by column, then by type
+    const {
+      errors
+    } = this;
+    if (!errors.length) {
+      return;
+    }
+    errors.sort((a, b) => {
+      return a.loc.end.line < b.loc.end.line ? -1 : a.loc.end.column < b.loc.end.column ? -1 : compareType(a.type, b.type);
+    });
+
+    // store the errors in a map by line
+    const errorMap = new Map();
+    for (const error of errors) {
+      const line = error.loc.end.line;
+      if (!errorMap.has(line)) {
+        errorMap.set(line, []);
+      }
+      errorMap.get(line).push(error);
+    }
+
+    // splice the errors into the lines
+    const errorLines = [];
+    const colors = [];
+    const counts = {
+      error: 0,
+      warning: 0,
+      info: 0
+    };
+    const LINE_SIZE = String(lines.length).length;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      errorLines.push(colorize ? `${String(i + 1).padEnd(LINE_SIZE, ' ')}  \t%c${line}%c` : `${String(i + 1).padEnd(LINE_SIZE, ' ')}  \t${line}`);
+      colors.push(`color: grey; background-color: transparent;`,
+      // first color sets color
+      `color: inherit; background-color: transparent;` // second color resets the color profile
+      );
+      if (errorMap.has(i + 1)) {
+        const errorsForLine = errorMap.get(i + 1);
+        for (const error of errorsForLine) {
+          counts[error.type]++;
+          const {
+            loc,
+            message
+          } = error;
+          const start = loc.end.line === loc.start.line ? loc.start.column - 1 : loc.end.column - 1;
+          const end = loc.end.column - 1;
+          const symbol = error.type === 'error' ? '❌' : error.type === 'warning' ? '⚠️' : 'ℹ️';
+          const errorLine = colorize ? `${''.padStart(LINE_SIZE, ' ') + symbol}\t${' '.repeat(start)}%c^${'~'.repeat(end - start)} %c//%c ${message}%c` : `${''.padStart(LINE_SIZE, ' ') + symbol}\t${' '.repeat(start)}^${'~'.repeat(end - start)} // ${message}`;
+          errorLines.push(errorLine);
+          colors.push(error.type === 'error' ? 'color: red;' : error.type === 'warning' ? 'color: orange;' : 'color: blue;', 'color: grey;', error.type === 'error' ? 'color: red;' : error.type === 'warning' ? 'color: orange;' : 'color: blue;', 'color: inherit; background-color: transparent;' // reset color
+          );
+        }
+      }
+    }
+    const contextStr = `${counts.error} errors and ${counts.warning} warnings found in the {json:api} document returned by ${this.contextDocument.request?.method} ${this.contextDocument.request?.url}`;
+    const errorString = contextStr + `\n\n` + errorLines.join('\n');
+
+    // eslint-disable-next-line no-console, @typescript-eslint/no-unused-expressions
+    colorize ? console.log(errorString, ...colors) : console.log(errorString);
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.features.JSON_API_CACHE_VALIDATION_ERRORS)) {
+      if (counts.error > 0) {
+        throw new Error(contextStr);
+      }
+    }
+  }
+}
+
+// we always want to sort errors first, then warnings, then info
+function compareType(a, b) {
+  if (a === b) {
+    return 0;
+  }
+  if (a === 'error') {
+    return -1;
+  }
+  if (b === 'error') {
+    return 1;
+  }
+  if (a === 'warning') {
+    return -1;
+  }
+  if (b === 'warning') {
+    return 1;
+  }
+  return 0;
+}
+const REGISTERED_EXTENSIONS = new Map();
+function isMetaDocument(doc) {
+  return !(doc instanceof Error) && doc.content && !('data' in doc.content) && !('included' in doc.content) && 'meta' in doc.content;
+}
+function isErrorDocument(doc) {
+  return doc instanceof Error;
+}
+function isPushedDocument(doc) {
+  return !!doc && typeof doc === 'object' && 'content' in doc && !('request' in doc) && !('response' in doc);
+}
+function logPotentialMatches(matches, kind) {
+  if (matches.length === 0) {
+    return '';
+  }
+  if (matches.length === 1) {
+    return `  Did you mean this available ${kind} "${matches[0].item}"?`;
+  }
+  const potentialMatches = matches.map(match => match.item).join('", "');
+  return `  Did you mean one of these available ${kind}s: "${potentialMatches}"?`;
+}
+function isRemoteField(v) {
+  return !(v.kind === '@local' || v.kind === 'alias' || v.kind === 'derived');
+}
+function getRemoteField(fields, key) {
+  const field = fields.get(key);
+  if (!field) {
+    return undefined;
+  }
+  if (!isRemoteField(field)) {
+    return undefined;
+  }
+  return field;
+}
+
+const VALID_TOP_LEVEL_MEMBERS = ['data', 'included', 'meta', 'jsonapi', 'links'];
+
+/**
+ * Reports issues which violate the JSON:API spec for top-level members.
+ *
+ * Version: 1.1
+ * Section: 7.1
+ * Link: https://jsonapi.org/format/#document-top-level
+ *
+ * @internal
+ */
+function validateTopLevelDocumentMembers(reporter, doc) {
+  const keys = Object.keys(doc);
+  for (const key of keys) {
+    if (!VALID_TOP_LEVEL_MEMBERS.includes(key)) {
+      if (key.includes(':')) {
+        // TODO @runspired expose the API to enable folks to add validation for their own extensions
+        const extensionName = key.split(':')[0];
+        if (reporter.hasExtension(extensionName)) {
+          const extension = reporter.getExtension(extensionName);
+          extension(reporter, [key]);
+        } else {
+          reporter.warn([key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} member`);
+        }
+      } else {
+        reporter.error([key], `Unrecognized top-level member. The data it provides is ignored as it is not a valid {json:api} member`);
+      }
+    }
+  }
+
+  // additional rules for top-level members
+  // ======================================
+
+  // 1. MUST have either `data`, `errors`, or `meta`
+  if (!('data' in doc) && !('errors' in doc) && !('meta' in doc)) {
+    reporter.error([], 'A {json:api} Document must contain one-of `data` `errors` or `meta`');
+  }
+
+  // 2. MUST NOT have both `data` and `errors`
+  if ('data' in doc && 'errors' in doc) {
+    reporter.error(['data'], 'A {json:api} Document MUST NOT contain both `data` and `errors` members');
+  }
+
+  // 3. MUST NOT have both `included` and `errors`
+  // while not explicitly stated in the spec, this is a logical extension of the above rule
+  // since `included` is only valid when `data` is present.
+  if ('included' in doc && 'errors' in doc) {
+    reporter.error(['included'], 'A {json:api} Document MUST NOT contain both `included` and `errors` members');
+  }
+
+  // 4. MUST NOT have `included` if `data` is not present
+  if ('included' in doc && !('data' in doc)) {
+    reporter.error(['included'], 'A {json:api} Document MUST NOT contain `included` if `data` is not present');
+  }
+
+  // 5. MUST NOT have `included` if `data` is null
+  // when strictly enforcing full linkage, we need to ensure that `included` is not present if `data` is null
+  // however, most APIs will ignore this rule for DELETE requests, so unless strict linkage is enabled, we will only warn
+  // about this issue.
+  if ('included' in doc && doc.data === null) {
+    const isMaybeDelete = reporter.contextDocument.request?.method?.toUpperCase() === 'DELETE' || reporter.contextDocument.request?.op === 'deleteRecord';
+    const method = !reporter.strict.linkage && isMaybeDelete ? 'warn' : 'error';
+    reporter[method](['included'], 'A {json:api} Document MUST NOT contain `included` if `data` is null');
+  }
+
+  // Simple Validation of Top-Level Members
+  // ==========================================
+  // 1. `data` MUST be a single resource object or an array of resource objects or `null`
+  if ('data' in doc) {
+    const dataMemberHasAppropriateForm = doc.data === null || Array.isArray(doc.data) || isSimpleObject(doc.data);
+    if (!dataMemberHasAppropriateForm) {
+      reporter.error(['data'], `The 'data' member MUST be a single resource object or an array of resource objects or null. Received data of type "${inspectType(doc.data)}"`);
+    }
+  }
+
+  // 2. `included` MUST be an array of resource objects
+  if ('included' in doc) {
+    if (!Array.isArray(doc.included)) {
+      reporter.error(['included'], `The 'included' member MUST be an array of resource objects. Received data of type "${inspectType(doc.included)}"`);
+    }
+  }
+
+  // 3. `meta` MUST be a simple object
+  if ('meta' in doc) {
+    if (!isSimpleObject(doc.meta)) {
+      reporter.error(['meta'], `The 'meta' member MUST be a simple object. Received data of type "${inspectType(doc.meta)}"`);
+    }
+  }
+
+  // 4. `jsonapi` MUST be a simple object
+  if ('jsonapi' in doc) {
+    if (!isSimpleObject(doc.jsonapi)) {
+      reporter.error(['jsonapi'], `The 'jsonapi' member MUST be a simple object. Received data of type "${inspectType(doc.jsonapi)}"`);
+    }
+  }
+
+  // 5. `links` MUST be a simple object
+  if ('links' in doc) {
+    if (!isSimpleObject(doc.links)) {
+      reporter.error(['links'], `The 'links' member MUST be a simple object. Received data of type "${inspectType(doc.links)}"`);
+    }
+  }
+
+  // 6. `errors` MUST be an array of error objects
+  if ('errors' in doc) {
+    if (!Array.isArray(doc.errors)) {
+      reporter.error(['errors'], `The 'errors' member MUST be an array of error objects. Received data of type "${inspectType(doc.errors)}"`);
+    }
+  }
+}
+
+const VALID_COLLECTION_LINKS = ['self', 'related', 'first', 'last', 'prev', 'next'];
+const VALID_RESOURCE_RELATIONSHIP_LINKS = ['self', 'related'];
+const VALID_RESOURCE_LINKS = ['self'];
+
+/**
+ * Validates the links object in a top-level JSON API document or resource object
+ *
+ * Version: 1.1
+ *
+ * Section: 7.1 Top Level
+ * Link: https://jsonapi.org/format/#document-top-level
+ *
+ * Section: 7.2.3 Resource Objects
+ * Link: https://jsonapi.org/format/#document-resource-object-links
+ *
+ * Section: 7.2.2.2 Resource Relationships
+ * Link: https://jsonapi.org/format/#document-resource-object-relationships
+ *
+ * Section: 7.6 Document Links
+ * Link: https://jsonapi.org/format/#document-links
+ *
+ * @internal
+ */
+function validateLinks(reporter, doc, type, path = ['links']) {
+  if (!('links' in doc)) {
+    return;
+  }
+  if (!isSimpleObject(doc.links)) {
+    // this is a violation but we report it when validating section 7.1
+    return;
+  }
+
+  // prettier-ignore
+  const VALID_TOP_LEVEL_LINKS = type === 'collection-document' || type === 'collection-relationship' ? VALID_COLLECTION_LINKS : type === 'resource-document' || type === 'resource-relationship' ? VALID_RESOURCE_RELATIONSHIP_LINKS : type === 'resource' ? VALID_RESOURCE_LINKS : [];
+  const links = doc.links;
+  const keys = Object.keys(links);
+  for (const key of keys) {
+    if (!VALID_TOP_LEVEL_LINKS.includes(key)) {
+      reporter.warn([...path, key], `Unrecognized top-level link. The data it provides may be ignored as it is not a valid {json:api} link for a ${type}`);
+    }
+    // links may be either a string or an object with an href property or null
+    if (links[key] === null) ; else if (typeof links[key] === 'string') {
+      if (links[key].length === 0) {
+        reporter.warn([...path, key], `Expected a non-empty string, but received an empty string`);
+      }
+      // valid, though we should potentially validate the URL here
+    } else if (isSimpleObject(links[key])) {
+      if ('href' in links[key]) {
+        const linksKeys = Object.keys(links[key]);
+        if (linksKeys.length > 1) {
+          reporter.warn([...path, key], `Expected the links object to only have an href property, but received unknown keys ${linksKeys.filter(k => k !== 'href').join(', ')}`);
+        }
+        if (typeof links[key].href !== 'string') {
+          reporter.error([...path, key, 'href'], `Expected a string value, but received ${inspectType(links[key].href)}`);
+        } else {
+          if (links[key].href.length === 0) {
+            reporter.warn([...path, key, 'href'], `Expected a non-empty string, but received an empty string`);
+          }
+          // valid, though we should potentially validate the URL here
+        }
+      } else {
+        const linksKeys = Object.keys(links[key]);
+        if (linksKeys.length > 0) {
+          reporter.error([...path, key], `Expected the links object to have an href property, but received only the unknown keys ${linksKeys.join(', ')}`);
+        } else {
+          reporter.error([...path, key], `Expected the links object to have an href property`);
+        }
+      }
+    } else {
+      // invalid
+      reporter.error([...path, key], `Expected a string, null, or an object with an href property for the link "${key}", but received ${inspectType(links[key])}`);
+    }
+  }
+}
+
+const SINGULAR_OPS = ['createRecord', 'updateRecord', 'deleteRecord', 'findRecord', 'queryRecord'];
+
+/**
+ * Validates the resource objects in either the `data` or `included` members of
+ * JSON:API document.
+ *
+ * Version: 1.1
+ * Section: 7.2
+ * Link: https://jsonapi.org/format/#document-resource-objects
+ *
+ * @internal
+ */
+function validateDocumentResources(reporter, doc) {
+  if ('data' in doc) {
+    // scan for common mistakes of single vs multiple resource objects
+    const op = reporter.contextDocument.request?.op;
+    if (op && SINGULAR_OPS.includes(op)) {
+      if (Array.isArray(doc.data)) {
+        reporter.error(['data'], `"${op}" requests expect a single resource object in the returned data, but received an array`);
+      }
+    }
+
+    // guard for a common mistake around deleteRecord
+    if (op === 'deleteRecord') {
+      if (doc.data !== null) {
+        reporter.warn(['data'], `"deleteRecord" requests expect the data member to be null, but received ${inspectType(doc.data)}. This can sometimes cause unexpected resurrection of the deleted record.`);
+      }
+    }
+    if (Array.isArray(doc.data)) {
+      doc.data.forEach((resource, index) => {
+        if (!isSimpleObject(resource)) {
+          reporter.error(['data', index], `Expected a resource object, but received ${inspectType(resource)}`);
+        } else {
+          validateResourceObject(reporter, resource, ['data', index]);
+        }
+      });
+    } else if (doc.data !== null) {
+      if (!isSimpleObject(doc.data)) {
+        reporter.error(['data'], `Expected a resource object, but received ${inspectType(doc.data)}`);
+      } else {
+        validateResourceObject(reporter, doc.data, ['data']);
+      }
+    }
+  }
+  if ('included' in doc && Array.isArray(doc.included)) {
+    doc.included.forEach((resource, index) => {
+      if (!isSimpleObject(resource)) {
+        reporter.error(['included', index], `Expected a resource object, but received ${inspectType(resource)}`);
+      } else {
+        validateResourceObject(reporter, resource, ['included', index]);
+      }
+    });
+  }
+}
+function validateResourceObject(reporter, resource, path) {
+  validateTopLevelResourceShape(reporter, resource, path);
+}
+const VALID_TOP_LEVEL_RESOURCE_KEYS = ['lid', 'id', 'type', 'attributes', 'relationships', 'meta', 'links'];
+function validateTopLevelResourceShape(reporter, resource, path) {
+  // a resource MUST have a string type
+  if (!('type' in resource)) {
+    reporter.error([...path, 'type'], `Expected a ResourceObject to have a type property`);
+  } else if (typeof resource.type !== 'string') {
+    reporter.error([...path, 'type'], `Expected a string value for the type property, but received ${inspectType(resource.type)}`, 'value');
+  } else if (resource.type.length === 0) {
+    reporter.error([...path, 'type'], `Expected a non-empty string value for the type property, but received an empty string`, 'value');
+  } else if (!reporter.schema.hasResource({
+    type: resource.type
+  })) {
+    const method = reporter.strict.unknownType ? 'error' : 'warn';
+    const potentialTypes = reporter.searchTypes(resource.type);
+    reporter[method]([...path, 'type'], `Expected a schema to be available for the ResourceType "${resource.type}" but none was found.${logPotentialMatches(potentialTypes, 'ResourceType')}`, 'value');
+  }
+
+  // a resource MUST have a string ID
+  if (!('id' in resource)) {
+    reporter.error([...path, 'id'], `Expected a ResourceObject to have an id property`);
+  } else if (typeof resource.id !== 'string') {
+    reporter.error([...path, 'id'], `Expected a string value for the id property, but received ${inspectType(resource.id)}`, 'value');
+  } else if (resource.id.length === 0) {
+    reporter.error([...path, 'id'], `Expected a non-empty string value for the id property, but received an empty string`, 'value');
+  }
+
+  // a resource MAY have a lid property
+  if ('lid' in resource && typeof resource.lid !== 'string') {
+    reporter.error([...path, 'lid'], `Expected a string value for the lid property, but received ${inspectType(resource.lid)}`, 'value');
+  }
+
+  // a resource MAY have a meta property
+  if ('meta' in resource && !isSimpleObject(resource.meta)) {
+    reporter.error([...path, 'meta'], `Expected a simple object for the meta property, but received ${inspectType(resource.meta)}`, 'value');
+  }
+
+  // a resource MAY have a links property
+  if ('links' in resource && !isSimpleObject(resource.links)) {
+    reporter.error([...path, 'links'], `Expected a simple object for the links property, but received ${inspectType(resource.links)}`, 'value');
+  } else if ('links' in resource) {
+    validateLinks(reporter, resource, 'resource', [...path, 'links']);
+  }
+  const hasAttributes = 'attributes' in resource && isSimpleObject(resource.attributes);
+  const hasRelationships = 'relationships' in resource && isSimpleObject(resource.relationships);
+
+  // We expect at least one of attributes or relationships to be present
+  if (!hasAttributes && !hasRelationships) {
+    reporter.warn(path, `Expected a ResourceObject to have either attributes or relationships`);
+  }
+
+  // we expect at least one of attributes or relationships to be non-empty
+  const attributesLength = hasAttributes ? Object.keys(resource.attributes).length : 0;
+  const relationshipsLength = hasRelationships ? Object.keys(resource.relationships).length : 0;
+  if ((hasAttributes || hasRelationships) && attributesLength === 0 && relationshipsLength === 0) {
+    reporter.warn([...path, hasAttributes ? 'attributes' : hasRelationships ? 'relationships' : 'attributes'], `Expected a ResourceObject to have either non-empty attributes or non-empty relationships`);
+  }
+
+  // check for unknown keys on the resource object
+  const keys = Object.keys(resource);
+  for (const key of keys) {
+    if (!VALID_TOP_LEVEL_RESOURCE_KEYS.includes(key)) {
+      // check for extension keys
+      if (key.includes(':')) {
+        const extensionName = key.split(':')[0];
+        if (reporter.hasExtension(extensionName)) {
+          const extension = reporter.getExtension(extensionName);
+          extension(reporter, [...path, key]);
+        } else {
+          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} ResourceObject member`);
+        }
+      } else {
+        // check if this is an attribute or relationship
+        let didYouMean = '  Likely this field should have been inside of either "attributes" or "relationships"';
+        const type = 'type' in resource ? resource.type : undefined;
+        if (type && reporter.schema.hasResource({
+          type
+        })) {
+          const fields = reporter.schema.fields({
+            type
+          });
+          const field = getRemoteField(fields, key);
+          if (field) {
+            const isRelationship = RELATIONSHIP_FIELD_KINDS.includes(field.kind);
+            didYouMean = `  Based on the ResourceSchema for "${type}" this field is likely a ${field.kind} and belongs inside of ${isRelationship ? 'relationships' : 'attributes'}, e.g. "${isRelationship ? 'relationships' : 'attributes'}": { "${key}": { ... } }`;
+          } else {
+            const fieldMatches = reporter.searchFields(type, key);
+            if (fieldMatches.length === 1) {
+              const matchedField = fields.get(fieldMatches[0].item);
+              const isRelationship = RELATIONSHIP_FIELD_KINDS.includes(matchedField.kind);
+              didYouMean = `  Based on the ResourceSchema for "${type}" this field is likely a ${matchedField.kind} and belongs inside of ${isRelationship ? 'relationships' : 'attributes'}, e.g. "${isRelationship ? 'relationships' : 'attributes'}": { "${matchedField.name}": { ... } }`;
+            } else if (fieldMatches.length > 1) {
+              const matchedField = fields.get(fieldMatches[0].item);
+              const isRelationship = RELATIONSHIP_FIELD_KINDS.includes(matchedField.kind);
+              didYouMean = `  Based on the ResourceSchema for "${type}" this field is likely one of "${fieldMatches.map(v => v.item).join('", "')}" and belongs inside of either "attributes" or "relationships", e.g. "${isRelationship ? 'relationships' : 'attributes'}": { "${matchedField.name}": { ... } }`;
+            }
+          }
+        }
+        reporter.error([...path, key], `Unrecognized ResourceObject member. The data it provides is ignored as it is not a valid {json:api} ResourceObject member.${didYouMean}`);
+      }
+    }
+  }
+
+  // if we have a schema, validate the individual attributes and relationships
+  const type = 'type' in resource ? resource.type : undefined;
+  if (type && reporter.schema.hasResource({
+    type
+  })) {
+    if ('attributes' in resource) {
+      validateResourceAttributes(reporter, type, resource.attributes, [...path, 'attributes']);
+    }
+    if ('relationships' in resource) {
+      validateResourceRelationships(reporter, type, resource.relationships, [...path, 'relationships']);
+    }
+  }
+}
+function validateResourceAttributes(reporter, type, resource, path) {
+  const fields = reporter.schema.fields({
+    type
+  });
+  const cacheFields = reporter.schema.cacheFields?.({
+    type
+  }) ?? fields;
+  for (const [key] of Object.entries(resource)) {
+    const field = getRemoteField(cacheFields, key);
+    const actualField = cacheFields.get(key);
+    if (!field && actualField) {
+      reporter.warn([...path, key], `Expected the ${actualField.kind} field "${key}" to not have its own data in the ResourceObject's attributes. Likely this field should either not be returned in this payload or the field definition should be updated in the schema.`);
+    } else if (!field) {
+      if (key.includes(':')) {
+        const extensionName = key.split(':')[0];
+        if (reporter.hasExtension(extensionName)) {
+          const extension = reporter.getExtension(extensionName);
+          extension(reporter, [...path, key]);
+        } else {
+          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} ResourceObject member`);
+        }
+      } else {
+        const method = reporter.strict.unknownAttribute ? 'error' : 'warn';
+
+        // TODO @runspired when we check for fuzzy matches we can adjust the message to say
+        // whether the expected field is an attribute or a relationship
+        const potentialFields = reporter.searchFields(type, key);
+        reporter[method]([...path, key], `Unrecognized attribute. The data it provides is ignored as it is not part of the ResourceSchema for "${type}".${logPotentialMatches(potentialFields, 'field')}`);
+      }
+    } else if (field && RELATIONSHIP_FIELD_KINDS.includes(field.kind)) {
+      reporter.error([...path, key], `Expected the "${key}" field to be in "relationships" as it has kind "${field.kind}", but received data for it in "attributes".`);
+    }
+  }
+
+  // TODO @runspired we should also deep-validate the field value
+  // TODO @runspired we should validate that field values are valid JSON and not instances
+}
+function validateResourceRelationships(reporter, type, resource, path) {
+  const schema = reporter.schema.fields({
+    type
+  });
+  for (const [key] of Object.entries(resource)) {
+    const field = getRemoteField(schema, key);
+    const actualField = schema.get(key);
+    if (!field && actualField) {
+      reporter.warn([...path, key], `Expected the ${actualField.kind} field "${key}" to not have its own data in the ResourceObject's relationships. Likely this field should either not be returned in this payload or the field definition should be updated in the schema.`);
+    } else if (!field) {
+      if (key.includes(':')) {
+        const extensionName = key.split(':')[0];
+        if (reporter.hasExtension(extensionName)) {
+          const extension = reporter.getExtension(extensionName);
+          extension(reporter, [...path, key]);
+        } else {
+          reporter.warn([...path, key], `Unrecognized extension ${extensionName}. The data provided by "${key}" will be ignored as it is not a valid {json:api} ResourceObject member`);
+        }
+      } else {
+        const method = reporter.strict.unknownRelationship ? 'error' : 'warn';
+
+        // TODO @runspired when we check for fuzzy matches we can adjust the message to say
+        // whether the expected field is an attribute or a relationship
+        const potentialFields = reporter.searchFields(type, key);
+        reporter[method]([...path, key], `Unrecognized relationship. The data it provides is ignored as it is not part of the ResourceSchema for "${type}".${logPotentialMatches(potentialFields, 'field')}`);
+      }
+    } else if (field && !RELATIONSHIP_FIELD_KINDS.includes(field.kind)) {
+      reporter.error([...path, key], `Expected the "${key}" field to be in "attributes" as it has kind "${field.kind}", but received data for it in "relationships".`);
+    }
+  }
+
+  // TODO @runspired we should also deep-validate the relationship payload
+  // TODO @runspired we should validate linksMode requirements for both Polaris and Legacy modes
+  // TODO @runspired we should warn if the discovered resource-type in a relationship is the abstract
+  //   type instead of the concrete type.
+}
+
+function validateDocument(capabilities, doc) {
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected a JSON:API Document as the content provided to the cache, received ${typeof doc.content}`);
+    }
+  })(doc instanceof Error || typeof doc.content === 'object' && doc.content !== null) : {};
+
+  // if the feature is not active and the payloads are not being logged
+  // we don't need to validate the payloads
+  if (macroCondition(!getGlobalConfig().WarpDriveMirror.features.JSON_API_CACHE_VALIDATION_ERRORS)) {
+    if (macroCondition(!getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+      if (!(getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE)) {
+        return;
+      }
+    }
+  }
+  if (macroCondition(!getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+    if (!(getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE)) {
+      if (macroCondition(!getGlobalConfig().WarpDriveMirror.features.JSON_API_CACHE_VALIDATION_ERRORS)) {
+        return;
+      }
+    }
+  }
+  if (isErrorDocument(doc)) {
+    return; // return validateErrorDocument(reporter, doc);
+  } else if (isMetaDocument(doc)) {
+    return; // return validateMetaDocument(reporter, doc);
+  } else if (isPushedDocument(doc)) {
+    return; // return validatePushedDocument(reporter, doc);
+  }
+  const reporter = new Reporter(capabilities, doc);
+  return validateResourceDocument(reporter, doc);
+}
+
+// function validateErrorDocument(reporter: Reporter, doc: StructuredErrorDocument) {}
+
+// function validateMetaDocument(reporter: Reporter, doc: StructuredDataDocument<ResourceMetaDocument>) {}
+
+// function validatePushedDocument(reporter: Reporter, doc: StructuredDataDocument<ResourceDocument>) {}
+
+function validateResourceDocument(reporter, doc) {
+  validateTopLevelDocumentMembers(reporter, doc.content);
+  validateLinks(reporter, doc.content, 'data' in doc.content && Array.isArray(doc.content?.data) ? 'collection-document' : 'resource-document');
+  validateDocumentResources(reporter, doc.content);
+
+  // TODO @runspired - validateMeta on document
+  // TODO @runspired - validateMeta on resource
+  // TODO @runspired - validateMeta on resource relationships
+  // TODO @runspired - validate no-meta on resource identifiers
+  //
+  // ---------------------------------
+  // super-strict-mode
+  //
+  // TODO @runspired - validate that all referenced resource identifiers are present in the document (full linkage)
+  // TODO @runspired - validate that all included resources have a path back to `data` (full linkage)
+  //
+  // ---------------------------------
+  // nice-to-haves
+  //
+  // TODO @runspired - validate links objects more thoroughly for spec props we don't use
+  // TODO @runspired - validate request includes are in fact included
+  // TODO @runspired - validate request fields are in fact present
+  // TODO @runspired - MAYBE validate request sort is in fact sorted? (useful for catching Mocking bugs)
+  // TODO @runspired - MAYBE validate request pagination is in fact paginated? (useful for catching Mocking bugs)
+
+  reporter.report();
+}
+
+function isImplicit(relationship) {
+  return relationship.definition.isImplicit;
+}
+const EMPTY_ITERATOR = {
+  iterator() {
+    return {
+      next() {
+        return {
+          done: true,
+          value: undefined
+        };
+      }
+    };
+  }
+};
+function makeCache() {
+  return {
+    id: null,
+    remoteAttrs: null,
+    localAttrs: null,
+    defaultAttrs: null,
+    inflightAttrs: null,
+    changes: null,
+    errors: null,
+    isNew: false,
+    isDeleted: false,
+    isDeletionCommitted: false
+  };
+}
+
+/**
+ * ```ts
+ * import { JSONAPICache } from '@warp-drive-mirror/json-api';
+ * ```
+ *
+ * A {@link Cache} implementation tuned for [{json:api}](https://jsonapi.org/)
+ *
+ * @categoryDescription Cache Management
+ * APIs for primary cache management functionality
+ * @categoryDescription Cache Forking
+ * APIs that support Cache Forking
+ * @categoryDescription SSR Support
+ * APIs that support SSR functionality
+ * @categoryDescription Resource Lifecycle
+ * APIs that support management of resource data
+ * @categoryDescription Resource Data
+ * APIs that support granular field level management of resource data
+ * @categoryDescription Resource State
+ * APIs that support managing Resource states
+ *
+ * @public
+ */
+class JSONAPICache {
+  /**
+   * The Cache Version that this implementation implements.
+   *
+   * @public
+   */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  constructor(capabilities) {
+    this.version = '2';
+    this._capabilities = capabilities;
+    this.__cache = new Map();
+    this.__graph = graphFor(capabilities);
+    this.__destroyedCache = new Map();
+    this.__documents = new Map();
+  }
+
+  ////////// ================ //////////
+  ////////// Cache Management //////////
+  ////////// ================ //////////
+
+  /**
+   * Cache the response to a request
+   *
+   * Implements `Cache.put`.
+   *
+   * Expects a StructuredDocument whose `content` member is a JsonApiDocument.
+   *
+   * ```js
+   * cache.put({
+   *   request: { url: 'https://api.example.com/v1/user/1' },
+   *   content: {
+   *     data: {
+   *       type: 'user',
+   *       id: '1',
+   *       attributes: {
+   *         name: 'Chris'
+   *       }
+   *     }
+   *   }
+   * })
+   * ```
+   *
+   * > **Note**
+   * > The nested `content` and `data` members are not a mistake. This is because
+   * > there are two separate concepts involved here, the `StructuredDocument` which contains
+   * > the context of a given Request that has been issued with the returned contents as its
+   * > `content` property, and a `JSON:API Document` which is the json contents returned by
+   * > this endpoint and which uses its `data` property to signify which resources are the
+   * > primary resources associated with the request.
+   *
+   * StructuredDocument's with urls will be cached as full documents with
+   * associated resource membership order and contents preserved but linked
+   * into the cache.
+   *
+   * @category Cache Management
+   * @public
+   */
+
+  put(doc) {
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+      validateDocument(this._capabilities, doc);
+    }
+    if (isErrorDocument(doc)) {
+      return this._putDocument(doc, undefined, undefined);
+    } else if (isMetaDocument(doc)) {
+      return this._putDocument(doc, undefined, undefined);
+    }
+    const jsonApiDoc = doc.content;
+    const included = jsonApiDoc.included;
+    let i, length;
+    const {
+      cacheKeyManager
+    } = this._capabilities;
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+      validateDocumentFields(this._capabilities.schema, jsonApiDoc);
+    }
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+        const Counts = new Map();
+        let totalCount = 0;
+        if (included) {
+          for (i = 0, length = included.length; i < length; i++) {
+            const type = included[i].type;
+            Counts.set(type, (Counts.get(type) || 0) + 1);
+            totalCount++;
+          }
+        }
+        if (Array.isArray(jsonApiDoc.data)) {
+          for (i = 0, length = jsonApiDoc.data.length; i < length; i++) {
+            const type = jsonApiDoc.data[i].type;
+            Counts.set(type, (Counts.get(type) || 0) + 1);
+            totalCount++;
+          }
+        } else if (jsonApiDoc.data) {
+          const type = jsonApiDoc.data.type;
+          Counts.set(type, (Counts.get(type) || 0) + 1);
+          totalCount++;
+        }
+        logGroup('cache', 'put', '<@document>', doc.content?.lid || doc.request?.url || 'unknown-request', `(${totalCount}) records`, '');
+        let str = `\tContent Counts:`;
+        Counts.forEach((count, type) => {
+          str += `\n\t\t${type}: ${count} record${count > 1 ? 's' : ''}`;
+        });
+        if (Counts.size === 0) {
+          str += `\t(empty)`;
+        }
+        // eslint-disable-next-line no-console
+        console.log(str);
+        // eslint-disable-next-line no-console
+        console.log({
+          lid: doc.content?.lid,
+          content: structuredClone(doc.content),
+          // we may need a specialized copy here
+          request: doc.request,
+          // structuredClone(doc.request),
+          response: doc.response // structuredClone(doc.response),
+        });
+        // eslint-disable-next-line no-console
+        console.groupEnd();
+      }
+    }
+    if (included) {
+      for (i = 0, length = included.length; i < length; i++) {
+        included[i] = putOne(this, cacheKeyManager, included[i]);
+      }
+    }
+    if (Array.isArray(jsonApiDoc.data)) {
+      length = jsonApiDoc.data.length;
+      const identifiers = [];
+      for (i = 0; i < length; i++) {
+        identifiers.push(putOne(this, cacheKeyManager, jsonApiDoc.data[i]));
+      }
+      return this._putDocument(doc, identifiers, included);
+    }
+    if (jsonApiDoc.data === null) {
+      return this._putDocument(doc, null, included);
+    }
+    const identifier = putOne(this, cacheKeyManager, jsonApiDoc.data);
+    return this._putDocument(doc, identifier, included);
+  }
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+  _putDocument(doc, data, included) {
+    // @ts-expect-error narrowing within is just horrible  in TS :/
+    const resourceDocument = isErrorDocument(doc) ? fromStructuredError(doc) : fromBaseDocument(doc);
+    if (data !== undefined) {
+      resourceDocument.data = data;
+    }
+    if (included !== undefined) {
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`There should not be included data on an Error document`);
+        }
+      })(!isErrorDocument(doc)) : {};
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`There should not be included data on a Meta document`);
+        }
+      })(!isMetaDocument(doc)) : {};
+      resourceDocument.included = included;
+    }
+    const request = doc.request;
+    const identifier = request ? this._capabilities.cacheKeyManager.getOrCreateDocumentIdentifier(request) : null;
+    if (identifier) {
+      resourceDocument.lid = identifier.lid;
+
+      // @ts-expect-error
+      doc.content = resourceDocument;
+      const hasExisting = this.__documents.has(identifier.lid);
+      this.__documents.set(identifier.lid, doc);
+      this._capabilities.notifyChange(identifier, hasExisting ? 'updated' : 'added', null);
+    }
+    if (doc.request?.op === 'findHasMany') {
+      const parentIdentifier = doc.request.options?.identifier;
+      const parentField = doc.request.options?.field;
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Expected a hasMany field`);
+        }
+      })(parentField?.kind === 'hasMany') : {};
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Expected a parent identifier for a findHasMany request`);
+        }
+      })(parentIdentifier && isResourceKey(parentIdentifier)) : {};
+      if (parentField && parentIdentifier) {
+        this.__graph.push({
+          op: 'updateRelationship',
+          record: parentIdentifier,
+          field: parentField.name,
+          value: resourceDocument
+        });
+      }
+    }
+    return resourceDocument;
+  }
+
+  /**
+   * Update the "remote" or "canonical" (persisted) state of the Cache
+   * by merging new information into the existing state.
+   *
+   * @category Cache Management
+   * @public
+   * @param op the operation or list of operations to perform
+   */
+  patch(op) {
+    if (Array.isArray(op)) {
+      if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+        if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+          logGroup('cache', 'patch', '<BATCH>', String(op.length) + ' operations', '', '');
+        }
+      }
+      assertPrivateCapabilities(this._capabilities);
+      this._capabilities._store._join(() => {
+        for (const operation of op) {
+          patchCache(this, operation);
+        }
+      });
+      if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+        if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+          // eslint-disable-next-line no-console
+          console.groupEnd();
+        }
+      }
+    } else {
+      patchCache(this, op);
+    }
+  }
+
+  /**
+   * Update the "local" or "current" (unpersisted) state of the Cache
+   *
+   * @category Cache Management
+   * @public
+   */
+  mutate(mutation) {
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+        logGroup('cache', 'mutate', mutation.record.type, mutation.record.lid, mutation.field, mutation.op);
+        try {
+          const _data = JSON.parse(JSON.stringify(mutation));
+          // eslint-disable-next-line no-console
+          console.log(_data);
+        } catch {
+          // eslint-disable-next-line no-console
+          console.log(mutation);
+        }
+      }
+    }
+    this.__graph.update(mutation, false);
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+        // eslint-disable-next-line no-console
+        console.groupEnd();
+      }
+    }
+  }
+
+  /**
+   * Peek resource data from the Cache.
+   *
+   * In development, if the return value
+   * is JSON the return value
+   * will be deep-cloned and deep-frozen
+   * to prevent mutation thereby enforcing cache
+   * Immutability.
+   *
+   * This form of peek is useful for implementations
+   * that want to feed raw-data from cache to the UI
+   * or which want to interact with a blob of data
+   * directly from the presentation cache.
+   *
+   * An implementation might want to do this because
+   * de-referencing records which read from their own
+   * blob is generally safer because the record does
+   * not require retainining connections to the Store
+   * and Cache to present data on a per-field basis.
+   *
+   * This generally takes the place of `getAttr` as
+   * an API and may even take the place of `getRelationship`
+   * depending on implementation specifics, though this
+   * latter usage is less recommended due to the advantages
+   * of the Graph handling necessary entanglements and
+   * notifications for relational data.
+   *
+   * @category Cache Management
+   * @public
+   */
+
+  peek(identifier) {
+    if (isResourceKey(identifier)) {
+      const peeked = this.__safePeek(identifier, false);
+      if (!peeked) {
+        return null;
+      }
+      const {
+        type,
+        id,
+        lid
+      } = identifier;
+      const attributes = structuredClone(Object.assign({}, peeked.remoteAttrs, peeked.inflightAttrs, peeked.localAttrs));
+      const relationships = {};
+      const rels = this.__graph.identifiers.get(identifier);
+      if (rels) {
+        Object.keys(rels).forEach(key => {
+          const rel = rels[key];
+          if (rel.definition.isImplicit) {
+            return;
+          } else {
+            relationships[key] = structuredClone(this.__graph.getData(identifier, key));
+          }
+        });
+      }
+      assertPrivateCapabilities(this._capabilities);
+      const store = this._capabilities._store;
+      const attrs = getCacheFields(this, identifier);
+      attrs.forEach((attr, key) => {
+        if (key in attributes && attributes[key] !== undefined) {
+          return;
+        }
+        const defaultValue = getDefaultValue(attr, identifier, store);
+        if (defaultValue !== undefined) {
+          attributes[key] = defaultValue;
+        }
+      });
+      return {
+        type,
+        id,
+        lid,
+        attributes,
+        relationships
+      };
+    }
+    const document = this.peekRequest(identifier);
+    if (document) {
+      if ('content' in document) return document.content;
+    }
+    return null;
+  }
+
+  /**
+   * Peek the remote resource data from the Cache.
+   *
+   * @category Cache Management
+   * @public
+   */
+
+  peekRemoteState(identifier) {
+    if (isResourceKey(identifier)) {
+      const peeked = this.__safePeek(identifier, false);
+      if (!peeked) {
+        return null;
+      }
+      const {
+        type,
+        id,
+        lid
+      } = identifier;
+      const attributes = structuredClone(peeked.remoteAttrs);
+      const relationships = {};
+      const rels = this.__graph.identifiers.get(identifier);
+      if (rels) {
+        Object.keys(rels).forEach(key => {
+          const rel = rels[key];
+          if (rel.definition.isImplicit) {
+            return;
+          } else {
+            relationships[key] = structuredClone(this.__graph.getData(identifier, key));
+          }
+        });
+      }
+      assertPrivateCapabilities(this._capabilities);
+      const store = this._capabilities._store;
+      const attrs = getCacheFields(this, identifier);
+      attrs.forEach((attr, key) => {
+        if (key in attributes && attributes[key] !== undefined) {
+          return;
+        }
+        const defaultValue = getDefaultValue(attr, identifier, store);
+        if (defaultValue !== undefined) {
+          attributes[key] = defaultValue;
+        }
+      });
+      return {
+        type,
+        id,
+        lid,
+        attributes,
+        relationships
+      };
+    }
+    const document = this.peekRequest(identifier);
+    if (document) {
+      if ('content' in document) return document.content;
+    }
+    return null;
+  }
+
+  /**
+   * Peek the Cache for the existing request data associated with
+   * a cacheable request.
+   *
+   * This is effectively the reverse of `put` for a request in
+   * that it will return the the request, response, and content
+   * whereas `peek` will return just the `content`.
+   *
+   * @category Cache Management
+   * @public
+   */
+  peekRequest(identifier) {
+    return this.__documents.get(identifier.lid) || null;
+  }
+
+  /**
+   * Push resource data from a remote source into the cache for this identifier
+   *
+   * @category Cache Management
+   * @public
+   * @return if `calculateChanges` is true then calculated key changes should be returned
+   */
+  upsert(identifier, data, calculateChanges) {
+    assertPrivateCapabilities(this._capabilities);
+    const store = this._capabilities._store;
+    if (!store._cbs) {
+      let result = undefined;
+      store._run(() => {
+        result = cacheUpsert(this, identifier, data, calculateChanges);
+      });
+      return result;
+    }
+    return cacheUpsert(this, identifier, data, calculateChanges);
+  }
+
+  ////////// ============= //////////
+  ////////// Cache Forking //////////
+  ////////// ============= //////////
+
+  /**
+   * Create a fork of the cache from the current state.
+   *
+   * Applications should typically not call this method themselves,
+   * preferring instead to fork at the Store level, which will
+   * utilize this method to fork the cache.
+   *
+   * @category Cache Forking
+   * @private
+   */
+  fork() {
+    throw new Error(`Not Implemented`);
+  }
+
+  /**
+   * Merge a fork back into a parent Cache.
+   *
+   * Applications should typically not call this method themselves,
+   * preferring instead to merge at the Store level, which will
+   * utilize this method to merge the caches.
+   *
+   * @category Cache Forking
+   * @private
+   */
+  merge(_cache) {
+    throw new Error(`Not Implemented`);
+  }
+
+  /**
+   * Generate the list of changes applied to all
+   * record in the store.
+   *
+   * Each individual resource or document that has
+   * been mutated should be described as an individual
+   * `Change` entry in the returned array.
+   *
+   * A `Change` is described by an object containing up to
+   * three properties: (1) the `identifier` of the entity that
+   * changed; (2) the `op` code of that change being one of
+   * `upsert` or `remove`, and if the op is `upsert` a `patch`
+   * containing the data to merge into the cache for the given
+   * entity.
+   *
+   * This `patch` is opaque to the Store but should be understood
+   * by the Cache and may expect to be utilized by an Adapter
+   * when generating data during a `save` operation.
+   *
+   * It is generally recommended that the `patch` contain only
+   * the updated state, ignoring fields that are unchanged
+   *
+   * ```ts
+   * interface Change {
+   *  identifier: ResourceKey | RequestKey;
+   *  op: 'upsert' | 'remove';
+   *  patch?: unknown;
+   * }
+   * ```
+   *
+   * @category Cache Forking
+   * @private
+   */
+  diff() {
+    throw new Error(`Not Implemented`);
+  }
+
+  ////////// =========== //////////
+  ////////// SSR Support //////////
+  ////////// =========== //////////
+
+  /**
+   * Serialize the entire contents of the Cache into a Stream
+   * which may be fed back into a new instance of the same Cache
+   * via `cache.hydrate`.
+   *
+   * @category SSR Support
+   * @private
+   */
+  dump() {
+    throw new Error(`Not Implemented`);
+  }
+
+  /**
+   * hydrate a Cache from a Stream with content previously serialized
+   * from another instance of the same Cache, resolving when hydration
+   * is complete.
+   *
+   * This method should expect to be called both in the context of restoring
+   * the Cache during application rehydration after SSR **AND** at unknown
+   * times during the lifetime of an already booted application when it is
+   * desired to bulk-load additional information into the cache. This latter
+   * behavior supports optimizing pre/fetching of data for route transitions
+   * via data-only SSR modes.
+   *
+   * @category SSR Support
+   * @private
+   */
+  hydrate(stream) {
+    throw new Error('Not Implemented');
+  }
+
+  ////////// ================== //////////
+  ////////// Resource Lifecycle //////////
+  ////////// ================== //////////
+
+  /**
+   * [LIFECYCLE] Signal to the cache that a new record has been instantiated on the client
+   *
+   * It returns properties from options that should be set on the record during the create
+   * process. This return value behavior is deprecated.
+   *
+   * @category Resource Lifecycle
+   * @public
+   */
+  clientDidCreate(identifier, options) {
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+        try {
+          const _data = options ? JSON.parse(JSON.stringify(options)) : options;
+          // eslint-disable-next-line no-console
+          console.log(`WarpDrive | Mutation - clientDidCreate ${identifier.lid}`, _data);
+        } catch {
+          // eslint-disable-next-line no-console
+          console.log(`WarpDrive | Mutation - clientDidCreate ${identifier.lid}`, options);
+        }
+      }
+    }
+    const cached = this._createCache(identifier);
+    cached.isNew = true;
+    const createOptions = {};
+    if (options !== undefined) {
+      const fields = getCacheFields(this, identifier);
+      const graph = this.__graph;
+      const propertyNames = Object.keys(options);
+      for (let i = 0; i < propertyNames.length; i++) {
+        const name = propertyNames[i];
+        const propertyValue = options[name];
+        if (name === 'id') {
+          continue;
+        }
+        const fieldType = fields.get(name);
+        const kind = fieldType !== undefined ? 'kind' in fieldType ? fieldType.kind : 'attribute' : null;
+        let relationship;
+        switch (kind) {
+          case 'attribute':
+            this.setAttr(identifier, name, propertyValue);
+            createOptions[name] = propertyValue;
+            break;
+          case 'belongsTo':
+            this.mutate({
+              op: 'replaceRelatedRecord',
+              field: name,
+              record: identifier,
+              value: propertyValue
+            });
+            relationship = graph.get(identifier, name);
+            relationship.state.hasReceivedData = true;
+            relationship.state.isEmpty = false;
+            break;
+          case 'hasMany':
+            this.mutate({
+              op: 'replaceRelatedRecords',
+              field: name,
+              record: identifier,
+              value: propertyValue
+            });
+            relationship = graph.get(identifier, name);
+            relationship.state.hasReceivedData = true;
+            relationship.state.isEmpty = false;
+            break;
+          default:
+            // reflect back (pass-thru) unknown properties
+            createOptions[name] = propertyValue;
+        }
+      }
+    }
+    this._capabilities.notifyChange(identifier, 'added', null);
+    return createOptions;
+  }
+
+  /**
+   * [LIFECYCLE] Signals to the cache that a resource
+   * will be part of a save transaction.
+   *
+   * @category Resource Lifecycle
+   * @public
+   */
+  willCommit(identifier, _context) {
+    if (Array.isArray(identifier)) {
+      for (const key of identifier) {
+        willCommit(this, key);
+      }
+    } else {
+      willCommit(this, identifier);
+    }
+  }
+
+  /**
+   * [LIFECYCLE] Signals to the cache that a resource
+   * was successfully updated as part of a save transaction.
+   *
+   * @category Resource Lifecycle
+   * @public
+   */
+
+  didCommit(committedIdentifier, result) {
+    const payload = result ? result.content : null;
+    const operation = result?.request?.op ?? null;
+    const data = payload && payload.data;
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+        try {
+          const payloadCopy = payload ? JSON.parse(JSON.stringify(payload)) : payload;
+          // eslint-disable-next-line no-console
+          console.log(`WarpDrive | Payload - ${operation}`, payloadCopy);
+        } catch {
+          // eslint-disable-next-line no-console
+          console.log(`WarpDrive | Payload - ${operation}`, payload);
+        }
+      }
+    }
+    const responseIsCollection = Array.isArray(data);
+    const hasMultipleIdentifiers = Array.isArray(committedIdentifier) && committedIdentifier.length > 1;
+    if (Array.isArray(committedIdentifier)) {
+      // if we get back an array of primary data, we treat each
+      // entry as a separate commit for each identifier
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Expected the array of primary data to match the array of committed identifiers`);
+        }
+      })(!hasMultipleIdentifiers || !responseIsCollection || data.length === committedIdentifier.length) : {};
+      if (responseIsCollection) {
+        for (let i = 0; i < committedIdentifier.length; i++) {
+          const identifier = committedIdentifier[i];
+          didCommit(this, identifier, data[i] ?? null, operation);
+        }
+        // but if we get back no data or a single entry, we apply
+        // the change back to the original identifier
+      } else {
+        for (let i = 0; i < committedIdentifier.length; i++) {
+          const identifier = committedIdentifier[i];
+          didCommit(this, identifier, i === 0 ? data : null, operation);
+        }
+      }
+    } else {
+      didCommit(this, committedIdentifier, data, operation);
+    }
+    const included = payload && payload.included;
+    const {
+      cacheKeyManager
+    } = this._capabilities;
+    if (included) {
+      for (let i = 0, length = included.length; i < length; i++) {
+        putOne(this, cacheKeyManager, included[i]);
+      }
+    }
+    return hasMultipleIdentifiers && responseIsCollection ? {
+      data: committedIdentifier
+    } : {
+      data: Array.isArray(committedIdentifier) ? committedIdentifier[0] : committedIdentifier
+    };
+  }
+
+  /**
+   * [LIFECYCLE] Signals to the cache that a resource
+   * was update via a save transaction failed.
+   *
+   * @category Resource Lifecycle
+   * @public
+   */
+  commitWasRejected(identifier, errors) {
+    if (Array.isArray(identifier)) {
+      for (let i = 0; i < identifier.length; i++) {
+        commitDidError(this, identifier[i], errors && i === 0 ? errors : null);
+      }
+      return;
+    }
+    return commitDidError(this, identifier, errors || null);
+  }
+
+  /**
+   * [LIFECYCLE] Signals to the cache that all data for a resource
+   * should be cleared.
+   *
+   * This method is a candidate to become a mutation
+   *
+   * @category Resource Lifecycle
+   * @public
+   */
+  unloadRecord(identifier) {
+    const storeWrapper = this._capabilities;
+    // TODO this is necessary because
+    // we maintain memebership inside InstanceCache
+    // for peekAll, so even though we haven't created
+    // any data we think this exists.
+    // TODO can we eliminate that membership now?
+    if (!this.__cache.has(identifier)) {
+      // the graph may still need to unload identity
+      peekGraph(storeWrapper)?.unload(identifier);
+      return;
+    }
+    const removeFromRecordArray = !this.isDeletionCommitted(identifier);
+    let removed = false;
+    const cached = this.__peek(identifier, false);
+    if (cached.isNew || cached.isDeletionCommitted) {
+      peekGraph(storeWrapper)?.push({
+        op: 'deleteRecord',
+        record: identifier,
+        isNew: cached.isNew
+      });
+    } else {
+      peekGraph(storeWrapper)?.unload(identifier);
+    }
+
+    // effectively clearing these is ensuring that
+    // we report as `isEmpty` during teardown.
+    cached.localAttrs = null;
+    cached.remoteAttrs = null;
+    cached.defaultAttrs = null;
+    cached.inflightAttrs = null;
+    const relatedIdentifiers = _allRelatedIdentifiers(storeWrapper, identifier);
+    if (areAllModelsUnloaded(storeWrapper, relatedIdentifiers)) {
+      for (let i = 0; i < relatedIdentifiers.length; ++i) {
+        const relatedIdentifier = relatedIdentifiers[i];
+        storeWrapper.notifyChange(relatedIdentifier, 'removed', null);
+        removed = true;
+        storeWrapper.disconnectRecord(relatedIdentifier);
+      }
+    }
+    this.__cache.delete(identifier);
+    this.__destroyedCache.set(identifier, cached);
+
+    /*
+     * The destroy cache is a hack to prevent applications
+     * from blowing up during teardown. Accessing state
+     * on a destroyed record is not safe, but historically
+     * was possible due to a combination of teardown timing
+     * and retention of cached state directly on the
+     * record itself.
+     *
+     * Once we have deprecated accessing state on a destroyed
+     * instance we may remove this. The timing isn't a huge deal
+     * as momentarily retaining the objects outside the bounds
+     * of a test won't cause issues.
+     */
+    if (this.__destroyedCache.size === 1) {
+      // TODO do we still need this?
+      setTimeout(() => {
+        this.__destroyedCache.clear();
+      }, 100);
+    }
+    if (!removed && removeFromRecordArray) {
+      storeWrapper.notifyChange(identifier, 'removed', null);
+    }
+  }
+
+  ////////// ============= //////////
+  ////////// Resource Data //////////
+  ////////// ============= //////////
+
+  /**
+   * Retrieve the data for an attribute from the cache
+   * with local mutations applied.
+   *
+   * @category Resource Data
+   * @public
+   */
+  getAttr(identifier, attr) {
+    const isSimplePath = !Array.isArray(attr) || attr.length === 1;
+    if (Array.isArray(attr) && attr.length === 1) {
+      attr = attr[0];
+    }
+    if (isSimplePath) {
+      const attribute = attr;
+      const cached = this.__peek(identifier, true);
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Cannot retrieve attributes for identifier ${String(identifier)} as it is not present in the cache`);
+        }
+      })(cached) : {};
+
+      // in Prod we try to recover when accessing something that
+      // doesn't exist
+      if (!cached) {
+        return undefined;
+      }
+      if (cached.localAttrs && attribute in cached.localAttrs) {
+        return cached.localAttrs[attribute];
+      } else if (cached.inflightAttrs && attribute in cached.inflightAttrs) {
+        return cached.inflightAttrs[attribute];
+      } else if (cached.remoteAttrs && attribute in cached.remoteAttrs) {
+        return cached.remoteAttrs[attribute];
+      } else if (cached.defaultAttrs && attribute in cached.defaultAttrs) {
+        return cached.defaultAttrs[attribute];
+      } else {
+        const attrSchema = getCacheFields(this, identifier).get(attribute);
+        assertPrivateCapabilities(this._capabilities);
+        const defaultValue = getDefaultValue(attrSchema, identifier, this._capabilities._store);
+        if (schemaHasLegacyDefaultValueFn(attrSchema)) {
+          cached.defaultAttrs = cached.defaultAttrs || Object.create(null);
+          cached.defaultAttrs[attribute] = defaultValue;
+        }
+        return defaultValue;
+      }
+    }
+
+    // TODO @runspired consider whether we need a defaultValue cache in ReactiveResource
+    // like we do for the simple case above.
+    const path = attr;
+    const cached = this.__peek(identifier, true);
+    const basePath = path[0];
+    let current = cached.localAttrs && basePath in cached.localAttrs ? cached.localAttrs[basePath] : undefined;
+    if (current === undefined) {
+      current = cached.inflightAttrs && basePath in cached.inflightAttrs ? cached.inflightAttrs[basePath] : undefined;
+    }
+    if (current === undefined) {
+      current = cached.remoteAttrs && basePath in cached.remoteAttrs ? cached.remoteAttrs[basePath] : undefined;
+    }
+    if (current === undefined) {
+      return undefined;
+    }
+    for (let i = 1; i < path.length; i++) {
+      current = current[path[i]];
+      if (current === undefined) {
+        return undefined;
+      }
+    }
+    return current;
+  }
+
+  /**
+   * Retrieve the remote data for an attribute from the cache
+   *
+   * @category Resource Data
+   * @public
+   */
+  getRemoteAttr(identifier, attr) {
+    const isSimplePath = !Array.isArray(attr) || attr.length === 1;
+    if (Array.isArray(attr) && attr.length === 1) {
+      attr = attr[0];
+    }
+    if (isSimplePath) {
+      const attribute = attr;
+      const cached = this.__peek(identifier, true);
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Cannot retrieve remote attributes for identifier ${String(identifier)} as it is not present in the cache`);
+        }
+      })(cached) : {};
+
+      // in Prod we try to recover when accessing something that
+      // doesn't exist
+      if (!cached) {
+        return undefined;
+      }
+      if (cached.remoteAttrs && attribute in cached.remoteAttrs) {
+        return cached.remoteAttrs[attribute];
+
+        // we still show defaultValues in the case of a remoteAttr access
+      } else if (cached.defaultAttrs && attribute in cached.defaultAttrs) {
+        return cached.defaultAttrs[attribute];
+      } else {
+        const attrSchema = getCacheFields(this, identifier).get(attribute);
+        assertPrivateCapabilities(this._capabilities);
+        const defaultValue = getDefaultValue(attrSchema, identifier, this._capabilities._store);
+        if (schemaHasLegacyDefaultValueFn(attrSchema)) {
+          cached.defaultAttrs = cached.defaultAttrs || Object.create(null);
+          cached.defaultAttrs[attribute] = defaultValue;
+        }
+        return defaultValue;
+      }
+    }
+
+    // TODO @runspired consider whether we need a defaultValue cache in ReactiveResource
+    // like we do for the simple case above.
+    const path = attr;
+    const cached = this.__peek(identifier, true);
+    const basePath = path[0];
+    let current = cached.remoteAttrs && basePath in cached.remoteAttrs ? cached.remoteAttrs[basePath] : undefined;
+    if (current === undefined) {
+      return undefined;
+    }
+    for (let i = 1; i < path.length; i++) {
+      current = current[path[i]];
+      if (current === undefined) {
+        return undefined;
+      }
+    }
+    return current;
+  }
+
+  /**
+   * Mutate the data for an attribute in the cache
+   *
+   * This method is a candidate to become a mutation
+   *
+   * @category Resource Data
+   * @public
+   */
+  setAttr(identifier, attr, value) {
+    // this assert works to ensure we have a non-empty string and/or a non-empty array
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error('setAttr must receive at least one attribute path');
+      }
+    })(attr.length > 0) : {};
+    const isSimplePath = !Array.isArray(attr) || attr.length === 1;
+    if (Array.isArray(attr) && attr.length === 1) {
+      attr = attr[0];
+    }
+    if (isSimplePath) {
+      const cached = this.__peek(identifier, false);
+      const currentAttr = attr;
+      const existing = cached.inflightAttrs && currentAttr in cached.inflightAttrs ? cached.inflightAttrs[currentAttr] : cached.remoteAttrs && currentAttr in cached.remoteAttrs ? cached.remoteAttrs[currentAttr] : undefined;
+      if (existing !== value) {
+        cached.localAttrs = cached.localAttrs || Object.create(null);
+        cached.localAttrs[currentAttr] = value;
+        cached.changes = cached.changes || Object.create(null);
+        cached.changes[currentAttr] = [existing, value];
+      } else if (cached.localAttrs) {
+        delete cached.localAttrs[currentAttr];
+        delete cached.changes[currentAttr];
+      }
+      if (cached.defaultAttrs && currentAttr in cached.defaultAttrs) {
+        delete cached.defaultAttrs[currentAttr];
+      }
+      this._capabilities.notifyChange(identifier, 'attributes', currentAttr);
+      return;
+    }
+
+    // get current value from local else inflight else remote
+    // structuredClone current if not local (or always?)
+    // traverse path, update value at path
+    // notify change at first link in path.
+    // second pass optimization is change notifyChange signature to take an array path
+
+    // guaranteed that we have path of at least 2 in length
+    const path = attr;
+    const cached = this.__peek(identifier, false);
+
+    // get existing cache record for base path
+    const basePath = path[0];
+    const existing = cached.inflightAttrs && basePath in cached.inflightAttrs ? cached.inflightAttrs[basePath] : cached.remoteAttrs && basePath in cached.remoteAttrs ? cached.remoteAttrs[basePath] : undefined;
+    let existingAttr;
+    if (existing) {
+      existingAttr = existing[path[1]];
+      for (let i = 2; i < path.length; i++) {
+        // the specific change we're making is at path[length - 1]
+        existingAttr = existingAttr[path[i]];
+      }
+    }
+    if (existingAttr !== value) {
+      cached.localAttrs = cached.localAttrs || Object.create(null);
+      cached.localAttrs[basePath] = cached.localAttrs[basePath] || structuredClone(existing);
+      cached.changes = cached.changes || Object.create(null);
+      let currentLocal = cached.localAttrs[basePath];
+      let nextLink = 1;
+      while (nextLink < path.length - 1) {
+        currentLocal = currentLocal[path[nextLink++]];
+      }
+      currentLocal[path[nextLink]] = value;
+      cached.changes[basePath] = [existing, cached.localAttrs[basePath]];
+
+      // since we initiaize the value as basePath as a clone of the value at the remote basePath
+      // then in theory we can use JSON.stringify to compare the two values as key insertion order
+      // ought to be consistent.
+      // we try/catch this because users have a habit of doing "Bad Things"TM wherein the cache contains
+      // stateful values that are not JSON serializable correctly such as Dates.
+      // in the case that we error, we fallback to not removing the local value
+      // so that any changes we don't understand are preserved. Thse objects would then sometimes
+      // appear to be dirty unnecessarily, and for folks that open an issue we can guide them
+      // to make their cache data less stateful.
+    } else if (cached.localAttrs) {
+      try {
+        if (!existing) {
+          return;
+        }
+        const existingStr = JSON.stringify(existing);
+        const newStr = JSON.stringify(cached.localAttrs[basePath]);
+        if (existingStr !== newStr) {
+          delete cached.localAttrs[basePath];
+          delete cached.changes[basePath];
+        }
+      } catch {
+        // noop
+      }
+    }
+    this._capabilities.notifyChange(identifier, 'attributes', basePath);
+  }
+
+  /**
+   * Query the cache for the changed attributes of a resource.
+   *
+   * @category Resource Data
+   * @public
+   * @return `{ '<field>': ['<old>', '<new>'] }`
+   */
+  changedAttrs(identifier) {
+    const cached = this.__peek(identifier, false);
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Cannot retrieve changed attributes for identifier ${String(identifier)} as it is not present in the cache`);
+      }
+    })(cached) : {};
+
+    // in Prod we try to recover when accessing something that
+    // doesn't exist
+    if (!cached) {
+      return Object.create(null);
+    }
+
+    // TODO freeze in dev
+    return cached.changes || Object.create(null);
+  }
+
+  /**
+   * Query the cache for whether any mutated attributes exist
+   *
+   * @category Resource Data
+   * @public
+   */
+  hasChangedAttrs(identifier) {
+    const cached = this.__peek(identifier, true);
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Cannot retrieve changed attributes for identifier ${String(identifier)} as it is not present in the cache`);
+      }
+    })(cached) : {};
+
+    // in Prod we try to recover when accessing something that
+    // doesn't exist
+    if (!cached) {
+      return false;
+    }
+    return cached.inflightAttrs !== null && Object.keys(cached.inflightAttrs).length > 0 || cached.localAttrs !== null && Object.keys(cached.localAttrs).length > 0;
+  }
+
+  /**
+   * Tell the cache to discard any uncommitted mutations to attributes
+   *
+   * This method is a candidate to become a mutation
+   *
+   * @category Resource Data
+   * @public
+   * @return the names of fields that were restored
+   */
+  rollbackAttrs(identifier) {
+    const cached = this.__peek(identifier, false);
+    let dirtyKeys;
+    cached.isDeleted = false;
+    if (cached.localAttrs !== null) {
+      dirtyKeys = Object.keys(cached.localAttrs);
+      cached.localAttrs = null;
+      cached.changes = null;
+    }
+    if (cached.isNew) {
+      // > Note: Graph removal handled by unloadRecord
+      cached.isDeletionCommitted = true;
+      cached.isDeleted = true;
+      cached.isNew = false;
+    }
+    cached.inflightAttrs = null;
+    cached.defaultAttrs = null;
+    if (cached.errors) {
+      cached.errors = null;
+      this._capabilities.notifyChange(identifier, 'errors', null);
+    }
+    this._capabilities.notifyChange(identifier, 'state', null);
+    if (dirtyKeys && dirtyKeys.length) {
+      notifyAttributes(this._capabilities, identifier, new Set(dirtyKeys));
+    }
+    return dirtyKeys || [];
+  }
+
+  /**
+   * Query the cache for the changes to relationships of a resource.
+   *
+   * Returns a map of relationship names to RelationshipDiff objects.
+   *
+   * ```ts
+   * type RelationshipDiff =
+     | {
+        kind: 'collection';
+        remoteState: ResourceKey[];
+        additions: Set<ResourceKey>;
+        removals: Set<ResourceKey>;
+        localState: ResourceKey[];
+        reordered: boolean;
+       }
+     | {
+        kind: 'resource';
+        remoteState: ResourceKey | null;
+        localState: ResourceKey | null;
+      };
+      ```
+   *
+   * @category Resource Data
+   * @public
+   */
+  changedRelationships(identifier) {
+    return this.__graph.getChanged(identifier);
+  }
+
+  /**
+   * Query the cache for whether any mutated relationships exist
+   *
+   * @category Resource Data
+   * @public
+   */
+  hasChangedRelationships(identifier) {
+    return this.__graph.hasChanged(identifier);
+  }
+
+  /**
+   * Tell the cache to discard any uncommitted mutations to relationships.
+   *
+   * This will also discard the change on any appropriate inverses.
+   *
+   * This method is a candidate to become a mutation
+   *
+   * @category Resource Data
+   * @public
+   * @return the names of relationships that were restored
+   */
+  rollbackRelationships(identifier) {
+    assertPrivateCapabilities(this._capabilities);
+    let result;
+    this._capabilities._store._join(() => {
+      result = this.__graph.rollback(identifier);
+    });
+    return result;
+  }
+
+  /**
+   * Query the cache for the current state of a relationship property
+   *
+   * @category Resource Data
+   * @public
+   * @return resource relationship object
+   */
+  getRelationship(identifier, field) {
+    return this.__graph.getData(identifier, field);
+  }
+
+  /**
+   * Query the cache for the remote state of a relationship property
+   *
+   * @category Resource Data
+   * @public
+   * @return resource relationship object
+   */
+  getRemoteRelationship(identifier, field) {
+    return this.__graph.getRemoteData(identifier, field);
+  }
+
+  ////////// ============== //////////
+  ////////// Resource State //////////
+  ////////// ============== //////////
+
+  /**
+   * Update the cache state for the given resource to be marked
+   * as locally deleted, or remove such a mark.
+   *
+   * This method is a candidate to become a mutation
+   *
+   * @category Resource State
+   * @public
+   */
+  setIsDeleted(identifier, isDeleted) {
+    const cached = this.__peek(identifier, false);
+    cached.isDeleted = isDeleted;
+    // > Note: Graph removal for isNew handled by unloadRecord
+    this._capabilities.notifyChange(identifier, 'state', null);
+  }
+
+  /**
+   * Query the cache for any validation errors applicable to the given resource.
+   *
+   * @category Resource State
+   * @public
+   */
+  getErrors(identifier) {
+    return this.__peek(identifier, true).errors || [];
+  }
+
+  /**
+   * Query the cache for whether a given resource has any available data
+   *
+   * @category Resource State
+   * @public
+   */
+  isEmpty(identifier) {
+    const cached = this.__safePeek(identifier, true);
+    return cached ? cached.remoteAttrs === null && cached.inflightAttrs === null && cached.localAttrs === null : true;
+  }
+
+  /**
+   * Query the cache for whether a given resource was created locally and not
+   * yet persisted.
+   *
+   * @category Resource State
+   * @public
+   */
+  isNew(identifier) {
+    // TODO can we assert here?
+    return this.__safePeek(identifier, true)?.isNew || false;
+  }
+
+  /**
+   * Query the cache for whether a given resource is marked as deleted (but not
+   * necessarily persisted yet).
+   *
+   * @category Resource State
+   * @public
+   */
+  isDeleted(identifier) {
+    // TODO can we assert here?
+    return this.__safePeek(identifier, true)?.isDeleted || false;
+  }
+
+  /**
+   * Query the cache for whether a given resource has been deleted and that deletion
+   * has also been persisted.
+   *
+   * @category Resource State
+   * @public
+   */
+  isDeletionCommitted(identifier) {
+    // TODO can we assert here?
+    return this.__safePeek(identifier, true)?.isDeletionCommitted || false;
+  }
+
+  /**
+   * Private method used to populate an entry for the identifier
+   *
+   * @internal
+   */
+  _createCache(identifier) {
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Expected no resource data to yet exist in the cache`);
+      }
+    })(!this.__cache.has(identifier)) : {};
+    const cache = makeCache();
+    this.__cache.set(identifier, cache);
+    return cache;
+  }
+
+  /**
+   * Peek whether we have cached resource data matching the identifier
+   * without asserting if the resource data is missing.
+   *
+   * @internal
+   */
+  __safePeek(identifier, allowDestroyed) {
+    let resource = this.__cache.get(identifier);
+    if (!resource && allowDestroyed) {
+      resource = this.__destroyedCache.get(identifier);
+    }
+    return resource;
+  }
+
+  /**
+   * Peek whether we have cached resource data matching the identifier
+   * Asserts if the resource data is missing.
+   *
+   * @internal
+   */
+  __peek(identifier, allowDestroyed) {
+    const resource = this.__safePeek(identifier, allowDestroyed);
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Expected Cache to have a resource entry for the identifier ${String(identifier)} but none was found`);
+      }
+    })(resource) : {};
+    return resource;
+  }
+}
+function addResourceToDocument(cache, op) {
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected field to be either 'data' or 'included'`);
+    }
+  })(op.field === 'data' || op.field === 'included') : {};
+  const doc = cache.__documents.get(op.record.lid);
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected to have a cached document on which to perform the add operation`);
+    }
+  })(doc) : {};
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected to have content on the document`);
+    }
+  })(doc.content) : {};
+  const {
+    content
+  } = doc;
+  if (op.field === 'data') {
+    let shouldNotify = false;
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Expected to have a data property on the document`);
+      }
+    })('data' in content) : {};
+
+    // if data is not an array, we set the data property directly
+    if (!Array.isArray(content.data)) {
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Expected to have a single record as the operation value`);
+        }
+      })(op.value && !Array.isArray(op.value)) : {};
+      shouldNotify = content.data !== op.value;
+      if (shouldNotify) content.data = op.value;
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`The value '${op.value.lid}' cannot be added from the data of document '${op.record.lid}' as it is already the current value '${content.data ? content.data.lid : '<null>'}'`);
+        }
+      })(shouldNotify) : {};
+    } else {
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Expected to have a non-null operation value`);
+        }
+      })(op.value) : {};
+      if (Array.isArray(op.value)) {
+        if (op.index !== undefined) {
+          // for collections, because we allow duplicates we are always changed.
+          shouldNotify = true;
+          content.data.splice(op.index, 0, ...op.value);
+        } else {
+          // for collections, because we allow duplicates we are always changed.
+          shouldNotify = true;
+          content.data.push(...op.value);
+        }
+      } else {
+        if (op.index !== undefined) {
+          // for collections, because we allow duplicates we are always changed.
+          shouldNotify = true;
+          content.data.splice(op.index, 0, op.value);
+        } else {
+          // for collections, because we allow duplicates we are always changed.
+          shouldNotify = true;
+          content.data.push(op.value);
+        }
+      }
+    }
+
+    // notify
+    if (shouldNotify) cache._capabilities.notifyChange(op.record, 'updated', null);
+    return;
+  }
+  content.included = content.included || [];
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected to have a non-null operation value`);
+    }
+  })(op.value) : {};
+  if (Array.isArray(op.value)) {
+    // included is not allowed to have duplicates, so we do a dirty check here
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`included should not contain duplicate members`);
+      }
+    })(new Set([...content.included, ...op.value]).size === content.included.length + op.value.length) : {};
+    content.included = content.included.concat(op.value);
+  } else {
+    // included is not allowed to have duplicates, so we do a dirty check here
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`included should not contain duplicate members`);
+      }
+    })(content.included.includes(op.value) === false) : {};
+    content.included.push(op.value);
+  }
+
+  // we don't notify in the included case because this is not reactively
+  // exposed. We should possibly consider doing so though for subscribers
+}
+function removeResourceFromDocument(cache, op) {
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected field to be either 'data' or 'included'`);
+    }
+  })(op.field === 'data' || op.field === 'included') : {};
+  const doc = cache.__documents.get(op.record.lid);
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected to have a cached document on which to perform the remove operation`);
+    }
+  })(doc) : {};
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected to have content on the document`);
+    }
+  })(doc.content) : {};
+  const {
+    content
+  } = doc;
+  if (op.field === 'data') {
+    let shouldNotify = false;
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Expected to have a data property on the document`);
+      }
+    })('data' in content) : {};
+
+    // if data is not an array, we set the data property directly
+    if (!Array.isArray(content.data)) {
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Expected to have a single record as the operation value`);
+        }
+      })(op.value && !Array.isArray(op.value)) : {};
+      shouldNotify = content.data === op.value;
+      // we only remove the value if it was our existing value
+      if (shouldNotify) content.data = null;
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`The value '${op.value.lid}' cannot be removed from the data of document '${op.record.lid}' as it is not the current value '${content.data ? content.data.lid : '<null>'}'`);
+        }
+      })(shouldNotify) : {};
+    } else {
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`Expected to have a non-null operation value`);
+        }
+      })(op.value) : {};
+      const toRemove = Array.isArray(op.value) ? op.value : [op.value];
+      for (let i = 0; i < toRemove.length; i++) {
+        const value = toRemove[i];
+        if (op.index !== undefined) {
+          // in production we want to recover gracefully
+          // so we fallback to first-index-of
+          const index = op.index < content.data.length && content.data[op.index] === value ? op.index : content.data.indexOf(value);
+          macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+            if (!test) {
+              throw new Error(`Mismatched Index: Expected index '${op.index}' to contain the value '${value.lid}' but that value is at index '${index}'`);
+            }
+          })(op.index < content.data.length && content.data[op.index] === value) : {};
+          if (index !== -1) {
+            // we remove the first occurrence of the value
+            shouldNotify = true;
+            content.data.splice(index, 1);
+          }
+        } else {
+          // we remove the first occurrence of the value
+          const index = content.data.indexOf(value);
+          if (index !== -1) {
+            shouldNotify = true;
+            content.data.splice(index, 1);
+          }
+        }
+      }
+    }
+
+    // notify
+    if (shouldNotify) cache._capabilities.notifyChange(op.record, 'updated', null);
+  } else {
+    content.included = content.included || [];
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Expected to have a non-null operation value`);
+      }
+    })(op.value) : {};
+    const toRemove = Array.isArray(op.value) ? op.value : [op.value];
+    for (const identifier of toRemove) {
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`attempted to remove a value from included that was not present in the included array`);
+        }
+      })(content.included.includes(identifier)) : {};
+      const index = content.included.indexOf(identifier);
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        if (!test) {
+          throw new Error(`The value '${identifier.lid}' cannot be removed from the included of document '${op.record.lid}' as it is not present`);
+        }
+      })(index !== -1) : {};
+      if (index !== -1) {
+        content.included.splice(index, 1);
+      }
+    }
+
+    // we don't notify in the included case because this is not reactively
+    // exposed. We should possibly consider doing so though for subscribers
+  }
+}
+function areAllModelsUnloaded(wrapper, identifiers) {
+  for (let i = 0; i < identifiers.length; ++i) {
+    const identifier = identifiers[i];
+    if (wrapper.hasRecord(identifier)) {
+      return false;
+    }
+  }
+  return true;
+}
+function getLocalState(rel) {
+  if (isBelongsTo(rel)) {
+    return rel.localState ? [rel.localState] : [];
+  }
+  return rel.additions ? [...rel.additions] : [];
+}
+function getRemoteState(rel) {
+  if (isBelongsTo(rel)) {
+    return rel.remoteState ? [rel.remoteState] : [];
+  }
+  return rel.remoteState;
+}
+function schemaHasLegacyDefaultValueFn(schema) {
+  if (!schema) return false;
+  return hasLegacyDefaultValueFn(schema.options);
+}
+function hasLegacyDefaultValueFn(options) {
+  return !!options && typeof options.defaultValue === 'function';
+}
+function getDefaultValue(schema, identifier, store) {
+  const options = schema?.options;
+  if (!schema || !options && !schema.type) {
+    return;
+  }
+  if (schema.kind !== 'attribute' && schema.kind !== 'field') {
+    return;
+  }
+
+  // legacy support for defaultValues that are functions
+  if (hasLegacyDefaultValueFn(options)) {
+    // If anyone opens an issue for args not working right, we'll restore + deprecate it via a Proxy
+    // that lazily instantiates the record. We don't want to provide any args here
+    // because in a non @ember-data-mirror/model world they don't make sense.
+    return options.defaultValue();
+    // legacy support for defaultValues that are primitives
+  } else if (options && 'defaultValue' in options) {
+    const defaultValue = options.defaultValue;
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Non primitive defaultValues are not supported because they are shared between all instances. If you would like to use a complex object as a default value please provide a function that returns the complex object.`);
+      }
+    })(typeof defaultValue !== 'object' || defaultValue === null) : {};
+    return defaultValue;
+
+    // new style transforms
+  } else if (schema.kind !== 'attribute' && schema.type) {
+    const transform = store.schema.transformation(schema);
+    if (transform?.defaultValue) {
+      return transform.defaultValue(options || null, identifier);
+    }
+  }
+}
+function notifyAttributes(storeWrapper, identifier, keys) {
+  if (!keys) {
+    storeWrapper.notifyChange(identifier, 'attributes', null);
+    return;
+  }
+  for (const key of keys) {
+    storeWrapper.notifyChange(identifier, 'attributes', key);
+  }
+}
+
+/*
+      TODO @deprecate IGOR DAVID
+      There seems to be a potential bug here, where we will return keys that are not
+      in the schema
+  */
+function calculateChangedKeys(cached, updates, fields) {
+  const changedKeys = new Set();
+  const keys = Object.keys(updates);
+  const length = keys.length;
+  const localAttrs = cached.localAttrs;
+  const original = Object.assign(Object.create(null), cached.remoteAttrs, cached.inflightAttrs);
+  for (let i = 0; i < length; i++) {
+    const key = keys[i];
+    if (!fields.has(key)) {
+      continue;
+    }
+    const value = updates[key];
+
+    // A value in localAttrs means the user has a local change to
+    // this attribute. We never override this value when merging
+    // updates from the backend so we should not sent a change
+    // notification if the server value differs from the original.
+    if (localAttrs && localAttrs[key] !== undefined) {
+      continue;
+    }
+    if (original[key] !== value) {
+      changedKeys.add(key);
+    }
+  }
+  return changedKeys;
+}
+function cacheIsEmpty(cached) {
+  return !cached || cached.remoteAttrs === null && cached.inflightAttrs === null && cached.localAttrs === null;
+}
+function _isEmpty(peeked) {
+  if (!peeked) {
+    return true;
+  }
+  const isNew = peeked.isNew;
+  const isDeleted = peeked.isDeleted;
+  const isEmpty = cacheIsEmpty(peeked);
+  return (!isNew || isDeleted) && isEmpty;
+}
+function recordIsLoaded(cached, filterDeleted = false) {
+  if (!cached) {
+    return false;
+  }
+  const isNew = cached.isNew;
+  const isEmpty = cacheIsEmpty(cached);
+
+  // if we are new we must consider ourselves loaded
+  if (isNew) {
+    return !cached.isDeleted;
+  }
+  // even if we have a past request, if we are now empty we are not loaded
+  // typically this is true after an unloadRecord call
+
+  // if we are not empty, not new && we have a fulfilled request then we are loaded
+  // we should consider allowing for something to be loaded that is simply "not empty".
+  // which is how RecordState currently handles this case; however, RecordState is buggy
+  // in that it does not account for unloading.
+  return filterDeleted && cached.isDeletionCommitted ? false : !isEmpty;
+}
+function _isLoading(peeked, capabilities, identifier) {
+  assertPrivateCapabilities(capabilities);
+  // TODO refactor things such that the cache is not required to know
+  // about isLoading
+  const req = capabilities._store.getRequestStateService();
+  // const fulfilled = req.getLastRequestForRecord(identifier);
+  const isLoaded = recordIsLoaded(peeked);
+  return !isLoaded &&
+  // fulfilled === null &&
+  req.getPendingRequestsForRecord(identifier).some(r => r.type === 'query');
+}
+function setupRelationships(graph, fields, identifier, data) {
+  for (const name in data.relationships) {
+    const relationshipData = data.relationships[name];
+    const field = fields.get(name);
+    // TODO consider asserting if the relationship is not in the schema
+    // we intentionally ignore relationships that are not in the schema
+    if (!relationshipData || !field || !isRelationship(field)) continue;
+    graph.push({
+      op: 'updateRelationship',
+      record: identifier,
+      field: name,
+      value: relationshipData
+    });
+  }
+}
+function isRelationship(field) {
+  const {
+    kind
+  } = field;
+  return kind === 'hasMany' || kind === 'belongsTo' || kind === 'resource' || kind === 'collection';
+}
+function patchLocalAttributes(cached, changedRemoteKeys) {
+  const {
+    localAttrs,
+    remoteAttrs,
+    inflightAttrs,
+    defaultAttrs,
+    changes
+  } = cached;
+  if (!localAttrs) {
+    cached.changes = null;
+    return false;
+  }
+  let hasAppliedPatch = false;
+  const mutatedKeys = Object.keys(localAttrs);
+  for (let i = 0, length = mutatedKeys.length; i < length; i++) {
+    const attr = mutatedKeys[i];
+    const existing = inflightAttrs && attr in inflightAttrs ? inflightAttrs[attr] : remoteAttrs && attr in remoteAttrs ? remoteAttrs[attr] : undefined;
+    if (existing === localAttrs[attr]) {
+      hasAppliedPatch = true;
+
+      // if the local change is committed, then
+      // the remoteKeyChange is no longer relevant
+      changedRemoteKeys?.delete(attr);
+      delete localAttrs[attr];
+      delete changes[attr];
+    }
+    if (defaultAttrs && attr in defaultAttrs) {
+      delete defaultAttrs[attr];
+    }
+  }
+  return hasAppliedPatch;
+}
+function putOne(cache, identifiers, resource) {
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`You must include an 'id' for the resource data ${resource.type}`);
+    }
+  })(resource.id !== null && resource.id !== undefined && resource.id !== '') : {};
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Missing Resource Type: received resource data with a type '${resource.type}' but no schema could be found with that name.`);
+    }
+  })(cache._capabilities.schema.hasResource(resource)) : {};
+  let identifier = identifiers.peekResourceKey(resource);
+  if (identifier) {
+    identifier = identifiers.updateRecordIdentifier(identifier, resource);
+  } else {
+    identifier = identifiers.getOrCreateRecordIdentifier(resource);
+  }
+  cache.upsert(identifier, resource, cache._capabilities.hasRecord(identifier));
+  // even if the identifier was not "existing" before, it is now
+  return identifier;
+}
+
+/*
+    Iterates over the set of internal models reachable from `this` across exactly one
+    relationship.
+  */
+function _directlyRelatedIdentifiersIterable(storeWrapper, originating) {
+  const graph = peekGraph(storeWrapper);
+  const initializedRelationships = graph?.identifiers.get(originating);
+  if (!initializedRelationships) {
+    return EMPTY_ITERATOR;
+  }
+  const initializedRelationshipsArr = [];
+  Object.keys(initializedRelationships).forEach(key => {
+    const rel = initializedRelationships[key];
+    if (rel && !isImplicit(rel)) {
+      initializedRelationshipsArr.push(rel);
+    }
+  });
+  let i = 0;
+  let j = 0;
+  let k = 0;
+  const findNext = () => {
+    while (i < initializedRelationshipsArr.length) {
+      while (j < 2) {
+        const relatedIdentifiers = j === 0 ? getLocalState(initializedRelationshipsArr[i]) : getRemoteState(initializedRelationshipsArr[i]);
+        while (k < relatedIdentifiers.length) {
+          const relatedIdentifier = relatedIdentifiers[k++];
+          if (relatedIdentifier !== null) {
+            return relatedIdentifier;
+          }
+        }
+        k = 0;
+        j++;
+      }
+      j = 0;
+      i++;
+    }
+    return undefined;
+  };
+  return {
+    iterator() {
+      return {
+        next: () => {
+          const value = findNext();
+          return {
+            value,
+            done: value === undefined
+          };
+        }
+      };
+    }
+  };
+}
+
+/*
+      Computes the set of Identifiers reachable from this Identifier.
+
+      Reachability is determined over the relationship graph (ie a graph where
+      nodes are identifiers and edges are belongs to or has many
+      relationships).
+
+      Returns an array including `this` and all identifiers reachable
+      from `this.identifier`.
+    */
+function _allRelatedIdentifiers(storeWrapper, originating) {
+  const array = [];
+  const queue = [];
+  const seen = new Set();
+  queue.push(originating);
+  while (queue.length > 0) {
+    const identifier = queue.shift();
+    array.push(identifier);
+    seen.add(identifier);
+    const iterator = _directlyRelatedIdentifiersIterable(storeWrapper, originating).iterator();
+    for (let obj = iterator.next(); !obj.done; obj = iterator.next()) {
+      const relatedIdentifier = obj.value;
+      if (relatedIdentifier && !seen.has(relatedIdentifier)) {
+        seen.add(relatedIdentifier);
+        queue.push(relatedIdentifier);
+      }
+    }
+  }
+  return array;
+}
+function fromBaseDocument(doc) {
+  const resourceDocument = {};
+  const jsonApiDoc = doc.content;
+  if (jsonApiDoc) {
+    copyLinksAndMeta(resourceDocument, jsonApiDoc);
+  }
+  return resourceDocument;
+}
+function fromStructuredError(doc) {
+  const errorDoc = {};
+  if (doc.content) {
+    copyLinksAndMeta(errorDoc, doc.content);
+    if ('errors' in doc.content) {
+      errorDoc.errors = doc.content.errors;
+    } else if (typeof doc.error === 'object' && 'errors' in doc.error) {
+      errorDoc.errors = doc.error.errors;
+    } else {
+      errorDoc.errors = [{
+        title: doc.message
+      }];
+    }
+  }
+  return errorDoc;
+}
+function copyLinksAndMeta(target, source) {
+  if ('links' in source) {
+    target.links = source.links;
+  }
+  if ('meta' in source) {
+    target.meta = source.meta;
+  }
+}
+function cacheUpsert(cache, identifier, data, calculateChanges) {
+  let changedKeys;
+  const peeked = cache.__safePeek(identifier, false);
+  const existed = !!peeked;
+  const cached = peeked || cache._createCache(identifier);
+  const isLoading = /*#__NOINLINE__*/_isLoading(peeked, cache._capabilities, identifier) || !recordIsLoaded(peeked);
+  const isUpdate = /*#__NOINLINE__*/!_isEmpty(peeked) && !isLoading;
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+    if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+      logGroup('cache', 'upsert', identifier.type, identifier.lid, existed ? 'merged' : 'inserted', calculateChanges ? 'has-subscription' : '');
+      try {
+        const _data = JSON.parse(JSON.stringify(data));
+
+        // eslint-disable-next-line no-console
+        console.log(_data);
+      } catch {
+        // eslint-disable-next-line no-console
+        console.log(data);
+      }
+    }
+  }
+  if (cached.isNew) {
+    cached.isNew = false;
+    cache._capabilities.notifyChange(identifier, 'identity', null);
+    cache._capabilities.notifyChange(identifier, 'state', null);
+  }
+  const fields = getCacheFields(cache, identifier);
+
+  // if no cache entry existed, no record exists / property has been accessed
+  // and thus we do not need to notify changes to any properties.
+  if (calculateChanges && existed && data.attributes) {
+    changedKeys = calculateChangedKeys(cached, data.attributes, fields);
+  }
+  cached.remoteAttrs = Object.assign(cached.remoteAttrs || Object.create(null), data.attributes);
+  if (cached.localAttrs) {
+    if (patchLocalAttributes(cached, changedKeys)) {
+      cache._capabilities.notifyChange(identifier, 'state', null);
+    }
+  }
+  if (!isUpdate) {
+    cache._capabilities.notifyChange(identifier, 'added', null);
+  }
+  if (data.id) {
+    cached.id = data.id;
+  }
+  if (data.relationships) {
+    setupRelationships(cache.__graph, fields, identifier, data);
+  }
+  if (changedKeys?.size) {
+    notifyAttributes(cache._capabilities, identifier, changedKeys);
+  }
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+    if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+      // eslint-disable-next-line no-console
+      console.groupEnd();
+    }
+  }
+  return changedKeys?.size ? Array.from(changedKeys) : undefined;
+}
+function patchCache(Cache, op) {
+  const isRecord = isResourceKey(op.record);
+  const isDocument = !isRecord && isRequestKey(op.record);
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected Cache.patch op.record to be a record or document identifier`);
+    }
+  })(isRecord || isDocument) : {};
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+    if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+      logGroup('cache', 'patch', isRecord ? op.record.type : '<@document>', op.record.lid, op.op, 'field' in op ? op.field : op.op === 'mergeIdentifiers' ? op.value.lid : '');
+      try {
+        const _data = JSON.parse(JSON.stringify(op));
+        // eslint-disable-next-line no-console
+        console.log(_data);
+      } catch {
+        // eslint-disable-next-line no-console
+        console.log(op);
+      }
+    }
+  }
+  switch (op.op) {
+    case 'mergeIdentifiers':
+      {
+        const cache = Cache.__cache.get(op.record);
+        if (cache) {
+          Cache.__cache.set(op.value, cache);
+          Cache.__cache.delete(op.record);
+        }
+        Cache.__graph.update(op, true);
+        break;
+      }
+    case 'update':
+      {
+        if (isRecord) {
+          if ('field' in op) {
+            const field = getCacheFields(Cache, op.record).get(op.field);
+            macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+              if (!test) {
+                throw new Error(`Expected ${op.field} to be a field on ${op.record.type}`);
+              }
+            })(field) : {};
+            if (isRelationship(field)) {
+              Cache.__graph.push(op);
+            } else {
+              Cache.upsert(op.record, {
+                type: op.record.type,
+                id: op.record.id,
+                attributes: {
+                  [op.field]: op.value
+                }
+              }, Cache._capabilities.hasRecord(op.record));
+            }
+          } else {
+            Cache.upsert(op.record, op.value, Cache._capabilities.hasRecord(op.record));
+          }
+        } else {
+          macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+            {
+              throw new Error(`Update operations on documents is not supported`);
+            }
+          })() : {};
+        }
+        break;
+      }
+    case 'add':
+      {
+        if (isRecord) {
+          if ('field' in op) {
+            Cache.__graph.push(op);
+          } else {
+            Cache.upsert(op.record, op.value, Cache._capabilities.hasRecord(op.record));
+          }
+        } else {
+          macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+            if (!test) {
+              throw new Error(`Expected a field in the add operation`);
+            }
+          })('field' in op) : {};
+          addResourceToDocument(Cache, op);
+        }
+        break;
+      }
+    case 'remove':
+      {
+        if (isRecord) {
+          if ('field' in op) {
+            Cache.__graph.push(op);
+          } else {
+            const cached = Cache.__safePeek(op.record, false);
+            if (cached) {
+              cached.isDeleted = true;
+              cached.isDeletionCommitted = true;
+              Cache.unloadRecord(op.record);
+            } else {
+              peekGraph(Cache._capabilities)?.push({
+                op: 'deleteRecord',
+                record: op.record,
+                isNew: false
+              });
+            }
+          }
+        } else {
+          if ('field' in op) {
+            macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+              if (!test) {
+                throw new Error(`Expected a field in the remove operation`);
+              }
+            })('field' in op) : {};
+            removeResourceFromDocument(Cache, op);
+          } else {
+            // TODO @runspired teardown associated state ... notify subscribers etc.
+            // This likely means that the instance cache needs to handle
+            // holding onto reactive documents instead of the CacheHandler
+            // and use a subscription to remove them.
+            // Cache.__documents.delete(op.record.lid);
+            macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+              {
+                throw new Error(`Removing documents from the cache is not yet supported`);
+              }
+            })() : {};
+          }
+        }
+        break;
+      }
+    default:
+      macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+        {
+          throw new Error(`Unhandled cache.patch operation ${op.op}`);
+        }
+      })() : {};
+  }
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_CACHE)) {
+    if (getGlobalConfig().WarpDriveMirror.debug.LOG_CACHE || globalThis.getWarpDriveRuntimeConfig().debug.LOG_CACHE) {
+      // eslint-disable-next-line no-console
+      console.groupEnd();
+    }
+  }
+}
+function getCacheFields(cache, identifier) {
+  if (cache._capabilities.schema.cacheFields) {
+    return cache._capabilities.schema.cacheFields(identifier);
+  }
+
+  // the model schema service cannot process fields that are not cache fields
+  return cache._capabilities.schema.fields(identifier);
+}
+function commitDidError(cache, identifier, errors) {
+  const cached = cache.__peek(identifier, false);
+  if (cached.inflightAttrs) {
+    const keys = Object.keys(cached.inflightAttrs);
+    if (keys.length > 0) {
+      const attrs = cached.localAttrs = cached.localAttrs || Object.create(null);
+      for (let i = 0; i < keys.length; i++) {
+        if (attrs[keys[i]] === undefined) {
+          attrs[keys[i]] = cached.inflightAttrs[keys[i]];
+        }
+      }
+    }
+    cached.inflightAttrs = null;
+  }
+  if (errors) {
+    cached.errors = errors;
+  }
+  cache._capabilities.notifyChange(identifier, 'errors', null);
+}
+function didCommit(cache, committedIdentifier, data, op) {
+  if (!data) {
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Your ${committedIdentifier.type} record was saved to the server, but the response does not have an id and no id has been set client side. Records must have ids. Please update the server response to provide an id in the response or generate the id on the client side either before saving the record or while normalizing the response.`);
+      }
+    })(committedIdentifier.id) : {};
+  }
+  const {
+    cacheKeyManager
+  } = cache._capabilities;
+  const existingId = committedIdentifier.id;
+  const identifier = op !== 'deleteRecord' && data ? cacheKeyManager.updateRecordIdentifier(committedIdentifier, data) : committedIdentifier;
+  const cached = cache.__peek(identifier, false);
+  if (cached.isDeleted || op === 'deleteRecord') {
+    cache.__graph.push({
+      op: 'deleteRecord',
+      record: identifier,
+      isNew: false
+    });
+    cached.isDeleted = true;
+    cached.isDeletionCommitted = true;
+    cache._capabilities.notifyChange(identifier, 'removed', null);
+    // TODO @runspired should we early exit here?
+  }
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+    if (cached.isNew && !identifier.id && (typeof data?.id !== 'string' || data.id.length > 0)) {
+      const error = new Error(`Expected an id ${String(identifier)} in response ${JSON.stringify(data)}`);
+      //@ts-expect-error
+      error.isAdapterError = true;
+      //@ts-expect-error
+      error.code = 'InvalidError';
+      throw error;
+    }
+  }
+  const fields = getCacheFields(cache, identifier);
+  cached.isNew = false;
+  let newCanonicalAttributes;
+  if (data) {
+    if (data.id && !cached.id) {
+      cached.id = data.id;
+    }
+    if (identifier === committedIdentifier && identifier.id !== existingId) {
+      cache._capabilities.notifyChange(identifier, 'identity', null);
+    }
+    macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`Expected the ID received for the primary '${identifier.type}' resource being saved to match the current id '${cached.id}' but received '${identifier.id}'.`);
+      }
+    })(identifier.id === cached.id) : {};
+    if (data.relationships) {
+      if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+        if (macroCondition(!getGlobalConfig().WarpDriveMirror.deprecations.DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE)) {
+          // assert against bad API behavior where a belongsTo relationship
+          // is saved but the return payload indicates a different final state.
+          fields.forEach((field, name) => {
+            if (field.kind === 'belongsTo') {
+              const relationshipData = data.relationships[name]?.data;
+              if (relationshipData !== undefined) {
+                const inFlightData = cached.inflightRelationships?.[name];
+                if (!inFlightData || !('data' in inFlightData)) {
+                  return;
+                }
+                const actualData = relationshipData ? cache._capabilities.cacheKeyManager.getOrCreateRecordIdentifier(relationshipData) : null;
+                macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+                  if (!test) {
+                    throw new Error(`Expected the resource relationship '<${identifier.type}>.${name}' on ${identifier.lid} to be saved as ${inFlightData.data ? inFlightData.data.lid : '<null>'} but it was saved as ${actualData ? actualData.lid : '<null>'}`);
+                  }
+                })(inFlightData.data === actualData) : {};
+              }
+            }
+          });
+          cached.inflightRelationships = null;
+        }
+      }
+      setupRelationships(cache.__graph, fields, identifier, data);
+    }
+    newCanonicalAttributes = data.attributes;
+  }
+  const changedKeys = newCanonicalAttributes && calculateChangedKeys(cached, newCanonicalAttributes, fields);
+  cached.remoteAttrs = Object.assign(cached.remoteAttrs || Object.create(null), cached.inflightAttrs, newCanonicalAttributes);
+  cached.inflightAttrs = null;
+  patchLocalAttributes(cached, changedKeys);
+  if (cached.errors) {
+    cached.errors = null;
+    cache._capabilities.notifyChange(identifier, 'errors', null);
+  }
+  if (changedKeys?.size) notifyAttributes(cache._capabilities, identifier, changedKeys);
+  cache._capabilities.notifyChange(identifier, 'state', null);
+}
+function willCommit(cache, identifier) {
+  const cached = cache.__peek(identifier, false);
+
+  /*
+      if we have multiple saves in flight at once then
+      we have information loss no matter what. This
+      attempts to lose the least information.
+       If we were to clear inflightAttrs, previous requests
+      would not be able to use it during their didCommit.
+       If we upsert inflightattrs, previous requests incorrectly
+      see more recent inflight changes as part of their own and
+      will incorrectly mark the new state as the correct remote state.
+       We choose this latter behavior to avoid accidentally removing
+      earlier changes.
+       If apps do not want this behavior they can either
+      - chain save requests serially vs allowing concurrent saves
+      - move to using a request handler that caches the inflight state
+        on a per-request basis
+      - change their save requests to only send a "PATCH" instead of a "PUT"
+        so that only latest changes are involved in each request, and then also
+        ensure that the API or their handler reflects only those changes back
+        for upsert into the cache.
+    */
+  if (cached.inflightAttrs) {
+    if (cached.localAttrs) {
+      Object.assign(cached.inflightAttrs, cached.localAttrs);
+    }
+  } else {
+    cached.inflightAttrs = cached.localAttrs;
+  }
+  cached.localAttrs = null;
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+    if (macroCondition(!getGlobalConfig().WarpDriveMirror.deprecations.DEPRECATE_RELATIONSHIP_REMOTE_UPDATE_CLEARING_LOCAL_STATE)) {
+      // save off info about saved relationships
+      const fields = getCacheFields(cache, identifier);
+      fields.forEach((schema, name) => {
+        if (schema.kind === 'belongsTo') {
+          if (cache.__graph._isDirty(identifier, name)) {
+            const relationshipData = cache.__graph.getData(identifier, name);
+            const inFlight = cached.inflightRelationships = cached.inflightRelationships || Object.create(null);
+            inFlight[name] = relationshipData;
+          }
+        }
+      });
+    }
+  }
+}
+
+export { JSONAPICache };