@warp-drive-mirror/core 5.10.0-alpha.2 → 5.10.0-alpha.20

package/dist/unpkg/dev/{src-kn6qfEPI.js → src-Dt1O1Pw1.js}

@@ -1,16 +1,16 @@
-import { a as setTransient, i as peekUniversalTransient, o as setUniversalTransient, r as peekTransient, t as getOrSetGlobal } from "./-private-BP52H-vC.js";
-import { A as ARRAY_SIGNAL, C as createInternalMemo, D as notifyInternalSignal, N as waitFor, O as peekInternalSignal, P as willSyncFlushWatchers, S as consumeInternalSignal, T as getOrCreateInternalSignal, _ as entangleSignal, f as createSignalDescriptor, g as entangleInitiallyStaleSignal, h as defineSignal, j as OBJECT_SIGNAL, k as withSignalStore, p as defineGate, w as createInternalSignal, x as Signals } from "./-private-CM5N2rtZ.js";
+import { getOrSetGlobal, peekTransient, peekUniversalTransient, setTransient, setUniversalTransient } from "./types/-private.js";
+import { A as ARRAY_SIGNAL, C as createInternalMemo, D as notifyInternalSignal, F as willSyncFlushWatchers, O as peekInternalSignal, P as waitFor, S as consumeInternalSignal, T as getOrCreateInternalSignal, _ as entangleSignal, f as createSignalDescriptor, g as entangleInitiallyStaleSignal, h as defineSignal, j as OBJECT_SIGNAL, k as withSignalStore, p as defineGate, w as createInternalSignal, x as Signals } from "./-private-B4pCmkq-.js";
 import { EnableHydration, STRUCTURED, SkipCache } from "./types/request.js";
 import { CACHE_OWNER, DEBUG_CLIENT_ORIGINATED, DEBUG_KEY_TYPE, DEBUG_STALE_CACHE_OWNER } from "./types/identifier.js";
-import { a as upgradePromise, c as executeNextHandler, d as getRequestResult, f as setPromiseResult, l as clearRequestResult, m as assertValidRequest, o as DOMError, p as cloneResponseProperties, s as IS_CACHE_HANDLER, t as withBrand } from "./request-DXPAtRhE.js";
+import { a as upgradePromise, c as executeNextHandler, d as getRequestResult, f as setPromiseResult, l as clearRequestResult, m as assertValidRequest, o as DOMError, p as cloneResponseProperties, s as IS_CACHE_HANDLER, t as withBrand } from "./request-oWpijCPQ.js";
 import { getRuntimeConfig, setIsMaybeMirage, setLogging } from "./types/runtime.js";
-import { a as SOURCE, i as Destroy, n as Commit, r as Context, t as Checkout } from "./-private-BO-nArRb.js";
-import { t as getGlobalConfig } from "./runtime-DW881fpw.js";
+import { a as SOURCE, i as Destroy, n as Commit, r as Context, t as Checkout } from "./-private-BiuED7nc.js";
+import { t as getGlobalConfig } from "./runtime-RYvEtg99.js";
 import { RecordStore, Type } from "./types/symbols.js";
 import { isResourceSchema } from "./types/schema/fields.js";
-import { t as DefaultCachePolicy } from "./store-C0p6sclI.js";
+import { t as DefaultCachePolicy } from "./store-dZViNfMK.js";
 
