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

package/index.mjs

@@ -1,10 +1,8 @@
 // src/adapter.ts
-import axios, { mergeConfig as mergeConfig5 } from "axios";
-import { castArray, isEmpty } from "@web-ts-toolkit/utils";
+import axios2, { mergeConfig as mergeConfig5 } from "axios";
 
 // src/services/model-service.ts
 import { mergeConfig as mergeConfig3 } from "axios";
-import { set as set3 } from "@web-ts-toolkit/utils";
 
 // src/model.ts
 import {
@@ -12,42 +10,162 @@ import {
   cloneDeep,
   get as getValue,
   hasOwn,
+  isEqual,
   omit,
   pick,
   set as setValue
 } from "@web-ts-toolkit/utils";
+var MissingPersistenceIdentityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MissingPersistenceIdentityError";
+  }
+};
 var Model = class _Model {
-  constructor(data, adapter) {
+  constructor(data, adapter, persistenceId, fromExisting) {
     this.modifiedPaths = /* @__PURE__ */ new Set();
+    this._persistenceId = persistenceId;
+    this._fromExisting = fromExisting ?? false;
     this._snapshot = cloneDeep(data);
     this.defineHiddenDataProp(cloneDeep(data));
     this.defineHiddenAdapterProp(adapter);
     this.definePublicDataProps();
     this.initializeDirtyState();
   }
-  static create(data, adapter) {
-    return new _Model(data, adapter);
-  }
+  static create(data, adapter, persistenceId, fromExisting) {
+    return new _Model(data, adapter, persistenceId, fromExisting);
+  }
+  /**
+   * 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.
+   */
   async save(reqConfig) {
-    let result;
-    if (this._data._id) {
-      result = await this._service.update(this._data._id, this.prepareData(), { returningAll: false }, reqConfig);
-    } else {
-      result = await this._service.create(this.prepareData(), null, reqConfig);
+    const submittedPaths = new Set(this.modifiedPaths);
+    const submittedValues = {};
+    for (const path of submittedPaths) {
+      submittedValues[path] = cloneDeep(getValue(this._data, path));
+    }
+    const submittedData = this.prepareData();
+    const persistenceId = this._data._id ?? this._persistenceId;
+    if (persistenceId == null && this._fromExisting) {
+      throw new MissingPersistenceIdentityError(
+        "Model.save() cannot determine create-vs-update without a persistence identity. A read of an existing document produced a Model whose projection strips `_id` and no identity was captured at read time. Use `read(id)` / `readAdvanced(id, ...)` (which capture the identifier as a persistence identity), or include `_id` in the projection."
+      );
+    }
+    const isCreate = persistenceId == null;
+    const result = isCreate ? await this._service.create(submittedData, null, reqConfig) : await this._service.update(String(persistenceId), submittedData, { returningAll: false }, reqConfig);
+    if (!result.success) {
+      return { ...result, data: null };
+    }
+    const isConcurrentEdit = (path) => {
+      if (!submittedPaths.has(path)) {
+        return this.modifiedPaths.has(path);
+      }
+      const current = getValue(this._data, path);
+      const submitted = submittedValues[path];
+      return !isEqual(current, submitted);
+    };
+    const serverData = result.raw ?? {};
+    for (const key of Object.keys(serverData)) {
+      const normKey = this.normalizePath(key);
+      if (normKey === "_id") continue;
+      if (isConcurrentEdit(normKey)) {
+        continue;
+      }
+      const serverValue = serverData[key];
+      const before = getValue(this._data, normKey);
+      if (!isEqual(before, serverValue)) {
+        this._data[normKey] = serverValue;
+      }
+      this.modifiedPaths.delete(normKey);
+    }
+    for (const path of submittedPaths) {
+      if (!isConcurrentEdit(path)) {
+        this.modifiedPaths.delete(path);
+      }
+    }
+    if (isCreate && serverData._id != null) {
+      this._data._id = String(serverData._id);
+      this.modifiedPaths.delete("_id");
     }
-    if (result.success) {
-      this.updateModel(result.raw);
-      this._snapshot = cloneDeep(this._data);
-      this.modifiedPaths.clear();
+    const latestId = this._data._id ?? (serverData._id != null ? String(serverData._id) : void 0);
+    if (latestId != null) {
+      this._persistenceId = latestId;
     }
+    const nextSnapshot = Array.isArray(this._snapshot) ? [] : {};
+    const dataRecord = this._data;
+    for (const key of Object.keys(dataRecord)) {
+      const normKey = this.normalizePath(key);
+      if (this.modifiedPaths.has(normKey)) {
+        if (submittedPaths.has(normKey)) {
+          nextSnapshot[key] = cloneDeep(hasOwn(serverData, key) ? serverData[key] : submittedValues[normKey]);
+        } else {
+          nextSnapshot[key] = cloneDeep(this._snapshot[key]);
+        }
+      } else {
+        nextSnapshot[key] = cloneDeep(dataRecord[key]);
+      }
+    }
+    this._snapshot = nextSnapshot;
+    this.definePublicDataProps();
     return {
       ...result,
-      data: result.success ? _Model.create(this._data, this._service) : null
+      // The post-save snapshot is always an existing document, so propagate
+      // `_fromExisting=true` plus the refreshed persistence identity so the
+      // returned wrapper cannot later silently create a duplicate. (If the
+      // caller intends a fresh draft, they construct `new Model({...}, s)`
+      // directly — `${_fromExisting}` defaults to `false` there.)
+      data: _Model.create(this._data, this._service, this._persistenceId, true)
     };
   }
   isDirty(path) {
     return path ? this.modifiedPaths.has(this.normalizePath(String(path))) : this.modifiedPaths.size > 0;
   }
+  /**
+   * 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) {
     this.trackModified(String(path));
     return this;
@@ -63,6 +181,7 @@ var Model = class _Model {
     setValue(this._data, path, value);
     this.trackModified(path);
     this.definePublicDataProps();
+    this.reconcilePath(this.normalizePath(path));
     return this;
   }
   assign(partial) {
@@ -75,6 +194,9 @@ var Model = class _Model {
       }
     }
     this.definePublicDataProps();
+    for (let x = 0; x < keys.length; x++) {
+      this.reconcilePath(this.normalizePath(String(keys[x])));
+    }
     return this;
   }
   reset() {
@@ -88,10 +210,6 @@ var Model = class _Model {
   toJSON() {
     return this.toObject();
   }
-  updateModel(data) {
-    assignObject(this._data, data);
-    this.definePublicDataProps();
-  }
   replaceData(data) {
     const nextData = cloneDeep(data);
     const currentKeys = Object.keys(this._data);
@@ -105,7 +223,7 @@ var Model = class _Model {
     this.definePublicDataProps();
   }
   initializeDirtyState() {
-    if (this._data._id) {
+    if (this._fromExisting || this._data._id) {
       return;
     }
     const keys = Object.keys(this._data);
@@ -129,6 +247,7 @@ var Model = class _Model {
           }
           this.trackModified(keystr);
           target[key] = value;
+          this.reconcilePath(this.normalizePath(keystr));
           return true;
         }
       }),
@@ -164,24 +283,42 @@ var Model = class _Model {
   normalizePath(path) {
     return path.split(".")[0];
   }
+  /**
+   * 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.
+   */
+  reconcilePath(path) {
+    if (path === "_id") return;
+    if (!this.modifiedPaths.has(path)) return;
+    const current = this._data[path];
+    const base = this._snapshot[path];
+    if (isEqual(current, base)) {
+      this.modifiedPaths.delete(path);
+    }
+  }
 };
 
 // src/services/service.ts
-import { AxiosHeaders } from "axios";
+import { AxiosHeaders as AxiosHeaders2 } from "axios";
 
 // src/constants.ts
 var CACHE_HEADER = "x-axios-cache";
 
 // src/services/wrap.ts
-import { mergeConfig } from "axios";
-import { set } from "@web-ts-toolkit/utils";
+import { AxiosHeaders, mergeConfig } from "axios";
 
 // src/helpers.ts
 import { isPlainObject, mapValues } from "@web-ts-toolkit/utils";
 function replaceSubQuery(filter) {
   if (!isPlainObject(filter)) return filter;
   const ret = mapValues(filter, (val) => {
-    if (val && val.__op && val.__query) {
+    if (isPlainObject(val) && "__op" in val && val.__op && "__query" in val && val.__query) {
       return {
         $$sq: val.__query
       };
@@ -196,16 +333,20 @@ function replaceSubQuery(filter) {
   });
   return ret;
 }
+function encodePathSegment(value) {
+  if (value === void 0 || value === null) return "";
+  return encodeURIComponent(String(value));
+}
 function template(templateString, data) {
   return templateString.replace(/\{\{(\w+)\}\}/g, (match, key) => {
-    return data[key] !== void 0 ? data[key] : match;
+    return data[key] !== void 0 ? encodePathSegment(data[key]) : match;
   });
 }
 function getWrapContext(url, options, config) {
   const { queryParams, pathParams } = options ?? {};
   const finalUrl = pathParams ? template(url, pathParams) : url;
-  if (queryParams && config) config.params = queryParams;
-  return { finalUrl, finalConfig: config };
+  const finalConfig = queryParams && config ? { ...config, params: queryParams } : queryParams && !config ? { params: queryParams } : config;
+  return { finalUrl, finalConfig };
 }
 
 // src/services/wrap.ts
@@ -215,10 +356,12 @@ function resolveUrl(basePath, url) {
   return basePath ? `${removeTrailingSlash(basePath)}/${removeLeadingSlash(url)}` : url;
 }
 function prepareConfig(defaultConfig, cacheValue, requestConfig) {
-  set(defaultConfig, `headers.${CACHE_HEADER}`, cacheValue);
-  return mergeConfig(defaultConfig, requestConfig);
+  const headerClone = new AxiosHeaders(defaultConfig.headers);
+  headerClone.set(CACHE_HEADER, cacheValue);
+  const defaulted = { ...defaultConfig, headers: headerClone };
+  return mergeConfig(defaulted, requestConfig);
 }
-function createWrapHelper(axios2, basePath) {
+function createWrapHelper(axios3, basePath) {
   return {
     wrapGet: (url, defaultConfig = {}) => {
       const _url = resolveUrl(basePath, url);
@@ -228,7 +371,7 @@ function createWrapHelper(axios2, basePath) {
           options,
           prepareConfig(defaultConfig, "true", requestConfig)
         );
-        return axios2.get(finalUrl, finalConfig);
+        return axios3.get(finalUrl, finalConfig);
       };
     },
     wrapPost: (url, defaultConfig = {}) => {
@@ -239,7 +382,7 @@ function createWrapHelper(axios2, basePath) {
           options,
           prepareConfig(defaultConfig, "false", requestConfig)
         );
-        return axios2.post(finalUrl, data, finalConfig);
+        return axios3.post(finalUrl, data, finalConfig);
       };
     },
     wrapPut: (url, defaultConfig = {}) => {
@@ -250,7 +393,7 @@ function createWrapHelper(axios2, basePath) {
           options,
           prepareConfig(defaultConfig, "false", requestConfig)
         );
-        return axios2.put(finalUrl, data, finalConfig);
+        return axios3.put(finalUrl, data, finalConfig);
       };
     },
     wrapPatch: (url, defaultConfig = {}) => {
@@ -261,7 +404,7 @@ function createWrapHelper(axios2, basePath) {
           options,
           prepareConfig(defaultConfig, "false", requestConfig)
         );
-        return axios2.patch(finalUrl, data, finalConfig);
+        return axios3.patch(finalUrl, data, finalConfig);
       };
     },
     wrapDelete: (url, defaultConfig = {}) => {
@@ -272,7 +415,7 @@ function createWrapHelper(axios2, basePath) {
           options,
           prepareConfig(defaultConfig, "false", requestConfig)
         );
-        return axios2.delete(finalUrl, finalConfig);
+        return axios3.delete(finalUrl, finalConfig);
       };
     }
   };
@@ -322,38 +465,77 @@ var stringifyErrorPayload = (value) => {
     return String(value);
   }
 };
+function finalizeOperationResult({
+  success,
+  raw,
+  status,
+  headers = {},
+  message,
+  totalCount
+}) {
+  if (success) {
+    return {
+      success: true,
+      raw,
+      data: raw,
+      message: "",
+      status,
+      headers,
+      ...totalCount == null ? {} : { totalCount }
+    };
+  }
+  return {
+    success: false,
+    raw,
+    data: null,
+    message: message ?? stringifyErrorPayload(raw),
+    status,
+    headers,
+    ...totalCount == null ? {} : { totalCount }
+  };
+}
+var normalizeTransportFailure = (error) => {
+  const transportError = error && typeof error === "object" ? error : {};
+  let raw = null;
+  let status = 0;
+  let headers = {};
+  let message;
+  if (transportError.response) {
+    status = transportError.response.status;
+    headers = transportError.response.headers;
+    raw = transportError.response.data;
+  } else if (transportError.request) {
+    message = "The server is not responding";
+  } else {
+    message = transportError.message;
+  }
+  return finalizeOperationResult({ success: false, raw, status, headers, message });
+};
 var Service = class {
-  constructor(axios2, basePath) {
-    this._axios = axios2;
+  constructor(axios3, basePath, throwOnError = false) {
+    this._axios = axios3;
     this._basePath = basePath;
-    this._wrap = createWrapHelper(axios2, basePath);
+    this._wrap = createWrapHelper(axios3, basePath);
+    this._throwOnError = throwOnError;
   }
   handleSuccess(res, extra = {}) {
-    return { success: true, raw: res.data, status: res.status, headers: res.headers, ...extra };
+    return {
+      ...finalizeOperationResult({
+        success: true,
+        raw: res.data,
+        status: res.status,
+        headers: res.headers
+      }),
+      ...extra
+    };
   }
   // See https://axios-http.com/docs/handling-errors
   handleError(error) {
-    const result = {
-      success: false,
-      raw: null,
-      data: null,
-      message: "",
-      status: 0,
-      headers: {}
-    };
-    if (error.response) {
-      result.status = error.response.status;
-      result.headers = error.response.headers;
-      const responseData = error.response.data;
-      result.raw = responseData;
-      result.data = responseData;
-      result.message = stringifyErrorPayload(responseData);
-    } else if (error.request) {
-      result.message = "The server is not responding";
-    } else {
-      result.message = error.message;
-    }
-    return result;
+    return normalizeTransportFailure(error);
+  }
+  /** Resolves per-call policy against the already-resolved service/adapter default. */
+  resolveThrowOnError(override) {
+    return override ?? this._throwOnError;
   }
   wrapGet(url, defaultAxiosRequestConfig = {}) {
     return this._wrap.wrapGet(url, defaultAxiosRequestConfig);
@@ -370,15 +552,40 @@ var Service = class {
   wrapDelete(url, defaultAxiosRequestConfig = {}) {
     return this._wrap.wrapDelete(url, defaultAxiosRequestConfig);
   }
+  /**
+   * 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(res, throwOnErrorOverride) {
+    const handler = this._handleCallbacks;
+    return handler ? handler(res, throwOnErrorOverride) : res;
+  }
+  /**
+   * 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, { ignoreCache }) {
     const cacheValue = ignoreCache ? "false" : "true";
     if (!headers) {
       return { [CACHE_HEADER]: cacheValue };
     }
-    if (headers instanceof AxiosHeaders) {
+    if (headers instanceof AxiosHeaders2) {
       if (headers.has(CACHE_HEADER)) return headers;
-      headers.set(CACHE_HEADER, cacheValue);
-      return headers;
+      const cloned = new AxiosHeaders2(headers.toJSON());
+      cloned.set(CACHE_HEADER, cacheValue);
+      return cloned;
     }
     if (CACHE_HEADER in headers) return headers;
     return {
@@ -391,16 +598,399 @@ var ServiceError = class extends Error {
   constructor(result) {
     super(result.message);
     this.name = "ServiceError";
-    this.success = result.success;
+    this.success = false;
     this.raw = result.raw;
-    this.data = result.data;
+    this.data = null;
     this.status = result.status;
     this.headers = result.headers;
   }
 };
 
+// src/services/interceptors.ts
+import axios, { AxiosHeaders as AxiosHeaders4 } from "axios";
+
+// src/services/cache-utils.ts
+import { AxiosHeaders as AxiosHeaders3 } from "axios";
+import { omitBy } from "@web-ts-toolkit/utils";
+var normalizeConfigValue = (value) => {
+  if (value == null) return value;
+  if (value instanceof AxiosHeaders3) {
+    return normalizeConfigValue(value.toJSON());
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeConfigValue(item));
+  }
+  if (typeof value === "object") {
+    return Object.entries(omitBy(value, (item) => item === void 0)).sort(([left], [right]) => left.localeCompare(right)).reduce((acc, [key, item]) => {
+      acc[key] = normalizeConfigValue(item);
+      return acc;
+    }, {});
+  }
+  return value;
+};
+
+// src/services/interceptors.ts
+var DEFAULT_CACHE_CAPACITY = 100;
+var CACHEABLE_METHODS = /* @__PURE__ */ new Set(["get"]);
+var MUTATION_METHODS = /* @__PURE__ */ new Set(["post", "put", "patch", "delete"]);
+var CACHEABLE_RESPONSE_TYPES = /* @__PURE__ */ new Set(["", "json", "text"]);
+var SENSITIVE_CACHE_HEADERS = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "proxy-authorization",
+  "www-authenticate"
+]);
+var cloneConfigWithCacheBypass = (config) => {
+  const baseConfig = config ?? {};
+  const next = { ...baseConfig };
+  const sourceHeaders = config?.headers;
+  if (sourceHeaders instanceof AxiosHeaders4) {
+    next.headers = sourceHeaders.toJSON();
+  } else if (sourceHeaders && typeof sourceHeaders === "object") {
+    next.headers = { ...sourceHeaders };
+  } else {
+    next.headers = {};
+  }
+  next.headers[CACHE_HEADER] = "false";
+  return next;
+};
+var SimpleCache = class {
+  constructor(opts = {}) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.timers = /* @__PURE__ */ new Map();
+    this.capacity = opts.capacity !== void 0 && Number.isFinite(opts.capacity) && opts.capacity > 0 ? Math.floor(opts.capacity) : DEFAULT_CACHE_CAPACITY;
+    this.clone = opts.clone ?? defaultClone;
+  }
+  set(key, value, ttl) {
+    if (this.cache.size >= this.capacity && !this.cache.has(key)) {
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.delete(oldestKey);
+      }
+    }
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    if (ttl && ttl > 0) {
+      const existing = this.timers.get(key);
+      if (existing) clearTimeout(existing);
+      const timer = setTimeout(() => {
+        this.cache.delete(key);
+        this.timers.delete(key);
+      }, ttl);
+      if (typeof timer === "object" && timer && "unref" in timer && typeof timer.unref === "function") {
+        timer.unref();
+      }
+      this.timers.set(key, timer);
+    }
+  }
+  get(key) {
+    const value = this.cache.get(key);
+    if (value === void 0) {
+      return void 0;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return this.clone(value);
+  }
+  has(key) {
+    return this.cache.has(key);
+  }
+  delete(key) {
+    const timer = this.timers.get(key);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+    return this.cache.delete(key);
+  }
+  clear() {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.cache.clear();
+  }
+  dispose() {
+    this.clear();
+  }
+};
+var defaultClone = (value) => {
+  if (value == null) return value;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return value;
+  }
+};
+var CACHE_REQUEST_STATE = /* @__PURE__ */ Symbol("access-router-client.cache-request-state");
+var CACHE_DISPOSED_ERROR = "Access router client cache was disposed while the request was in flight";
+var setCacheRequestState = (config, state) => {
+  Object.defineProperty(config, CACHE_REQUEST_STATE, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: Object.freeze(state)
+  });
+};
+var isUnsupportedResponseBody = (response) => {
+  const responseType = response.config?.responseType;
+  if (responseType === "stream" || responseType === "arraybuffer" || responseType === "blob" || responseType === "document") {
+    return true;
+  }
+  const data = response.data;
+  if (data == null) return false;
+  if (typeof data === "string") return false;
+  if (typeof data !== "object") return false;
+  if (Array.isArray(data)) return false;
+  try {
+    JSON.stringify(data);
+    return false;
+  } catch {
+    return true;
+  }
+};
+var snapshotResponse = (response) => {
+  const headers = response.headers instanceof AxiosHeaders4 ? response.headers.toJSON() : { ...response.headers ?? {} };
+  return {
+    data: defaultClone(response.data),
+    status: response.status,
+    statusText: response.statusText,
+    headers: defaultClone(headers)
+  };
+};
+var serializeHeaders = (headers) => {
+  const resolvedHeaders = headers instanceof AxiosHeaders4 ? headers.toJSON() : headers;
+  const normalizedHeaders = Object.entries(resolvedHeaders ?? {}).filter(([key, value]) => {
+    const normalizedKey = key.toLowerCase();
+    return normalizedKey !== CACHE_HEADER.toLowerCase() && !SENSITIVE_CACHE_HEADERS.has(normalizedKey) && value !== void 0;
+  }).reduce((acc, [key, value]) => {
+    acc[key.toLowerCase()] = value;
+    return acc;
+  }, {});
+  return JSON.stringify(normalizeConfigValue(normalizedHeaders));
+};
+var hasStableCacheValue = (value, seen = /* @__PURE__ */ new Set()) => {
+  if (value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+    return true;
+  if (typeof value !== "object") return false;
+  if (seen.has(value)) return false;
+  if (value instanceof AxiosHeaders4) {
+    return hasStableCacheValue(value.toJSON(), seen);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) return false;
+  seen.add(value);
+  const stable = Object.values(value).every((item) => hasStableCacheValue(item, seen));
+  seen.delete(value);
+  return stable;
+};
+var sameTransform = (configured, defaultValue) => {
+  const configuredList = Array.isArray(configured) ? configured : [configured];
+  const defaultList = Array.isArray(defaultValue) ? defaultValue : [defaultValue];
+  return configuredList.length === defaultList.length && configuredList.every((item, index) => item === defaultList[index]);
+};
+var sameConfigIdentity = (configured, defaultValue) => {
+  if (Array.isArray(configured) && Array.isArray(defaultValue)) {
+    return configured.length === defaultValue.length && configured.every((item, index) => item === defaultValue[index]);
+  }
+  return configured === defaultValue;
+};
+var isCacheEligible = (config, instance) => {
+  const method = (config.method ?? "get").toLowerCase();
+  const responseType = config.responseType ?? "";
+  return CACHEABLE_METHODS.has(method) && CACHEABLE_RESPONSE_TYPES.has(responseType) && config.paramsSerializer === void 0 && config.auth === void 0 && config.signal === void 0 && config.cancelToken === void 0 && config.onDownloadProgress === void 0 && config.onUploadProgress === void 0 && sameConfigIdentity(config.adapter, instance.defaults.adapter) && sameTransform(config.transformRequest, instance.defaults.transformRequest) && sameTransform(config.transformResponse, instance.defaults.transformResponse) && hasStableCacheValue(config.params) && hasStableCacheValue(config.data) && hasStableCacheValue(config.headers);
+};
+function generateCacheKey(config, partition) {
+  const responseSemantics = JSON.stringify({
+    responseType: config.responseType ?? "",
+    responseEncoding: config.responseEncoding ?? "",
+    decompress: config.decompress ?? true,
+    timeout: config.timeout ?? 0,
+    maxContentLength: config.maxContentLength ?? -1,
+    maxBodyLength: config.maxBodyLength ?? -1,
+    withCredentials: Boolean(config.withCredentials),
+    transitional: normalizeConfigValue(config.transitional)
+  });
+  const key = `${config.baseURL}/${config.url}_${config.method}_${generateParamKey(config.params)}_${generateDataKey(
+    config.data
+  )}_${partition ?? ""}_${serializeHeaders(config.headers)}_${responseSemantics}`;
+  return encodeURI(key);
+}
+function generateParamKey(params) {
+  if (!params) return "";
+  return JSON.stringify(normalizeConfigValue(params));
+}
+function generateDataKey(data) {
+  if (!data) return "";
+  return typeof data === "string" ? data : JSON.stringify(normalizeConfigValue(data));
+}
+var resolveWithCredentials = (config, withCredentialsDefault) => {
+  if (config.withCredentials !== void 0) {
+    return Boolean(config.withCredentials);
+  }
+  return withCredentialsDefault;
+};
+function useCacheInterceptors(instance, policyOrTtl) {
+  const policy = typeof policyOrTtl === "number" ? { ttl: policyOrTtl } : policyOrTtl;
+  const store = new SimpleCache({ capacity: policy.capacity, clone: policy.clone });
+  const withCredentialsDefault = policy.withCredentialsDefault ?? Boolean(instance.defaults.withCredentials);
+  const inflight = /* @__PURE__ */ new Map();
+  let generation = 0;
+  let disposed = false;
+  const finalizeInflight = (slot) => {
+    if (inflight.get(slot.key) === slot) {
+      inflight.delete(slot.key);
+    }
+  };
+  const resolveInflight = (slot, response) => {
+    if (slot.settled) return;
+    slot.settled = true;
+    slot.resolve(response);
+    finalizeInflight(slot);
+  };
+  const rejectInflight = (slot, error) => {
+    if (slot.settled) return;
+    slot.settled = true;
+    slot.reject(error);
+    finalizeInflight(slot);
+  };
+  const invalidate = () => {
+    generation += 1;
+    store.clear();
+    inflight.clear();
+  };
+  instance.interceptors.request.use(
+    async (config) => {
+      if (disposed || config.headers[CACHE_HEADER] === "false" || !isCacheEligible(config, instance)) return config;
+      const isCredentialed = resolveWithCredentials(config, withCredentialsDefault);
+      const partitionKey = policy.partitionForRequest?.(config);
+      if (isCredentialed && !partitionKey) {
+        return config;
+      }
+      const key = generateCacheKey(config, partitionKey);
+      policy.onCacheKey?.(key);
+      const snapshot = store.get(key);
+      if (snapshot) {
+        setCacheRequestState(config, Object.freeze({ key, generation, role: "hit" }));
+        config.adapter = async (_config) => {
+          return {
+            data: snapshot.data,
+            status: snapshot.status,
+            statusText: snapshot.statusText,
+            headers: { ...snapshot.headers, [CACHE_HEADER]: "true" },
+            config: _config
+          };
+        };
+        return config;
+      }
+      const existing = inflight.get(key);
+      if (existing) {
+        config.adapter = async (_config) => {
+          const response = await existing.promise;
+          const shared = response;
+          return {
+            data: defaultClone(shared.data),
+            status: shared.status,
+            statusText: shared.statusText,
+            headers: { ...shared.headers, [CACHE_HEADER]: "true" },
+            config: _config
+          };
+        };
+        setCacheRequestState(config, Object.freeze({ key, generation, role: "tail", slot: existing }));
+        return config;
+      }
+      let resolvePromise;
+      let rejectPromise;
+      const inflightPromise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+      });
+      inflightPromise.catch(() => {
+      });
+      const slot = {
+        key,
+        generation,
+        promise: inflightPromise,
+        resolve: resolvePromise,
+        reject: rejectPromise,
+        settled: false
+      };
+      inflight.set(key, slot);
+      const nextConfig = { ...config };
+      setCacheRequestState(nextConfig, Object.freeze({ key, generation, role: "source", slot }));
+      let realAdapter = config.adapter;
+      if (realAdapter === void 0 || realAdapter === null) {
+        realAdapter = instance.defaults.adapter;
+      }
+      const dispatch = typeof realAdapter === "function" ? realAdapter : typeof axios.getAdapter === "function" ? axios.getAdapter(
+        realAdapter,
+        instance.defaults
+      ) : void 0;
+      nextConfig.adapter = async (adapterConfig) => {
+        if (!dispatch) {
+          const response = await adapterConfig.adapter;
+          return response;
+        }
+        try {
+          const response = await dispatch(adapterConfig);
+          return response;
+        } catch (error) {
+          rejectInflight(slot, error);
+          throw error;
+        }
+      };
+      return nextConfig;
+    },
+    (error) => Promise.reject(error)
+  );
+  instance.interceptors.response.use(
+    (response) => {
+      const method = (response.config.method ?? "get").toLowerCase();
+      if (response.config.headers[CACHE_HEADER] === "false" || MUTATION_METHODS.has(method)) {
+        if (response.status >= 200 && response.status < 300) {
+          invalidate();
+        }
+        return response;
+      }
+      const state = response.config[CACHE_REQUEST_STATE];
+      if (!state || state.role !== "source" || !state.slot) {
+        return response;
+      }
+      if (response.status >= 200 && response.status < 300) {
+        if (!disposed && state.generation === generation && !isUnsupportedResponseBody(response)) {
+          store.set(state.key, snapshotResponse(response), policy.ttl);
+        }
+      }
+      resolveInflight(state.slot, response);
+      return response;
+    },
+    (error) => {
+      const state = (error?.config ?? {})[CACHE_REQUEST_STATE];
+      if (state?.role === "source" && state.slot) {
+        rejectInflight(state.slot, error);
+      }
+      return Promise.reject(error);
+    }
+  );
+  return {
+    clear: invalidate,
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      generation += 1;
+      store.dispose();
+      const error = new Error(CACHE_DISPOSED_ERROR);
+      for (const slot of inflight.values()) {
+        rejectInflight(slot, error);
+      }
+      inflight.clear();
+    }
+  };
+}
+
 // src/services/shared.ts
