akanjs 3.0.0-alpha.71 → 3.0.0-alpha.73

package/fetch/client/fetchClient.ts

@@ -1,13 +1,6 @@
-import { DataList, getEnv, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
+import { getEnv, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
 import { capitalize, type FetchPolicy, fileUploadContract, Logger, resolveFileUploadCapability } from "akanjs/common";
-import {
-  type BaseInsight,
-  type BaseObject,
-  ConstantRegistry,
-  deserialize,
-  serialize,
-  withSharedInstances,
-} from "akanjs/constant";
+import { type BaseInsight, type BaseObject, ConstantRegistry, deserialize, serialize } from "akanjs/constant";
 import type {
   DatabaseSignal,
   SerializedArg,
@@ -19,14 +12,11 @@ import type {
 } from "akanjs/signal";
 import { agentTurnConstant } from "../agentTurn";
 import type { ClientSignal, FetchClientType, FetchSignalInput, MergeAllFetchTypes, SliceMeta } from "../fetchType";
-import {
-  getRequestStore,
-  memoizeRequestQuery,
-  cookies as requestCookies,
-  headers as requestHeaders,
-} from "../requestStorage";
+import { claimRequestQuery, cookies as requestCookies, headers as requestHeaders } from "../requestStorage";
 import type { GetSliceMetaObjFromDatabaseSignals } from "../types";
+import { FetchHandle } from "./fetchHandle";
 import { type ErrorConstructor, HttpClient } from "./httpClient";
+import { SliceInitHandle } from "./sliceInitHandle";
 import { WsClient } from "./wsClient";
 
 type FetchHandler = (...args: unknown[]) => PromiseOrObject<unknown>;
@@ -313,11 +303,12 @@ export class FetchClient {
           const baseUrl = option?.origin;
 
           const requestQuery = () => this.http.get(url, { headers, baseUrl });
-          const response = baseUrl
-            ? await requestQuery()
-            : await memoizeRequestQuery(FetchClient.#makeRequestQueryCacheKey(this.origin, url, headers), requestQuery);
 
-          const payload = !baseUrl && getRequestStore() ? FetchClient.#deepCopy(response) : response;
+          const claim = baseUrl
+            ? { value: requestQuery(), owned: true }
+            : claimRequestQuery(FetchClient.#makeRequestQueryCacheKey(this.origin, url, headers), requestQuery);
+          const response = await claim.value;
+          const payload = claim.owned ? response : FetchClient.#deepCopy(response);
           return parseReturn(payload, { crystalize: option?.crystalize ?? true });
         };
         return queryFn;
@@ -525,19 +516,8 @@ export class FetchClient {
     const anyCruGuards = signal.cruGuards ?? signal.createGuards ?? signal.updateGuards ?? signal.removeGuards;
     const updateGuards = signal.updateGuards ?? signal.cruGuards;
     if (anyCruGuards) {
-      this.#setHandlerFactory(
-        names.viewModel,
-        () =>
-          (async (id: string, option?: FetchPolicy) => {
-            const cnst = ConstantRegistry.getDatabase(refName);
-            const modelFn = this.#requireHandler(names.model, names.viewModel);
-            const modelObj = await modelFn(id, { ...option, crystalize: false });
-            const model = new cnst.full(modelObj as object);
-            return {
-              [refName]: model,
-              [`${refName}View`]: { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() },
-            };
-          }) as FetchHandler,
+      this.#setHandlerFactory(names.viewModel, () =>
+        this.#makeModelHandleFn(refName, names.model, names.viewModel, `${refName}View`),
       );
       this.#setHandlerFactory(
         names.getModelView,
@@ -548,19 +528,8 @@ export class FetchClient {
             return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
           }) as FetchHandler,
       );
-      this.#setHandlerFactory(
-        names.editModel,
-        () =>
-          (async (id: string, option?: FetchPolicy) => {
-            const cnst = ConstantRegistry.getDatabase(refName);
-            const modelFn = this.#requireHandler(names.model, names.editModel);
-            const modelObj = await modelFn(id, { ...option, crystalize: false });
-            const model = new cnst.full(modelObj as object);
-            return {
-              [refName]: model,
-              [`${refName}Edit`]: { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() },
-            };
-          }) as FetchHandler,
+      this.#setHandlerFactory(names.editModel, () =>
+        this.#makeModelHandleFn(refName, names.model, names.editModel, `${refName}Edit`),
       );
       this.#setHandlerFactory(
         names.getModelEdit,
@@ -606,6 +575,35 @@ export class FetchClient {
     );
   }
 
+  /**
+   * `view<Model>` and `edit<Model>` differ only in the key their payload lands under, so they share one read.
+   * The full model is built lazily for the same reason a slice's list is: a route that only hands the payload to
+   * `Load.View` never reads it, and `ViewAt` is stamped once so two reads agree.
+   */
+  #makeModelHandleFn(refName: string, modelKey: string, callerKey: string, payloadKey: string) {
+    return ((id: string, option?: FetchPolicy) => {
+      const cnst = ConstantRegistry.getDatabase(refName);
+      const modelFn = this.#requireHandler(modelKey, callerKey);
+      const modelRequest = modelFn(id, { ...option, crystalize: false }) as Promise<object>;
+      let model: object | undefined;
+      let payload: object | undefined;
+      const modelOf = (modelObj: object) => (model ??= new cnst.full(modelObj));
+      const payloadOf = (modelObj: object) =>
+        (payload ??= { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() });
+      return FetchHandle.of<Record<string, unknown>, Record<string, Promise<unknown>>>(
+        [modelRequest],
+        async () => {
+          const modelObj = await modelRequest;
+          return FetchHandle.lazy({}, { [refName]: () => modelOf(modelObj), [payloadKey]: () => payloadOf(modelObj) });
+        },
+        {
+          [refName]: () => modelRequest.then(modelOf),
+          [payloadKey]: () => modelRequest.then(payloadOf),
+        },
+      );
+    }) as FetchHandler;
+  }
+
   static getEndpointFromSlice(
     refName: string,
     suffix: string,
@@ -654,7 +652,7 @@ export class FetchClient {
 
     const argLength = slice.args.length;
     this.slice[sliceName] = { refName, sliceName, argLength };
-    this.#setHandlerFactory(names.init, () => async (...argData: unknown[]) => {
+    this.#setHandlerFactory(names.init, () => (...argData: unknown[]) => {
       const cnst = ConstantRegistry.getDatabase(refName);
       const queryArgs = normalizeQueryArgs(
         Array.from({ length: Math.min(argData.length, argLength) }, (_, idx) => argData[idx]),
@@ -667,56 +665,35 @@ export class FetchClient {
       const listFn = this.#requireHandler<(...args: unknown[]) => Promise<unknown[]>>(names.list, names.init);
       const insightFn = this.#requireHandler<(...args: unknown[]) => Promise<unknown>>(names.insight, names.init);
 
-      const [modelObjList, modelObjInsight] = (await Promise.all([
-        listFn(...fetchQueryArgs, skip, limit, sort, { ...option, crystalize: false }),
-        fetchInsight ? insightFn(...fetchQueryArgs, { ...option, crystalize: false }) : null,
-      ])) as unknown as [BaseObject[], BaseInsight];
-      const lastPage = modelObjInsight?.count
-        ? Math.max(Math.floor((modelObjInsight.count - 1) / (limit || 20)) + 1, 1)
-        : 1;
-
-      const serverInit = {
+      const listRequest = listFn(...fetchQueryArgs, skip, limit, sort, {
+        ...option,
+        crystalize: false,
+      }) as Promise<BaseObject[]>;
+      const insightRequest = (
+        fetchInsight ? insightFn(...fetchQueryArgs, { ...option, crystalize: false }) : Promise.resolve(null)
+      ) as Promise<BaseInsight | null>;
+      return new SliceInitHandle({
         refName,
+        capRefName,
+        capSuffix,
         sliceName,
         argLength,
-        [`${refName}ObjList`]: modelObjList,
-        [`${refName}ObjInsight`]: modelObjInsight,
-        [`pageOf${capRefName}`]: page,
-        [`lastPageOf${capRefName}`]: lastPage,
-        [`limitOf${capRefName}`]: limit,
-        [`queryArgsOf${capRefName}`]: queryArgs,
-        [`sortOf${capRefName}`]: sort,
-        [`${refName}InitAt`]: new Date(),
-      };
-      
-      let modelList: DataList<BaseObject> | undefined;
-      let modelInsight: object | undefined;
-      return Object.defineProperties({ [`${refName}Init${capSuffix}`]: serverInit } as Record<string, unknown>, {
-        [`${refName}List${capSuffix}`]: {
-          enumerable: true,
-          get: () => {
-            modelList ??= new DataList(
-              withSharedInstances(() => modelObjList.map((modelObj) => new cnst.light(modelObj) as BaseObject)),
-            );
-            return modelList;
-          },
-        },
-        [`${refName}Insight${capSuffix}`]: {
-          enumerable: true,
-          get: () => {
-            modelInsight ??= new cnst.insight(modelObjInsight);
-            return modelInsight;
-          },
-        },
-      });
+        queryArgs,
+        page,
+        limit,
+        sort,
+        listRequest,
+        insightRequest,
+        light: cnst.light as unknown as new (obj?: unknown) => BaseObject,
+        insight: cnst.insight as unknown as new (obj?: unknown) => object,
+      }).build();
     });
     this.#setHandlerFactory(names.getInit, () => async (...args: unknown[]) => {
-      const initFn = this.#requireHandler<(...args: unknown[]) => Promise<Record<string, unknown>>>(
+      const initFn = this.#requireHandler<(...args: unknown[]) => Record<string, Promise<unknown>>>(
         names.init,
         names.getInit,
       );
-      const result = await initFn(...args);
-      return result[`${refName}Init${capSuffix}`];
+      return await initFn(...args)[`${refName}Init${capSuffix}`];
     });
   }
   #makeArgSerializer(args: SerializedArg[]) {