-//#region src/reactive/-private/document.ts
+// src/reactive/-private/document.ts
 function urlFromLink(link) {
 	if (typeof link === "string") return link;
 	return link.href;
@@ -20,10 +20,15 @@ function urlFromLink(link) {
 * returned by `Cache.put` or `Cache.peek`, converting ResourceKeys into
 * ReactiveResource instances.
 *
+* The [Using The Response](/guides/the-manual/requests/using-the-response) guide
+* shows when a request's content is a ReactiveDocument.
+*
 * It is not directly instantiated by the user, and its properties should not
 * be directly modified. Whether individual properties are mutable or not is
 * determined by the record instance itself.
 *
+* @summary The reactive wrapper around a request's response document that exposes its data or errors
+* as live records, plus meta, links, and pagination helpers.
 * @public
 */
 const ReactiveDocumentProto = {
@@ -143,8 +148,7 @@ function createReactiveDocument(store, cacheKey, localCache) {
 	return doc;
 }
 
-//#endregion
-//#region src/store/-private/debug/utils.ts
+// src/store/-private/debug/utils.ts
 const TEXT_COLORS = {
 	TEXT: "inherit",
 	notify: [
@@ -373,8 +377,7 @@ function _log(scope, prefix, subScop1, subScop2, subScop3, subScop4) {
 	return [];
 }
 
-//#endregion
-//#region src/store/-private/caches/resource-utils.ts
+// src/store/-private/caches/resource-utils.ts
 function isResource(resource) {
 	return Boolean(resource && typeof resource === "object");
 }
@@ -391,8 +394,7 @@ function hasType(resource) {
 	return hasProp(resource, "type");
 }
 
-//#endregion
-//#region src/store/-private/utils/coerce-id.ts
+// src/store/-private/utils/coerce-id.ts
 /**
 * Normalizes a resource `id` entering the store to a string (or `null`).
 *
@@ -428,8 +430,7 @@ function ensureStringId(id) {
 	return normalized;
 }
 
-//#endregion
-//#region src/store/-private/utils/normalize-model-name.ts
+// src/store/-private/utils/normalize-model-name.ts
 /**
 * Normalizes a resource `type` to its dasherized form, e.g. `myClass` to
 * `my-class`. Re-exported elsewhere as `_deprecatingNormalize`.
@@ -444,8 +445,7 @@ function normalizeModelName(type) {
 	return type;
 }
 
-//#endregion
-//#region src/store/-private/managers/cache-key-manager.ts
+// src/store/-private/managers/cache-key-manager.ts
 /**
 * Type-guard that returns `true` if the given value is a stable {@link ResourceKey}
 * (as opposed to a {@link RequestKey} or arbitrary, not-yet-stabilized resource data).
@@ -460,6 +460,57 @@ function isResourceKey(identifier) {
 function isRequestKey(identifier) {
 	return !!identifier && typeof identifier === "object" && "type" in identifier && !("id" in identifier) && identifier.type === "@document" && identifier[CACHE_OWNER] !== void 0;
 }
+/**
+* The identity of a field's value, as returned by {@link fieldValueIdentity}.
+* Today only schema-object values (a `schema-object` field, or one element of
+* a `schema-array`) have one: the concrete schema-object type the value
+* resolves to, and the identity hash that type's `ObjectSchema` declares for
+* it, or `null` when the schema declares `identity: null`.
+*/
+/**
+* The identity of `value` as a value of `field`, when the field kind has one.
+*
+* A `schema-object` value, or one element of a `schema-array`, resolves to its
+* concrete schema-object type and the identity hash that type's `ObjectSchema`
+* declares (`null` when the schema declares `identity: null`). A
+* non-polymorphic field names the type directly; a polymorphic field reads it
+* off the value at `options.type` (default `'type'`), or computes it with the
+* hash function named by `field.type` when `options.type` is `'@hash'`.
+*
+* Every other field kind, and any non-object value, has no identity and
+* returns `null`.
+*/
+function fieldValueIdentity(schema, field, value) {
+	if (field.kind !== "schema-object" && field.kind !== "schema-array") return null;
+	if (!value || typeof value !== "object") return null;
+	const rawValue = value;
+	let type;
+	if (field.options?.polymorphic) {
+		const typePath = field.options.type ?? "type";
+		if (typePath === "@hash") {
+			((test) => {
+				if (!test) throw new Error(`Expected the field to define a hashFn as its type`);
+			})(field.type);
+			type = schema.hashFn({ type: field.type })(rawValue, null, null);
+		} else {
+			type = rawValue[typePath];
+			((test) => {
+				if (!test) throw new Error(`Expected the type path for the field to be a value on the raw object`);
+			})(typePath && type && typeof type === "string");
+		}
+	} else {
+		((test) => {
+			if (!test) throw new Error(`A non-polymorphic ${field.kind} field must provide a SchemaObject type in its definition`);
+		})(field.type);
+		type = field.type;
+	}
+	const hashField = schema.resource({ type }).identity;
+	const hash = hashField && hashField.kind === "@hash" ? schema.hashFn(hashField)(rawValue, hashField.options ?? null, hashField.name) : null;
+	return {
+		type,
+		hash
+	};
+}
 const _crypto = typeof FastBoot !== "undefined" ? FastBoot.require("crypto") : globalThis.crypto;
 function uuidv4() {
 	((test) => {
@@ -540,6 +591,8 @@ implement this hook.
 
 ⚠️ Caution: Requests that do not have a `method` assigned are assumed to be `GET`
 
+@summary Overrides how the store generates `lid` cache keys for resources and documents; must be set
+before the store is created.
 @public
 */
 function setIdentifierGenerationMethod(method) {
@@ -574,6 +627,8 @@ prior to this `UpdateMethod` being called; however, calls to the parent method
 `updateRecordIdentifier` that attempt to change the `id` or calling update
 without providing an `id` when one is missing will throw an error.
 
+@summary Registers a callback run when an existing resource key receives new data, for updating your
+own secondary lookup tables.
 @public
 */
 function setIdentifierUpdateMethod(method) {
@@ -591,6 +646,8 @@ import { setIdentifierForgetMethod } from '@warp-drive-mirror/core';
 Takes method which can expect to receive an existing `Identifier` that should be eliminated
 from any secondary lookup tables or caches that the user has populated for it.
 
+@summary Registers a callback run when the store releases a resource key, for cleaning up your own
+lookup tables.
 @public
 */
 function setIdentifierForgetMethod(method) {
@@ -610,6 +667,8 @@ Takes a method which can expect to be called when the parent application is dest
 If you have properly used a WeakMap to encapsulate the state of your customization
 to the application instance, you may not need to implement the `resetMethod`.
 
+@summary Registers a callback run when the store's key cache is torn down, for resetting any custom
+key-generation state.
 @public
 */
 function setIdentifierResetMethod(method) {
@@ -628,6 +687,8 @@ This configuration MUST occur prior to the store instance being created.
 import { setKeyInfoForResource } from '@warp-drive-mirror/core';
 ```
 
+@summary Overrides how the store derives the `type` and `id` of a new `ResourceKey` from resource data;
+must be set before the store is created.
 @public
 */
 function setKeyInfoForResource(method) {
@@ -1082,8 +1143,7 @@ function addResourceToCache(cache, identifier) {
 	if (identifier.id) typeSet.id.set(identifier.id, identifier);
 }
 
-//#endregion
-//#region src/store/-private/managers/cache-capabilities-manager.ts
+// src/store/-private/managers/cache-capabilities-manager.ts
 var CacheCapabilitiesManager = class {
 	/** @internal */
 	/** @internal */
@@ -1188,8 +1248,7 @@ var CacheCapabilitiesManager = class {
 */
 function assertPrivateCapabilities(manager) {}
 
-//#endregion
-//#region src/store/-private/caches/instance-cache.ts
+// src/store/-private/caches/instance-cache.ts
 function isDestroyable(record) {
 	return Boolean(record && typeof record === "object" && typeof record.destroy === "function");
 }
@@ -1211,6 +1270,7 @@ const identifier = recordIdentifierFor(record);
 const { id, type, lid } = identifier;
 ```
 
+@summary Returns the stable `ResourceKey` (type, id, and lid) the store assigned to a record instance.
 @public
 @param record a record instance previously obstained from the store.
 */
@@ -1476,8 +1536,7 @@ function unloadRecord(instances, identifier) {
 	}
 }
 
-//#endregion
-//#region src/store/-private/managers/cache-manager.ts
+// src/store/-private/managers/cache-manager.ts
 /**
 * The CacheManager wraps a Cache enforcing that only
 * the public API surface area is exposed.
@@ -1561,7 +1620,8 @@ var CacheManager = class {
 	* Push resource data from a remote source into the cache for this ResourceKey
 	*
 	* @public
-	* @return if `hasRecord` is true then calculated key changes should be returned
+	* @return when `hasRecord` is true, the names of the attributes whose persisted value
+	*   this push changed, or `undefined` when none did. Otherwise `void`.
 	*/
 	upsert(key, data, hasRecord) {
 		return this.___cache.upsert(key, data, hasRecord);
@@ -1863,13 +1923,18 @@ var CacheManager = class {
 	}
 };
 
-//#endregion
-//#region src/store/-private/managers/notification-manager.ts
+// src/store/-private/managers/notification-manager.ts
 /**
 * The kinds of change notifications the {@link NotificationManager} can emit for a resource.
+*
+* @summary The lifecycle notification kinds sent to resource subscribers: `added`, `removed`, `updated`,
+* or `state`.
 */
 /**
 * The kinds of change notifications the {@link NotificationManager} can emit for a request document.
+*
+* @summary The notification kinds sent to request document subscribers, such as `updated` or
+* `invalidated`.
 */
 function isCacheOperationValue(value) {
 	return value === "added" || value === "state" || value === "updated" || value === "removed" || value === "invalidated";
@@ -1877,6 +1942,9 @@ function isCacheOperationValue(value) {
 /**
 * The full set of notification kinds the {@link NotificationManager} can emit for a resource,
 * including both {@link CacheOperation}s and finer-grained field-level change notifications.
+*
+* @summary Every notification kind a resource subscriber can receive, from lifecycle operations to
+* `attributes`, `relationships`, `errors`, `meta`, and `identity` changes.
 */
 /**
 * The shape accepted by {@link NotificationManager.notify} and
@@ -1884,6 +1952,8 @@ function isCacheOperationValue(value) {
 * the `'attributes'` or `'relationships'` namespaces in a single call
 * instead of once per key.
 *
+* @summary A set of field names passed to `notify` or `notifyChange` to report many `attributes` or
+* `relationships` changes in one call.
 * @since 5.9.0
 * @public
 */
@@ -1918,6 +1988,8 @@ function isCacheOperationValue(value) {
 * `DocumentCacheOperation` values) are never filtered by channel since they
 * have no local/remote duality.
 *
+* @summary Scopes an `attributes` or `relationships` notification to a resource's local (editable) or
+* remote (persisted) view so only matching subscribers hear it.
 * @public
 */
 /**
@@ -2054,6 +2126,8 @@ function _unsubscribe(token, cache) {
 * This Feature is what allows WarpDrive to create subscriptions that
 * work with any framework or change-notification system.
 *
+* @summary The store service that lets code subscribe to and batch-deliver change notifications for
+* cached resources and request documents.
 * @hideconstructor
 * @public
 */
@@ -2268,8 +2342,7 @@ function hasSubscribers(cache, cacheKey, value) {
 	return Boolean(callbackMap?.length);
 }
 
-//#endregion
-//#region src/store/-private/record-arrays/-utils.ts
+// src/store/-private/record-arrays/-utils.ts
 /**
 * LegacyArrays have the capability of updating via `array.update()`
 * and saving each contained record individually via `array.save()`
@@ -2348,8 +2421,7 @@ function safeForEach$1(instance, arr, store, callback, target) {
 	return instance;
 }
 
-//#endregion
-//#region src/reactive/-private/fields/extension.ts
+// src/reactive/-private/fields/extension.ts
 function expectNever(value) {}
 function isExtensionProp(extensions, prop) {
 	return Boolean(extensions && typeof prop !== "number" && extensions.has(prop));
@@ -2437,8 +2509,7 @@ function performArrayExtensionGet(receiver, extensions, signals, prop, _SIGNAL,
 	}
 }
 
-//#endregion
-//#region src/store/-private/record-arrays/native-proxy-type-fix.ts
+// src/store/-private/record-arrays/native-proxy-type-fix.ts
 /**
 * The global `Proxy` constructor, retyped with the corrected
 * {@link ProxyConstructor} signature above so that `target` and `receiver`
@@ -2448,8 +2519,7 @@ function performArrayExtensionGet(receiver, extensions, signals, prop, _SIGNAL,
 */
 const NativeProxy = Proxy;
 
-//#endregion
-//#region src/store/-private/record-arrays/resource-array.ts
+// src/store/-private/record-arrays/resource-array.ts
 const IS_COLLECTION = getOrSetGlobal("IS_COLLECTION", Symbol.for("Collection"));
 function isContextProp(prop) {
 	return prop === "destroy" || prop === "isDestroying" || prop === "isDestroyed";
@@ -2476,10 +2546,15 @@ const MUTABLE_PROPS = [
 * as the base for relationship and legacy record-array types such as
 * {@link LegacyLiveArray}, {@link LegacyQueryArray} and {@link LegacyManyArray}.
 *
+* The [Key Terminology](/guides/the-manual/caching/key-terms#resources) guide explains
+* how it relates to resources.
+*
 * Behaves like a native Array: `Array.isArray(arr)` and `arr instanceof Array`
 * both report `true`. The array stays in sync with the cache, updating
 * reactively as the underlying {@link ResourceKey}s change.
 *
+* @summary Native-Array-compatible reactive list of records backed by cache keys, returned for collection responses
+* and underlying relationship and legacy record arrays.
 * @public
 */
 /**
@@ -2736,8 +2811,7 @@ function createRequestCollection(config) {
 	});
 }
 
-//#endregion
-//#region src/store/-private/record-arrays/legacy-live-array.ts
+// src/store/-private/record-arrays/legacy-live-array.ts
 /**
 * LiveArrays contain all the known records for a given `ResourceType`.
 *
@@ -2798,6 +2872,8 @@ function createRequestCollection(config) {
 * and "bmw" will have populated LiveArrays, but the LiveArray for "car"
 * would be empty.
 *
+* @summary Legacy reactive array of every record of one type in the store, returned by `store.peekAll` and
+* `store.findAll`.
 * @legacy we recommend againt using LiveArrays. Use {@link Store.request} instead
 */
 /**
@@ -2841,8 +2917,7 @@ function _updateLiveArray() {
 	return context.store.findAll(this.modelName, { reload: true });
 }
 
-//#endregion
-//#region src/store/-private/record-arrays/legacy-query.ts
+// src/store/-private/record-arrays/legacy-query.ts
 /**
 * QueryArrays contain the primary records returned when querying
 * for records by `ResourceType`.
@@ -2913,6 +2988,8 @@ function _updateLiveArray() {
 * from the cache, but it does remove the array as well as the overhead it requires
 * from the store for book-keeping.
 *
+* @summary Legacy immutable reactive array of the primary records returned by `store.query`, refreshable with
+* `update()` and released with `destroy()`.
 * @legacy we recommend againt using QueryArrays. Use {@link Store.request} instead
 */
 /**
@@ -2975,8 +3052,7 @@ function destroyCollection(clear) {
 	manager._pending.delete(this);
 }
 
-//#endregion
-//#region src/store/-private/managers/record-array-manager.ts
+// src/store/-private/managers/record-array-manager.ts
 const FAKE_ARR = getOrSetGlobal("FAKE_ARR", {});
 const SLICE_BATCH_SIZE = 4761;
 /**
@@ -3395,8 +3471,7 @@ function isLegacyLiveArray(array) {
 	return context.features !== null && context.features.DEPRECATED_CLASS_NAME === "LiveArray";
 }
 
-//#endregion
-//#region src/store/-private/network/request-cache.ts
+// src/store/-private/network/request-cache.ts
 const Touching = getOrSetGlobal("Touching", Symbol("touching"));
 const RequestPromise = getOrSetGlobal("RequestPromise", Symbol("promise"));
 const EMPTY_ARR = Object.freeze([]);
@@ -3607,8 +3682,7 @@ var RequestStateService = class {
 *
 * @private
 */
-//#endregion
-//#region src/store/-private/store-service.ts
+// src/store/-private/store-service.ts
 globalThis.setWarpDriveLogging = setLogging;
 globalThis.getWarpDriveRuntimeConfig = getRuntimeConfig;
 if (getGlobalConfig().WarpDriveMirror.debug.LOG_METRIC_COUNTS || globalThis.getWarpDriveRuntimeConfig().debug.LOG_METRIC_COUNTS) {
@@ -3720,6 +3794,10 @@ const app = new EmberApp(defaults, {
 * The `Store` is the central piece of the ***Warp*Drive** experience. It connects
 * requests for data with schemas, caching and reactivity.
 *
+* The [Setup](/guides/configuration/#configure-the-store) guide shows how to configure
+* one, and [Making Requests](/guides/the-manual/requests/) shows how to request data
+* through it.
+*
 * While it's easy to use ***just*** ***Warp*Drive**'s request management, most projects will find they
 * require far more than basic fetch management. For this reason it's often best to start with a `Store`
 * even when you aren't sure yet.
@@ -3727,6 +3805,7 @@ const app = new EmberApp(defaults, {
 * Most projects will only have a single `Store`, though using multiple distinct stores
 * is possible.
 *
+* @summary Central coordinator that connects requests for data with schemas, the cache and reactivity.
 * @public
 * @hideconstructor
 */
@@ -3934,12 +4013,25 @@ var Store = class extends BaseClass {
 		}
 	}
 	/**
-	* ::: tip 💡 For a more complete overview see the [Request Guide](/guides/2-requests/1-overview)
+	* ::: tip 💡 For a more complete overview see the [Request Guide](/guides/the-manual/requests/)
 	* :::
 	*
 	* Issue a request via the configured {@link RequestManager},
 	* inserting the response into the {@link Store.cache | cache} and handing
-	* back a {@link Future} which resolves to a {@link ReactiveDocument | ReactiveDocument}
+	* back a {@link Future} which resolves to a {@link ReactiveDocument | ReactiveDocument}.
+	* Use `store.request` for anything the Store's cache should own, which is nearly all app
+	* code; reach for {@link RequestManager.request | requestManager.request} directly only when
+	* there is no `Store` involved, or you specifically want the unprocessed
+	* {@link StructuredDocument}.
+	*
+	* #### Building Requests
+	*
+	* `requestConfig` can be written by hand, but for anything reused more than once prefer a
+	* request builder — a plain function that returns the right shape for `store.request`. This
+	* repo ships builders for common operations (`findRecord`, `query`, `createRecord`, and more)
+	* for {json:api}, REST, and ActiveRecord-style APIs in `@warp-drive-mirror/utilities`; each builder's
+	* return value also carries its own response type, so `RT` below is inferred automatically
+	* instead of being written by hand. See [Builders](/guides/the-manual/requests/builders.md).
 	*
 	* #### Request Cache Keys
 	*
@@ -3984,6 +4076,29 @@ var Store = class extends BaseClass {
 	* is that `store.request` will convert the response into a {@link ReactiveDocument}
 	* containing {@link Store.instantiateRecord | ReactiveResources}.
 	*
+	* A {@link ReactiveDocument} is either a {@link ReactiveDataDocument} (`content.data` holds
+	* the resource(s)) or a {@link ReactiveErrorDocument} (`content.errors` holds the API's error
+	* objects), depending on whether the `Future` resolves or rejects; both carry the response's
+	* `content.meta`. Read either state reactively with {@link getRequestState} or the
+	* `<Request />` component instead of always `await`-ing the `Future` directly — see
+	* [Using the Response](/guides/the-manual/requests/using-the-response.md).
+	*
+	* #### Typing The Response
+	*
+	* `request<RT>` accepts an explicit type argument, but the more common path is to let it be
+	* inferred: build the request with {@link withResponseType} (or {@link withReactiveResponse}
+	* for the common reactive-document case), or with a builder from `@warp-drive-mirror/utilities` as
+	* described above, and `RT` is inferred from the request object itself. See
+	* [Typing Requests](/guides/the-manual/requests/typing-requests.md) for the full mechanism.
+	*
+	* @example
+	* ```ts
+	* import { findRecord } from '@warp-drive-mirror/utilities/json-api';
+	*
+	* const { content } = await store.request(findRecord('user', '1'));
+	* content.data; // ReactiveResource, typed from the builder's response type
+	* ```
+	*
 	* @public
 	*/
 	request(requestConfig) {
@@ -4522,8 +4637,7 @@ function extractIdentifierFromRecord$1(recordOrPromiseRecord) {
 	return recordIdentifierFor(recordOrPromiseRecord);
 }
 
-//#endregion
-//#region src/store/-private/cache-handler/utils.ts
+// src/store/-private/cache-handler/utils.ts
 const MUTATION_OPS$1 = /* @__PURE__ */ new Set([
 	"createRecord",
 	"updateRecord",
@@ -4563,15 +4677,20 @@ function getPriority(identifier, deduped, priority) {
 	return priority;
 }
 
-//#endregion
-//#region src/store/-private/cache-handler/handler.ts
+// src/store/-private/cache-handler/handler.ts
 /**
 * The request shape accepted by {@link Store.request}, either a fully-formed
 * {@link ImmutableRequestInfo} or the looser {@link LooseStoreRequestInfo}.
+*
+* @summary The request object `store.request` accepts, either a full immutable request info or a looser
+* form with plain `records` and `headers`.
 */
 /**
 * A CacheHandler that adds support for using an WarpDrive Cache with a RequestManager.
 *
+* The [Caching](/guides/the-manual/caching/) guide explains how it decides whether a
+* request can use the cache.
+*
 * This handler will only run when a request has supplied a `store` instance. Requests
 * issued by the store via `store.request()` will automatically have the `store` instance
 * attached to the request.
@@ -4607,7 +4726,10 @@ function getPriority(identifier, deduped, priority) {
 *   method: 'GET',
 *   [EnableHydration]: true
 * });
+* ```
 *
+* @summary The RequestManager cache handler that serves, dedupes, and caches store requests and returns
+* reactive documents when hydration is enabled.
 */
 const CacheHandler = { request(context, next) {
 	if (!context.request.store || context.request.cacheOptions?.[SkipCache]) return next(context.request);
@@ -4780,14 +4902,12 @@ function fetchContentAndHydrate(next, context, identifier, priority) {
 	}] });
 }
 
-//#endregion
-//#region src/store/-private/utils/is-non-empty-string.ts
+// src/store/-private/utils/is-non-empty-string.ts
 function isNonEmptyString(str) {
 	return Boolean(str && typeof str === "string");
 }
 
-//#endregion
-//#region src/store/-private/utils/construct-resource.ts
+// src/store/-private/utils/construct-resource.ts
 /**
 * Given an existing resource identifier object (or a {@link ResourceKey}),
 * returns it unchanged aside from coercing its `id`, if present, to a string.
@@ -4859,8 +4979,7 @@ function constructResource(type, id, lid) {
 	}
 }
 
-//#endregion
-//#region src/store/-private/record-arrays/legacy-many-array.ts
+// src/store/-private/record-arrays/legacy-many-array.ts
 /**
 A `ManyArray` is a `MutableArray` that represents the contents of a has-many
 relationship.
@@ -4901,6 +5020,7 @@ the has-many.
 We call the record to which a relationship belongs-to the
 relationship's _owner_.
 
+@summary Legacy mutable reactive array holding the related records of a legacy or linksMode has-many relationship.
 @public
 */
 /**
@@ -4932,7 +5052,7 @@ function createLegacyManyArray(options) {
 			isAsync: options.isAsync,
 			isPolymorphic: options.isPolymorphic,
 			identifier: options.identifier,
-			key: options.field.name,
+			key: options.field.sourceKey ?? options.field.name,
 			reload,
 			createRecord,
 			notify
@@ -5131,8 +5251,7 @@ function mutate(collection, mutation, _SIGNAL) {
 	notifyInternalSignal(_SIGNAL);
 }
 
-//#endregion
-//#region src/reactive/-private/kind/alias-field.ts
+// src/reactive/-private/kind/alias-field.ts
 function getAliasField(context) {
 	((test) => {
 		if (!test) throw new Error(`Alias field access is not implemented`);
@@ -5145,8 +5264,7 @@ function setAliasField(context) {
 	return false;
 }
 
-//#endregion
-//#region src/reactive/-private/fields/managed-array.ts
+// src/reactive/-private/fields/managed-array.ts
 const ARRAY_GETTER_METHODS = /* @__PURE__ */ new Set([
 	Symbol.iterator,
 	"concat",
@@ -5246,31 +5364,11 @@ var ManagedArray = class {
 						if (field.type) return schema.transformation(field).hydrate(rawValue, field.options ?? null, self.owner);
 						return rawValue;
 					}
-					/**
-					* When the array is polymorphic, we need to determine the real type
-					* in order to apply the correct identity as schema-object identity
-					* is only required to be unique by type
-					*/
-					let objectType;
-					if (field.options?.polymorphic) {
-						const typePath = field.options.type ?? "type";
-						if (typePath === "@hash") {
-							((test) => {
-								if (!test) throw new Error(`Expected the field to define a hashFn as its type`);
-							})(field.type);
-							objectType = schema.hashFn({ type: field.type })(rawValue, null, null);
-						} else {
-							objectType = rawValue[typePath];
-							((test) => {
-								if (!test) throw new Error(`Expected the type path for the field to be a value on the raw object`);
-							})(typePath && objectType && typeof objectType === "string");
-						}
-					} else {
-						((test) => {
-							if (!test) throw new Error(`A non-polymorphic SchemaArrayField must provide a SchemaObject type in its definition`);
-						})(field.type);
-						objectType = field.type;
-					}
+					const identity = fieldValueIdentity(schema, field, rawValue);
+					((test) => {
+						if (!test) throw new Error(`Expected a schema-array element to resolve to a schema-object identity`);
+					})(identity !== null);
+					const { type: objectType, hash } = identity;
 					/**
 					* When KeyMode=@hash the ReactiveResource is keyed into
 					* ManagedRecordRefs by the return value of @hash on the rawValue.
@@ -5280,8 +5378,10 @@ var ManagedArray = class {
 					*/
 					let schemaObjectKeyValue;
 					if (KeyMode === "@hash") {
-						const hashField = schema.resource({ type: objectType }).identity;
-						schemaObjectKeyValue = schema.hashFn(hashField)(rawValue, hashField.options ?? null, hashField.name);
+						((test) => {
+							if (!test) throw new Error(`Expected the '${objectType}' schema to declare an identity hash for key: '@hash'`);
+						})(hash !== null);
+						schemaObjectKeyValue = hash;
 					} else {
 						if (KeyMode !== "@identity" && KeyMode !== "@index") {
 							((test) => {
@@ -5426,8 +5526,7 @@ Object.defineProperty(ManagedArray.prototype, "[]", {
 	get: function() {}
 });
 
-//#endregion
-//#region src/reactive/-private/kind/array-field.ts
+// src/reactive/-private/kind/array-field.ts
 function getArrayField(context) {
 	const signal = entangleSignal(context.signals, context.record, context.path.at(-1), null);
 	const { record } = context;
@@ -5473,8 +5572,7 @@ function setArrayField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/attribute-field.ts
+// src/reactive/-private/kind/attribute-field.ts
 function getAttributeField(context) {
 	entangleInitiallyStaleSignal(context.signals, context.record, context.path.at(-1), null);
 	const { cache } = context.store;
@@ -5485,8 +5583,7 @@ function setAttributeField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/fields/get-field-key.ts
+// src/reactive/-private/fields/get-field-key.ts
 const InvalidKinds = [
 	"alias",
 	"derived",
@@ -5505,8 +5602,7 @@ function getFieldCacheKey(field) {
 	return "sourceKey" in field && field.sourceKey ? field.sourceKey : field.name;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/belongs-to-field.ts
+// src/reactive/-private/kind/belongs-to-field.ts
 function getBelongsToField(context) {
 	entangleSignal(context.signals, context.record, context.path.at(-1), null);
 	const { field, resourceKey, store } = context;
@@ -5549,8 +5645,7 @@ function getResourceKey(record) {
 	return recordIdentifierFor(record);
 }
 
-//#endregion
-//#region src/reactive/-private/kind/collection-field.ts
+// src/reactive/-private/kind/collection-field.ts
 function getCollectionField(context) {
 	entangleSignal(context.signals, context.record, context.path.at(-1), null);
 	((test) => {
@@ -5564,8 +5659,7 @@ function setCollectionField(context) {
 	return false;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/derived-field.ts
+// src/reactive/-private/kind/derived-field.ts
 function getDerivedField(context) {
 	const { schema } = context.store;
 	return schema.derivation(context.field)(context.record, context.field.options ?? null, context.field.name);
@@ -5577,8 +5671,7 @@ function setDerivedField(context) {
 	return false;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/generic-field.ts
+// src/reactive/-private/kind/generic-field.ts
 function getGenericField(context) {
 	const signal = entangleInitiallyStaleSignal(context.signals, context.record, context.path.at(-1), null);
 	signal.isStale = false;
@@ -5600,8 +5693,7 @@ function setGenericField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/fields/many-array-manager.ts
+// src/reactive/-private/fields/many-array-manager.ts
 var ManyArrayManager = class {
 	constructor(record, editable) {
 		const context = record[Context];
@@ -5663,8 +5755,7 @@ function extractCacheOptions(options) {
 	return cacheOptions;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/has-many-field.ts
+// src/reactive/-private/kind/has-many-field.ts
 function getHasManyField(context) {
 	const signal = entangleSignal(context.signals, context.record, context.path.at(-1), null);
 	const { store, field } = context;
@@ -5710,8 +5801,7 @@ function setHasManyField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/hash-field.ts
+// src/reactive/-private/kind/hash-field.ts
 function getHashField(context) {
 	const { field, path, resourceKey } = context;
 	const { schema, cache } = context.store;
@@ -5729,8 +5819,7 @@ function setHashField(context) {
 	return false;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/identity-field.ts
+// src/reactive/-private/kind/identity-field.ts
 function getIdentityField(context) {
 	entangleSignal(context.signals, context.record, "@identity", null);
 	return context.resourceKey.id;
@@ -5752,8 +5841,7 @@ function setIdentityField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/local-field.ts
+// src/reactive/-private/kind/local-field.ts
 function getLocalField(context) {
 	const { field } = context;
 	const signal = getOrCreateInternalSignal(context.signals, context.record, field.name, field.options?.defaultValue ?? null);
@@ -5770,8 +5858,7 @@ function setLocalField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/fields/managed-object.ts
+// src/reactive/-private/fields/managed-object.ts
 const ObjectSymbols = /* @__PURE__ */ new Set([
 	OBJECT_SIGNAL,
 	Context,
@@ -5855,8 +5942,7 @@ function peekManagedObject(record, field) {
 	if (managedObjectMapForRecord) return managedObjectMapForRecord.get(field.name);
 }
 
-//#endregion
-//#region src/reactive/-private/kind/object-field.ts
+// src/reactive/-private/kind/object-field.ts
 function getObjectField(context) {
 	entangleSignal(context.signals, context.record, context.path.at(-1), null);
 	const { record, field } = context;
@@ -5912,8 +5998,7 @@ function setObjectField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/resource-field.ts
+// src/reactive/-private/kind/resource-field.ts
 var ResourceRelationship = class {
 	constructor(context) {
 		const { store, resourceKey } = context;
@@ -5956,8 +6041,7 @@ function setResourceField(context) {
 	return false;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/schema-array-field.ts
+// src/reactive/-private/kind/schema-array-field.ts
 function setSchemaArrayField(context) {
 	const arrayValue = context.value === null ? null : context.value?.slice();
 	const fieldSignal = peekInternalSignal(context.signals, context.path.at(-1));
@@ -5974,8 +6058,7 @@ function setSchemaArrayField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/kind/schema-object-field.ts
+// src/reactive/-private/kind/schema-object-field.ts
 function getSchemaObjectField(context) {
 	const signal = entangleSignal(context.signals, context.record, context.path.at(-1), null);
 	const { store, resourceKey, path, field } = context;
@@ -5992,29 +6075,12 @@ function getSchemaObjectField(context) {
 		}
 		return null;
 	}
-	const { schema } = store;
-	let objectType;
-	if (field.options?.polymorphic) {
-		const typePath = field.options.type ?? "type";
-		if (typePath === "@hash") {
-			((test) => {
-				if (!test) throw new Error(`Expected the field to define a hashFn as its type`);
-			})(field.type);
-			objectType = schema.hashFn({ type: field.type })(rawValue, null, null);
-		} else {
-			objectType = rawValue[typePath];
-			((test) => {
-				if (!test) throw new Error(`Expected the type path for the field to be a value on the raw object`);
-			})(typePath && objectType && typeof objectType === "string");
-		}
-	} else {
-		((test) => {
-			if (!test) throw new Error(`A non-polymorphic SchemaObjectField must provide a SchemaObject type in its definition`);
-		})(field.type);
-		objectType = field.type;
-	}
-	const hashField = schema.resource({ type: objectType }).identity;
-	const identity = hashField ? schema.hashFn(hashField)(rawValue, hashField.options ?? null, hashField.name) : field.name;
+	const resolved = fieldValueIdentity(store.schema, field, rawValue);
+	((test) => {
+		if (!test) throw new Error(`Expected a schema-object value to resolve to a schema-object identity`);
+	})(resolved !== null);
+	const { type: objectType, hash } = resolved;
+	const identity = hash ?? field.name;
 	const cachedSchemaObject = signal.value;
 	if (cachedSchemaObject) {
 		if (cachedSchemaObject.type === objectType && cachedSchemaObject.identity === identity) return cachedSchemaObject.value;
@@ -6059,8 +6125,7 @@ function setSchemaObjectField(context) {
 	return true;
 }
 
-//#endregion
-//#region src/reactive/-private/default-mode.ts
+// src/reactive/-private/default-mode.ts
 /**
 * A ReactiveResource context object passed to
 * the get/set functions of a field kind implementation.
@@ -6176,14 +6241,15 @@ const DefaultMode = {
 	}
 };
 
-//#endregion
-//#region src/reactive/-private/record.ts
+// src/reactive/-private/record.ts
 const IgnoredGlobalFields = /* @__PURE__ */ new Set([
 	"length",
 	"nodeType",
 	"then",
 	"setInterval",
 	"document",
+	"unknownProperty",
+	"size",
 	STRUCTURED
 ]);
 const RecordSymbols = /* @__PURE__ */ new Set([
@@ -6208,10 +6274,14 @@ const Editables = /* @__PURE__ */ new Map();
 * and a ResourceKey to transform data from the cache into a rich, reactive
 * object.
 *
+* The [ResourceSchemas](/guides/the-manual/schemas/resources/) guide shows how to
+* define the schema it reads.
+*
 * This class is not directly instantiable. To use it, you should
 * configure the store's `instantiateRecord` and `teardownRecord` hooks
 * with the matching hooks provided by this package.
 *
+* @summary The rich, reactive record object that presents a resource's cached data through its `ResourceSchema`.
 * @hideconstructor
 * @public
 */
@@ -6665,6 +6735,8 @@ function assertNeverField(identifier, field, path) {
 * Edits to editable resources will be automatically committed if a new
 * payload from the cache matches their existing value.
 *
+* @summary Resolves with an editable copy of an immutable `ReactiveResource` so its fields can be
+* changed locally.
 * @public
 *
 * @returns a promise that resolves to the editable resource
@@ -6681,14 +6753,15 @@ function checkout(resource) {
 * approach is for either the API or a Handler to reflect saved
 * changes back to update the cache.
 *
+* @summary Forcibly makes an editable resource's local changes its new remote (immutable) state,
+* bypassing a save round-trip.
 * @public
 */
 function commit(record) {
 	return record[Commit]();
 }
 
-//#endregion
-//#region src/reactive/-private/hooks.ts
+// src/reactive/-private/hooks.ts
 /**
 * The store's default `instantiateRecord` hook implementation, which
 * produces a {@link ReactiveResource} for `identifier` using the resource
@@ -6698,6 +6771,8 @@ function commit(record) {
 * schema is `legacy`, matching the historical behavior of assigning initial
 * properties when creating a new legacy record.
 *
+* @summary Default store `instantiateRecord` hook that creates a `ReactiveResource` for a resource key
+* from its registered schema.
 * @public
 */
 function instantiateRecord(store, identifier, createArgs) {
@@ -6730,6 +6805,8 @@ function assertReactiveResource(record) {
 * that `record` is a {@link ReactiveResource} and invokes its `Destroy`
 * behavior.
 *
+* @summary Default store `teardownRecord` hook that destroys a `ReactiveResource` when the store
+* releases it.
 * @public
 */
 function teardownRecord(record) {
@@ -6737,8 +6814,7 @@ function teardownRecord(record) {
 	record[Destroy]();
 }
 
-//#endregion
-//#region src/reactive/-private/schema.ts
+// src/reactive/-private/schema.ts
 const Support = getOrSetGlobal("Support", /* @__PURE__ */ new WeakMap());
 const ConstructorField = {
 	type: "@constructor",
@@ -6784,16 +6860,25 @@ _constructor[Type] = "@constructor";
 * This should only be used for temporary migration purposes
 * to the new schema system when migrating from either Model
 * or ModelFragments.
+*
+* @summary Registers named methods, getters, and values to add to ReactiveResources, ReactiveObjects,
+* or ReactiveArrays; meant only as a temporary aid when migrating from Model or ModelFragments.
 */
 /**
 * Describes one feature added to a resource by a schema extension, as
 * classified by {@link processExtension} from the property descriptor it
 * was declared with (a method, a plain value, or a getter/setter pair).
+*
+* @summary One normalized feature of a schema extension, tagged by kind as a method, a readonly or
+* mutable value, or a getter/setter accessor.
 */
 /**
 * The result of {@link processExtension} normalizing a
 * {@link CAUTION_MEGA_DANGER_ZONE_Extension} into a lookup of its features
 * by name.
+*
+* @summary A registered schema extension normalized into its kind, name, and a map of its features
+* keyed by property name.
 */
 const BannedKeys = ["constructor", "__proto__"];
 function processExtension(extension) {
@@ -6893,14 +6978,19 @@ function processExtensions(schema, field, scenario, resolvedType) {
 * Utility for constructing a ResourceSchema with the recommended
 * fields for the PolarisMode experience.
 *
+* The [ResourceSchemas](/guides/the-manual/schemas/resources/) guide shows how to
+* create a schema with it.
+*
 * Using this requires registering the PolarisMode derivations
 *
 * ```ts
-* import { registerDerivations } from '@warp-drive-mirror/schema-record';
+* import { registerDerivations } from '@warp-drive-mirror/core/reactive';
 *
 * registerDerivations(schema);
 * ```
 *
+* @summary Adds the default `id` identity plus `$key`, `$type`, and `constructor` derived fields to a
+* PolarisMode resource schema.
 * @public
 * @param schema
 * @return {PolarisResourceSchema}
@@ -6931,6 +7021,8 @@ function withDefaults(schema) {
 *
 * `^` returns the entire identifier object.
 *
+* @summary The `@identity` derivation, which reads a record's `id`, `lid`, `type`, or whole resource key
+* for use in derived fields.
 * @public
 */
 const fromIdentity = (record, options, key) => {
@@ -6954,9 +7046,14 @@ fromIdentity[Type] = "@identity";
 * to use the PolarisMode defaults provided by
 *
 * ```ts
-* import { withDefaults } from '@warp-drive-mirror/schema-record';
+* import { withDefaults } from '@warp-drive-mirror/core/reactive';
 * ```
 *
+* The [Derivations](/guides/the-manual/schemas/derivations#about-built-in-derivations)
+* guide explains when you need to call it.
+*
+* @summary Registers the `@identity` and `@constructor` derivations that schemas built with
+* `withDefaults` depend on.
 * @public
 */
 function registerDerivations(schema) {
@@ -7032,6 +7129,9 @@ function assertConsistentAbstractFieldShape(abstractType, fieldName, existing, i
 * Defines how to convert a `GenericField`, `ObjectField`, or `ArrayField`
 * between the raw value `T` stored in the cache and the presentation value
 * `PT` exposed on the record.
+*
+* @summary A registered converter between a field's raw cache value and the value exposed on the
+* record, with optional default.
 */
 /**
 * Wraps a derivation in a new function with Derivation signature but that looks
@@ -7054,6 +7154,12 @@ function makeCachedDerivation(derivation) {
 /**
 * A SchemaService designed to work with dynamically registered schemas.
 *
+* The [Schemas](/guides/the-manual/schemas/) guide shows how to register schemas
+* with it, and [Advanced Store Configuration](/guides/configuration/advanced#add-a-source-for-schema-for-your-data)
+* shows how to give a store one.
+*
+* @summary The default schema service, which stores resource and object schemas, traits, derivations,
+* transformations, hash functions and extensions registered at runtime.
 * @public
 */
 var SchemaService = class {
@@ -7443,284 +7549,7 @@ function mergeMap(base, toApply) {
 	for (const [key, value] of toApply) base.set(key, value);
 }
 
-//#endregion
-//#region src/reactive.ts
-/**
-* # About
-*
-* This module provides an implementation of reactive objects that a Store may use for creating
-* reactive representations of the raw data for requests, resources and their relationships
-* stored in the cache.
-*
-* - For configuring the store to use these reactive objects, see [The Setup Guide](/guides/configuration/)
-* - For defining resource schemas, see [The Schema Guide](/guides/the-manual/schemas/)
-*
-* Any method that returns a record instance will use the `instantiateRecord`
-* hook configured above to instantiate a ReactiveResource once this is in place.
-* After that, its up to you what ReactiveResource can do.
-*
-* ## Modes
-*
-* ReactiveResource has two modes: `legacy` and `polaris`.
-*
-* **LegacyMode** can be used to emulate the behaviors and capabilities of WarpDrive's `Model` class,
-* and because there is little distinction between Model and a ReactiveResource in LegacyMode we refer
-* to both of these approaches as LegacyMode. This mode is the default experience in V5.
-*
-* In LegacyMode:
-*
-* - records are mutable
-* - local changes immediately reflect app wide
-* - records have all the APIs of Model (references, state props, currentState, methods etc)
-* - the continued use of `@warp-drive-mirror/legacy` is required (though most imports from it can be removed)
-* - `async: true` relationships are supported (but not recommended outside of [LinksMode](/guides/the-manual/misc/links-mode.md))
-*
-* ---
-*
-* **PolarisMode** is an upcoming suite of features that will become the default experience in V6.
-*
-* In PolarisMode:
-*
-* - records are immutable, unless creating a new resource or explicitly checking out a record for editing
-* - local changes are isolated until committed, displaying only via the editable version of the record
-* - records have a more limited API, focused on only what is in their schema.
-* - some common operations may have more friction to perform because intended utilities are not yet available
-* - `async: true` relationships are not supported (see [LinksMode](/guides/the-manual/misc/links-mode.md))
-* - The `@warp-drive-mirror/legacy` package is not required
-*
-* These modes are interopable. The reactive object (record) for a resource in PolarisMode can relate to
-* a record in LegacyMode and vice-versa. This interopability is true whether the record in LegacyMode is
-* a ReactiveResource or a Model.
-*
-* ---
-*
-* ## Basic Usage
-*
-* ReactiveResource is a reactive object that transforms raw data from an associated
-* cache into reactive data backed by Signals.
-*
-* The shape of the object and the transformation of raw cache data into its
-* reactive form is controlled by a resource schema.
-*
-* For instance, lets say your API is a [{json:api}](https://jsonapi.org) and your store is using
-* the Cache provided by {@link @warp-drive-mirror/json-api! | @warp-drive-mirror/json-api}, and a request
-* returns the following raw data:
-*
-* ```ts
-* {
-*   data: {
-*     type: 'user',
-*     id: '1',
-*     attributes: { firstName: 'Chris', lastName: 'Thoburn' },
-*     relationships: { pets: { data: [{ type: 'dog', id: '1' }] }}
-*   },
-*   included: [
-*     {
-*       type: 'dog',
-*       id: '1',
-*       attributes: { name: 'Rey' },
-*       relationships: { owner: { data: { type: 'user', id: '1' }}}
-*     }
-*   ]
-* }
-* ```
-*
-* We could describe the `'user'` and `'dog'` resources in the above payload
-* with the following schemas:
-*
-* ```ts
-* store.schema.registerResources([
-*   {
-*     type: 'user',
-*     identity: { type: '@id', name: 'id' },
-*     fields: [
-*       {
-*         type: '@identity',
-*         name: '$type',
-*         kind: 'derived',
-*         options: { key: 'type' },
-*       },
-*       { kind: 'field', name: 'firstName' },
-*       { kind: 'field', name: 'lastName' },
-*       {
-*         kind: 'derived',
-*         name: 'name',
-*         type: 'concat',
-*         options: { fields: ['firstName', 'lastName'], separator: ' ' }
-*       },
-*       {
-*         kind: 'hasMany',
-*         name: 'pets',
-*         type: 'pet',
-*         options: {
-*           async: false,
-*           inverse: 'owner',
-*           polymorphic: true,
-*           linksMode: true,
-*         }
-*       }
-*     ]
-*   },
-*   {
-*     type: 'dog',
-*     identity: { type: '@id', name: 'id' },
-*     fields: [
-*       {
-*         type: '@identity',
-*         name: '$type',
-*         kind: 'derived',
-*         options: { key: 'type' },
-*       },
-*       { kind: 'field', name: 'name' },
-*       {
-*         kind: 'belongsTo',
-*         name: 'owner',
-*         type: 'user',
-*         options: {
-*           async: false,
-*           inverse: 'pets',
-*           as: 'pet',
-*           linksMode: true,
-*         }
-*       }
-*     ]
-*   }
-* ]);
-* ```
-*
-* With these schemas in place, the reactive objects that the store would
-* provide us whenever we encountered a `'user'` or a `'dog'` would be:
-*
-* ```ts
-* interface Pet {
-*   readonly id: string;
-*   readonly owner: User;
-* }
-*
-* interface Dog extends Pet {
-*   readonly $type: 'dog';
-*   readonly name: string;
-* }
-*
-* interface EditableUser {
-*   readonly $type: 'user';
-*   readonly id: string;
-*   firstName: string;
-*   lastName: string;
-*   readonly name: string;
-*   pets: Array<Dog | Pet>;
-* }
-*
-* interface User {
-*   readonly $type: 'user';
-*   readonly id: string;
-*   readonly firstName: string;
-*   readonly lastName: string;
-*   readonly name: string;
-*   readonly pets: Readonly<Array<Dog | Pet>>;
-*   [Checkout](): Promise<EditableUser>
-* }>
-* ```
-*
-* Note how based on the schema the reactive object we receive is able to produce
-* `name` on user (despite no name field being in the cache), provide `$type`
-* pulled from the identity of the resource, and flatten the individual attributes
-* and relationships onto the record for easier use.
-*
-* Notice also how we typed this object with `readonly`. This is because while
-* ReactiveResource instances are ***deeply reactive***, they are also ***immutable***.
-*
-* We can mutate a ReactiveResource only be explicitly asking permission to do so, and
-* in the process gaining access to an editable copy. The immutable version will
-* not show any in-process edits made to this editable copy.
-*
-* ```ts
-* import { Checkout } from '@warp-drive-mirror/schema-record';
-*
-* const editable = await user[Checkout]();
-* ```
-*
-* ## Utilities
-*
-* ReactiveResource provides a schema builder that simplifies setting up a couple of
-* conventional fields like identity and `$type`. We can rewrite the schema
-* definition above using this utility like so:
-*
-* ```ts
-* import { withDefaults } from '@warp-drive-mirror/core/reactive';
-*
-* store.schema.registerResources([
-*   withDefaults({
-*     type: 'user',
-*     fields: [
-*       { kind: 'field', name: 'firstName' },
-*       { kind: 'field', name: 'lastName' },
-*       {
-*         kind: 'derived',
-*         name: 'name',
-*         type: 'concat',
-*         options: { fields: ['firstName', 'lastName'], separator: ' ' }
-*       },
-*       {
-*         kind: 'hasMany',
-*         name: 'pets',
-*         type: 'pet',
-*         options: {
-*           async: false,
-*           inverse: 'owner',
-*           polymorphic: true,
-*           linksMode: true,
-*           resetOnRemoteUpdate: false,
-*         }
-*       }
-*     ]
-*   }),
-*   withDefaults({
-*     type: 'dog',
-*     fields: [
-*       { kind: 'field', name: 'name' },
-*       {
-*         kind: 'belongsTo',
-*         name: 'owner',
-*         type: 'user',
-*         options: {
-*           async: false,
-*           inverse: 'pets',
-*           as: 'pet',
-*           linksMode: true,
-*           resetOnRemoteUpdate: false,
-*         }
-*       }
-*     ]
-*   })
-* ]);
-* ```
-*
-* ## Type Support
-*
-* ### Resource Schemas
-*
-* - {@link PolarisResourceSchema}
-* - {@link LegacyResourceSchema}
-* - {@link ObjectSchema}
-*
-* ### Resource Schema Type Utils
-*
-* - {@link resourceSchema}
-* - {@link objectSchema}
-* - {@link isResourceSchema}
-* - {@link isLegacyResourceSchema}
-*
-* ### Field Schemas
-*
-* - {@link LegacyModeFieldSchema}
-* - {@link PolarisModeFieldSchema}
-*
-* @module
-*/
-
-//#endregion
-//#region src/request/-private/fetch.ts
+// src/request/-private/fetch.ts
 const _fetch = typeof fetch !== "undefined" ? (...args) => fetch(...args) : typeof FastBoot !== "undefined" ? (...args) => FastBoot.require("node-fetch")(...args) : () => {
 	throw new Error("No Fetch Implementation Found");
 };
@@ -7798,6 +7627,9 @@ const ERROR_STATUS_CODE_FOR = /* @__PURE__ */ new Map([
 * A basic Fetch Handler which converts a request into a
 * `fetch` call presuming the response to be `json`.
 *
+* The [Making Requests](/guides/the-manual/requests/#requests-do-not-need-to-use-fetch)
+* guide shows where it sits in the handler chain.
+*
 * ```ts
 * import { RequestManager, Fetch } from '@warp-drive-mirror/core';
 *
@@ -7805,6 +7637,8 @@ const ERROR_STATUS_CODE_FOR = /* @__PURE__ */ new Map([
 *   .use([Fetch]);
 * ```
 *
+* @summary Terminal request handler that sends the request with native `fetch` and resolves with the
+* parsed JSON body, turning HTTP failures into errors.
 * @public
 * @badge Handler
 */
@@ -7925,8 +7759,7 @@ function isDict(v) {
 	return v !== null && typeof v === "object";
 }
 
-//#endregion
-//#region src/request/-private/manager.ts
+// src/request/-private/manager.ts
 /**
 * ## Import
 *
@@ -7934,7 +7767,8 @@ function isDict(v) {
 * import { RequestManager } from '@warp-drive-mirror/core';
 * ```
 *
-* For complete usage guide see the [RequestManager Documentation](/guides/).
+* For a complete usage guide see [Making Requests](/guides/the-manual/requests/), and
+* [Handlers](/guides/the-manual/requests/handlers) for writing the handlers it runs.
 *
 * ## How It Works
 *
@@ -7957,11 +7791,28 @@ function isDict(v) {
 * ```ts [Setup.ts]
 * import { RequestManager, Fetch } from '@warp-drive-mirror/core';
 * import { AutoCompress } from '@warp-drive-mirror/utilities/handlers';
-* import Auth from 'ember-simple-auth/handler';
+* import { AuthHandler } from './auth-handler';
 *
 * // ... create manager
 * const manager = new RequestManager()
-*    .use([Auth, new AutoCompress(), Fetch]); // [!code focus]
+*    .use([AuthHandler, new AutoCompress(), Fetch]); // [!code focus]
+* ```
+*
+* ```ts [auth-handler.ts]
+* import type { Handler, NextFn } from '@warp-drive-mirror/core/request';
+* import type { RequestContext } from '@warp-drive-mirror/core/types/request';
+*
+* const token = '<token>';
+*
+* // adds a bearer token to every request, then passes it along
+* export const AuthHandler: Handler = {
+*   request<T>(context: RequestContext, next: NextFn<T>) {
+*     const headers = new Headers(context.request.headers);
+*     headers.append('Authorization', `Bearer ${token}`);
+*
+*     return next(Object.assign({}, context.request, { headers }));
+*   },
+* };
 * ```
 *
 * ```ts [Usage.ts]
@@ -7977,6 +7828,20 @@ function isDict(v) {
 *
 * :::
 *
+* ### RequestManager vs {@link Store.request}
+*
+* A bare `RequestManager` is the low-level primitive: it runs a request through the configured
+* {@link Handler | handler chain} and settles with the raw {@link StructuredDocument}. It has no
+* cache and does not hydrate {@link ReactiveDocument | ReactiveDocuments} unless you register a
+* cache handler yourself via {@link RequestManager.useCache} and the request opts in.
+*
+* {@link Store.request} issues requests through this same `RequestManager`, but with the Store's
+* cache handler and hydration already wired up — inserting the response into the Store's cache
+* and resolving with a `ReactiveDocument` instead. Use `store.request` for anything the Store's
+* cache should own, which is nearly all app code. Reach for `requestManager.request` directly
+* only when there is no {@link Store} involved, or you specifically want the unprocessed
+* `StructuredDocument`.
+*
 * ### Futures
 *
 * The return value of `manager.request` is a `Future`, which allows
@@ -8015,6 +7880,7 @@ function isDict(v) {
 * type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;
 * ```
 *
+* @summary Runs each request through a chain of handlers that can fulfill, modify, or pass it along, and returns a `Future` for the response.
 * @public
 */
 var RequestManager = class {
@@ -8074,7 +7940,23 @@ var RequestManager = class {
 	/**
 	* Issue a Request.
 	*
-	* Returns a Future that fulfills with a StructuredDocument
+	* Runs `request` through the configured {@link Handler | handler chain} and settles with the
+	* {@link StructuredDocument} the chain produces — a plain `{ request, response, content }`
+	* object, not a {@link ReactiveDocument}. Caching and hydration only happen if a cache handler
+	* has been registered via {@link RequestManager.useCache} and the request opts in; a
+	* `RequestManager` created on its own has neither.
+	*
+	* Most app code should use {@link Store.request} instead, which calls this same method with
+	* the Store's cache handler and hydration already configured. Reach for `requestManager.request`
+	* directly when there is no {@link Store} involved, or when you want the unprocessed
+	* `StructuredDocument`. The `<RT>` generic can be set explicitly or inferred from a request
+	* built with {@link withResponseType} or {@link withReactiveResponse} — see
+	* [Typing Requests](/guides/the-manual/requests/typing-requests.md).
+	*
+	* @example
+	* ```ts
+	* const { content } = await requestManager.request({ url: '/users' });
+	* ```
 	*
 	* @public
 	*/
@@ -8155,9 +8037,10 @@ var RequestManager = class {
 *
 * @private
 */
-//#endregion
-//#region src/index.ts
+// src/index.ts
 /**
+* @summary Main entry point for WarpDrive: the `Store`, `RequestManager`, `Fetch` handler, `CacheHandler`, and
+* `useRecommendedStore` for building a configured store.
 * @module
 * @mergeModuleWith <project>
 */
@@ -8166,11 +8049,17 @@ globalThis.getWarpDriveRuntimeConfig = getRuntimeConfig;
 globalThis.setWarpDriveIsMaybeMirage = setIsMaybeMirage;
 /**
 * Options for setting up a Store instance with `useRecommendedStore`.
+*
+* @summary Configures the cache, cache policy, request handlers, schemas, and schema extensions that
+* `useRecommendedStore` wires into a Store class.
 */
 /**
 * Creates a configured Store class with recommended defaults
 * for schema handling, reactivity, caching, and request management.
 *
+* The [Setup](/guides/configuration/#configure-the-store) guide walks through
+* configuring the store with it.
+*
 * ```ts
 * import { useRecommendedStore } from '@warp-drive-mirror/core';
 * import { JSONAPICache } from '@warp-drive-mirror/json-api';
@@ -8273,6 +8162,9 @@ globalThis.setWarpDriveIsMaybeMirage = setIsMaybeMirage;
 * {@link RequestManager} won't have it set unless the caller supplies it
 * explicitly, so a handler relying on it should treat it as optional (as
 * `LoggingHandler` does above).
+*
+* @summary Builds a Store subclass preconfigured with the given cache, schemas, and handlers, plus
+* `Fetch`, `CacheHandler`, and a default cache policy.
 */
 function useRecommendedStore(options, StoreKlass = Store) {
 	return class AppStore extends StoreKlass {
@@ -8326,6 +8218,5 @@ function useRecommendedStore(options, StoreKlass = Store) {
 	};
 }
 
-//#endregion
-export { setIdentifierResetMethod as A, setRecordIdentifier as C, isResourceKey as D, isRequestKey as E, ensureStringId as F, log as I, logGroup as L, setKeyInfoForResource as M, normalizeModelName as N, setIdentifierForgetMethod as O, coerceId as P, recordIdentifierFor as S, assertPrivateCapabilities as T, isPrivateStore as _, fromIdentity as a, StoreMap as b, instantiateRecord as c, commit as d, createLegacyManyArray as f, assertPrivateStore as g, Store as h, SchemaService as i, setIdentifierUpdateMethod as j, setIdentifierGenerationMethod as k, teardownRecord as l, CacheHandler as m, RequestManager as n, registerDerivations as o, constructResource as p, Fetch as r, withDefaults as s, useRecommendedStore as t, checkout as u, RecordArrayManager as v, storeFor as w, _clearCaches as x, fastPush as y };
-//# sourceMappingURL=src-kn6qfEPI.js.map
+export { setIdentifierGenerationMethod as A, setRecordIdentifier as C, isRequestKey as D, fieldValueIdentity as E, coerceId as F, ensureStringId as I, log as L, setIdentifierUpdateMethod as M, setKeyInfoForResource as N, isResourceKey as O, normalizeModelName as P, logGroup as R, recordIdentifierFor as S, assertPrivateCapabilities as T, isPrivateStore as _, fromIdentity as a, StoreMap as b, instantiateRecord as c, commit as d, createLegacyManyArray as f, assertPrivateStore as g, Store as h, SchemaService as i, setIdentifierResetMethod as j, setIdentifierForgetMethod as k, teardownRecord as l, CacheHandler as m, RequestManager as n, registerDerivations as o, constructResource as p, Fetch as r, withDefaults as s, useRecommendedStore as t, checkout as u, RecordArrayManager as v, storeFor as w, _clearCaches as x, fastPush as y };
+//# sourceMappingURL=src-Dt1O1Pw1.js.map