@web-ts-toolkit/access-router-client 0.32.0 → 0.34.0

package/index.d.ts

@@ -1,5 +1,5 @@
 import * as axios from 'axios';
-import { AxiosInstance, AxiosResponse, AxiosRequestConfig, AxiosHeaders } from 'axios';
+import { AxiosInstance, AxiosResponse, AxiosRequestConfig, InternalAxiosRequestConfig } from 'axios';
 
 interface SubQueryOptions {
     path?: string;
@@ -74,6 +74,7 @@ interface CreateAdvancedOptions {
 }
 interface UpdateOptions {
     returningAll?: boolean;
+    includePermissions?: boolean;
 }
 interface UpdateAdvancedArgs<TSelect extends Projection = Projection> {
     select?: TSelect;
@@ -113,35 +114,51 @@ interface DataListArgs {
     pageSize?: number;
 }
 interface DataListOptions {
-    includePermissions?: boolean;
     includeCount?: boolean;
     includeExtraHeaders?: boolean;
     ignoreCache?: boolean;
 }
 interface DataListAdvancedArgs<TSelect extends Projection = Projection> {
     select?: TSelect;
-    sort?: Sort;
+    sort?: string;
     skip?: string | number;
     limit?: string | number;
     page?: string | number;
     pageSize?: string | number;
 }
 interface DataListAdvancedOptions {
-    includePermissions?: boolean;
     includeCount?: boolean;
     includeExtraHeaders?: boolean;
     ignoreCache?: boolean;
 }
 interface DataReadOptions {
-    includePermissions?: boolean;
     ignoreCache?: boolean;
 }
 interface DataReadAdvancedArgs<TSelect extends Projection = Projection> {
     select?: TSelect;
-    ignoreCache?: boolean;
 }
+/**
+ * Options for `DataService.readAdvanced` and `DataService.readAdvancedFilter`.
+ *
+ * `ignoreCache` is the documented cache-bypass knob for advanced reads. It
+ * lives here — not on `DataReadAdvancedArgs` — so callers use `{ ignoreCache:
+ * true }` in the options position to skip an existing cache entry, matching
+ * the placement used by the basic `list`, `listAdvanced`, and `read` service
+ * methods.
+ *
+ * `includePermissions` is intentionally absent. The access-router data
+ * router body schema for advanced reads (`dataReadByIdBodySchema` and
+ * `dataReadFilterBodySchema`) explicitly rejects the `options` key, and the
+ * root router drops `item.options` when dispatching data operations
+ * server-side (root-router.ts passes `{}` as the options argument to
+ * `findById`/`findOne`). Advertising `includePermissions` here was a
+ * type-level promise the server cannot honor and the grouped path silently
+ * passed through `__query.options.includePermissions` only for the root
+ * router to discard it — a direct/grouped asymmetry. The fix removes the
+ * dead-letter field from the type and from `__query.options` so direct and
+ * grouped advanced reads compose identical payloads.
+ */
 interface DataReadAdvancedOptions {
-    includePermissions?: boolean;
     ignoreCache?: boolean;
 }
 interface DataDefaults {
@@ -157,67 +174,81 @@ interface AdditionalReqConfig {
     throwOnError?: boolean;
 }
 
+/**
+ * Normalized failure payload. Mirrors {@link FailureResult} but kept
+ * structurally loose (the {@link Response} discriminated union narrows
+ * these fields automatically when consumers branch on `result.success`).
+ */
 interface ResultError {
-    success: boolean;
+    success: false;
     raw: unknown;
-    data: unknown;
+    data: null;
     message: string;
     status: number;
     headers: Record<string, unknown>;
+    totalCount?: number;
 }
+/**
+ * Low-level base class shared by {@link ModelService} and {@link DataService}.
+ * Subclassing is supported as an advanced opt-in for callers that need a
+ * bespoke service shape: subclasses extend `Service`, build on the shared
+ * Axios instance, and reuse the `wrapGet`/`wrapPost`/... paths registered
+ * against the adapter's `basePath`. Most callers should use
+ * `adapter.createModelService<T>(...)` / `adapter.createDataService<T>(...)`
+ * rather than subclassing `Service` directly.
+ *
+ * The `handleSuccess`/`handleError` helpers normalize Axios responses into
+ * the package's {@link Response} discriminated union so direct subclasses
+ * produce the same success/failure contract as the built-in services.
+ */
 declare class Service {
     protected _axios: AxiosInstance;
     protected _basePath: string;
     private _wrap;
-    constructor(axios: AxiosInstance, basePath: string);
+    private _throwOnError;
+    constructor(axios: AxiosInstance, basePath: string, throwOnError?: boolean);
     protected handleSuccess(res: AxiosResponse<unknown, unknown>, extra?: {}): Response<unknown>;
-    protected handleError<T extends ResultError>(error: {
-        response?: {
-            status: number;
-            headers: Record<string, unknown>;
-            data: unknown;
-        };
-        request?: unknown;
-        message?: string;
-    }): T;
+    protected handleError<T extends Response<unknown, unknown>>(error: unknown): Extract<T, FailureResult>;
+    /** Resolves per-call policy against the already-resolved service/adapter default. */
+    resolveThrowOnError(override?: boolean): boolean;
     wrapGet<T = unknown>(url: string, defaultAxiosRequestConfig?: AxiosRequestConfig): (options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
     wrapPost<T = unknown>(url: string, defaultAxiosRequestConfig?: AxiosRequestConfig): (data?: unknown, options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
     wrapPut<T = unknown>(url: string, defaultAxiosRequestConfig?: AxiosRequestConfig): (data?: unknown, options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
     wrapPatch<T = unknown>(url: string, defaultAxiosRequestConfig?: AxiosRequestConfig): (data?: unknown, options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
     wrapDelete<T = unknown>(url: string, defaultAxiosRequestConfig?: AxiosRequestConfig): (options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<AxiosResponse<T, any, {}>>;
+    /**
+     * Public bridge to the per-service success/failure callback pipeline and
+     * `throwOnError` policy. Adapter-internal grouping machinery calls this so
+     * that grouped entries go through the same finalization the direct path
+     * uses (`createResponseHandler`). Returns `res` unchanged on success and
+     * throws `ServiceError` when both `res.success === false` and the
+     * `throwOnError` override (or the service-level default) are enabled.
+     */
+    applyResponseCallbacks<T extends {
+        success: boolean;
+    }>(res: T, throwOnErrorOverride?: boolean): T;
+    /**
+     * Returns a fresh headers object that includes the package-owned
+     * `CACHE_HEADER` set to `"true"` (cache eligible) or `"false"` (bypass)
+     * according to the `ignoreCache` option. The caller's `CACHE_HEADER`
+     * value, if any, wins over the `ignoreCache` default.
+     *
+     * The input `headers` object is **never mutated**: an `AxiosHeaders`
+     * instance is cloned via `.toJSON()` before any value is set, and a
+     * plain-object headers input is shallow-copied. Reusing the same
+     * caller-owned headers across multiple requests therefore has no
+     * hidden side effects, and the order of invocations is irrelevant.
+     */
     updateHeaders(headers: AxiosRequestConfig['headers'], { ignoreCache }: {
         ignoreCache?: boolean;
-    }): AxiosHeaders | (Partial<axios.RawAxiosHeaders & {
-        Accept: axios.AxiosHeaderValue;
-        "Content-Length": axios.AxiosHeaderValue;
-        "User-Agent": axios.AxiosHeaderValue;
-        "Content-Encoding": axios.AxiosHeaderValue;
-        Authorization: axios.AxiosHeaderValue;
-        Location: axios.AxiosHeaderValue;
-    } & {
-        'Content-Type': axios.AxiosHeaderValue;
-    }> & Partial<{
-        get: AxiosHeaders;
-        delete: AxiosHeaders;
-        head: AxiosHeaders;
-        options: AxiosHeaders;
-        post: AxiosHeaders;
-        put: AxiosHeaders;
-        patch: AxiosHeaders;
-        purge: AxiosHeaders;
-        link: AxiosHeaders;
-        unlink: AxiosHeaders;
-        query: AxiosHeaders;
-    } & {
-        common: AxiosHeaders;
-    }>);
+    }): AxiosRequestConfig['headers'];
 }
 declare class ServiceError extends Error {
-    success: boolean;
-    raw: unknown;
-    data: unknown;
-    status: number;
-    headers: Record<string, unknown>;
+    success: false;
+    readonly raw: unknown;
+    readonly data: null;
+    readonly status: number;
+    readonly headers: Record<string, unknown>;
     constructor(result: ResultError);
 }
 
@@ -249,54 +280,54 @@ declare class ModelService<T extends Document> extends Service {
     constructor({ axios, modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError }: Props$1, defaults?: Defaults);
     list<TData extends Partial<T> = T>(args?: ListArgs, options?: ListOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ListModelResponse<T, TData>>;
     listAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(filter: FilterQuery<T>, args?: ListAdvancedArgs<TSelect>, options?: ListAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ListModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
-    create<TData extends Partial<T> = T>(data: object, options?: CreateOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
+    create<TData extends Partial<T> = T>(data: object[], options?: CreateOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ArrayModelResponse<T, TData>>;
+    create<TData extends Partial<T> = T>(data: object, options?: CreateOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, TData>>;
+    createAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: object[], args?: CreateAdvancedArgs<TSelect>, options?: CreateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ArrayModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     createAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: object, args?: CreateAdvancedArgs<TSelect>, options?: CreateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     upsert<TData extends Partial<T> = T>(data: object, options?: UpsertOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
     upsertAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(data: object, args?: UpsertAdvancedArgs<TSelect>, options?: UpsertAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
-    delete(identifier: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string, string>>;
+    delete(identifier: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string>>;
     new<TData extends Partial<T> = T>(axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
-    distinct(field: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[], string[]>>;
-    distinctAdvanced(field: string, conditions: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[], string[]>>;
-    count(axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number, number>>;
-    countAdvanced(filter: FilterQuery<T>, args?: {
-        access?: 'list' | 'read';
-    }, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number, number>>;
+    distinct(field: string, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[]>>;
+    distinctAdvanced(field: string, conditions: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<string[]>>;
+    count(axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number>>;
+    countAdvanced(filter: FilterQuery<T>, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<Response<number>>;
     read<TData extends Partial<T> = T>(identifier: string, options?: ReadOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
     readAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(identifier: string, args?: ReadAdvancedArgs<TSelect>, options?: ReadAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     readAdvancedFilter<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(filter: FilterQuery<T>, args?: ReadAdvancedArgs<TSelect>, options?: ReadAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     update<TData extends Partial<T> = T>(identifier: string, data: object, options?: UpdateOptions, axiosRequestConfig?: RequestConfig$1): ModelPromiseMeta & LazyRequest<ModelResponse<T, TData>>;
     updateAdvanced<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(identifier: string, data: object, args?: UpdateAdvancedArgs<TSelect>, options?: UpdateAdvancedOptions, axiosRequestConfig?: RequestConfig$1): ModelRequest<ModelResponse<T, ResolvedSelectedShape<T, TSelect, TData>>>;
     id(id: string): {
-        subs: <S = T>(field: keyof T) => {
+        subs: <S = never, K extends keyof T = keyof T>(field: K) => {
             list: (axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<ListModelResponse<S>>;
-            listAdvanced: <TData extends Partial<S> = never, TSelect extends readonly string[] = readonly string[]>(filter?: FilterQuery<S>, args?: {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
+            listAdvanced: <TData extends Partial<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S> = never, TSelect extends readonly string[] = readonly string[]>(filter?: FilterQuery<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>, args?: {
                 select?: TSelect;
             }, axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<ListModelResponse<S, ResolvedSelectedShape<S, TSelect, TData>>>;
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, ResolvedSelectedShape<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, TSelect, TData>>>;
             read: (subId: string, axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<ModelResponse<S>>;
-            readAdvanced: <TData extends Partial<S> = never, TSelect_1 extends readonly string[] = readonly string[]>(subId: string, args?: {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
+            readAdvanced: <TData extends Partial<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S> = never, TSelect_1 extends readonly string[] = readonly string[]>(subId: string, args?: {
                 select?: TSelect_1;
                 populate?: unknown;
             }, axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<ModelResponse<S, ResolvedSelectedShape<S, TSelect_1, TData>>>;
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, ResolvedSelectedShape<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S, TSelect_1, TData>>>;
             update: (subId: string, data: object, axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<ModelResponse<S>>;
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
             bulkUpdate: (data: object[], axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<ListModelResponse<S>>;
-            create: (data: object, axiosRequestConfig?: AxiosRequestConfig<any> & {
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
+            create: (data: object | object[], axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<ModelResponse<S>>;
+            }) => ModelPromiseMeta & LazyRequest<SubDocumentListResponse<[S] extends [never] ? NonNullable<T[K]> extends readonly (infer TItem)[] ? TItem : never : S>>;
             delete: (subId: string, axiosRequestConfig?: AxiosRequestConfig<any> & {
                 throwOnError?: boolean;
-            }) => ModelPromiseMeta & LazyRequest<Response<string, string>>;
+            }) => ModelPromiseMeta & LazyRequest<Response<string>>;
         };
         fetch: (args?: ReadAdvancedArgs, options?: ReadAdvancedOptions, axiosRequestConfig?: RequestConfig$1) => ModelRequest<ModelResponse<T, Partial<T>>>;
     };
@@ -332,15 +363,109 @@ declare class DataService<T> extends Service {
     readAdvancedFilter<TData extends Partial<T> | never = never, TSelect extends Projection = Projection>(filter: FilterQuery<T>, args?: DataReadAdvancedArgs<TSelect>, options?: DataReadAdvancedOptions, axiosRequestConfig?: RequestConfig): DataRequest<DataResponse<ResolvedSelectedShape<T, TSelect, TData>>>;
 }
 
+/**
+ * Thrown by {@link Model.save} when the wrapper cannot determine whether
+ * to create or update. This is the "no silent create from a projected
+ * read" guarantee (ARC-21): when a read projection omits `_id` AND no
+ * persistence identity was captured at read time (the case for
+ * `readAdvancedFilter` and other list/filter reads that do not know a
+ * single document id), `save()` refuses to POST a new document the
+ * caller may not have meant to create. Callers can recover by reading the
+ * document with `read(id)` / `readAdvanced(id, ...)` (both capture a
+ * persistence identity), or by including `_id` in the projection.
+ */
+declare class MissingPersistenceIdentityError extends Error {
+    constructor(message: string);
+}
+/**
+ * A dirty-tracking wrapper around a model document. Constructed via
+ * {@link ModelService.create}, {@link ModelService.read},
+ * {@link ModelService.findOne}, or the list methods that return
+ * `Model<T>[]`. Property access through the wrapper directly reads/writes
+ * the underlying data; `save()` persists only the paths flagged dirty
+ * since the last save and merges the server response per the documented
+ * concurrency contract.
+ *
+ * `Model.create<T>(data, service)` is typed as `Model<T, TData> & TData` so
+ * callers can read/write fields directly on the wrapper (`user.role =
+ * 'owner'`) while still calling `save()`/`reset()`/`isDirty(...)`. The
+ * returned wrapper is a fresh snapshot of the post-operation local state;
+ * mutating it does not affect sibling wrappers created from the same
+ * underlying document.
+ *
+ * Persistence identity (ARC-21): identity is stored SEPARATELY from the
+ * projected document data. When a service reads a single document by id
+ * (`read`, `readAdvanced`), it threads an explicit `persistenceId` into
+ * `Model.create(...)` so that `save()` resolves the create-vs-update
+ * branch from that captured identity, not from `_data._id`. This means a
+ * read projection that deliberately omits `_id` (e.g. `select: { name: 1,
+ * _id: 0 }`) cannot silently cause a subsequent `save()` to create a
+ * duplicate — `save()` updates the same document the wrapper was read
+ * from. When neither a `persistenceId` nor an `_id` is present (e.g. an
+ * `readAdvancedFilter` projection that strips `_id`), `save()` throws an
+ * explicit `MissingPersistenceIdentityError` rather than POSTing a new
+ * document the user did not mean to create.
+ */
 declare class Model<T extends Document, TData extends Partial<T> = T> {
     private _data;
     private _snapshot;
     private readonly _service;
     private modifiedPaths;
-    constructor(data: TData, adapter: ModelService<T>);
-    static create<T, TData extends Partial<T> = T>(data: TData, adapter: ModelService<T>): Model<T, TData> & TData;
-    save(reqConfig?: AxiosRequestConfig): Promise<any>;
+    private _persistenceId;
+    private readonly _fromExisting;
+    constructor(data: TData, adapter: ModelService<T>, persistenceId?: string, fromExisting?: boolean);
+    static create<T extends Document, TData extends Partial<T> = T>(data: TData, adapter: ModelService<T>, persistenceId?: string, fromExisting?: boolean): Model<T, TData> & TData;
+    /**
+     * Persists the currently dirty paths to the server, then merges the
+     * server's response back into local state.
+     *
+     * Concurrency contract:
+     *
+     * 1. Submitted paths and their values are snapshotted before the request
+     *    starts, so an in-flight response cannot wipe edits that were made
+     *    while the request was pending.
+     * 2. On success, a submitted path is cleared from `modifiedPaths` only if
+     *    its current local value still equals the submitted value — i.e. the
+     *    user has not concurrently re-edited it to a different value.
+     * 3. Server-returned values overwrite local values for paths the user did
+     *    NOT concurrently re-modify during the in-flight save; for paths the
+     *    user did concurrently re-modify, the local value is preserved and
+     *    the dirty flag is retained so the concurrent edit is resubmitted on
+     *    the next `save()`. (Deterministic conflict rule: the newer local
+     *    edit wins for the same path; the server value becomes its reset
+     *    baseline without replacing the newer local value.)
+     * 4. On failure, no dirty state is cleared and no local value is
+     *    overwritten; the caller can retry `save()` with the same set.
+     * 5. The return value echoes `{ ...result, data }` where `data` is a
+     *    refreshed `Model` snapshot of the post-save local state (or `null`
+     *    on failure), matching `ModelResponse<T, TData>`.
+     *
+     * Persistence identity (ARC-21): create-vs-update is resolved from a
+     * captured persistence identity rather than from the projected `_data`
+     * payload alone, so a read that strips `_id` (e.g. `select: { name: 1,
+     * _id: 0 }`) cannot turn a subsequent `save()` into a silent create of
+     * a duplicate. When `_data._id` is present it takes precedence so callers
+     * can still deliberately aim `_id` at a bogus id to observe a failing
+     * save. When neither `_data._id` nor a captured persistence identity is
+     * available (e.g. `readAdvancedFilter` with an `_id`-excluding
+     * projection), `save()` throws `MissingPersistenceIdentityError` instead
+     * of POSTing a new document.
+     */
+    save(reqConfig?: AxiosRequestConfig): Promise<ModelResponse<T, TData>>;
     isDirty(path?: keyof TData | string): boolean;
+    /**
+     * Marks a path dirty and skips snapshot reconciliation. This is the
+     * explicit "include this path on the next save()" escape hatch: even when
+     * the effective value still equals the snapshot, the path stays dirty so
+     * callers can force a field to be re-sent to the server (e.g., to retrigger
+     * server-side defaults or to re-submit a value that another client may
+     * have reverted).
+     *
+     * For implicit writes that reconcile against the snapshot automatically
+     * (reverting a field to its baseline clears the dirty flag), use `set()`,
+     * `assign(...)`, or direct property assignment — those entry points all
+     * run `reconcilePath` after the write.
+     */
     markModified(path: keyof TData | string): this;
     get<TKey extends keyof TData>(path: TKey): TData[TKey];
     get(path: string): unknown;
@@ -350,7 +475,6 @@ declare class Model<T extends Document, TData extends Partial<T> = T> {
     reset(): this;
     toObject(): TData;
     toJSON(): TData;
-    private updateModel;
     private replaceData;
     private initializeDirtyState;
     private prepareData;
@@ -359,12 +483,36 @@ declare class Model<T extends Document, TData extends Partial<T> = T> {
     private definePublicDataProps;
     private trackModified;
     private normalizePath;
+    /**
+     * Removes `path` from the dirty set when its current top-level value deeply
+     * equals the snapshot baseline. Used uniformly by `set()`, `assign()`,
+     * public property setters (via the proxy), and `markModified()` so all
+     * entry points share the same tracking rule.
+     *
+     * Note: `_id` is intentionally never reconciled away here — it is excluded
+     * from `initializeDirtyState` and managed explicitly during `save()`
+     * reconciliation.
+     */
+    private reconcilePath;
 }
 
 type AnyArray<T> = T[] | ReadonlyArray<T>;
 type Unpacked<T> = T extends (infer U)[] ? U : T extends ReadonlyArray<infer U> ? U : T;
-type ApplyBasicQueryCasting<T> = T | T[] | (T extends (infer U)[] ? U : unknown) | unknown;
-type Condition<T> = ApplyBasicQueryCasting<T> | QuerySelector<ApplyBasicQueryCasting<T>>;
+/**
+ * Values a known field condition accepts without an operator wrapper.
+ *
+ * - The scalar value itself (`name: 'Max'`).
+ * - An array of scalars — the sibling server expands this to an `$in` query.
+ * - For array-typed document fields, the element type is also accepted as a
+ *   bare condition (e.g. `tags: 'vip'` matches any array containing `'vip'`).
+ * - RegExp is only accepted where `T` is (or unwraps to) `string`.
+ *
+ * The naked `unknown` that previously terminated this union is gone. Use
+ * `ServerSideCast<T>` / `DottedPathFilter<T>` for the cases that needed it
+ * (dynamic dotted paths and explicit server-side casting).
+ */
+type ApplyBasicQueryCasting<T> = T | T[] | (T extends AnyArray<unknown> ? Unpacked<T> : never) | (T extends string ? RegExp : never);
+type Condition<T> = ApplyBasicQueryCasting<T> | QuerySelector<ApplyBasicQueryCasting<T>> | LazyRequest<unknown>;
 type _FilterQuery<T> = {
     [P in keyof T]?: Condition<T[P]>;
 } & RootQuerySelector<T>;
@@ -386,7 +534,6 @@ type RootQuerySelector<T> = {
     $where?: string | ((...args: never[]) => unknown);
     /** @see https://www.mongodb.com/docs/manual/reference/operator/query/comment/#op._S_comment */
     $comment?: string;
-    [key: string]: unknown;
 };
 type QuerySelector<T> = {
     $eq?: T;
@@ -410,11 +557,56 @@ type QuerySelector<T> = {
     $regex?: T extends string ? RegExp | string : never;
     $options?: T extends string ? string : never;
 };
+/**
+ * Escape hatch for dynamic dotted paths and explicit server-side casting.
+ *
+ * `DottedPathFilter<T>` restores schema-less field matching: every
+ * `Record<string, unknown>` value is forwarded to the sibling server
+ * untouched, so dotted paths such as `'user.friends.name'` and values cast
+ * on the server side still typecheck.
+ *
+ * Crucially, `DottedPathFilter<T>` restores this looseness only when the
+ * caller explicitly asks for it; it does NOT weaken the typed
+ * `FilterQuery<T>` surface, so a stray invalid value on a known field still
+ * fails to compile.
+ */
+type DottedPathFilter<T> = _FilterQuery<T> & {
+    [key: string]: unknown;
+};
+/**
+ * Escape hatch for explicit server-side casting. Use this at the call site
+ * of any typed `FilterQuery<T>` parameter when you need to forward a value
+ * the client type cannot express (server-side casting, aggregation-shaped
+ * values for `$expr`, or a dotted-path condition that the typed surface does
+ * not model). The sibling server accepts arbitrary objects/arrays for
+ * filters (`objectOrArraySchema`), so this never causes a runtime failure;
+ * it is purely a deliberate compile-time opt-out.
+ */
+type ServerSideCast<T> = DottedPathFilter<T>;
 
 /**
  * Wraps a lazy promise function with optional metadata.
- * The promise is only created when `.then()`, `.catch()`, `.finally()`, or `.exec()` is called.
- * Metadata properties are merged onto the returned object via `Object.assign`.
+ *
+ * The promise is only created when `.then()`, `.catch()`, `.finally()`, or
+ * `.exec()` is called, and a single underlying promise is shared across all
+ * of those entry points so repeated chaining attaches to the same execution
+ * rather than re-invoking the executor.
+ *
+ * Behavior notes:
+ *
+ * - **Sync executor failures become rejections.** The executor is invoked
+ *   through `Promise.resolve().then(execute)`, so a synchronous throw from
+ *   `execute` is converted to a rejected promise and reaches `.catch()`
+ *   and `await` as a rejection rather than escaping synchronously.
+ * - **Metadata is private.** Each meta entry is installed with
+ *   `Object.defineProperty(..., { enumerable: false, writable: false,
+ *   configurable: false })` so consumers cannot accidentally iterate,
+ *   serialize, or reassign it. Direct property reads (`prom.__query`) still
+ *   work for adapter-internal machinery (e.g. `adapter.group(...)`).
+ * - **One execution.** The first call to `exec()`, `.then()`,
+ *   `.catch()`, or `.finally()` caches the underlying promise and stamps
+ *   the wrapper with `STARTED_KEY = true`. Subsequent calls reuse the same
+ *   promise and never re-invoke the executor.
  */
 declare const wrapLazyPromise: <T, M = undefined>(promiseFn: () => Promise<T>, meta?: M) => M & LazyRequest<T>;
 
@@ -435,6 +627,7 @@ type Sort = string | {
     [key: string]: SortOrder;
 } | [string, SortOrder][] | undefined | null;
 type FilterQuery<T> = _FilterQuery<T>;
+
 interface Include {
     model: string;
     op: 'list' | 'read' | 'count';
@@ -455,19 +648,79 @@ interface Populate {
 interface Document {
     _id?: string;
 }
-interface Response<T1, T2 = T1> {
-    success: boolean;
+/**
+ * Successful response. `raw` and `data` are non-null and `success` is
+ * narrowed to `true` so `if (result.success)` exposes the documented
+ * payload shape. `message` is initialized for symmetry with failures but
+ * may be the empty string when the server omits a message on success.
+ */
+interface SuccessResult<T1, T2 = T1> {
+    success: true;
     raw: T1;
     data: T2;
     message: string;
     status: number;
     headers: Record<string, string>;
 }
-type ModelResponse<T, TData extends Partial<T> = T> = Response<TData, Model<T, TData> & TData>;
-type ArrayModelResponse<T, TData extends Partial<T> = T> = Response<TData[], (Model<T, TData> & TData)[]>;
-type ListModelResponse<T, TData extends Partial<T> = T> = ArrayModelResponse<T, TData> & {
+/**
+ * Failure response. `raw` carries the server error payload (or `null`
+ * when no response body was received, e.g. a network error). `data` is
+ * always `null` on failure. `message` is populated from the structured
+ * problem payload when possible; `status` is the failing HTTP status
+ * (or `0` when no response was received).
+ */
+interface FailureResult<TError = unknown> {
+    success: false;
+    raw: TError | null;
+    data: null;
+    message: string;
+    status: number;
+    headers: Record<string, string>;
+}
+/**
+ * Discriminated response union. Branch on `result.success` to narrow
+ * `raw`/`data` to their successful shapes or to the documented error
+ * payload.
+ *
+ * `T1` is the successful `raw` payload type; `T2` is the successful `data`
+ * payload type (after client wrapping, e.g. `Model<T>`). `TError` is the
+ * optional server error payload type and defaults to `unknown`. On failure,
+ * `data` is `null` and `raw` is `TError | null`, never the success payload
+ * type unless a caller explicitly chooses that error type.
+ */
+type Response<T1, T2 = T1, TError = unknown> = SuccessResult<T1, T2> | FailureResult<TError>;
+type ModelResponse<T extends Document, TData extends Partial<T> = T> = Response<TData, Model<T, TData> & TData>;
+type ArrayModelResponse<T extends Document, TData extends Partial<T> = T> = Response<TData[], (Model<T, TData> & TData)[]>;
+/**
+ * `ListModelResponse` always carries `totalCount` on both branches. The field
+ * defaults to `0` at runtime on failure or when the server did not emit count
+ * metadata (`includeCount: false`), so callers that read it without narrowing
+ * see a deterministic number rather than `undefined`.
+ */
+type ListModelResponse<T extends Document, TData extends Partial<T> = T> = ArrayModelResponse<T, TData> & {
     totalCount: number;
 };
+/**
+ * Subdocument responses deliberately do NOT wrap `data` in `Model<S>`.
+ * Returning a save-capable `Model<S>` here was unsafe because `Model.save()`
+ * would target the parent route with the subdocument `_id` instead of
+ * `/:parentId/:sub/:subId`. Subdocument callers that need persistence must
+ * call `subService.update(subId, data)` (or `create`/`bulkUpdate`) explicitly
+ * with the parent-scoped helper returned by `id(parentId).subs(field)`.
+ *
+ * `SubDocumentResponse` is the single-document shape; `data` is the plain
+ * subdocument payload or `null` on failure.
+ */
+type SubDocumentResponse<S, TData extends Partial<S> = S> = Response<TData, TData>;
+/**
+ * Subdocument list/array responses. `data` is the plain array of subdocument
+ * payloads (no `Model` wrapping) and `raw` is the server's original array
+ * payload. `count` mirrors the server's `count` field (the length of the
+ * returned array); the sibling server never emits a `totalCount` here.
+ */
+type SubDocumentListResponse<S, TData extends Partial<S> = S> = Response<TData[], TData[]> & {
+    count: number;
+};
 interface Task {
     type: string;
     args: unknown;
@@ -478,7 +731,15 @@ type RootDataOperation = 'list' | 'read';
 interface RootModelQueryMeta {
     target: 'model';
     name: string;
-    model: string;
+    /**
+     * Carries the model name when this entry is consumed as a sub-query
+     * source: the sibling server reads `model` from a `$$sq` payload to
+     * resolve the target model service. Top-level root entries omit `model`
+     * (the sibling `RootQueryEntry` schema uses `name`); the server schema
+     * permits extra fields via `.passthrough()`, so a stray `model` is
+     * harmless there.
+     */
+    model?: string;
     op: RootModelOperation;
     id?: string;
     sub?: string;
@@ -505,6 +766,7 @@ interface RootDataQueryMeta {
 type RootQueryMeta = RootModelQueryMeta | RootDataQueryMeta;
 interface ModelPromiseMeta {
     __op: string;
+    __throwOnError?: boolean;
     __query: RootModelQueryMeta;
     __requestConfig?: AxiosRequestConfig;
     __service?: ModelService<Document>;
@@ -520,6 +782,7 @@ type ListDataResponse<T> = ArrayDataResponse<T> & {
 };
 interface DataPromiseMeta {
     __op: string;
+    __throwOnError?: boolean;
     __query: RootDataQueryMeta;
     __requestConfig?: AxiosRequestConfig;
     __service?: DataService<unknown>;
@@ -532,15 +795,86 @@ interface WrapOptions {
     pathParams?: Record<string, string | number>;
 }
 
+/**
+ * Adapter-scoped cache control surface returned by `useCacheInterceptors`.
+ * The adapter delegates `clearCache()` to {@link clear} on credential
+ * transitions (login/logout/token refresh/tenant change) and
+ * `disposeCache()` to {@link dispose} when the adapter is torn down to
+ * release cache timers so they do not keep a Node process alive.
+ */
+interface CacheController {
+    clear(): void;
+    dispose(): void;
+}
+/**
+ * Resolves a stable, non-secret identity partition token for a credentialed
+ * request. Requests that share a token share cache entries; requests with
+ * different tokens never do. Returning `undefined` bypasses the cache for that
+ * credentialed request, so credentials cannot be reused across identities.
+ *
+ * The token is mixed into the cache key alongside the URL and request body. Do
+ * not return raw cookies, authorization values, or other secrets; sensitive
+ * auth headers are excluded from cache keys regardless of the returned token.
+ */
+type CachePartitioner = (config: InternalAxiosRequestConfig) => string | undefined;
+
+/**
+ * Options for {@link createAdapter}. `rootRouterPath` is the single-segment
+ * path used by `adapter.group(...)` for batched root requests
+ * (defaults to `'root'`). Per-adapter `onSuccess`/`onFailure`/`throwOnError`
+ * apply to every service created by this adapter and are overridden by
+ * per-service options on {@link ModelServiceOptions} and
+ * {@link DataServiceOptions}.
+ *
+ * Cache controls (only in effect when `cacheTTL > 0`):
+ *
+ * - `cacheTTL` — seconds a cached GET response is reused before revalidation.
+ * - `cachePartition` — required to cache credentialed requests safely (see
+ *   {@link CachePartitioner}); credentialed requests without a stable,
+ *   non-secret partition token bypass the cache so one identity cannot
+ *   receive a response created under another.
+ * - `cacheCapacity` — bounds the number of cached entries; defaults to 100 and
+ *   evicts the LRU entry when the limit is exceeded.
+ *
+ * Use the returned adapter's `clearCache()` on credential transitions
+ * (login/logout/token refresh/tenant change) and `disposeCache()` when the
+ * adapter is no longer needed to release cache timers.
+ */
 interface AdapterOptions {
     rootRouterPath?: string;
     onSuccess?: ResponseCallback;
     onFailure?: ResponseCallback;
     throwOnError?: boolean;
     cacheTTL?: number;
+    /**
+     * Partition strategy for credentialed cache entries. When the adapter is
+     * credentialed (which is the default), caching is only enabled for requests
+     * whose `cachePartition` returns a stable, non-secret identity token. Requests
+     * without a partition key bypass the cache so that one identity can never
+     * receive a response created under another identity.
+     *
+     * The returned value must be a stable, non-secret token (for example a user
+     * id or tenant id). Never return raw cookies, authorization values, or other
+     * secrets; those headers are excluded from cache keys regardless.
+     */
+    cachePartition?: CachePartitioner;
+    /**
+     * Maximum number of cached entries retained per adapter. Defaults to 100.
+     */
+    cacheCapacity?: number;
     modelDefaults?: Defaults;
     dataDefaults?: DataDefaults;
 }
+/**
+ * Options for {@link createAdapter}.createModelService<T>. Mirrors the
+ * server-side `access-router` model route configuration: `modelName` is the
+ * server-registered model name, `basePath` is the URL segment relative to
+ * the adapter `baseURL` (e.g. `'users'` resolves to `${baseURL}/users`),
+ * `queryPath` defaults to `'__query'` and `mutationPath` defaults to
+ * `'__mutation'` — match these to the server's `queryRouteSegment` and
+ * mutation route configuration. Per-service `onSuccess`/`onFailure`/
+ * `throwOnError` override the adapter-level defaults.
+ */
 interface ModelServiceOptions {
     modelName: string;
     basePath: string;
@@ -550,6 +884,14 @@ interface ModelServiceOptions {
     onFailure?: ResponseCallback;
     throwOnError?: boolean;
 }
+/**
+ * Options for {@link createAdapter}.createDataService<T>. Mirrors the
+ * server-side `access-router` data route configuration: `dataName` is the
+ * server-registered data name, `basePath` is the URL segment relative to
+ * the adapter `baseURL`, `queryPath` defaults to `'__query'`. Per-service
+ * `onSuccess`/`onFailure`/`throwOnError` override the adapter-level
+ * defaults.
+ */
 interface DataServiceOptions {
     dataName: string;
     basePath: string;
@@ -561,13 +903,39 @@ interface DataServiceOptions {
 /**
  * Creates a typed API adapter for `@web-ts-toolkit/access-router` model and data routes.
  *
+ * The adapter owns its own Axios instance, optional request cache, and
+ * per-adapter identity token (used by {@link group} to reject requests
+ * owned by a different adapter before any network activity). The returned
+ * adapter is frozen and exposes:
+ *
+ * - `axios` — the underlying Axios instance for advanced configuration or
+ *   attaching interceptors (the package's cache interceptors are installed
+ *   when `cacheTTL > 0`).
+ * - `createModelService<T>(...)` / `createDataService<T>(...)` — typed
+ *   factories for the model and data route clients.
+ * - `clearCache()` / `disposeCache()` — adapter-scoped cache controls
+ *   installed by {@link AdapterOptions.cacheTTL}. `clearCache()` drops all
+ *   cached entries (call on login/logout/token refresh/tenant switch);
+ *   `disposeCache()` also releases the cache's timers so a long-lived
+ *   adapter can be torn down cleanly.
+ * - `wrapGet` / `wrapPost` / `wrapPut` / `wrapPatch` / `wrapDelete` —
+ *   low-level helpers that wrap a raw Axios call to a single path segment
+ *   with `pathParams`/`queryParams` templating and the package's
+ *   normalized success/failure handling.
+ * - `group(...)` — batches multiple lazy requests created by this
+ *   adapter's services into one root round trip. Rejected before network
+ *   activity if any input has already started execution or was created by
+ *   a different adapter.
+ *
  * @example
  * const adapter = createAdapter({ baseURL: 'http://localhost:3000/api' });
  * const userService = adapter.createModelService<User>({ modelName: 'User', basePath: 'users' });
  */
 declare function createAdapter(axiosConfig?: AxiosRequestConfig, adapterOptions?: AdapterOptions): Readonly<{
     axios: axios.AxiosInstance;
-    createModelService: <T>({ modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError, }: ModelServiceOptions, defaults?: Defaults) => ModelService<T>;
+    clearCache: () => void;
+    disposeCache: () => void;
+    createModelService: <T extends Document>({ modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError, }: ModelServiceOptions, defaults?: Defaults) => ModelService<T>;
     createDataService: <T>({ dataName, basePath, queryPath, onSuccess, onFailure, throwOnError }: DataServiceOptions, defaults?: DataDefaults) => DataService<T>;
     wrapGet: <T = unknown>(url: string, defaultConfig?: AxiosRequestConfig) => (options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<axios.AxiosResponse<T, any, {}>>;
     wrapPost: <T = unknown>(url: string, defaultConfig?: AxiosRequestConfig) => (data?: unknown, options?: WrapOptions, requestConfig?: AxiosRequestConfig) => Promise<axios.AxiosResponse<T, any, {}>>;
@@ -596,4 +964,4 @@ declare function removeItemById<T extends {
     _id: string;
 }>(items: T[], targetItem: T): T[];
 
-export { type AdditionalReqConfig, type ArrayDataResponse, type ArrayModelResponse, type CreateAdvancedArgs, type CreateAdvancedOptions, type CreateOptions, CustomHeaders, type DataDefaults, type DataListAdvancedArgs, type DataListAdvancedOptions, type DataListArgs, type DataListOptions, type DataPromiseMeta, type DataReadAdvancedArgs, type DataReadAdvancedOptions, type DataReadOptions, type DataRequest, type DataResponse, DataService, type Defaults, type Document, type FilterQuery, type Include, type KeyValueProjection, type LazyRequest, type ListAdvancedArgs, type ListAdvancedOptions, type ListArgs, type ListDataResponse, type ListModelResponse, type ListOptions, Model, type ModelPromiseMeta, type ModelRequest, type ModelResponse, ModelService, type Populate, type PopulateAccess, type Projection, type ReadAdvancedArgs, type ReadAdvancedOptions, type ReadOptions, type ResolvedSelectedShape, type Response, type ResponseCallback, type ResultError, type RootDataQueryMeta, type RootModelQueryMeta, type RootQueryMeta, type SelectedKeys, type SelectedShape, Service, ServiceError, type Sort, type SortOrder, type SubQueryOptions, type Task, type UpdateAdvancedArgs, type UpdateAdvancedOptions, type UpdateOptions, type UpsertAdvancedArgs, type UpsertAdvancedOptions, type UpsertOptions, type WrapOptions, createAdapter, removeItemById, replaceItemById, wrapLazyPromise };
+export { type AdapterOptions, type AdditionalReqConfig, type ArrayDataResponse, type ArrayModelResponse, type CacheController, type CachePartitioner, type CreateAdvancedArgs, type CreateAdvancedOptions, type CreateOptions, CustomHeaders, type DataDefaults, type DataListAdvancedArgs, type DataListAdvancedOptions, type DataListArgs, type DataListOptions, type DataPromiseMeta, type DataReadAdvancedArgs, type DataReadAdvancedOptions, type DataReadOptions, type DataRequest, type DataResponse, DataService, type DataServiceOptions, type Defaults, type Document, type DottedPathFilter, type FailureResult, type FilterQuery, type Include, type KeyValueProjection, type LazyRequest, type ListAdvancedArgs, type ListAdvancedOptions, type ListArgs, type ListDataResponse, type ListModelResponse, type ListOptions, MissingPersistenceIdentityError, Model, type ModelPromiseMeta, type ModelRequest, type ModelResponse, ModelService, type ModelServiceOptions, type Populate, type PopulateAccess, type Projection, type ReadAdvancedArgs, type ReadAdvancedOptions, type ReadOptions, type ResolvedSelectedShape, type Response, type ResponseCallback, type ResultError, type RootDataQueryMeta, type RootModelQueryMeta, type RootQueryMeta, type SelectedKeys, type SelectedShape, type ServerSideCast, Service, ServiceError, type Sort, type SortOrder, type SubDocumentListResponse, type SubDocumentResponse, type SubQueryOptions, type SuccessResult, type Task, type UpdateAdvancedArgs, type UpdateAdvancedOptions, type UpdateOptions, type UpsertAdvancedArgs, type UpsertAdvancedOptions, type UpsertOptions, type WrapOptions, createAdapter, removeItemById, replaceItemById, wrapLazyPromise };