package/fetch/client/fetchHandle.ts

@@ -0,0 +1,57 @@
+type FieldFactories<Handle> = { [Key in keyof Handle]: () => Handle[Key] };
+
+/**
+ * A fetch result that is both awaitable and destructurable.
+ *
+ * `await` gives the object the helper has always given, so every existing call site reads unchanged. Reading a
+ * field off the un-awaited result gives that field's own promise instead, so a route can hand each one to the
+ * section that renders it and let the slowest arrive last rather than holding the whole page.
+ */
+export class FetchHandle {
+  /**
+   * @param requests the calls already in flight. Each gets a swallowing handler so a field nobody reads cannot
+   *   surface as an unhandled rejection; the handle's own `then` is what reports one.
+   * @param settle builds the awaited shape — its own fields stay lazy, so awaiting costs nothing extra.
+   * @param fields one factory per field of the un-awaited shape, memoized on first read.
+   */
+  static of<Awaited extends object, Handle extends object>(
+    requests: Promise<unknown>[],
+    settle: () => Promise<Awaited>,
+    fields: FieldFactories<Handle>,
+  ): PromiseLike<Awaited> & Handle {
+    for (const request of requests) void request.catch(() => undefined);
+    let settled: Promise<Awaited> | undefined;
+    const resolve = () => {
+      if (settled) return settled;
+      settled = settle();
+      void settled.catch(() => undefined);
+      return settled;
+    };
+    const read = new Map<string, unknown>();
+    const factories = fields as { [key: string]: () => unknown };
+    const handle = {} as { [key: string]: unknown };
+    for (const key of Object.keys(factories)) {
+      Object.defineProperty(handle, key, {
+        enumerable: true,
+        get: () => {
+          if (!read.has(key)) read.set(key, factories[key]());
+          return read.get(key);
+        },
+      });
+    }
+
+    return Object.defineProperties(handle, {
+      
+      then: { value: (...args: unknown[]) => Reflect.apply(resolve().then, resolve(), args) },
+      catch: { value: (...args: unknown[]) => Reflect.apply(resolve().catch, resolve(), args) },
+      finally: { value: (...args: unknown[]) => Reflect.apply(resolve().finally, resolve(), args) },
+    }) as PromiseLike<Awaited> & Handle;
+  }
+
+  /** The awaited shape's fields stay lazy for the same reason the handle's do: a caller reads one, not all. */
+  static lazy<Target extends object>(target: Target, fields: { [key: string]: () => unknown }): Target {
+    for (const [key, factory] of Object.entries(fields))
+      Object.defineProperty(target, key, { enumerable: true, get: factory });
+    return target;
+  }
+}