-import { get, noop, set as set2 } from "@web-ts-toolkit/utils";
+import { castArray, get, noop, set } from "@web-ts-toolkit/utils";
 
 // src/enums.ts
 var CustomHeaders = /* @__PURE__ */ ((CustomHeaders2) => {
@@ -415,10 +1005,118 @@ var CustomHeaders = /* @__PURE__ */ ((CustomHeaders2) => {
 })(CustomHeaders || {});
 
 // src/services/shared.ts
+var getSubdocumentResultShape = (query) => {
+  if (query.target !== "model") return void 0;
+  switch (query.op) {
+    case "subList":
+    case "subCreate":
+    case "subBulkUpdate":
+      return "list";
+    case "subRead":
+    case "subUpdate":
+      return "single";
+    case "subDelete":
+      return "scalar";
+    default:
+      return void 0;
+  }
+};
+function finalizeRootEntry(query, entry, responseHeaders, service) {
+  const { result, message: entryMessage, statusCode, op } = entry;
+  const success = result.success;
+  const baseResult = finalizeOperationResult({
+    success,
+    raw: success ? result.data : result,
+    status: statusCode,
+    headers: responseHeaders,
+    message: success ? void 0 : entryMessage
+  });
+  let _raw = baseResult.raw;
+  let _data = baseResult.data;
+  const subdocumentResultShape = getSubdocumentResultShape(query);
+  if (!success) {
+    _data = null;
+  } else if (subdocumentResultShape) {
+    if (subdocumentResultShape === "list") {
+      const rows = result.data == null ? [] : castArray(result.data);
+      _raw = rows;
+      _data = rows;
+    }
+  } else if (query.target === "model") {
+    const modelService = service;
+    if (result.kind === "list" && Array.isArray(result.data)) {
+      if (op === "create" && !Array.isArray(query.data) && result.data.length === 1) {
+        _raw = result.data[0];
+        if (modelService) {
+          _data = Model.create(result.data[0], modelService, void 0, true);
+        }
+      } else if (op !== "distinct") {
+        const rows = castArray(result.data);
+        if (modelService) {
+          _data = rows.map((item) => Model.create(item, modelService, void 0, true));
+        } else {
+          _data = rows;
+        }
+      }
+    } else if (result.kind === "single" && (op === "new" || op === "read" || op === "update" || op === "upsert")) {
+      if (op === "new" && result.data && typeof result.data === "object") {
+        const { _id: _generatedId, ...draft } = result.data;
+        void _generatedId;
+        _raw = draft;
+        _data = draft;
+      }
+      if (modelService) {
+        const fromExisting = op !== "new";
+        const persistenceId = op === "read" && query.target === "model" && "id" in query ? query.id : void 0;
+        _data = Model.create(_data, modelService, persistenceId, fromExisting);
+      }
+    }
+  }
+  const isSubdocumentList = subdocumentResultShape === "list";
+  const isModelOrDataList = !subdocumentResultShape && query.op === "list";
+  const returnedCount = Array.isArray(_data) ? _data.length : 0;
+  const totalCount = success && query.options?.includeCount === true ? result.totalCount ?? result.count ?? returnedCount : 0;
+  return {
+    success,
+    raw: _raw,
+    data: _data,
+    message: baseResult.message,
+    status: statusCode,
+    ...isSubdocumentList ? { count: success ? returnedCount : 0 } : {},
+    ...isModelOrDataList ? { totalCount } : {},
+    headers: responseHeaders
+  };
+}
+function finalizeRootTransportFailure(query, error) {
+  const failure = normalizeTransportFailure(error);
+  const subdocumentResultShape = getSubdocumentResultShape(query);
+  return {
+    ...failure,
+    ...subdocumentResultShape === "list" ? { count: 0 } : {},
+    ...!subdocumentResultShape && query.op === "list" ? { totalCount: 0 } : {}
+  };
+}
+function applyGroupCallbacks(entries, services, groupThrowOnError) {
+  let callbackError;
+  for (let i = 0; i < entries.length; i++) {
+    const svc = services[i];
+    try {
+      entries[i] = svc?.applyResponseCallbacks ? svc.applyResponseCallbacks(entries[i], false) : entries[i];
+    } catch (error) {
+      callbackError ??= error;
+    }
+  }
+  if (callbackError) throw callbackError;
+  if (groupThrowOnError) {
+    const failure = entries.find((entry) => !entry.success);
+    if (failure) throw new ServiceError(toResultError(failure));
+  }
+  return entries;
+}
 var toResultError = (result) => ({
   success: false,
   raw: result.raw ?? null,
-  data: result.data ?? null,
+  data: null,
   message: result.message ?? "",
   status: result.status ?? 0,
   headers: result.headers ?? {}
@@ -431,9 +1129,13 @@ var isLegacyListPayload = (value) => {
 };
 var setDefaultObjectProp = (obj, key, value) => {
   if (!get(obj, key)) {
-    set2(obj, key, value);
+    set(obj, key, value);
   }
 };
+var ensureListResultCount = (result) => {
+  result.totalCount ??= 0;
+  return result;
+};
 var createResponseHandler = (onSuccess, onFailure, throwOnError) => {
   const successHandler = onSuccess ?? noop;
   const failureHandler = onFailure ?? noop;
@@ -450,6 +1152,7 @@ var createResponseHandler = (onSuccess, onFailure, throwOnError) => {
   };
 };
 function processListResult(result, { includeCount, includeExtraHeaders }, wrapItem) {
+  ensureListResultCount(result);
   const wrappedRows = get(result, "raw.data");
   const wrappedTotalCount = get(result, "raw.meta.totalCount");
   if (Array.isArray(wrappedRows)) {
@@ -482,11 +1185,40 @@ function processListResult(result, { includeCount, includeExtraHeaders }, wrapIt
 }
 
 // src/lazy-promise.ts
+var STARTED_KEY = /* @__PURE__ */ Symbol("started");
+var executionClaims = /* @__PURE__ */ new WeakMap();
+var claimLazyRequest = (request, mode, owner) => {
+  const claim = executionClaims.get(request);
+  if (!claim) {
+    executionClaims.set(request, { mode, owner });
+    return;
+  }
+  if (mode === "grouped") {
+    if (claim.mode === "direct") {
+      throw new Error(
+        "Cannot group a request that has already started execution; group() must be called before await/then/catch/finally/exec on each input"
+      );
+    }
+    throw new Error("Cannot group a request already claimed for grouped execution");
+  }
+  throw new Error("Cannot execute a request already claimed for grouped execution");
+};
+var releaseLazyRequestClaim = (request, owner) => {
+  const claim = executionClaims.get(request);
+  if (claim?.mode === "grouped" && claim.owner === owner) {
+    executionClaims.delete(request);
+  }
+};
 var wrapLazyPromise = (promiseFn, meta) => {
   let promise;
   const exec = () => {
     if (!promise) {
-      promise = promiseFn();
+      try {
+        claimLazyRequest(prom, "direct");
+        promise = Promise.resolve().then(promiseFn);
+      } catch (error) {
+        promise = Promise.reject(error);
+      }
     }
     return promise;
   };
@@ -509,32 +1241,62 @@ var wrapLazyPromise = (promiseFn, meta) => {
     value: "Promise",
     writable: false,
     enumerable: false,
-    configurable: true
+    configurable: false
+  });
+  Object.defineProperty(prom, STARTED_KEY, {
+    get: () => executionClaims.has(prom),
+    enumerable: false,
+    configurable: false
   });
-  Object.assign(prom, meta);
+  if (meta != null) {
+    const metaKeys = Object.keys(meta);
+    for (let i = 0; i < metaKeys.length; i++) {
+      const key = metaKeys[i];
+      Object.defineProperty(prom, key, {
+        value: meta[key],
+        enumerable: false,
+        writable: false,
+        configurable: false
+      });
+    }
+  }
   return prom;
 };
 
 // src/services/request.ts
 function makeRequest(execute, meta) {
-  return wrapLazyPromise(execute, meta);
+  const effectiveMeta = {
+    ...meta,
+    __throwOnError: meta.__service?.resolveThrowOnError(meta.__throwOnError) ?? Boolean(meta.__throwOnError)
+  };
+  return wrapLazyPromise(execute, effectiveMeta);
 }
 
 // src/services/sub-ops.ts
 import { mergeConfig as mergeConfig2 } from "axios";
+var toArray = (value) => Array.isArray(value) ? value : value == null ? [] : [value];
+var ensureSubdocumentListCount = (result) => {
+  result.count ??= 0;
+  return result;
+};
 function buildSubDocumentOps(ctx, id, sub) {
-  const { axios: axios2, basePath, modelName, queryPath, handleSuccess, handleError, _handleCallbacks, parentService } = ctx;
-  const asS = parentService;
+  const { axios: axios3, basePath, modelName, queryPath, handleSuccess, handleError, _handleCallbacks, parentService } = ctx;
   return {
     list: (axiosRequestConfig) => {
       const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
       return makeRequest(
-        () => axios2.get(`${basePath}/${id}/${sub}`, mergeConfig2(reqConfig, { params: {} })).then(handleSuccess).then((result) => {
-          result.totalCount = Array.isArray(result.raw) ? result.raw.length : 0;
-          result.data = Array.isArray(result.raw) ? result.raw.map((item) => Model.create(item, asS)) : [];
+        () => axios3.get(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}`,
+          mergeConfig2(reqConfig, { params: {} })
+        ).then(handleSuccess).then((result) => {
+          const rawArray = toArray(result.raw);
+          result.raw = rawArray;
+          result.count = rawArray.length;
+          result.data = rawArray;
           return result;
-        }).catch(handleError).then((res) => _handleCallbacks(res, throwOnError)),
+        }).catch(handleError).then(ensureSubdocumentListCount).then((res) => _handleCallbacks(res, throwOnError)),
         {
+          __throwOnError: throwOnError,
           __op: "listSub",
           __query: {
             target: "model",
@@ -556,14 +1318,21 @@ function buildSubDocumentOps(ctx, id, sub) {
       const select = args?.select;
       const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
       return makeRequest(
-        () => axios2.post(`${basePath}/${id}/${sub}/${queryPath}`, { filter, select }, reqConfig).then(handleSuccess).then((result) => {
-          result.totalCount = Array.isArray(result.raw) ? result.raw.length : 0;
-          result.data = Array.isArray(result.raw) ? result.raw.map((item) => Model.create(item, asS)) : [];
+        () => axios3.post(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}/${queryPath}`,
+          { filter, select },
+          reqConfig
+        ).then(handleSuccess).then((result) => {
+          const rawArray = toArray(result.raw);
+          result.raw = rawArray;
+          result.count = rawArray.length;
+          result.data = rawArray;
           return result;
-        }).catch(handleError).then(
+        }).catch(handleError).then(ensureSubdocumentListCount).then(
           (res) => _handleCallbacks(res, throwOnError)
         ),
         {
+          __throwOnError: throwOnError,
           __op: "listAdvancedSub",
           __query: {
             target: "model",
@@ -584,11 +1353,15 @@ function buildSubDocumentOps(ctx, id, sub) {
     read: (subId, axiosRequestConfig) => {
       const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
       return makeRequest(
-        () => axios2.get(`${basePath}/${id}/${sub}/${subId}`, mergeConfig2(reqConfig, { params: {} })).then(handleSuccess).then((result) => {
-          result.data = result.success ? Model.create(result.raw, asS) : null;
+        () => axios3.get(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}/${encodePathSegment(subId)}`,
+          mergeConfig2(reqConfig, { params: {} })
+        ).then(handleSuccess).then((result) => {
+          result.data = result.success ? result.raw : null;
           return result;
         }).catch(handleError).then((res) => _handleCallbacks(res, throwOnError)),
         {
+          __throwOnError: throwOnError,
           __op: "readSub",
           __query: {
             target: "model",
@@ -610,13 +1383,18 @@ function buildSubDocumentOps(ctx, id, sub) {
       const { select, populate } = args ?? {};
       const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
       return makeRequest(
-        () => axios2.post(`${basePath}/${id}/${sub}/${subId}/${queryPath}`, { select, populate }, reqConfig).then(handleSuccess).then((result) => {
-          result.data = result.success ? Model.create(result.raw, asS) : null;
+        () => axios3.post(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}/${encodePathSegment(subId)}/${queryPath}`,
+          { select, populate },
+          reqConfig
+        ).then(handleSuccess).then((result) => {
+          result.data = result.success ? result.raw : null;
           return result;
         }).catch(handleError).then(
           (res) => _handleCallbacks(res, throwOnError)
         ),
         {
+          __throwOnError: throwOnError,
           __op: "readAdvancedSub",
           __query: {
             target: "model",
@@ -635,13 +1413,18 @@ function buildSubDocumentOps(ctx, id, sub) {
       );
     },
     update: (subId, data, axiosRequestConfig) => {
-      const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
+      const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
       return makeRequest(
-        () => axios2.patch(`${basePath}/${id}/${sub}/${subId}`, data, mergeConfig2(reqConfig, { params: {} })).then(handleSuccess).then((result) => {
-          result.data = result.success ? Model.create(result.raw, asS) : null;
+        () => axios3.patch(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}/${encodePathSegment(subId)}`,
+          data,
+          mergeConfig2(reqConfig, { params: {} })
+        ).then(handleSuccess).then((result) => {
+          result.data = result.success ? result.raw : null;
           return result;
         }).catch(handleError).then((res) => _handleCallbacks(res, throwOnError)),
         {
+          __throwOnError: throwOnError,
           __op: "updateSub",
           __query: {
             target: "model",
@@ -660,13 +1443,21 @@ function buildSubDocumentOps(ctx, id, sub) {
       );
     },
     bulkUpdate: (data, axiosRequestConfig) => {
-      const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
+      const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
       return makeRequest(
-        () => axios2.patch(`${basePath}/${id}/${sub}`, data, mergeConfig2(reqConfig, { params: {} })).then(handleSuccess).then((result) => {
-          result.data = Array.isArray(result.raw) ? result.raw.map((item) => Model.create(item, asS)) : [];
+        () => axios3.patch(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}`,
+          data,
+          mergeConfig2(reqConfig, { params: {} })
+        ).then(handleSuccess).then((result) => {
+          const rawArray = toArray(result.raw);
+          result.raw = rawArray;
+          result.count = rawArray.length;
+          result.data = rawArray;
           return result;
-        }).catch(handleError).then((res) => _handleCallbacks(res, throwOnError)),
+        }).catch(handleError).then(ensureSubdocumentListCount).then((res) => _handleCallbacks(res, throwOnError)),
         {
+          __throwOnError: throwOnError,
           __op: "bulkUpdateSub",
           __query: {
             target: "model",
@@ -684,30 +1475,42 @@ function buildSubDocumentOps(ctx, id, sub) {
       );
     },
     create: (data, axiosRequestConfig) => {
-      const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
+      const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
       return makeRequest(
-        () => axios2.post(`${basePath}/${id}/${sub}`, data, mergeConfig2(reqConfig, { params: {} })).then(handleSuccess).then((result) => {
-          result.data = result.success ? Model.create(result.raw, asS) : null;
+        () => axios3.post(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}`,
+          data,
+          mergeConfig2(reqConfig, { params: {} })
+        ).then(handleSuccess).then((result) => {
+          const rawArray = toArray(result.raw);
+          result.raw = rawArray;
+          result.count = rawArray.length;
+          result.data = rawArray;
           return result;
-        }).catch(handleError).then((res) => _handleCallbacks(res, throwOnError)),
+        }).catch(handleError).then(ensureSubdocumentListCount).then((res) => _handleCallbacks(res, throwOnError)),
         {
+          __throwOnError: throwOnError,
           __op: "createSub",
-          __query: { target: "model", name: modelName, model: modelName, op: "subCreate", id, sub, data, options: {} },
+          __query: { target: "model", name: modelName, op: "subCreate", id, sub, data, options: {} },
           __requestConfig: reqConfig,
           __service: parentService
         }
       );
     },
     delete: (subId, axiosRequestConfig) => {
-      const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
+      const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
       return makeRequest(
-        () => axios2.delete(`${basePath}/${id}/${sub}/${subId}`, reqConfig).then(handleSuccess).then((result) => {
-          result.data = result.raw;
+        () => axios3.delete(
+          `${basePath}/${encodePathSegment(id)}/${encodePathSegment(sub)}/${encodePathSegment(subId)}`,
+          reqConfig
+        ).then(handleSuccess).then((result) => {
+          if (result.success) result.data = result.raw;
           return result;
         }).catch(handleError).then((res) => _handleCallbacks(res, throwOnError)),
         {
+          __throwOnError: throwOnError,
           __op: "deleteSub",
-          __query: { target: "model", name: modelName, model: modelName, op: "subDelete", id, sub, subId },
+          __query: { target: "model", name: modelName, op: "subDelete", id, sub, subId },
           __requestConfig: reqConfig,
           __service: parentService
         }
@@ -718,8 +1521,8 @@ function buildSubDocumentOps(ctx, id, sub) {
 
 // src/services/model-service.ts
 var ModelService = class extends Service {
-  constructor({ axios: axios2, modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError }, defaults) {
-    super(axios2, basePath);
+  constructor({ axios: axios3, modelName, basePath, queryPath, mutationPath, onSuccess, onFailure, throwOnError }, defaults) {
+    super(axios3, basePath, throwOnError);
     this._modelName = modelName;
     this._queryPath = queryPath;
     this._mutationPath = mutationPath;
@@ -783,10 +1586,15 @@ var ModelService = class extends Service {
         return processListResult(
           result,
           { includeCount, includeExtraHeaders },
-          (item) => Model.create(item, this)
+          // ARC-21: list items come from existing documents, so mark
+          // them as `_fromExisting=true` even if the server response
+          // (or a custom adapter) strips `_id` — a save on such an item
+          // must throw rather than silently re-create.
+          (item) => Model.create(item, this, void 0, true)
         );
-      }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
+      }).catch(this.handleError).then(ensureListResultCount).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "list",
         __query: {
           target: "model",
@@ -795,7 +1603,7 @@ var ModelService = class extends Service {
           op: "list",
           filter: {},
           args: { skip, limit, page, pageSize },
-          options: { skim, includePermissions, includeCount, includeExtraHeaders },
+          options: { skim, includePermissions, includeCount },
           sqOptions: sq
         },
         __requestConfig: reqConfig,
@@ -848,12 +1656,18 @@ var ModelService = class extends Service {
         return processListResult(
           result,
           { includeCount, includeExtraHeaders },
-          (item) => Model.create(item, this)
+          (item) => (
+            // ARC-21: listAdvanced items come from existing documents;
+            // mark `_fromExisting=true` so a save cannot silently re-create
+            // when a server response shape drops `_id`.
+            Model.create(item, this, void 0, true)
+          )
         );
-      }).catch(this.handleError).then(
+      }).catch(this.handleError).then(ensureListResultCount).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "listAdvanced",
         __query: {
           target: "model",
@@ -862,7 +1676,7 @@ var ModelService = class extends Service {
           op: "list",
           filter: _filter,
           args: { select, sort, populate, include, skip, limit, page, pageSize, tasks },
-          options: { skim, includePermissions, includeCount, includeExtraHeaders, populateAccess },
+          options: { skim, includePermissions, includeCount, populateAccess },
           sqOptions: sq
         },
         __requestConfig: reqConfig,
@@ -872,14 +1686,25 @@ var ModelService = class extends Service {
   }
   create(data, options, axiosRequestConfig) {
     const { includePermissions = this._defaults.createOptions.includePermissions ?? true } = options ?? {};
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
+    const bulk = Array.isArray(data);
     return makeRequest(
       () => this._axios.post(this._basePath, data, mergeConfig3(reqConfig, { params: { include_permissions: includePermissions } })).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        if (result.success) {
+          if (bulk) {
+            const rows = Array.isArray(result.raw) ? result.raw : [result.raw];
+            result.raw = rows;
+            result.data = rows.map((row) => Model.create(row, this, void 0, true));
+          } else {
+            result.data = Model.create(result.raw, this, void 0, true);
+          }
+        }
         return result;
-      }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
+      }).catch(this.handleError).then(
+        (res) => this._handleCallbacks(res, throwOnError)
+      ),
       {
+        __throwOnError: throwOnError,
         __op: "create",
         __query: {
           target: "model",
@@ -901,20 +1726,27 @@ var ModelService = class extends Service {
       includePermissions = this._defaults.createAdvancedOptions.includePermissions ?? true,
       populateAccess = this._defaults.createAdvancedOptions.populateAccess
     } = options ?? {};
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
+    const bulk = Array.isArray(data);
     return makeRequest(
       () => this._axios.post(
         `${this._basePath}/${this._mutationPath}`,
         { data, select, populate, tasks, options: { includePermissions, populateAccess } },
         reqConfig
       ).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        if (result.success) {
+          if (bulk) {
+            const rows = Array.isArray(result.raw) ? result.raw : [result.raw];
+            result.raw = rows;
+            result.data = rows.map((row) => Model.create(row, this, void 0, true));
+          } else {
+            result.data = Model.create(result.raw, this, void 0, true);
+          }
+        }
         return result;
-      }).catch(this.handleError).then(
-        (res) => this._handleCallbacks(res, throwOnError)
-      ),
+      }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "createAdvanced",
         __query: {
           target: "model",
@@ -931,15 +1763,24 @@ var ModelService = class extends Service {
     );
   }
   upsert(data, options, axiosRequestConfig) {
-    const { returningAll = this._defaults.upsertOptions.returningAll ?? true } = options ?? {};
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const {
+      returningAll = this._defaults.upsertOptions.returningAll ?? true,
+      includePermissions = this._defaults.upsertOptions.includePermissions ?? true
+    } = options ?? {};
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
     return makeRequest(
-      () => this._axios.put(this._basePath, data, mergeConfig3(reqConfig, { params: { returning_all: returningAll } })).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+      () => this._axios.put(
+        this._basePath,
+        data,
+        mergeConfig3(reqConfig, {
+          params: { returning_all: returningAll, include_permissions: includePermissions }
+        })
+      ).then(this.handleSuccess).then((result) => {
+        result.data = result.success ? Model.create(result.raw, this, void 0, true) : null;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "upsert",
         __query: {
           target: "model",
@@ -947,7 +1788,7 @@ var ModelService = class extends Service {
           model: this._modelName,
           op: "upsert",
           data,
-          options: { returningAll }
+          options: { returningAll, includePermissions }
         },
         __requestConfig: reqConfig,
         __service: this
@@ -962,8 +1803,7 @@ var ModelService = class extends Service {
       includePermissions = this._defaults.upsertAdvancedOptions.includePermissions ?? true,
       populateAccess = this._defaults.upsertAdvancedOptions.populateAccess
     } = options ?? {};
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
     return makeRequest(
       () => this._axios.put(
         `${this._basePath}/${this._mutationPath}`,
@@ -976,12 +1816,13 @@ var ModelService = class extends Service {
         },
         reqConfig
       ).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        result.data = result.success ? Model.create(result.raw, this, void 0, true) : null;
         return result;
       }).catch(this.handleError).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "upsertAdvanced",
         __query: {
           target: "model",
@@ -998,14 +1839,14 @@ var ModelService = class extends Service {
     );
   }
   delete(identifier, axiosRequestConfig) {
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
     return makeRequest(
-      () => this._axios.delete(`${this._basePath}/${identifier}`, reqConfig).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+      () => this._axios.delete(`${this._basePath}/${encodePathSegment(identifier)}`, reqConfig).then(this.handleSuccess).then((result) => {
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "delete",
         __query: {
           target: "model",
@@ -1020,15 +1861,17 @@ var ModelService = class extends Service {
     );
   }
   new(axiosRequestConfig) {
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
     return makeRequest(
       () => this._axios.get(`${this._basePath}/new`, reqConfig).then(this.handleSuccess).then((result) => {
-        delete result.raw._id;
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        if (result.success) {
+          delete result.raw._id;
+          result.data = Model.create(result.raw, this);
+        }
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "new",
         __query: {
           target: "model",
@@ -1044,11 +1887,12 @@ var ModelService = class extends Service {
   distinct(field, axiosRequestConfig) {
     const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
     return makeRequest(
-      () => this._axios.get(`${this._basePath}/distinct/${field}`, reqConfig).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+      () => this._axios.get(`${this._basePath}/distinct/${encodePathSegment(field)}`, reqConfig).then(this.handleSuccess).then((result) => {
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "distinct",
         __query: {
           target: "model",
@@ -1065,11 +1909,12 @@ var ModelService = class extends Service {
   distinctAdvanced(field, conditions, axiosRequestConfig) {
     const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
     return makeRequest(
-      () => this._axios.post(`${this._basePath}/distinct/${field}`, conditions, reqConfig).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+      () => this._axios.post(`${this._basePath}/distinct/${encodePathSegment(field)}`, { filter: conditions }, reqConfig).then(this.handleSuccess).then((result) => {
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "distinctAdvanced",
         __query: {
           target: "model",
@@ -1088,10 +1933,11 @@ var ModelService = class extends Service {
     const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
     return makeRequest(
       () => this._axios.get(`${this._basePath}/count`, reqConfig).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "count",
         __query: {
           target: "model",
@@ -1104,23 +1950,22 @@ var ModelService = class extends Service {
       }
     );
   }
-  countAdvanced(filter, args, axiosRequestConfig) {
-    const { access } = args ?? {};
+  countAdvanced(filter, axiosRequestConfig) {
     const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
     return makeRequest(
-      () => this._axios.post(`${this._basePath}/count`, { filter, options: { access } }, reqConfig).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+      () => this._axios.post(`${this._basePath}/count`, { filter }, reqConfig).then(this.handleSuccess).then((result) => {
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "countAdvanced",
         __query: {
           target: "model",
           name: this._modelName,
           model: this._modelName,
           op: "count",
-          filter,
-          options: { access }
+          filter
         },
         __requestConfig: reqConfig,
         __service: this
@@ -1141,15 +1986,16 @@ var ModelService = class extends Service {
     reqConfig.headers = this.updateHeaders(reqConfig.headers, { ignoreCache });
     return makeRequest(
       () => this._axios.get(
-        `${this._basePath}/${identifier}`,
+        `${this._basePath}/${encodePathSegment(identifier)}`,
         mergeConfig3(reqConfig, {
           params: { include_permissions: includePermissions, try_list: tryList }
         })
       ).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        result.data = result.success ? Model.create(result.raw, this, identifier, true) : null;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "read",
         __query: {
           target: "model",
@@ -1185,7 +2031,7 @@ var ModelService = class extends Service {
     reqConfig.headers = this.updateHeaders(reqConfig.headers, { ignoreCache });
     return makeRequest(
       () => this._axios.post(
-        `${this._basePath}/${this._queryPath}/${identifier}`,
+        `${this._basePath}/${this._queryPath}/${encodePathSegment(identifier)}`,
         {
           select,
           populate,
@@ -1195,12 +2041,13 @@ var ModelService = class extends Service {
         },
         reqConfig
       ).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        result.data = result.success ? Model.create(result.raw, this, identifier, true) : null;
         return result;
       }).catch(this.handleError).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "readAdvanced",
         __query: {
           target: "model",
@@ -1250,12 +2097,13 @@ var ModelService = class extends Service {
         },
         reqConfig
       ).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        result.data = result.success ? Model.create(result.raw, this, void 0, true) : null;
         return result;
       }).catch(this.handleError).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "readAdvancedFilter",
         __query: {
           target: "model",
@@ -1273,19 +2121,24 @@ var ModelService = class extends Service {
     );
   }
   update(identifier, data, options, axiosRequestConfig) {
-    const { returningAll = this._defaults.updateOptions.returningAll ?? true } = options ?? {};
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const {
+      returningAll = this._defaults.updateOptions.returningAll ?? true,
+      includePermissions = this._defaults.updateOptions.includePermissions ?? true
+    } = options ?? {};
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
     return makeRequest(
       () => this._axios.patch(
-        `${this._basePath}/${identifier}`,
+        `${this._basePath}/${encodePathSegment(identifier)}`,
         data,
-        mergeConfig3(reqConfig, { params: { returning_all: returningAll } })
+        mergeConfig3(reqConfig, {
+          params: { returning_all: returningAll, include_permissions: includePermissions }
+        })
       ).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        result.data = result.success ? Model.create(result.raw, this, void 0, true) : null;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "update",
         __query: {
           target: "model",
@@ -1294,7 +2147,7 @@ var ModelService = class extends Service {
           op: "update",
           id: identifier,
           data,
-          options: { returningAll }
+          options: { returningAll, includePermissions }
         },
         __requestConfig: reqConfig,
         __service: this
@@ -1309,11 +2162,10 @@ var ModelService = class extends Service {
       includePermissions = this._defaults.updateAdvancedOptions.includePermissions ?? true,
       populateAccess = this._defaults.updateAdvancedOptions.populateAccess
     } = options ?? {};
-    const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
-    set3(reqConfig, `headers.${CACHE_HEADER}`, "false");
+    const { throwOnError, ...reqConfig } = cloneConfigWithCacheBypass(axiosRequestConfig ?? {});
     return makeRequest(
       () => this._axios.patch(
-        `${this._basePath}/${this._mutationPath}/${identifier}`,
+        `${this._basePath}/${this._mutationPath}/${encodePathSegment(identifier)}`,
         {
           data,
           select,
@@ -1323,12 +2175,13 @@ var ModelService = class extends Service {
         },
         reqConfig
       ).then(this.handleSuccess).then((result) => {
-        result.data = result.success ? Model.create(result.raw, this) : null;
+        result.data = result.success ? Model.create(result.raw, this, void 0, true) : null;
         return result;
       }).catch(this.handleError).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "updateAdvanced",
         __query: {
           target: "model",
@@ -1377,8 +2230,8 @@ var ModelService = class extends Service {
 // src/services/data-service.ts
 import { mergeConfig as mergeConfig4 } from "axios";
 var DataService = class extends Service {
-  constructor({ axios: axios2, dataName, basePath, queryPath, onSuccess, onFailure, throwOnError }, defaults) {
-    super(axios2, basePath);
+  constructor({ axios: axios3, dataName, basePath, queryPath, onSuccess, onFailure, throwOnError }, defaults) {
+    super(axios3, basePath, throwOnError);
     this._dataName = dataName;
     this._queryPath = queryPath;
     this._defaults = defaults ?? {};
@@ -1404,7 +2257,6 @@ var DataService = class extends Service {
       pageSize = this._defaults.listArgs.pageSize
     } = args ?? {};
     const {
-      includePermissions = this._defaults.listOptions.includePermissions ?? false,
       includeCount = this._defaults.listOptions.includeCount ?? false,
       includeExtraHeaders = this._defaults.listOptions.includeExtraHeaders ?? false,
       ignoreCache = this._defaults.listOptions.ignoreCache ?? false
@@ -1420,15 +2272,15 @@ var DataService = class extends Service {
             limit,
             page,
             page_size: pageSize,
-            include_permissions: includePermissions,
             include_count: includeCount,
             include_extra_headers: includeExtraHeaders
           }
         })
       ).then(this.handleSuccess).then((result) => {
         return processListResult(result, { includeCount, includeExtraHeaders });
-      }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
+      }).catch(this.handleError).then(ensureListResultCount).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "list",
         __query: {
           target: "data",
@@ -1436,7 +2288,7 @@ var DataService = class extends Service {
           op: "list",
           filter: {},
           args: { skip, limit, page, pageSize },
-          options: { includePermissions, includeCount, includeExtraHeaders }
+          options: { includeCount }
         },
         __requestConfig: reqConfig,
         __service: this
@@ -1453,7 +2305,6 @@ var DataService = class extends Service {
     } = args ?? {};
     const select = args?.select ?? this._defaults.listAdvancedArgs.select;
     const {
-      includePermissions = this._defaults.listAdvancedOptions.includePermissions ?? false,
       includeCount = this._defaults.listAdvancedOptions.includeCount ?? false,
       includeExtraHeaders = this._defaults.listAdvancedOptions.includeExtraHeaders ?? false,
       ignoreCache = this._defaults.listAdvancedOptions.ignoreCache ?? false
@@ -1472,7 +2323,7 @@ var DataService = class extends Service {
           limit,
           page,
           pageSize,
-          options: { includePermissions, includeCount, includeExtraHeaders }
+          options: { includeCount, includeExtraHeaders }
         },
         reqConfig
       ).then(this.handleSuccess).then((result) => {
@@ -1480,10 +2331,11 @@ var DataService = class extends Service {
           includeCount,
           includeExtraHeaders
         });
-      }).catch(this.handleError).then(
+      }).catch(this.handleError).then(ensureListResultCount).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "listAdvanced",
         __query: {
           target: "data",
@@ -1491,7 +2343,7 @@ var DataService = class extends Service {
           op: "list",
           filter: _filter,
           args: { select, sort, skip, limit, page, pageSize },
-          options: { includePermissions, includeCount, includeExtraHeaders }
+          options: { includeCount }
         },
         __requestConfig: reqConfig,
         __service: this
@@ -1502,23 +2354,16 @@ var DataService = class extends Service {
   // Document operations
   // ---------------------------------------------------------------------------
   read(identifier, options, axiosRequestConfig) {
-    const {
-      includePermissions = this._defaults.readOptions.includePermissions ?? true,
-      ignoreCache = this._defaults.readOptions.ignoreCache ?? false
-    } = options ?? {};
+    const { ignoreCache = this._defaults.readOptions.ignoreCache ?? false } = options ?? {};
     const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
     reqConfig.headers = this.updateHeaders(reqConfig.headers, { ignoreCache });
     return makeRequest(
-      () => this._axios.get(
-        `${this._basePath}/${identifier}`,
-        mergeConfig4(reqConfig, {
-          params: { include_permissions: includePermissions }
-        })
-      ).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+      () => this._axios.get(`${this._basePath}/${encodePathSegment(identifier)}`, reqConfig).then(this.handleSuccess).then((result) => {
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then((res) => this._handleCallbacks(res, throwOnError)),
       {
+        __throwOnError: throwOnError,
         __op: "read",
         __query: {
           target: "data",
@@ -1526,7 +2371,7 @@ var DataService = class extends Service {
           op: "read",
           id: identifier,
           args: {},
-          options: { includePermissions }
+          options: {}
         },
         __requestConfig: reqConfig,
         __service: this
@@ -1534,19 +2379,19 @@ var DataService = class extends Service {
     );
   }
   readAdvanced(identifier, args, options, axiosRequestConfig) {
-    const { ignoreCache = this._defaults.readAdvancedArgs.ignoreCache ?? false } = args ?? {};
     const select = args?.select ?? this._defaults.readAdvancedArgs.select;
-    const { includePermissions = this._defaults.readAdvancedOptions.includePermissions ?? true } = options ?? {};
+    const { ignoreCache = this._defaults.readAdvancedOptions.ignoreCache ?? false } = options ?? {};
     const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
     reqConfig.headers = this.updateHeaders(reqConfig.headers, { ignoreCache });
     return makeRequest(
-      () => this._axios.post(`${this._basePath}/${this._queryPath}/${identifier}`, { select }, reqConfig).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+      () => this._axios.post(`${this._basePath}/${this._queryPath}/${encodePathSegment(identifier)}`, { select }, reqConfig).then(this.handleSuccess).then((result) => {
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "readAdvanced",
         __query: {
           target: "data",
@@ -1554,7 +2399,7 @@ var DataService = class extends Service {
           op: "read",
           id: identifier,
           args: { select },
-          options: { includePermissions }
+          options: {}
         },
         __requestConfig: reqConfig,
         __service: this
@@ -1563,19 +2408,19 @@ var DataService = class extends Service {
   }
   readAdvancedFilter(filter, args, options, axiosRequestConfig) {
     const select = args?.select ?? this._defaults.readAdvancedArgs.select;
-    const { ignoreCache = this._defaults.readAdvancedArgs.ignoreCache ?? false } = args ?? {};
-    const { includePermissions = this._defaults.readAdvancedOptions.includePermissions ?? true } = options ?? {};
+    const { ignoreCache = this._defaults.readAdvancedOptions.ignoreCache ?? false } = options ?? {};
     const { throwOnError, ...reqConfig } = axiosRequestConfig ?? {};
     reqConfig.headers = this.updateHeaders(reqConfig.headers, { ignoreCache });
     const _filter = replaceSubQuery(filter);
     return makeRequest(
       () => this._axios.post(`${this._basePath}/${this._queryPath}/__filter`, { filter: _filter, select }, reqConfig).then(this.handleSuccess).then((result) => {
-        result.data = result.raw;
+        if (result.success) result.data = result.raw;
         return result;
       }).catch(this.handleError).then(
         (res) => this._handleCallbacks(res, throwOnError)
       ),
       {
+        __throwOnError: throwOnError,
         __op: "readAdvancedFilter",
         __query: {
           target: "data",
@@ -1583,7 +2428,7 @@ var DataService = class extends Service {
           op: "read",
           filter: _filter,
           args: { select },
-          options: { includePermissions }
+          options: {}
         },
         __requestConfig: reqConfig,
         __service: this
@@ -1592,132 +2437,8 @@ var DataService = class extends Service {
   }
 };
 
-// src/services/interceptors.ts
-import { AxiosHeaders as AxiosHeaders3 } from "axios";
-
-// src/services/cache-utils.ts
-import { AxiosHeaders as AxiosHeaders2 } from "axios";
-import { omitBy } from "@web-ts-toolkit/utils";
-var normalizeConfigValue = (value) => {
-  if (value == null) return value;
-  if (value instanceof AxiosHeaders2) {
-    return normalizeConfigValue(value.toJSON());
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => normalizeConfigValue(item));
-  }
-  if (typeof value === "object") {
-    return Object.entries(omitBy(value, (item) => item === void 0)).sort(([left], [right]) => left.localeCompare(right)).reduce((acc, [key, item]) => {
-      acc[key] = normalizeConfigValue(item);
-      return acc;
-    }, {});
-  }
-  return value;
-};
-
-// src/services/interceptors.ts
-var SimpleCache = class {
-  constructor() {
-    this.cache = /* @__PURE__ */ new Map();
-    this.timers = /* @__PURE__ */ new Map();
-  }
-  set(key, value, ttl) {
-    this.cache.set(key, value);
-    if (ttl && ttl > 0) {
-      const existing = this.timers.get(key);
-      if (existing) clearTimeout(existing);
-      this.timers.set(
-        key,
-        setTimeout(() => {
-          this.cache.delete(key);
-          this.timers.delete(key);
-        }, ttl)
-      );
-    }
-  }
-  get(key) {
-    return this.cache.get(key);
-  }
-  has(key) {
-    return this.cache.has(key);
-  }
-  delete(key) {
-    const timer = this.timers.get(key);
-    if (timer) {
-      clearTimeout(timer);
-      this.timers.delete(key);
-    }
-    return this.cache.delete(key);
-  }
-};
-var IGNORED_CACHE_HEADERS = /* @__PURE__ */ new Set([
-  "accept",
-  "accept-encoding",
-  "cache-control",
-  "connection",
-  "content-length",
-  "content-type",
-  "expires",
-  "host",
-  "pragma",
-  "user-agent"
-]);
-var serializeHeaders = (headers) => {
-  const resolvedHeaders = headers instanceof AxiosHeaders3 ? headers.toJSON() : headers;
-  const normalizedHeaders = Object.entries(resolvedHeaders ?? {}).filter(([key, value]) => {
-    const normalizedKey = key.toLowerCase();
-    return normalizedKey !== CACHE_HEADER.toLowerCase() && !IGNORED_CACHE_HEADERS.has(normalizedKey) && value !== void 0;
-  }).reduce((acc, [key, value]) => {
-    acc[key.toLowerCase()] = value;
-    return acc;
-  }, {});
-  return JSON.stringify(normalizeConfigValue(normalizedHeaders));
-};
-function generateCacheKey(config) {
-  const key = `${config.baseURL}/${config.url}_${config.method}_${generateParamKey(config.params)}_${generateDataKey(
-    config.data
-  )}_${serializeHeaders(config.headers)}`;
-  return encodeURI(key);
-}
-function generateParamKey(params) {
-  if (!params) return "";
-  return JSON.stringify(normalizeConfigValue(params));
-}
-function generateDataKey(data) {
-  if (!data) return "";
-  return typeof data === "string" ? data : JSON.stringify(normalizeConfigValue(data));
-}
-function useCacheInterceptors(instance, cacheTTL) {
-  const store = new SimpleCache();
-  instance.interceptors.request.use(
-    async (config) => {
-      if (config.headers[CACHE_HEADER] === "false") return config;
-      const key = generateCacheKey(config);
-      const cachedResponse = store.get(key);
-      if (!cachedResponse) {
-        return config;
-      }
-      config.adapter = async (_config) => {
-        return {
-          ...cachedResponse,
-          config: _config,
-          headers: { ...cachedResponse.headers, [CACHE_HEADER]: "true" }
-        };
-      };
-      return config;
-    },
-    (error) => Promise.reject(error)
-  );
-  instance.interceptors.response.use(
-    (response) => {
-      if (response.config.headers[CACHE_HEADER] === "false") return response;
-      const key = generateCacheKey(response.config);
-      store.set(key, response, cacheTTL);
-      return response;
-    },
-    (error) => Promise.reject(error)
-  );
-}
+// src/services/symbols.ts
+var ADAPTER_ID_KEY = /* @__PURE__ */ Symbol("adapterId");
 
 // src/adapter.ts
 var defaultAxiosConfig = Object.freeze({
@@ -1730,7 +2451,12 @@ var defaultAxiosConfig = Object.freeze({
     Expires: "0"
   }
 });
-var isModelQuery = (query) => query.target === "model";
+var noopCacheController = {
+  clear: () => {
+  },
+  dispose: () => {
+  }
+};
 var serializeRequestConfig = (config) => JSON.stringify(normalizeConfigValue(config ?? {}));
 var isObjectRecord = (value) => value != null && typeof value === "object" && !Array.isArray(value);
 var mergeServiceDefaults = (adapterDefaults, serviceDefaults) => {
@@ -1755,20 +2481,39 @@ var mergeServiceDefaults = (adapterDefaults, serviceDefaults) => {
 };
 function createAdapter(axiosConfig, adapterOptions) {
   const merged = mergeConfig5(defaultAxiosConfig, axiosConfig ?? {});
-  const instance = axios.create(merged);
+  const instance = axios2.create(merged);
   const {
     rootRouterPath = "root",
     onSuccess: onSuccessRoot,
     onFailure: onFailureRoot,
     throwOnError: throwOnErrorRoot,
     cacheTTL = 0,
+    cachePartition,
+    cacheCapacity,
     modelDefaults: adapterModelDefaults,
     dataDefaults: adapterDataDefaults
   } = adapterOptions ?? {};
-  if (cacheTTL > 0) useCacheInterceptors(instance, cacheTTL);
+  const cacheController = cacheTTL > 0 ? useCacheInterceptors(instance, {
+    ttl: cacheTTL,
+    capacity: cacheCapacity,
+    withCredentialsDefault: Boolean(instance.defaults.withCredentials),
+    partitionForRequest: cachePartition
+  }) : noopCacheController;
   const wraps = createWrapHelper(instance);
+  const adapterId = /* @__PURE__ */ Symbol("adapter");
+  const stampAdapterId = (service) => {
+    Object.defineProperty(service, ADAPTER_ID_KEY, {
+      value: adapterId,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+    return service;
+  };
   return Object.freeze({
     axios: instance,
+    clearCache: cacheController.clear,
+    disposeCache: cacheController.dispose,
     createModelService: ({
       modelName,
       basePath,
@@ -1778,7 +2523,7 @@ function createAdapter(axiosConfig, adapterOptions) {
       onFailure,
       throwOnError
     }, defaults) => {
-      return new ModelService(
+      const service = new ModelService(
         {
           axios: instance,
           modelName,
@@ -1791,9 +2536,10 @@ function createAdapter(axiosConfig, adapterOptions) {
         },
         mergeServiceDefaults(adapterModelDefaults, defaults)
       );
+      return stampAdapterId(service);
     },
     createDataService: ({ dataName, basePath, queryPath = "__query", onSuccess, onFailure, throwOnError }, defaults) => {
-      return new DataService(
+      const service = new DataService(
         {
           axios: instance,
           dataName,
@@ -1805,6 +2551,7 @@ function createAdapter(axiosConfig, adapterOptions) {
         },
         mergeServiceDefaults(adapterDataDefaults, defaults)
       );
+      return stampAdapterId(service);
     },
     wrapGet: wraps.wrapGet,
     wrapPost: wraps.wrapPost,
@@ -1814,55 +2561,72 @@ function createAdapter(axiosConfig, adapterOptions) {
     group: async (...proms) => {
       let sharedConfig;
       let sharedConfigKey;
+      let groupThrowOnError;
       const defs = proms.map((prom, index) => {
-        if (!isEmpty(prom.__requestConfig)) {
-          const configKey = serializeRequestConfig(prom.__requestConfig);
-          if (sharedConfigKey && sharedConfigKey !== configKey) {
-            throw new Error("Grouped requests must share the same axios request config");
-          }
-          sharedConfig = prom.__requestConfig;
-          sharedConfigKey = configKey;
+        const service = prom.__service;
+        if (!service || service[ADAPTER_ID_KEY] !== adapterId) {
+          throw new Error(
+            "Cannot group a request owned by a different adapter; create the request from this adapter's services"
+          );
+        }
+        if (groupThrowOnError != null && groupThrowOnError !== prom.__throwOnError) {
+          throw new Error("Grouped requests must share the same effective throwOnError policy");
+        }
+        groupThrowOnError = prom.__throwOnError;
+        const configKey = serializeRequestConfig(prom.__requestConfig);
+        if (sharedConfigKey != null && sharedConfigKey !== configKey) {
+          throw new Error("Grouped requests must share the same axios request config");
         }
+        sharedConfig = prom.__requestConfig ?? {};
+        sharedConfigKey = configKey;
         const query = { ...prom.__query };
+        if (query.target === "model") {
+          delete query.model;
+        }
         if (prom.__query.order == null) {
           query.order = index;
         }
         return query;
       });
-      const result = await instance.post(rootRouterPath, defs, sharedConfig ?? {}).then((res) => {
-        const responseHeaders = res.headers ?? {};
-        return res.data.map(({ result: result2, message, statusCode, op }, index) => {
-          const service = proms[index].__service;
-          const query = proms[index].__query;
-          const success = result2.success;
-          let _raw = success ? result2.data : null;
-          let _data = _raw;
-          if (!success) {
-            _data = null;
-          } else if (isModelQuery(query)) {
-            const modelService = service;
-            if (result2.kind === "list" && Array.isArray(result2.data)) {
-              if (op === "create" && result2.data.length === 1) {
-                _raw = result2.data[0];
-                _data = Model.create(result2.data[0], modelService);
-              } else if (!["distinct", "subList"].includes(op)) {
-                _data = castArray(result2.data).map((item) => Model.create(item, modelService));
-              }
-            } else if (result2.kind === "single" && ["new", "read", "update", "upsert"].includes(op)) {
-              _data = Model.create(result2.data, modelService);
-            }
-          }
-          return {
-            success,
-            raw: _raw,
-            data: _data,
+      const groupOwner = /* @__PURE__ */ Symbol("group");
+      const claimed = [];
+      try {
+        for (const prom of proms) {
+          claimLazyRequest(prom, "grouped", groupOwner);
+          claimed.push(prom);
+        }
+      } catch (error) {
+        for (const prom of claimed) {
+          releaseLazyRequestClaim(prom, groupOwner);
+        }
+        throw error;
+      }
+      const result = await instance.post(rootRouterPath, defs, sharedConfig ?? {}).then(
+        (res) => {
+          const rawEntries = res.data.map(({ result: result2, message, statusCode, op }) => ({
+            result: result2,
             message,
-            status: statusCode,
-            totalCount: result2.success && result2.kind === "list" ? result2.totalCount ?? result2.count ?? 0 : 0,
-            headers: responseHeaders
-          };
-        });
-      });
+            statusCode,
+            op
+          }));
+          const finalized = rawEntries.map(
+            (rawEntry, index) => finalizeRootEntry(proms[index].__query, rawEntry, {}, proms[index].__service)
+          );
+          return applyGroupCallbacks(
+            finalized,
+            proms.map((p) => p.__service),
+            groupThrowOnError ?? false
+          );
+        },
+        (error) => {
+          const failures = proms.map((prom) => finalizeRootTransportFailure(prom.__query, error));
+          return applyGroupCallbacks(
+            failures,
+            proms.map((p) => p.__service),
+            groupThrowOnError ?? false
+          );
+        }
+      );
       return result;
     }
   });
@@ -1886,6 +2650,7 @@ function removeItemById(items, targetItem) {
 export {
   CustomHeaders,
   DataService,
+  MissingPersistenceIdentityError,
   Model,
   ModelService,
   Service,