@warp-drive-mirror/core 5.10.0-alpha.12 → 5.10.0-alpha.13

package/dist/{src-B9WcEdYg.js → src-DlNeupkA.js}

@@ -1,14 +1,14 @@
 import { getOrSetGlobal, peekTransient, peekUniversalTransient, setTransient, setUniversalTransient } from "./types/-private.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-CjK1Dmuh.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-BpyvBYFj.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-Di274pQz.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-MiwUbGdT.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-Dtj8O5W7.js";
+import { a as SOURCE, i as Destroy, n as Commit, r as Context, t as Checkout } from "./-private-CmNOwhK0.js";
 import { dasherize } from "./utils/string.js";
 import { RecordStore, Type } from "./types/symbols.js";
 import { isResourceSchema } from "./types/schema/fields.js";
-import { t as DefaultCachePolicy } from "./store-DNF9Rgoh.js";
+import { t as DefaultCachePolicy } from "./store-lcyaxrpj.js";
 import { dependencySatisfies, getGlobalConfig, importSync, macroCondition } from "@embroider/macros";
 import { deprecate, warn } from "@ember/debug";
 
@@ -22,10 +22,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 = {
@@ -671,6 +676,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) {
@@ -705,6 +712,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) {
@@ -722,6 +731,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) {
@@ -741,6 +752,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) {
@@ -759,6 +772,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) {
@@ -1374,6 +1389,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.
 */
@@ -2051,9 +2067,15 @@ var CacheManager = class {
 //#region 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";
@@ -2061,6 +2083,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
@@ -2068,6 +2093,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
 */
@@ -2102,6 +2129,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
 */
 /**
@@ -2240,6 +2269,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
 */
@@ -2674,10 +2705,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
 */
 /**
@@ -2998,6 +3034,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
 */
 /**
@@ -3113,6 +3151,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
 */
 /**
@@ -3935,6 +3975,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.
@@ -3942,6 +3986,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
 */
@@ -4156,12 +4201,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
 	*
@@ -4206,6 +4264,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) {
@@ -4844,6 +4925,8 @@ function _convertPreloadRelationshipToJSON(value, type) {
 * for @warp-drive-mirror/legacy/model or when wrapping schema for legacy
 * Adapters/Serializers.
 *
+* @summary Legacy shape of a Model class's static schema API (fields, attributes, relationships, iterators) used
+* by the legacy schema service and Adapters/Serializers.
 */
 function _resourceIsFullDeleted(identifier, cache) {
 	return cache.isDeletionCommitted(identifier) || cache.isNew(identifier) && cache.isDeleted(identifier);
@@ -5082,7 +5165,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.deprecations.ENABLE_LEGACY_
 			id: "warp-drive:deprecate-legacy-request-methods",
 			until: "6.0",
 			for: "@warp-drive-mirror/core",
-			url: "https://docs.warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
+			url: "https://warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
 			since: {
 				enabled: "5.7",
 				available: "5.7"
@@ -5127,7 +5210,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.deprecations.ENABLE_LEGACY_
 			id: "warp-drive:deprecate-legacy-request-methods",
 			until: "6.0",
 			for: "@warp-drive-mirror/core",
-			url: "https://docs.warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
+			url: "https://warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
 			since: {
 				enabled: "5.7",
 				available: "5.7"
@@ -5156,7 +5239,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.deprecations.ENABLE_LEGACY_
 			id: "warp-drive:deprecate-legacy-request-methods",
 			until: "6.0",
 			for: "@warp-drive-mirror/core",
-			url: "https://docs.warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
+			url: "https://warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
 			since: {
 				enabled: "5.7",
 				available: "5.7"
@@ -5189,7 +5272,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.deprecations.ENABLE_LEGACY_
 			id: "warp-drive:deprecate-legacy-request-methods",
 			until: "6.0",
 			for: "@warp-drive-mirror/core",
-			url: "https://docs.warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
+			url: "https://warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
 			since: {
 				enabled: "5.7",
 				available: "5.7"
@@ -5222,7 +5305,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.deprecations.ENABLE_LEGACY_
 			id: "warp-drive:deprecate-legacy-request-methods",
 			until: "6.0",
 			for: "@warp-drive-mirror/core",
-			url: "https://docs.warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
+			url: "https://warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
 			since: {
 				enabled: "5.7",
 				available: "5.7"
@@ -5255,7 +5338,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.deprecations.ENABLE_LEGACY_
 			id: "warp-drive:deprecate-legacy-request-methods",
 			until: "6.0",
 			for: "@warp-drive-mirror/core",
-			url: "https://docs.warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
+			url: "https://warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
 			since: {
 				enabled: "5.7",
 				available: "5.7"
@@ -5277,7 +5360,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.deprecations.ENABLE_LEGACY_
 			id: "warp-drive:deprecate-legacy-request-methods",
 			until: "6.0",
 			for: "@warp-drive-mirror/core",
-			url: "https://docs.warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
+			url: "https://warp-drive.io/api/@warp-drive-mirror/core/build-config/deprecations/variables/ENABLE_LEGACY_REQUEST_METHODS",
 			since: {
 				enabled: "5.7",
 				available: "5.7"
@@ -5364,10 +5447,16 @@ function getPriority(identifier, deduped, priority) {
 /**
 * 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.
@@ -5403,7 +5492,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);
@@ -5705,6 +5797,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
 */
 /**
@@ -7066,10 +7159,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
 */
@@ -7523,6 +7620,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
@@ -7539,6 +7638,8 @@ 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) {
@@ -7556,6 +7657,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) {
@@ -7588,6 +7691,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) {
@@ -7642,16 +7747,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) {
@@ -7751,14 +7865,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}
@@ -7789,6 +7908,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) => {
@@ -7812,9 +7933,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) {
@@ -7890,6 +8016,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
@@ -7912,6 +8041,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 {
@@ -8621,6 +8756,8 @@ function mergeMap(base, toApply) {
 * - {@link LegacyModeFieldSchema}
 * - {@link PolarisModeFieldSchema}
 *
+* @summary Schema-driven reactive records, arrays, and documents the store builds from cached data, plus the
+* `SchemaService` and schema types that define them.
 * @module
 */
 
@@ -8703,6 +8840,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';
 *
@@ -8710,6 +8850,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
 */
@@ -8839,7 +8981,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
 *
@@ -8862,11 +9005,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]
@@ -8882,6 +9042,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
@@ -8984,7 +9158,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
 	*/
@@ -9072,6 +9262,8 @@ var RequestManager = class {
 //#endregion
 //#region 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>
 */
@@ -9082,11 +9274,17 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.env.TESTING)) {
 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';
@@ -9189,6 +9387,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 {
@@ -9244,4 +9445,4 @@ function useRecommendedStore(options, StoreKlass = Store) {
 
 //#endregion
 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-B9WcEdYg.js.map
+//# sourceMappingURL=src-DlNeupkA.js.map