package/fetch/client/httpClient.ts

@@ -25,6 +25,8 @@ export interface ErrorConstructor {
 interface FetchOptions {
   headers?: Record<string, string>;
   baseUrl?: string;
+  /** Milliseconds before the request is abandoned; `false` waits as long as the browser will. */
+  timeout?: number | false;
 }
 
 const jsonContentType = /^application\/(?:[\w.+-]+\+)?json\b/i;
@@ -39,6 +41,15 @@ const transportErrorKeyMap = {
 const serverUnreachableKey = "base.error.serverUnreachable";
 const unexpectedResponseKey = "base.error.unexpectedResponse";
 const transportDetailLimit = 200;
+/**
+ * How long a call waits before giving up.
+ *
+ * Nothing else bounds it: a gateway answers a dead upstream with a 504, but a solo process has no gateway and a
+ * severed connection produces no response at all — the request then sits until the browser's own limit, which is
+ * minutes. The dictionary already has the wording for a slow server (`gatewayTimeout`), so this is the client
+ * side of an answer that only existed for one deployment shape.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
 
 export class HttpClient {
   readonly baseUrl: string;
@@ -63,9 +74,11 @@ export class HttpClient {
     return { Accept: "application/json", ...headers, ...options.headers };
   }
   async get<Returns = unknown>(url: string, options: FetchOptions = {}): Promise<Returns> {
-    return await this.#request<Returns>(this.#resolveUrl(url, options), {
-      headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options),
-    });
+    return await this.#request<Returns>(
+      this.#resolveUrl(url, options),
+      { headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options) },
+      options,
+    );
   }
   #makeReqContent(data: FormData | Record<string, unknown>): { body: BodyInit; headers: Record<string, string> } {
 
@@ -79,11 +92,11 @@ export class HttpClient {
     options: FetchOptions = {},
   ): Promise<Returns> {
     const { body, headers } = this.#makeReqContent(data);
-    return await this.#request<Returns>(this.#resolveUrl(url, options), {
-      method,
-      body,
-      headers: HttpClient.#makeHeaders(headers, options),
-    });
+    return await this.#request<Returns>(
+      this.#resolveUrl(url, options),
+      { method, body, headers: HttpClient.#makeHeaders(headers, options) },
+      options,
+    );
   }
   async put<Returns = unknown>(
     url: string,
@@ -100,17 +113,29 @@ export class HttpClient {
     return await this.send<Returns>("POST", url, data, options);
   }
   async delete<Returns = unknown>(url: string, options: FetchOptions = {}): Promise<Returns> {
-    return await this.#request<Returns>(this.#resolveUrl(url, options), {
-      method: "DELETE",
-      headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options),
-    });
+    return await this.#request<Returns>(
+      this.#resolveUrl(url, options),
+      { method: "DELETE", headers: HttpClient.#makeHeaders({ "Content-Type": "application/json" }, options) },
+      options,
+    );
   }
 
-  async #request<Returns>(url: string, init: RequestInit): Promise<Returns> {
-    const res = await this.#fetch(url, init);
+  async #request<Returns>(url: string, init: RequestInit, options: FetchOptions = {}): Promise<Returns> {
+    const res = await this.#fetch(url, HttpClient.#withTimeout(init, options));
     return await this.#readJsonResponse<Returns>(res);
   }
 
+  /**
+   * An upload gets no deadline of its own: a large file on a slow uplink is a long request that is working, and
+   * the request body is the only thing this side can tell that from. Everything else takes the default unless
+   * the caller named one.
+   */
+  static #withTimeout(init: RequestInit, options: FetchOptions): RequestInit {
+    const timeout = options.timeout ?? (init.body instanceof FormData ? false : DEFAULT_TIMEOUT_MS);
+    if (timeout === false || !Number.isFinite(timeout) || timeout <= 0) return init;
+    return { ...init, signal: AbortSignal.timeout(timeout) };
+  }
+
   /**
    * `fetch` rejects only when no response arrived at all — a refused connection, a DNS failure, a socket
    * dropped mid-flight. That is the server being unreachable, not an error this API reported, so it is
@@ -120,6 +145,9 @@ export class HttpClient {
     try {
       return await fetch(url, init);
     } catch (error) {
+
+      if (error instanceof Error && error.name === "TimeoutError")
+        throw this.#restoreError({ error: transportErrorKeyMap[408], data: { status: 408 } }, 408);
       if (error instanceof Error && error.name === "AbortError") throw error;
       throw this.#restoreError({ error: serverUnreachableKey, details: String(error) }, 503);
     }

package/fetch/client/sliceInitHandle.ts

@@ -0,0 +1,101 @@
+import { DataList } from "akanjs/base";
+import { type BaseInsight, type BaseObject, withSharedInstances } from "akanjs/constant";
+
+import { FetchHandle } from "./fetchHandle";
+
+export interface SliceInitInput {
+  refName: string;
+  capRefName: string;
+  capSuffix: string;
+  sliceName: string;
+  argLength: number;
+  queryArgs: unknown[];
+  page: number;
+  limit: number;
+  sort: string;
+  listRequest: Promise<BaseObject[]>;
+  /** `null` when the caller passed `{ insight: false }` — the aggregate query is then never made. */
+  insightRequest: Promise<BaseInsight | null>;
+  light: new (obj?: unknown) => BaseObject;
+  insight: new (obj?: unknown) => object;
+}
+
+/**
+ * The two calls a slice's `init` makes and the three values callers read off them.
+ *
+ * The list does not wait for the aggregate: `x<Slice>List` resolves as soon as the rows land, while
+ * `x<Slice>Init` — which carries `lastPageOf<Model>` and therefore needs the count — waits for both. Every
+ * derived value is memoized, so the awaited shape and the un-awaited handle hand out the same instances.
+ */
+export class SliceInitHandle {
+  readonly #input: SliceInitInput;
+  #serverInit?: object;
+  #modelList?: DataList<BaseObject>;
+  #modelInsight?: object;
+
+  constructor(input: SliceInitInput) {
+    this.#input = input;
+  }
+
+  build() {
+    const { refName, capSuffix, listRequest, insightRequest } = this.#input;
+    const keys = {
+      init: `${refName}Init${capSuffix}`,
+      list: `${refName}List${capSuffix}`,
+      insight: `${refName}Insight${capSuffix}`,
+    };
+    return FetchHandle.of<Record<string, unknown>, Record<string, Promise<unknown>>>(
+      [listRequest, insightRequest],
+      async () => {
+        const [modelObjList, modelObjInsight] = await Promise.all([listRequest, insightRequest]);
+        return FetchHandle.lazy({ [keys.init]: this.#serverInitOf(modelObjList, modelObjInsight) }, {
+          [keys.list]: () => this.#listOf(modelObjList),
+          [keys.insight]: () => this.#insightOf(modelObjInsight),
+        } as { [key: string]: () => unknown });
+      },
+      {
+        [keys.init]: () =>
+          Promise.all([listRequest, insightRequest]).then(([modelObjList, modelObjInsight]) =>
+            this.#serverInitOf(modelObjList, modelObjInsight),
+          ),
+        [keys.list]: () => listRequest.then((modelObjList) => this.#listOf(modelObjList)),
+        [keys.insight]: () => insightRequest.then((modelObjInsight) => this.#insightOf(modelObjInsight)),
+      },
+    );
+  }
+
+  #serverInitOf(modelObjList: BaseObject[], modelObjInsight: BaseInsight | null) {
+    const { refName, capRefName, sliceName, argLength, queryArgs, page, limit, sort } = this.#input;
+    const lastPage = modelObjInsight?.count
+      ? Math.max(Math.floor((modelObjInsight.count - 1) / (limit || 20)) + 1, 1)
+      : 1;
+    this.#serverInit ??= {
+      refName,
+      sliceName,
+      argLength,
+      [`${refName}ObjList`]: modelObjList,
+      [`${refName}ObjInsight`]: modelObjInsight,
+      [`pageOf${capRefName}`]: page,
+      [`lastPageOf${capRefName}`]: lastPage,
+      [`limitOf${capRefName}`]: limit,
+      [`queryArgsOf${capRefName}`]: queryArgs,
+      [`sortOf${capRefName}`]: sort,
+      [`${refName}InitAt`]: new Date(),
+    };
+    return this.#serverInit;
+  }
+
+  #listOf(modelObjList: BaseObject[]) {
+    const { light } = this.#input;
+    this.#modelList ??= new DataList(
+      withSharedInstances(() => modelObjList.map((modelObj) => new light(modelObj) as BaseObject)),
+    );
+    return this.#modelList;
+  }
+
+  #insightOf(modelObjInsight: BaseInsight | null) {
+    const { insight } = this.#input;
+    this.#modelInsight ??= new insight(modelObjInsight);
+    return this.#modelInsight;
+  }
+}

