akanjs 3.0.0-alpha.99 → 3.0.0-beta.0

package/constant/cascadePaths.ts

@@ -6,8 +6,10 @@ import type { ConstantModelRef } from "./via";
  * Which end of a relation goes away with the other. `removeRef` removes what the field points at when this
  * document is removed; `removeWith` removes this document when what the field points at is removed. The two
  * read identically on a relation field, so the value has to name the direction — a mistake here is a data loss.
+ * `removeWithAny` is `removeWith` over an owner that is unknowable at build time, and it names the whole
+ * decision in one value so the widening cannot be declared apart from the direction it widens.
  */
-export const cascadeActions = ["removeRef", "removeWith"] as const;
+export const cascadeActions = ["removeRef", "removeWith", "removeWithAny"] as const;
 export type CascadeAction = (typeof cascadeActions)[number];
 
 /** How a `removeWith` field names the owner whose removal takes this document with it. */
@@ -21,7 +23,7 @@ export interface CascadeWithPath {
   readonly typeKey: string | null;
   /** The refNames `typeKey` may hold. Empty unless the field is polymorphic over an enum. */
   readonly typeValues: readonly string[];
-  /** Set by `polymorphic: "any"`: `typeKey` is free-form, so the owner is whatever refName the row holds. */
+  /** Set by `cascade: "removeWithAny"`: `typeKey` is free-form, so the owner is whatever refName the row holds. */
   readonly anyOwner: boolean;
 }
 
