akanjs 3.0.0 → 3.0.2-rc.0

package/base/base.ts

@@ -27,7 +27,7 @@ export type EnumInstance<RefName extends string = string, T = string | number> =
 export const isEnum = (enumRef: Cls) => Object.getPrototypeOf(Object.getPrototypeOf(enumRef) ?? {}) === EnumPrototype;
 
 /** `type` is `String` for string values, else `Int` when every value is an integer, else `Float`. */
-export const enumOf = <RefName extends string, T = string | number>(
+export const enumOf = <RefName extends string, const T = string | number>(
   refName: RefName,
   values: readonly T[],
 ): EnumInstance<RefName, T> => {

package/client/cookie.ts

@@ -46,19 +46,17 @@ export const cookies = (): Map<string, { name: string; value: string }> => {
 export const setCookie = (
   key: string,
   value: string,
-  options: CookieOptions = { path: "/", sameSite: "none", secure: true },
+  { path = "/", sameSite = "lax", secure = true }: CookieOptions = {},
 ) => {
   if (getEnv().side === "server") return;
   if (!pageKeepsCookies()) {
     writeCookieJar({ ...readCookieJar(), [key]: value });
     return;
   }
-  const encoded = `${key}=${value}`;
-  const path = options.path ? `; path=${options.path}` : "";
-  const sameSite = options.sameSite ? `; SameSite=${options.sameSite}` : "";
-  const secure = options.secure ? "; Secure" : "";
+  const pathAttr = path ? `; path=${path}` : "";
+  const secureAttr = secure ? "; Secure" : "";
   
-  document.cookie = `${encoded}${path}${sameSite}${secure}`;
+  document.cookie = `${key}=${value}${pathAttr}; SameSite=${sameSite}${secureAttr}`;
 };
 
 /** Reads through `cookies()` on both sides: a hand-rolled `split("=")` cuts base64 padding and skips the `j:` form. */

package/client/csrTypes.ts

@@ -116,6 +116,8 @@ export interface RouteRender {
   resolveHead?: ResolveHead;
   getPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
   getLayoutPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
+  /** A root layout's `theme`, readable before it renders. */
+  getLayoutTheme?: () => PromiseOrObject<string | undefined>;
   /** The `page()` chain behind a page render, when it was declared as one — what a page prompt is read off. */
   getRouteDefinition?: () => PromiseOrObject<RouteDefinition | undefined>;
 }
@@ -179,7 +181,6 @@ export interface Route {
   /** Synthetic layout render from a `_overrides.tsx` at this node; wraps the subtree in a UI-override provider. */
   renderOverrides?: RouteRender;
   pageIncludesOwnLayout?: boolean;
-  isSpecialRoute?: boolean;
   loader?: () => unknown;
   pageState?: PageState;
   pageConfigChain?: PageConfig[];
@@ -355,7 +356,6 @@ export interface PathRoute {
   renderRootLayouts: RouteRender[];
   renderLayouts: RouteRender[];
   resolveHead?: ResolveHead;
-  isSpecialRoute?: boolean;
 }
 
 export type FrameSlotScope = "page" | "layout";

package/common/Logger.ts

@@ -169,6 +169,16 @@ export class Logger {
   static isPromoted(record: LogRecord) {
     return record.attrs?.flight === true || record.attrs?.debug === true;
   }
+  /** `value` as one line of JSON for a message, a secret-named key masked at any depth and the text cut at `max`. */
+  static inlineData(value: unknown, max = 500): string {
+    let text: string;
+    try {
+      text = JSON.stringify(value, (key, val) => (key && redactedAttrKey.test(key) ? "[redacted]" : val)) ?? "";
+    } catch {
+      text = "[unserializable]";
+    }
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+  }
   static redactAttrs(attrs: LogAttrs): LogAttrs {
     let redacted: LogAttrs | null = null;
     for (const key of Object.keys(attrs)) {

package/common/index.ts

@@ -139,7 +139,6 @@ export {
   getPageSourceFileViolation,
   getRouteExports,
   isRouteSourceFile,
-  isSpecialRouteLeaf,
   LAYOUT_ROUTE_EXPORTS,
   matchRoutePattern,
   normalizeRoutePattern,

package/common/routeConvention.ts

@@ -3,7 +3,6 @@ const SOURCE_EXT_RE = /\.(tsx|ts|jsx|js)$/;
 const RESERVED_ROUTE_FILES = new Set(["_layout", "_index", "_overrides"]);
 const INTERNAL_ROOT_LAYOUT_LEAF = "__root_layout";
 const IMPLICIT_LOCALE_SEGMENT = "[lang]";
-const SPECIAL_ROUTE_LEAVES = new Set(["robots.txt"]);
 
 const DIRECTORY_SCOPED_LEAVES = new Set(["_layout", "_index", "_overrides"]);
 
@@ -45,7 +44,6 @@ export interface ParsedRouteModuleKey {
   ext: string;
   leaf: string;
   pattern: string;
-  isSpecialRoute: boolean;
   isInternalRootLayout: boolean;
 }
 
@@ -140,8 +138,7 @@ export function parseRouteModuleKey(key: string): ParsedRouteModuleKey {
 
   const sourceRouteSegments =
     DIRECTORY_SCOPED_LEAVES.has(leaf) || isInternalRootLayout ? moduleSegments.slice(0, -1) : moduleSegments;
-  const isSpecialRoute = kind === "page" && SPECIAL_ROUTE_LEAVES.has(leaf);
-  const routeSegments = isSpecialRoute ? sourceRouteSegments : [IMPLICIT_LOCALE_SEGMENT, ...sourceRouteSegments];
+  const routeSegments = [IMPLICIT_LOCALE_SEGMENT, ...sourceRouteSegments];
   for (const segment of routeSegments) validateRouteSegment(segment, key);
 
   return {
@@ -153,15 +150,10 @@ export function parseRouteModuleKey(key: string): ParsedRouteModuleKey {
     ext,
     leaf,
     pattern: normalizeRoutePattern(routeSegments),
-    isSpecialRoute,
     isInternalRootLayout,
   };
 }
 
-export function isSpecialRouteLeaf(leaf: string): boolean {
-  return SPECIAL_ROUTE_LEAVES.has(leaf);
-}
-
 export function tryParseRouteModuleKey(key: string): ParsedRouteModuleKey | null {
   try {
     return parseRouteModuleKey(key);

package/dictionary/base.dictionary.ts

@@ -40,10 +40,15 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "The server took too long to answer. Please try again in a moment.",
       "서버 응답이 지연되고 있습니다. 잠시 후 다시 시도해주세요.",
     ],
+    tooManyRequests: [
+      "Too many requests. Please try again in {seconds} seconds.",
+      "요청이 너무 많습니다. {seconds}초 후 다시 시도해주세요.",
+    ],
     unexpectedResponse: [
       "The server returned an unexpected response ({status}).",
       "서버가 예상하지 못한 응답을 보냈습니다. ({status})",
     ],
+    immutableField: ["{field} cannot be changed after creation.", "{field}은(는) 생성 후에는 바꿀 수 없습니다."],
   })
   .translate({
     somethingWrong: ["Something's wrong!", "문제가 생겼어요!"],
@@ -69,6 +74,8 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     phoneInvalidError: ["Phone is not valid", "유효하지 않은 전화번호입니다."],
     ok: ["OK", "확인"],
     cancel: ["Cancel", "취소"],
+    retry: ["Try again", "다시 시도"],
+    pageLoadFailed: ["This page could not be loaded.", "이 화면을 불러오지 못했습니다."],
     unauthorized: ["Unauthorized", "권한 없음"],
     agent: ["Agent", "에이전트"],
     agentIntro: ["Ask about this page or tell the agent what to do.", "이 화면에 대해 묻거나 할 일을 지시해 보세요."],

package/dictionary/trans.ts

@@ -1,5 +1,5 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
-import { interpolateTranslation, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
+import { interpolateTranslation, Logger, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
 
 import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
@@ -122,6 +122,12 @@ export const makeTrans = <
       this.timestamp = option.timestamp;
     }
 
+    override toString() {
+      return this.data === undefined
+        ? `${this.name}: ${this.message}`
+        : `${this.name}: ${this.message} ${Logger.inlineData(this.data)}`;
+    }
+
     toJSON() {
       return {
         error: this.message,

package/document/documentQuery.ts

@@ -101,7 +101,12 @@ export type DocumentUpdate<T = any> = {
   [K in DocumentPath<T>]?: DocumentUpdateValue;
 };
 
-export interface DocumentUpdateOptions {
+/** Server-only: no endpoint or slice builds it from a request, so a caller can never widen a read to removed rows. */
+export interface DocumentScopeOptions {
+  withRemoved?: boolean;
+}
+
+export interface DocumentUpdateOptions extends DocumentScopeOptions {
   upsert?: boolean;
 }
 

package/document/index.ts

@@ -6,6 +6,7 @@ export * from "./documentQuery";
 export * from "./documentSchema";
 export * from "./filterMeta";
 export * from "./into";
+export * from "./liveRowScope";
 export * from "./loaderInfo";
 export * from "./noDocumentError";
 export * from "./queryEvaluator";

package/document/into.ts

@@ -4,7 +4,7 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { FilterCls, FilterQueryOf, FilterSortOf, SchemaOf } from ".";
 import type { CacheDatabase, QueryMethodPart } from "./database";
 import type { DataLoader } from "./dataLoader";
-import type { DocumentQuery, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery";
+import type { DocumentQuery, DocumentScopeOptions, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery";
 import { type LoaderBuilder, type ModelCls, makeLoaderBuilder } from "./loaderInfo";
 import type { DocumentProjection } from "./types";
 
@@ -61,18 +61,26 @@ export type Mdl<
 > = DefaultMdlStats<Doc, _RawDoc, Partial<_RawDoc>, _RawQuery, _Projection> & {
   refName: string;
   new (data: Partial<_RawDoc> | Partial<Doc>): Doc;
-  find(query: _RawQuery, projection?: _Projection): FindManyChain<Doc>;
-  findOne(query: _RawQuery, projection?: _Projection): FindOneChain<Doc>;
-  findById(id: string | undefined, projection?: _Projection): Promise<Doc | null>;
-  count(query: _RawQuery): Promise<number>;
-  exists(query: _RawQuery): Promise<string | null>;
+  find(query: _RawQuery, projection?: _Projection | null, options?: DocumentScopeOptions): FindManyChain<Doc>;
+  findOne(query: _RawQuery, projection?: _Projection | null, options?: DocumentScopeOptions): FindOneChain<Doc>;
+  findById(
+    id: string | undefined,
+    projection?: _Projection | null,
+    options?: DocumentScopeOptions,
+  ): Promise<Doc | null>;
+  count(query: _RawQuery, options?: DocumentScopeOptions): Promise<number>;
+  exists(query: _RawQuery, options?: DocumentScopeOptions): Promise<string | null>;
 
   updateOne(
     query: _RawQuery,
     update: DocumentUpdateInput<_RawDoc>,
     options?: DocumentUpdateOptions,
   ): Promise<UpdateResult>;
-  updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>): Promise<UpdateResult>;
+  updateMany(
+    query: _RawQuery,
+    update: DocumentUpdateInput<_RawDoc>,
+    options?: DocumentScopeOptions,
+  ): Promise<UpdateResult>;
   removeOne(query: _RawQuery): Promise<UpdateResult>;
   removeMany(query: _RawQuery): Promise<UpdateResult>;
   updateById(id: string, update: DocumentUpdateInput<_RawDoc>, options?: DocumentUpdateOptions): Promise<UpdateResult>;

package/document/liveRowScope.ts

@@ -0,0 +1,79 @@
+import {
+  type DocumentQuery,
+  type DocumentQueryNode,
+  type DocumentQueryOperator,
+  queryOperatorKeys,
+} from "./documentQuery";
+
+type RemovedAtTest = "isNull" | "isNotNull" | "value";
+
+/**
+ * Why a query can never match a live row, or null: without `withRemoved` every read and write is scoped to
+ * `removedAt IS NULL`. `q.raw()` is SQL this walk cannot read, so it goes unchecked.
+ */
+export class LiveRowScope {
+  static conflictOf(query: DocumentQuery | undefined, negated = false): string | null {
+    if (!query || typeof query !== "object") return null;
+    if (LiveRowScope.#isNode(query)) {
+      if (query.kind === "all" || query.kind === "any")
+        return query.queries.reduce<string | null>(
+          (found, sub) => found ?? LiveRowScope.conflictOf(sub, negated),
+          null,
+        );
+      if (query.kind === "not") return LiveRowScope.conflictOf(query.query, !negated);
+      return null;
+    }
+    return Object.entries(query).reduce<string | null>(
+      (found, [path, value]) => found ?? LiveRowScope.#fieldConflict(path, value, negated),
+      null,
+    );
+  }
+
+  static #fieldConflict(path: string, value: unknown, negated: boolean): string | null {
+    if (LiveRowScope.#isNode(value) && value.kind !== "op") return LiveRowScope.conflictOf(value, negated);
+    if (path !== "removedAt") return null;
+    for (const [test, spelled] of LiveRowScope.#testsOf(value)) {
+      const named = negated ? `not(removedAt ${spelled})` : `removedAt ${spelled}`;
+      
+      if (test === "value") return `${named} compares a value no live row holds`;
+      if ((test === "isNotNull") !== negated) return `${named} asks for removed rows`;
+    }
+    return null;
+  }
+
+  static #testsOf(value: unknown): [RemovedAtTest, string][] {
+    if (value === undefined) return [];
+    if (value === null) return [["isNull", "null"]];
+    if (LiveRowScope.#isNode(value) && value.kind === "op") {
+      const test = LiveRowScope.#testOf(value.op, value.value);
+      return test ? [test] : [];
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const operators = value as Record<string, unknown>;
+      const keys = Object.keys(operators).filter((key) => queryOperatorKeys.has(key));
+      if (keys.length)
+        return keys.flatMap((key): [RemovedAtTest, string][] => {
+          const spelled = `{ ${key}: ${String(operators[key])} }`;
+          
+          if (key === "exists") return [[operators.exists ? "isNotNull" : "isNull", spelled]];
+          if (key === "missing" || key === "empty") return [[operators[key] ? "isNull" : "isNotNull", spelled]];
+          const test = LiveRowScope.#testOf(key as DocumentQueryOperator, operators[key]);
+          return test ? [test] : [];
+        });
+    }
+    return [["value", "eq"]];
+  }
+
+  static #testOf(op: DocumentQueryOperator, operand: unknown): [RemovedAtTest, string] | null {
+    if (op === "exists") return ["isNotNull", op];
+    if (op === "missing" || op === "empty") return ["isNull", op];
+    if ((op === "eq" || op === "ne") && operand === null) return [op === "eq" ? "isNull" : "isNotNull", `${op}(null)`];
+    
+    if ((op === "oneOf" || op === "notOneOf") && !(operand as unknown[] | undefined)?.length) return null;
+    return ["value", op];
+  }
+
+  static #isNode(value: unknown): value is DocumentQueryNode {
+    return !!value && typeof value === "object" && "kind" in value;
+  }
+}

package/fetch/client/fetchClient.ts

@@ -92,6 +92,9 @@ export class FetchClient {
   readonly #handlerStore: Record<string, FetchHandler> = {};
   readonly #handlerFactory = new Map<string, FetchHandlerFactory>();
   #sharedRegistryAppliedVersion = 0;
+  #clientIp: string | null = null;
+  static #testClientIps = false;
+  static #testClientIpSeq = 0;
   serializedSignal: { [key: string]: SerializedSignal } = {};
   jwt: string | null = null;
 
@@ -120,6 +123,19 @@ export class FetchClient {
     sharedClientState.proxy = null;
     sharedClientState.origin = null;
   }
+  /**
+   * In a signal test every agent reaches the test server from loopback, so an IP rate limit would count them all as
+   * one caller: from here on each clone names its own address (RFC 2544's benchmarking range), which loopback is
+   * trusted to report.
+   */
+  static useTestClientIps(enabled = true) {
+    FetchClient.#testClientIps = enabled;
+    FetchClient.#testClientIpSeq = 0;
+  }
+  static #nextTestClientIp() {
+    const seq = ++FetchClient.#testClientIpSeq;
+    return `198.${18 + ((seq >> 16) & 1)}.${(seq >> 8) & 255}.${seq & 255}`;
+  }
   static #resolveSharedClientProxy(origin: string, Err?: ErrorConstructor) {
     if (typeof window === "undefined") return null;
     
@@ -238,8 +254,22 @@ export class FetchClient {
     for (const ws of this.#originWs.values()) ws.destroy();
     this.#originWs.clear();
   }
-  clone({ origin, connect = true, jwt }: { origin?: string; connect?: boolean; jwt?: string } = {}) {
+  
+  clone({
+    origin,
+    connect = !(origin && typeof window === "undefined"),
+    jwt,
+    clientIp,
+  }: {
+    origin?: string;
+    connect?: boolean;
+    jwt?: string;
+    /** Sent as `x-real-ip`, which a server believes only from a trusted proxy — a test's loopback is one. */
+    clientIp?: string | null;
+  } = {}) {
     const instance = new FetchClient(origin ?? this.origin, {}, this.serializedSignal, this.ErrorCls);
+    instance.#clientIp =
+      clientIp !== undefined ? clientIp : FetchClient.#testClientIps ? FetchClient.#nextTestClientIp() : this.#clientIp;
     Object.entries(this.handler).forEach(([key, handler]) => {
       if (!(key in instance.handler)) instance.handler[key] = handler;
     });
@@ -265,6 +295,21 @@ export class FetchClient {
     ws.connect();
     return ws;
   }
+  #makeRequestHeaders(option?: FetchPolicy): Record<string, string> {
+    const clientIp = this.#clientIp ? { "x-real-ip": this.#clientIp } : FetchClient.#forwardedClientIp(option);
+    return { ...this.#makeAuthHeaders(option), ...clientIp };
+  }
+
+  static #forwardedClientIp(option?: FetchPolicy): Record<string, string> {
+    if (option?.origin) return {};
+    try {
+      if (getEnv().side !== "server") return {};
+      const clientIp = requestHeaders().get("x-real-ip");
+      return clientIp ? { "x-real-ip": clientIp } : {};
+    } catch {
+      return {};
+    }
+  }
   #makeAuthHeaders(option?: FetchPolicy): Record<string, string> {
     if (option?.token) return { Authorization: `Bearer ${option.token}` };
     try {
@@ -299,7 +344,7 @@ export class FetchClient {
       case "query":
         return async (...argData: unknown[]) => {
           const { option, argMap, url } = requestOf(argData);
-          const headers = this.#makeAuthHeaders(option);
+          const headers = this.#makeRequestHeaders(option);
           const baseUrl = this.#baseUrlOf(endpoint, option?.origin);
           const timeout = option?.timeout ?? endpoint.timeout;
           
@@ -318,7 +363,7 @@ export class FetchClient {
           const { option, argMap, url } = requestOf(argData);
           const body = HttpClient.makeBody(bodyArgs, uploadArgs, argMap);
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
-            headers: this.#makeAuthHeaders(option),
+            headers: this.#makeRequestHeaders(option),
             baseUrl: this.#baseUrlOf(endpoint, option?.origin),
             timeout: option?.timeout ?? endpoint.timeout,
           });
@@ -429,16 +474,16 @@ export class FetchClient {
       modelId: `${refName}Id`,
       lightModel: `light${capRefName}`,
     };
-    const createGuards = signal.createGuards ?? signal.cruGuards;
-    const updateGuards = signal.updateGuards ?? signal.cruGuards;
-    const removeGuards = signal.removeGuards ?? signal.cruGuards;
+    const createGuards = FetchClient.#mountedGuards(signal, "create");
+    const updateGuards = FetchClient.#mountedGuards(signal, "update");
+    const removeGuards = FetchClient.#mountedGuards(signal, "remove");
     
     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) {
+    if (FetchClient.#mountedGuards(signal, "get")) {
       endpoint[names.model] = {
         type: "query",
         args: [{ type: "param", name: names.modelId, refName: "ID" }],
@@ -486,6 +531,11 @@ export class FetchClient {
     }
     return endpoint;
   }
+  static #mountedGuards(signal: SerializedSignal, verb: "get" | "create" | "update" | "remove") {
+    if (signal.crud?.[verb] === false) return undefined;
+    if (verb === "get") return signal.getGuards;
+    return signal[`${verb}Guards`] ?? signal.cruGuards;
+  }
   #registerModelBaseEndpoint(refName: string, signal: SerializedSignal) {
     const capRefName = capitalize(refName);
     const names = {
@@ -503,15 +553,17 @@ export class FetchClient {
       this.#setHandlerFactory(key, () => this.#makeHttpFn(key, value, signal.prefix));
     });
 
-    const anyCruGuards = signal.cruGuards ?? signal.createGuards ?? signal.updateGuards ?? signal.removeGuards;
-    const updateGuards = signal.updateGuards ?? signal.cruGuards;
-    if (signal.getGuards) {
+    const getGuards = FetchClient.#mountedGuards(signal, "get");
+    const updateGuards = FetchClient.#mountedGuards(signal, "update");
+    const anyCruGuards =
+      FetchClient.#mountedGuards(signal, "create") ?? updateGuards ?? FetchClient.#mountedGuards(signal, "remove");
+    if (getGuards) {
       this.#setHandlerFactory(names.viewModel, () =>
         this.#makeModelHandleFn(refName, names.model, names.viewModel, `${refName}View`),
       );
       this.#setHandlerFactory(names.getModelView, () => this.#makeModelObjFn(refName, names.getModelView));
     }
-    if (signal.getGuards && anyCruGuards) {
+    if (getGuards && anyCruGuards) {
       this.#setHandlerFactory(names.editModel, () =>
         this.#makeModelHandleFn(refName, names.model, names.editModel, `${refName}Edit`),
       );
@@ -547,7 +599,7 @@ export class FetchClient {
           if (parentId) formData.append(fields.parentId, parentId);
           const url = FetchClient.makeHttpUrl(cap.endpointKey, endpoint, cap.prefix, new Map());
           return await this.http.post(url, formData, {
-            headers: this.#makeAuthHeaders(option),
+            headers: this.#makeRequestHeaders(option),
             baseUrl: this.#baseUrlOf(endpoint),
           });
         }) as FetchHandler,

package/fetch/client/httpClient.ts

@@ -16,6 +16,7 @@ const jsonContentType = /^application\/(?:[\w.+-]+\+)?json\b/i;
 
 const transportErrorKeyMap = {
   408: "base.error.gatewayTimeout",
+  429: "base.error.tooManyRequests",
   502: "base.error.serverUnavailable",
   503: "base.error.serverUnavailable",
   504: "base.error.gatewayTimeout",
@@ -130,12 +131,12 @@ export class HttpClient {
       try {
         return (await res.json()) as unknown;
       } catch (error) {
-        throw this.#transportError(res.status, String(error));
+        throw this.#transportError(res, String(error));
       }
     }
     const raw = await res.text();
     const parsed = HttpClient.#parseJson(raw);
-    if (parsed === undefined) throw this.#transportError(res.status, raw);
+    if (parsed === undefined) throw this.#transportError(res, raw);
     return parsed;
   }
 
@@ -147,9 +148,17 @@ export class HttpClient {
     }
   }
 
-  #transportError(status: number, detail: string): RestoredError {
+  #transportError(res: Response, detail: string): RestoredError {
+    const { status } = res;
     const error = transportErrorKeyMap[status as keyof typeof transportErrorKeyMap] ?? unexpectedResponseKey;
-    return this.#restoreError({ error, data: { status }, details: detail.slice(0, transportDetailLimit) }, status);
+    const data = status === 429 ? { status, seconds: HttpClient.#retryAfterSeconds(res) } : { status };
+    return this.#restoreError({ error, data, details: detail.slice(0, transportDetailLimit) }, status);
+  }
+
+  static #retryAfterSeconds(res: Response): number {
+    const header = res.headers.get("retry-after")?.trim() ?? "";
+    const seconds = /^\d+$/.test(header) ? Number(header) : Math.ceil((Date.parse(header) - Date.now()) / 1000);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : 60;
   }
 
   #restoreError(body: unknown, fallbackStatusCode: number): RestoredError {

package/index.ts

@@ -213,6 +213,28 @@ export interface AkanNativeDesktopConfig {
    * for a native addon signed by another team. Read when the app is signed with a team (a Developer ID).
    */
   entitlements?: Record<string, AkanNativeValue>;
+  /**
+   * macOS: the Finder window `build-desktop --installer` opens its dmg in — no toolbar or sidebar, the app's and the
+   * Applications link's icons on a background, the app's icon on the mounted disk. Without it the window is 660×400 pt
+   * on the framework's background, an arrow from the app at (180, 170) to Applications at (480, 170). A position is an
+   * icon's center in points from the window's top left; the default background lines up with the default positions.
+   */
+  dmg?: AkanNativeDmgConfig;
+}
+
+export interface AkanNativeDmgConfig {
+  /** A PNG (or TIFF) the size of the window in points, relative to the app folder; `false` for a plain window. */
+  background?: string | false;
+  /** The same picture at twice the pixels, for a Retina display. */
+  background2x?: string;
+  /** The area under the title bar, in points. Default the background's size, at 200, 120 on the screen. */
+  window?: { x?: number; y?: number; width?: number; height?: number };
+  /** Default 128. */
+  iconSize?: number;
+  /** Default 13. */
+  textSize?: number;
+  app?: { x: number; y: number };
+  applications?: { x: number; y: number };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0",
+  "version": "3.0.2-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanOption.ts

@@ -1,6 +1,13 @@
 import type { BackendEnv, PromiseOrObject } from "akanjs/base";
 import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
-import type { AgentQuotaHook, AgentUsageHook, CrossSiteOption, GuardCls, MiddlewareCls } from "akanjs/signal";
+import type {
+  AgentQuotaHook,
+  AgentUsageHook,
+  CrossSiteOption,
+  GuardCls,
+  MiddlewareCls,
+  RateLimitSetting,
+} from "akanjs/signal";
 import type { McpServerOption } from "./akanServer";
 import type { WebProxyRegistration } from "./proxy";
 import { HostBasePathWebProxy, LocaleWebProxy } from "./proxy";
@@ -21,6 +28,7 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   #agentUsage: AgentUsageHook | null | undefined;
   #agentQuota: AgentQuotaHook | null | undefined;
   #crossSite: CrossSiteOption | undefined;
+  #getRateLimit: ((env: Env) => RateLimitSetting | false) | undefined;
   use(fnOrObject: ((env: Env) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>) {
     if (typeof fnOrObject === "function")
       this.#getUses.push(fnOrObject as (env: Env) => Record<string, PromiseOrObject<unknown>>);
@@ -65,6 +73,14 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
     this.#crossSite = crossSite;
     return this;
   }
+  /**
+   * Endpoint budgets: a default for endpoints that declare none, overrides by endpoint key, and who `by: "account"`
+   * counts. Merged in mount order, the app's last; `AKAN_RATE_LIMIT=off` still turns them all off.
+   */
+  setRateLimit(settingOrFn: RateLimitSetting | false | ((env: Env) => RateLimitSetting | false)) {
+    this.#getRateLimit = typeof settingOrFn === "function" ? settingOrFn : () => settingOrFn;
+    return this;
+  }
   /** Injected into the `LlmAdaptorRole` adaptor as the `llmOption` use; merged in mount order, the app's last. */
   setLlm<Option extends LlmOption>(llmOrFn: Option | ((env: Env) => Option)) {
     if (typeof llmOrFn === "function") this.#getLlms.push(llmOrFn);
@@ -99,6 +115,9 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   getCrossSite(): CrossSiteOption | undefined {
     return this.#crossSite;
   }
+  getRateLimit(env: Env): RateLimitSetting | false | undefined {
+    return this.#getRateLimit?.(env);
+  }
   getLlm(env: Env): LlmOption {
     return Object.assign({}, ...this.#getLlms.map((fn) => fn(env)));
   }

package/server/akanServer.ts

@@ -15,6 +15,7 @@ import type {
 import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs/signal";
 import { AgentMeter } from "../signal/agentMeter";
 import { CrossSiteGuard } from "../signal/CrossSiteGuard";
+import { EndpointRateLimit } from "../signal/endpointRateLimit";
 import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
@@ -189,6 +190,7 @@ export class AkanServer {
     this.env = { ...env };
     this.openapi = options?.openapi ?? this.openapi;
     
+    EndpointRateLimit.reset();
     libs.forEach((lib) => {
       const mcp = lib.option.getMcp(this.env);
       if (mcp !== undefined) this.setMcp(mcp);
@@ -198,7 +200,10 @@ export class AkanServer {
       if (usage !== undefined || quota !== undefined) AgentMeter.use({ usage, quota });
       const crossSite = lib.option.getCrossSite();
       if (crossSite !== undefined) CrossSiteGuard.configure(crossSite);
+      const rateLimit = lib.option.getRateLimit(this.env);
+      if (rateLimit !== undefined) EndpointRateLimit.configure(rateLimit);
     });
+    EndpointRateLimit.applyEnv(process.env.AKAN_RATE_LIMIT, getEnv().environment);
     this.setMcp(options?.mcp ?? this.mcp);
     this.serverMode = serverMode;