package/fetch/fetchType/appliedReturn.type.ts

@@ -35,7 +35,8 @@ type ServerInitShape<
 > = SliceMeta & {
   [K in `${RefName}ObjList`]: LightObj[];
 } & {
-  [K in `${RefName}ObjInsight`]: InsightObj;
+  /** `null` when the caller passed `{ insight: false }`: the aggregate query was never made. */
+  [K in `${RefName}ObjInsight`]: InsightObj | null;
 } & {
   [K in `pageOf${CapRefName}`]: number;
 } & {
@@ -100,6 +101,31 @@ export type EditReturn<RefName extends string, Full> = {
   [K in `${RefName}Edit`]: ServerEdit<RefName, Full>;
 };
 
+/**
+ * What `fetch.view<Model>` / `fetch.edit<Model>` / `fetch.init<Model><Suffix>` return: awaitable for the shape
+ * the helper has always given, and destructurable into one promise per field for a route that wants each
+ * section to render as its own data lands instead of holding the page for the slowest.
+ */
+export type FetchHandleOf<Awaited, Fields> = PromiseLike<Awaited> & Fields;
+
+export type ViewHandle<RefName extends string, Full> = FetchHandleOf<
+  ViewReturn<RefName, Full>,
+  {
+    [K in RefName]: Promise<Full>;
+  } & {
+    [K in `${RefName}View`]: Promise<ServerView<RefName, Full>>;
+  }
+>;
+
+export type EditHandle<RefName extends string, Full> = FetchHandleOf<
+  EditReturn<RefName, Full>,
+  {
+    [K in RefName]: Promise<Full>;
+  } & {
+    [K in `${RefName}Edit`]: Promise<ServerEdit<RefName, Full>>;
+  }
+>;
+
 type InitReturnShape<
   RefName extends string,
   CapSuffix extends string,
@@ -127,3 +153,40 @@ export type InitReturn<
   Insight
 >;
 
+/**
+ * The list resolves without waiting for the aggregate, so `x<Slice>List` lands before `x<Slice>Init` — which
+ * carries `lastPageOf<Model>` and therefore needs the count.
+ *
+ * `x<Slice>List` and `x<Slice>Insight` hold hydrated model instances, which React Flight refuses as props to a
+ * client component: consume them in a server component and hand `x<Slice>Init` to a `Zone`.
+ */
+type InitHandleShape<
+  RefName extends string,
+  CapSuffix extends string,
+  Init,
+  ListItem extends { id: string },
+  Insight,
+> = {
+  [K in `${RefName}Init${CapSuffix}`]: Promise<Init>;
+} & {
+  [K in `${RefName}List${CapSuffix}`]: Promise<DataList<ListItem>>;
+} & { [K in `${RefName}Insight${CapSuffix}`]: Promise<Insight> };
+
+export type InitHandle<
+  RefName extends string,
+  Suffix extends string,
+  Light,
+  Insight,
+  Args,
+  Filter extends FilterInstance,
+> = FetchHandleOf<
+  InitReturn<RefName, Suffix, Light, Insight, Args, Filter>,
+  InitHandleShape<
+    RefName,
+    Capitalize<Suffix>,
+    ServerInit<RefName, Light, Insight, Args, Filter>,
+    Light extends { id: string } ? Light : { id: string },
+    Insight
+  >
+>;
+

package/fetch/fetchType/sliceFetch.type.ts

@@ -15,7 +15,7 @@ import type {
   SliceCls,
   SliceInfoArgs,
 } from "akanjs/signal";
-import type { EditReturn, InitReturn, ServerEdit, ServerInit, ServerView, ViewReturn } from "./appliedReturn.type";
+import type { EditHandle, InitHandle, ServerEdit, ServerInit, ServerView, ViewHandle } from "./appliedReturn.type";
 
 type _SliceMap<S extends SliceCls> = S[typeof SLICE_META];
 type _RefName<S extends SliceCls> = SlceCnstRefName<S>;
@@ -47,7 +47,7 @@ type SliceInsightFetch<S extends SliceCls> = {
   ) => Promise<_Insight<S>>;
 };
 
-type SliceInit<S extends SliceCls, Suffix extends keyof _SliceMap<S>> = InitReturn<
+type SliceInit<S extends SliceCls, Suffix extends keyof _SliceMap<S>> = InitHandle<
   _RefName<S>,
   Suffix & string,
   _Light<S>,
@@ -67,7 +67,7 @@ type SliceServerInit<S extends SliceCls, Suffix extends keyof _SliceMap<S>> = Se
 type SliceInitFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `init${_Cap<S>}${Capitalize<Suffix>}` : never]: (
     ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: SliceInitOption<S>]
-  ) => Promise<SliceInit<S, Suffix>>;
+  ) => SliceInit<S, Suffix>;
 };
 
 type SliceGetInitFetch<S extends SliceCls> = {
@@ -130,11 +130,11 @@ type AppliedBaseSliceFetchType<
   _CapitalizedRefName extends string = Capitalize<RefName>,
   _PurifiedInput = PurifiedModel<Input>,
 > = {
-  [K in `view${_CapitalizedRefName}`]: (id: string, option?: FetchPolicy) => Promise<ViewReturn<RefName, Full>>;
+  [K in `view${_CapitalizedRefName}`]: (id: string, option?: FetchPolicy) => ViewHandle<RefName, Full>;
 } & {
   [K in `get${_CapitalizedRefName}View`]: (id: string, option?: FetchPolicy) => Promise<ServerView<RefName, Full>>;
 } & {
-  [K in `edit${_CapitalizedRefName}`]: (id: string, option?: FetchPolicy) => Promise<EditReturn<RefName, Full>>;
+  [K in `edit${_CapitalizedRefName}`]: (id: string, option?: FetchPolicy) => EditHandle<RefName, Full>;
 } & {
   [K in `get${_CapitalizedRefName}Edit`]: (id: string, option?: FetchPolicy) => Promise<ServerEdit<RefName, Full>>;
 } & {

package/fetch/requestStorage.ts

@@ -169,15 +169,29 @@ export function getRequestDynamicUsage(): AkanDynamicUsage | undefined {
   return getRequestStore()?.dynamicUsage;
 }
 
-/** Deduplicates a promise-producing query within the active request. */
-export function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>): Promise<T> {
+/**
+ * Deduplicates a promise-producing query within the active request, and says whether this caller is the one
+ * that started it.
+ *
+ * `owned` is what lets the caller skip copying the response. The copy exists because one response object is
+ * handed to every caller in the request and a parsed model can hold references into it, so a second caller must
+ * not be given the same graph — but a query asked for once (which is nearly all of them: the key carries the
+ * URL and the auth headers) has no second caller to protect, and copying for it is a whole JSON round-trip
+ * spent on nothing.
+ */
+export function claimRequestQuery<T>(key: string, factory: () => Promise<T>): { value: Promise<T>; owned: boolean } {
   const store = getRequestStore();
-  if (!store) return factory();
+  if (!store) return { value: factory(), owned: true };
   const existing = store.queryCache.get(key);
-  if (existing) return existing as Promise<T>;
+  if (existing) return { value: existing as Promise<T>, owned: false };
   const promise = factory();
   store.queryCache.set(key, promise);
-  return promise;
+  return { value: promise, owned: true };
+}
+
+/** Deduplicates a promise-producing query within the active request. */
+export function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>): Promise<T> {
+  return claimRequestQuery(key, factory).value;
 }
 
 /** Returns current request headers as a Map, or an empty Map outside a request. */

package/index.ts

@@ -291,6 +291,20 @@ export interface FileConventionScanResult {
   zone: { databases: string[]; services: string[]; scalars: string[] };
 }
 
+/**
+ * What a *live* scan exposes on `AppInfo.file` / `LibInfo.file`: a set per module kind, with every file
+ * type carrying all four kinds. `FileConventionScanResult` above is the serialized form that crosses a
+ * process boundary as JSON, which is why it is arrays and why each file type lists only the kinds it can
+ * hold. The two are not interchangeable — every reader of `.file` calls `.has()`.
+ */
+export interface FileConventionScanSet {
+  all: Set<string>;
+  databases: Set<string>;
+  services: Set<string>;
+  scalars: Set<string>;
+}
+export type FileConventionScanSets = { [key in keyof FileConventionScanResult]: FileConventionScanSet };
+
 export interface ScanResult {
   name: string;
   type: "app" | "lib";
@@ -333,7 +347,7 @@ export interface AppInfo {
   readonly database: Map<string, Set<string>>;
   readonly service: Map<string, Set<string>>;
   readonly scalar: Map<string, Set<string>>;
-  readonly file: FileConventionScanResult;
+  readonly file: FileConventionScanSets;
   getLibs(): string[];
   getLibInfos(): Map<string, LibInfo>;
   getDatabaseModules(): string[];
@@ -347,7 +361,7 @@ export interface LibInfo {
   readonly database: Map<string, Set<string>>;
   readonly service: Map<string, Set<string>>;
   readonly scalar: Map<string, Set<string>>;
-  readonly file: FileConventionScanResult;
+  readonly file: FileConventionScanSets;
   getLibs(): string[];
   getLibInfos(): Map<string, LibInfo>;
   getLibInfo(libName: string): LibInfo | undefined;