@@ -35,7 +37,6 @@ export class CascadePaths {
 
   collect(fieldMap: FieldObject) {
     for (const [key, field] of Object.entries(fieldMap)) {
-      this.#assertPolymorphicIsWiredUp(key, field);
       if (!field.cascade) continue;
       this.#assertKnownAction(key, field.cascade);
       if (field.cascade === "removeRef") this.removeRef.set(key, this.#readOwnedRelation(key, field));
@@ -44,16 +45,6 @@ export class CascadePaths {
     return this;
   }
 
-  /** `polymorphic` widens one thing and nothing else, so anywhere else it is a declaration that does nothing. */
-  #assertPolymorphicIsWiredUp(key: string, field: ConstantField) {
-    if (!field.polymorphic) return;
-    if (field.cascade === "removeWith" && field.refPath) return;
-    throw new Error(
-      `Field "${key}" declares polymorphic: "${field.polymorphic}", which only widens a ` +
-        `cascade: "removeWith" field that names its owner type with refPath`,
-    );
-  }
-
   #assertKnownAction(key: string, action: CascadeAction) {
 
     if (!cascadeActions.includes(action)) {
@@ -74,7 +65,15 @@ export class CascadePaths {
 
     if (field.arrDepth > 0) throw new Error(`Cascade field "${key}" is an array and names more than one owner`);
     if (field.isMap) throw new Error(`Cascade field "${key}" is a Map and names no owner`);
-    if (field.refPath) return this.#readPolymorphicOwner(key, field, fieldMap);
+    const anyOwner = field.cascade === "removeWithAny";
+    if (field.refPath) return this.#readPolymorphicOwner(key, field, fieldMap, anyOwner);
+    
+    if (anyOwner) {
+      throw new Error(
+        `Cascade field "${key}" declares cascade: "removeWithAny" and must name the field holding the owner's ` +
+          `refName with refPath: "<typeField>"`,
+      );
+    }
     if (field.ref) {
       this.#assertHoldsId(key, field);
       return { key, modelRef: null, refName: field.ref, typeKey: null, typeValues: [], anyOwner: false };
@@ -88,18 +87,18 @@ export class CascadePaths {
     );
   }
 
-  #readPolymorphicOwner(key: string, field: ConstantField, fieldMap: FieldObject): CascadeWithPath {
+  #readPolymorphicOwner(key: string, field: ConstantField, fieldMap: FieldObject, anyOwner: boolean): CascadeWithPath {
     if (field.ref) throw new Error(`Cascade field "${key}" declares both ref and refPath; keep one`);
     this.#assertHoldsId(key, field);
     const typeKey = field.refPath as string;
     const typeField = fieldMap[typeKey];
     if (!typeField) throw new Error(`Cascade field "${key}" declares refPath: "${typeKey}", which is not a field`);
-    if (field.polymorphic === "any") return this.#readAnyOwner(key, typeKey, typeField);
+    if (anyOwner) return this.#readAnyOwner(key, typeKey, typeField);
 
     if (!typeField.enum) {
       throw new Error(
         `Cascade field "${key}" declares refPath: "${typeKey}", which must be an enumOf(...) naming the owner ` +
-          `refNames it may hold; declare polymorphic: "any" to pay for a sweep on every removal instead`,
+          `refNames it may hold; declare cascade: "removeWithAny" to pay for a sweep on every removal instead`,
       );
     }
     const typeValues = typeField.enum.values.map((value) => String(value));
@@ -110,14 +109,15 @@ export class CascadePaths {
     
     if (typeField.enum) {
       throw new Error(
-        `Cascade field "${key}" declares polymorphic: "any" and a refPath naming an enumOf(...); keep one`,
+        `Cascade field "${key}" declares cascade: "removeWithAny" and a refPath naming an enumOf(...), which ` +
+          `already names its owners; use cascade: "removeWith"`,
       );
     }
 
     if (this.#primitiveNameOf(typeField) !== "String") {
       throw new Error(
-        `Cascade field "${key}" declares polymorphic: "any", so refPath: "${typeKey}" must be a String field ` +
-          `holding the owner's refName`,
+        `Cascade field "${key}" declares cascade: "removeWithAny", so refPath: "${typeKey}" must be a String ` +
+          `field holding the owner's refName`,
       );
     }
     return { key, modelRef: null, refName: null, typeKey, typeValues: [], anyOwner: true };

package/constant/deserialize.ts

@@ -1,4 +1,12 @@
-import { Any, applyFnToArrayObjects, type Cls, FIELD_META, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+import {
+  Any,
+  applyFnToArrayObjects,
+  type Cls,
+  type EnumInstance,
+  FIELD_META,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+} from "akanjs/base";
 
 import { type ConstantCls, type ConstantModelRef, ConstantRegistry, type FieldProps, withSharedInstances } from ".";
 
@@ -50,6 +58,7 @@ const deserializeInput = <Input = unknown>(
           : deserialize(field.modelRef, field.arrDepth, (value as Record<string, unknown>)[key], {
               key,
               nullable: field.nullable,
+              enum: field.enum,
             }),
       ]),
     ) as unknown as Input;
@@ -57,15 +66,33 @@ const deserializeInput = <Input = unknown>(
   }
 };
 
+interface DeserializeOption {
+  key?: string;
+  nullable?: boolean;
+  convertFn?: (value: unknown) => unknown;
+  enum?: EnumInstance;
+}
+
+const assertEnumValue = (enumRef: EnumInstance, value: unknown, key?: string): void => {
+  if (Array.isArray(value)) {
+    for (const item of value) assertEnumValue(enumRef, item, key);
+    return;
+  }
+  if (value === null || value === undefined || enumRef.has(value as never)) return;
+  throw new Error(`Invalid Enum Value in ${key}: ${String(value)} is not one of ${enumRef.values.join(", ")}`);
+};
+
 export const deserialize = (
   argRef: ConstantModelRef | PrimitiveScalar,
   arrDepth: number,
   value: unknown,
-  { key, nullable = false, convertFn }: { key?: string; nullable?: boolean; convertFn?: (value: unknown) => unknown },
+  { key, nullable = false, convertFn, enum: enumRef }: DeserializeOption,
 ) => {
   if (nullable && (value === null || value === undefined)) return null;
   else if (!nullable && (value === null || value === undefined) && argRef !== Any)
     throw new Error(`Invalid Value (Nullable) in ${key} ${argRef} for value ${value}`);
 
-  return withSharedInstances(() => deserializeInput(value, argRef, arrDepth, convertFn)) as object[];
+  const result = withSharedInstances(() => deserializeInput(value, argRef, arrDepth, convertFn)) as object[];
+  if (enumRef) assertEnumValue(enumRef, result, key);
+  return result;
 };

package/constant/fieldInfo.ts

@@ -106,11 +106,6 @@ export interface ConstantFieldProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
-  /**
-   * Widens a `cascade: "removeWith"` field whose `refPath` names a free-form `String` instead of an `enumOf`:
-   * the owner is whatever refName the row happens to hold, found by sweeping at removal time.
-   */
-  polymorphic?: "any";
   /**
    * Renders on the page, never reaches an agent. Stripped wherever a value is masked for an AI caller — the
    * in-page agent's reads and every MCP result — and left untouched everywhere else, so a `File`'s blur
@@ -209,7 +204,6 @@ interface ConstantFieldBuildProps<
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
   cascade?: CascadeAction;
-  polymorphic?: "any";
   visual: boolean;
   modelRef: ConstantModelRef;
   arrDepth: number;
@@ -335,7 +329,6 @@ export class ConstantField<
   readonly validate?: (value: FieldValue, model: any) => boolean;
   readonly text?: TextFieldRole;
   readonly cascade?: CascadeAction;
-  readonly polymorphic?: "any";
   readonly visual: boolean;
   readonly modelRef: ConstantModelRef;
   readonly arrDepth: number;
@@ -369,7 +362,6 @@ export class ConstantField<
     this.validate = props.validate;
     this.text = props.text;
     this.cascade = props.cascade;
-    this.polymorphic = props.polymorphic;
     this.visual = props.visual;
     this.modelRef = props.modelRef;
     this.arrDepth = props.arrDepth;
@@ -450,7 +442,6 @@ export class ConstantField<
       validate: option.validate,
       text: option.text,
       cascade: option.cascade,
-      polymorphic: option.polymorphic,
       visual: option.visual ?? false,
       modelRef,
       arrDepth: arrDepth,
@@ -498,7 +489,6 @@ export class ConstantField<
       validate: this.validate,
       text: this.text,
       cascade: this.cascade,
-      polymorphic: this.polymorphic,
       visual: this.visual,
       modelRef: this.modelRef,
       arrDepth: this.arrDepth,
@@ -523,19 +513,35 @@ export interface FieldObject {
  */
 type WithoutTextRole<Option> = Option extends unknown ? Omit<Option, "text"> : never;
 
+/**
+ * A wildcard owner is read off the row at removal time, so `removeWithAny` without a `refPath` names nothing to
+ * read it from — and the price of that action (no cascade in the app removes in one query) is one nobody should
+ * pay for a declaration that cascades nothing. Pairing the two in the option type refuses it at the call site;
+ * `CascadePaths` keeps the same refusal for the macro and bundled paths that reach it without a typecheck.
+ */
+type CascadeOption =
+  | { cascade?: "removeRef" | "removeWith"; refPath?: string }
+  | { cascade: "removeWithAny"; refPath: string };
+
+type WithCascadePair<Option> = Omit<Option, "cascade" | "refPath"> & CascadeOption;
+
 type FieldOption<
   Value extends ConstantFieldTypeInput,
   MapValue = Value extends MapConstructor ? typeof PrimitiveScalar : never,
   Metadata extends { [key: string]: any } = { [key: string]: any },
   _FieldToValue = FieldToValue<Value, MapValue> | null | undefined,
 > =
-  | Omit<
-      ConstantFieldProps<ConstantFieldKind, _FieldToValue, MapValue, Metadata>,
-      "enum" | "meta" | "nullable" | "fieldType" | "select"
+  | WithCascadePair<
+      Omit<
+        ConstantFieldProps<ConstantFieldKind, _FieldToValue, MapValue, Metadata>,
+        "enum" | "meta" | "nullable" | "fieldType" | "select"
+      >
     >
-  | Omit<
-      ConstantFieldProps<ConstantFieldKind, SingleValue<_FieldToValue>, MapValue, Metadata>,
-      "enum" | "meta" | "nullable" | "fieldType" | "select"
+  | WithCascadePair<
+      Omit<
+        ConstantFieldProps<ConstantFieldKind, SingleValue<_FieldToValue>, MapValue, Metadata>,
+        "enum" | "meta" | "nullable" | "fieldType" | "select"
+      >
     >[];
 
 export type PlainTypeToFieldType<PlainType> = PlainType extends [infer First, ...infer Rest]

package/constant/purify.ts

@@ -105,6 +105,8 @@ const purify = (field: FieldProps, key: string, value: unknown, self: Record<str
     throw new Error(`Invalid Date Value (Default) in ${key} for value ${value}`);
   if ([String, ID].includes(field.modelRef as unknown as StringConstructor | typeof ID) && (value === "" || !value))
     throw new Error(`Invalid String Value (Default) in ${key} for value ${value}`);
+  if (field.enum && !field.enum.has(value as never))
+    throw new Error(`Invalid Enum Value in ${key}: ${String(value)} is not one of ${field.enum.values.join(", ")}`);
   if (field.validate && !field.validate(value, self))
     throw new Error(`Invalid Value (Failed to pass validation) / ${value} in ${key}`);
   if (!field.nullable && !value && value !== 0 && value !== false && (field.modelRef as Cls) !== Any)

package/constant/types.ts

@@ -63,18 +63,22 @@ export class BaseInsight {
   declare count: number;
 }
 
-export interface ProtoFile {
+export interface ProtoLightFile {
   id: string;
   filename: string;
   abstractData: string | null;
   imageSize: [number, number];
-  progress: number | null;
+  progress?: number | null;
   url: string;
   size: number;
   status: string;
   createdAt: Dayjs;
   updatedAt: Dayjs;
   removedAt: Dayjs | null;
+}
+
+export interface ProtoFile extends ProtoLightFile {
+  progress: number | null;
   mimetype: string;
   encoding: string;
   origin: string | null;

package/dictionary/base.dictionary.ts

@@ -146,6 +146,7 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     password: ["Password", "비밀번호"],
     passwordConfirm: ["Password Confirm", "비밀번호 확인"],
     noOptions: ["Can't find any datas", "데이터를 찾을 수 없습니다."],
+    noSelection: ["No selection", "선택 안 함"],
     addModel: ["Add {model}", "{model} 추가"],
     createModel: ["Create {model}", "{model} 생성하기"],
     createSuccess: ["{model} create success", "{model} 생성 완료"],

package/document/documentSchema.ts

@@ -53,6 +53,26 @@ export class DocumentSchema<Doc = unknown> {
     return this;
   }
 
+  removePre<HookDoc = Doc>(type: SaveEventType, hook: DocumentSaveHook<HookDoc>) {
+    const hooks = this.preHooks.get(type);
+    if (hooks)
+      this.preHooks.set(
+        type,
+        hooks.filter((registered) => registered !== (hook as unknown)),
+      );
+    return this;
+  }
+
+  removePost<HookDoc = Doc>(type: SaveEventType, hook: DocumentSaveHook<HookDoc>) {
+    const hooks = this.postHooks.get(type);
+    if (hooks)
+      this.postHooks.set(
+        type,
+        hooks.filter((registered) => registered !== (hook as unknown)),
+      );
+    return this;
+  }
+
   hook(type: DocumentHookName, hook: DocumentSaveHook<Doc>) {
     const [, phase, event] = /^(before|after)(.+)$/.exec(type) ?? [];
     if (!phase || !event) throw new Error(`Invalid document hook: ${type}`);

package/document/filterMeta.ts

@@ -100,6 +100,27 @@ export const fillMissingFilterArgs = (filterInfo: FilterInfo, args: unknown[]) =
   return [...args, ...Array(filterInfo.args.length - args.length).fill(undefined)];
 };
 
+const queryOptionKeys = new Set(["select", "skip", "limit", "sort", "sample"]);
+
+const isQueryOptionArg = (value: unknown) => {
+  if (!value || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  return Object.keys(value).every((key) => queryOptionKeys.has(key));
+};
+
+/**
+ * Splits a generated filter method's arguments into the filter's own args and the trailing query option.
+ * Shared by the database and service resolvers so the two cannot drift into disagreeing about what an option is.
+ */
+export const splitFilterArgs = (filterInfo: FilterInfo, args: unknown[]) => {
+  const hasQueryOption = args.length > filterInfo.args.length || isQueryOptionArg(args.at(-1));
+  return {
+    queryArgs: fillMissingFilterArgs(filterInfo, hasQueryOption ? args.slice(0, -1) : args),
+    queryOption: (hasQueryOption ? args.at(-1) : {}) as Record<string, unknown>,
+  };
+};
+
 export interface FilterArgInfo {
   name: string;
   argRef: ConstantFieldType;

package/document/into.ts

@@ -24,14 +24,6 @@ interface DefaultMdlStats<
   pickById: (docId: string | undefined, projection?: _Projection) => Promise<TDocument>;
   sample: (query: _FilterQuery, size?: number) => Promise<TDocument[]>;
   sampleOne: (query: _FilterQuery) => Promise<TDocument | null>;
-  preSaveListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
-  postSaveListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
-  preCreateListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
-  postCreateListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
-  preUpdateListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
-  postUpdateListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
-  preRemoveListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
-  postRemoveListenerSet: Set<(doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>>;
   listenPre: (
     eventType: SaveEventType,
     listener: (doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>,

package/fetch/client/fetchClient.ts

@@ -19,10 +19,16 @@ import type {
 } from "akanjs/signal";
 import { agentTurnConstant } from "../agentTurn";
 import type { ClientSignal, FetchClientType, FetchSignalInput, MergeAllFetchTypes, SliceMeta } from "../fetchType";
-import { claimRequestQuery, cookies as requestCookies, headers as requestHeaders } from "../requestStorage";
+import {
+  claimRequestQuery,
+  recordRequestQuery,
+  cookies as requestCookies,
+  headers as requestHeaders,
+} from "../requestStorage";
 import type { GetSliceMetaObjFromDatabaseSignals } from "../types";
 import { FetchHandle } from "./fetchHandle";
-import { type ErrorConstructor, HttpClient } from "./httpClient";
+import { HttpClient } from "./httpClient";
+import type { ErrorConstructor } from "./remoteError";
 import { SliceInitHandle } from "./sliceInitHandle";
 import { WsClient } from "./wsClient";
 
@@ -302,8 +308,6 @@ export class FetchClient {
     const parseReturn = this.#makeReturnParser(endpoint.returns);
     const { bodyArgs, uploadArgs } = FetchClient.classifyHttpArgs(endpoint.args);
     switch (endpoint.type) {
-      
-      case "prompt":
       case "query": {
         const queryFn = async (...argData: unknown[]) => {
           const args = argData.slice(0, argLength);
@@ -318,6 +322,7 @@ export class FetchClient {
           const claim = baseUrl
             ? { value: requestQuery(), owned: true }
             : claimRequestQuery(FetchClient.#makeRequestQueryCacheKey(this.origin, url, headers), requestQuery);
+          recordRequestQuery({ key, args: Object.fromEntries(argMap), returns: endpoint.returns, value: claim.value });
           const response = await claim.value;
           const payload = claim.owned ? response : FetchClient.#deepCopy(response);
           return parseReturn(payload, { crystalize: option?.crystalize ?? true });
@@ -346,7 +351,6 @@ export class FetchClient {
   }
   #registerEndpoint(key: string, endpoint: SerializedEndpoint, prefix?: string) {
     switch (endpoint.type) {
-      case "prompt":
       case "query": {
         this.#setHandlerFactory(key, () => this.#makeHttpFn(key, endpoint, prefix));
         return;
@@ -455,8 +459,10 @@ export class FetchClient {
     const updateGuards = signal.updateGuards ?? signal.cruGuards;
     const removeGuards = signal.removeGuards ?? signal.cruGuards;
 
-    const mcp = (verb: keyof NonNullable<SerializedSignal["mcp"]>) =>
-      signal.mcp?.[verb] === false ? { mcp: false as const } : {};
+    const mcp = (verb: keyof NonNullable<SerializedSignal["mcp"]>) => ({
+      ...(signal.mcp?.[verb] === false ? { mcp: false as const } : {}),
+      ...(signal.agents?.[verb] === false ? { agents: false as const } : {}),
+    });
     const endpoint: { [key: string]: SerializedEndpoint } = {};
     if (signal.getGuards) {
       endpoint[names.model] = {
@@ -630,7 +636,10 @@ export class FetchClient {
       live: `${refName}Live${capSuffix}`,
     };
 
-    const mcp = slice.mcp === false ? { mcp: false as const } : {};
+    const mcp = {
+      ...(slice.mcp === false ? { mcp: false as const } : {}),
+      ...(slice.agents === false ? { agents: false as const } : {}),
+    };
     const endpoint: { [key: string]: SerializedEndpoint } = {
       [names.list]: {
         type: "query",

package/fetch/client/httpClient.ts

@@ -1,26 +1,5 @@
 import type { HttpMutationMethod, SerializedArg } from "akanjs/signal";
-
-export interface ErrorResponsePayload {
-  error: string;
-  statusCode?: number;
-  data?: Record<string, unknown>;
-  details?: unknown;
-  path?: string;
-  timestamp?: string;
-}
-
-export interface RestoredError extends Error {
-  error?: string;
-  statusCode?: number;
-  data?: unknown;
-  details?: unknown;
-  path?: string;
-  timestamp?: string;
-}
-
-export interface ErrorConstructor {
-  fromJSON: (payload: ErrorResponsePayload) => RestoredError;
-}
+import { type ErrorConstructor, type RestoredError, restoreRemoteError } from "./remoteError";
 
 export interface HttpClientOptions {
   headers?: Record<string, string>;
@@ -199,14 +178,7 @@ export class HttpClient {
   }
 
   #restoreError(body: unknown, fallbackStatusCode: number): RestoredError {
-    const payload =
-      body && typeof body === "object" && "error" in body
-        ? ({ statusCode: fallbackStatusCode, ...(body as Record<string, unknown>) } as ErrorResponsePayload)
-        : ({ error: String(body), statusCode: fallbackStatusCode } satisfies ErrorResponsePayload);
-    if (this.ErrorCls) return this.ErrorCls.fromJSON(payload);
-    const error = new Error(payload.error);
-    Object.assign(error, payload);
-    return error;
+    return restoreRemoteError(body, fallbackStatusCode, this.ErrorCls);
   }
   static makePath(key: string, paramArgs: SerializedArg[], prefix?: string) {
     const paramPath = paramArgs.length > 0 ? `/${paramArgs.map((arg) => `:${arg.name}`).join("/")}` : "";

package/fetch/client/index.ts

@@ -1,3 +1,4 @@
 export * from "./fetchClient";
 export * from "./httpClient";
+export * from "./remoteError";
 export * from "./wsClient";

package/fetch/client/remoteError.ts

@@ -0,0 +1,57 @@
+export interface ErrorResponsePayload {
+  error: string;
+  statusCode?: number;
+  data?: Record<string, unknown>;
+  details?: unknown;
+  path?: string;
+  timestamp?: string;
+}
+
+export interface RestoredError extends Error {
+  error?: string;
+  statusCode?: number;
+  data?: unknown;
+  details?: unknown;
+  path?: string;
+  timestamp?: string;
+  toJSON?: () => ErrorResponsePayload;
+}
+
+export interface ErrorConstructor {
+  fromJSON: (payload: ErrorResponsePayload) => RestoredError;
+}
+
+/**
+ * Rebuilds what a remote process reported: the caller's own `Err` when this client was given one, and a
+ * duck-typed `Error` carrying the same payload otherwise.
+ *
+ * The `toJSON` is what makes the second case rethrowable. A server process that calls another with `{ origin }`
+ * and lets the failure propagate is answered by `SignalContext.try`, which forwards a payload only when the
+ * thrown value carries both `statusCode` and `toJSON`; anything else is this repo's own bug and is generalized
+ * to `Internal Server Error`. Without it the hop loses the dictionary key and its data, and the browser toasts
+ * the generalization instead of the sentence the remote endpoint chose.
+ */
+export const restoreRemoteError = (
+  body: unknown,
+  fallbackStatusCode: number,
+  ErrorCls?: ErrorConstructor,
+): RestoredError => {
+  const payload =
+    body && typeof body === "object" && "error" in body
+      ? ({ statusCode: fallbackStatusCode, ...(body as Record<string, unknown>) } as ErrorResponsePayload)
+      : ({ error: String(body), statusCode: fallbackStatusCode } satisfies ErrorResponsePayload);
+  if (ErrorCls) return ErrorCls.fromJSON(payload);
+  const error = new Error(payload.error) as RestoredError;
+  Object.assign(error, payload);
+  
+  const json: ErrorResponsePayload = {
+    error: payload.error,
+    statusCode: payload.statusCode ?? fallbackStatusCode,
+    ...(payload.details !== undefined ? { details: payload.details } : {}),
+    ...(payload.data !== undefined ? { data: payload.data } : {}),
+    ...(payload.path !== undefined ? { path: payload.path } : {}),
+    ...(payload.timestamp !== undefined ? { timestamp: payload.timestamp } : {}),
+  };
+  error.toJSON = () => json;
+  return error;
+};

package/fetch/client/wsClient.ts

@@ -7,7 +7,7 @@ import type {
   WebsocketResData,
   WebsocketSubscribeAck,
 } from "akanjs/signal";
-import type { ErrorConstructor, ErrorResponsePayload, RestoredError } from "./httpClient";
+import { type ErrorConstructor, type RestoredError, restoreRemoteError } from "./remoteError";
 
 export interface WsClientReconnectOptions {
   enabled?: boolean;
@@ -216,14 +216,7 @@ export class WsClient {
   }
 
   #restoreError(body: unknown): RestoredError {
-    const payload =
-      body && typeof body === "object" && "error" in body
-        ? (body as ErrorResponsePayload)
-        : ({ error: String(body), statusCode: 500 } satisfies ErrorResponsePayload);
-    if (this.ErrorCls) return this.ErrorCls.fromJSON(payload);
-    const error = new Error(payload.error);
-    Object.assign(error, payload);
-    return error;
+    return restoreRemoteError(body, 500, this.ErrorCls);
   }
 
   destroy() {

package/fetch/requestStorage.ts

@@ -12,11 +12,20 @@ export interface AkanDynamicUsage {
   cookies: boolean;
 }
 
+/** One `fetch.*` query a request made, by endpoint and argument — what a page's data footprint is read off. */
+export interface RequestQueryRecord {
+  key: string;
+  args: Record<string, unknown>;
+  returns: { refName: string; modelType?: string; arrDepth?: number; nullable?: boolean };
+  value: Promise<unknown>;
+}
+
 export interface AkanRequestStore {
   request: Request;
   theme?: AkanTheme;
   frameState?: unknown;
   queryCache: Map<string, Promise<unknown>>;
+  queryLog: RequestQueryRecord[];
   policy: AkanRequestPolicy;
   dynamicUsage: AkanDynamicUsage;
 }
@@ -62,6 +71,7 @@ export function createRequestStore(
   return {
     request,
     queryCache: new Map(),
+    queryLog: [],
     policy: { ...createRequestPolicy(), ...policy },
     dynamicUsage: { headers: false, cookies: false },
   };
@@ -189,6 +199,11 @@ export function claimRequestQuery<T>(key: string, factory: () => Promise<T>): {
   return { value: promise, owned: true };
 }
 
+/** Appends to the active request's query log; outside a request there is nothing to read it, so nothing is kept. */
+export function recordRequestQuery(record: RequestQueryRecord): void {
+  getRequestStore()?.queryLog.push(record);
+}
+
 /** 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.99",
+  "version": "3.0.0-beta.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {