akanjs 3.1.1 → 3.1.2-rc.0

package/common/codeAgentProfile.ts

@@ -75,7 +75,13 @@ export interface CodeAgentProfile {
   paths: { root: string; allow?: string[]; deny?: string[] };
   session: { store: "file" | "memory" | "remote"; crossSession: boolean };
   interaction: { question: CodeAgentInteractionMode; approval: CodeAgentInteractionMode };
-  network: { allowHosts?: string[]; proxyBaseUrl?: string };
+  network: {
+    /** Hosts `web_fetch` may reach at all; any other is refused. Unset reaches any host. */
+    allowHosts?: string[];
+    /** Hosts (and subdomains) fetched without asking; others and networking commands need approval. Unset never asks. */
+    askOutside?: string[];
+    proxyBaseUrl?: string;
+  };
   ui: { canPrompt: boolean };
   limits: {
     turnMs: number;
@@ -97,8 +103,49 @@ export const codeAgentReadOnlyBuiltins: CodeAgentBuiltinTool[] = ["read", "ls",
 
 const baseLimits = { turnMs: 900_000, toolOutputBytes: 200_000, contextTokens: 0, feedback: 2 };
 
-/** Paths no profile may read, whatever its allowlist says. */
-export const codeAgentDeniedPaths = ["**/.env", "**/.env.*", "**/secrets/**", "**/*.pem", "**/*.key"];
+/** Paths no profile may read or write, whatever its allowlist says. `~/` is the home directory. */
+export const codeAgentDeniedPaths = [
+  "**/.env",
+  "**/.env.*",
+  
+  "**/env.server.{debug,develop,main,testing,local}*.ts",
+  "**/secrets/**",
+  "**/*.pem",
+  "**/*.key",
+  "**/*-secret.yaml",
+  "**/*secrets.yaml",
+  "**/kubeconfig*",
+  "**/regcred.yaml",
+  "**/credentials.sh",
+  "**/.jenkins.conf",
+  "**/bunkan-id*",
+  
+  "**/.akan/code/mcp.json",
+  "**/.akan/code/extensions/**",
+  "~/.akan/**",
+  "~/.ssh/**",
+  "~/.aws/**",
+  "~/.kube/**",
+  "~/.docker/config.json",
+  "~/.netrc",
+  "~/.git-credentials",
+];
+
+/** Documentation and registry hosts the `local` profile reads without asking; nobody but their owner sees a request. */
+const trustedHosts = [
+  "akanjs.com",
+  "github.com",
+  "githubusercontent.com",
+  "npmjs.com",
+  "npmjs.org",
+  "bun.sh",
+  "bun.com",
+  "developer.mozilla.org",
+  "nodejs.org",
+  "typescriptlang.org",
+  "react.dev",
+  "tailwindcss.com",
+];
 
 export const codeAgentPresets = {
   local: (root: string): CodeAgentProfile => ({
@@ -114,7 +161,7 @@ export const codeAgentPresets = {
     paths: { root, deny: codeAgentDeniedPaths },
     session: { store: "file", crossSession: true },
     interaction: { question: "await", approval: "await" },
-    network: {},
+    network: { askOutside: trustedHosts },
     ui: { canPrompt: true },
     limits: baseLimits,
     context: { projectFiles: true, skills: true },

package/common/index.ts

@@ -1,3 +1,13 @@
+export {
+  databaseStateNames,
+  endpointNames,
+  formSetterNames,
+  modelNames,
+  moduleNames,
+  queryNames,
+  sliceNames,
+  stateSetterName,
+} from "./akanNames";
 export { AppHosts } from "./appHosts";
 export { applyMixins, getAllPropertyDescriptors } from "./applyMixins";
 export { cookieHeaderHasAuthToken, isAuthTokenKey, legacyAuthTokenKey } from "./authCookie";
@@ -109,10 +119,13 @@ export {
 export {
   type AkanI18nConfig,
   type AkanI18nConfigInput,
+  type AkanLocalePrefix,
+  akanLocalePrefixes,
   DEFAULT_AKAN_I18N,
   parseAkanI18nEnv,
   resolveAkanI18nConfig,
 } from "./localeConfig";
+export { LocalePath } from "./localePath";
 export {
   type LogContextReader,
   type LogContextSnapshot,

package/common/localeConfig.ts

@@ -1,16 +1,26 @@
+export const akanLocalePrefixes = ["always", "as-needed"] as const;
+export type AkanLocalePrefix = (typeof akanLocalePrefixes)[number];
+
 export interface AkanI18nConfig {
   defaultLocale: string;
   locales: string[];
+  /**
+   * `"always"` (absent means this) serves every page under `/<locale>/…` and redirects an unprefixed path by
+   * Accept-Language; `"as-needed"` serves the default locale's pages unprefixed, so a single-locale app has no prefix.
+   */
+  localePrefix?: AkanLocalePrefix;
 }
 
 export interface AkanI18nConfigInput {
   defaultLocale?: string;
   locales?: readonly string[];
+  localePrefix?: AkanLocalePrefix;
 }
 
 export const DEFAULT_AKAN_I18N: AkanI18nConfig = Object.freeze({
   defaultLocale: "en",
   locales: Object.freeze(["en", "ko"]) as unknown as string[],
+  localePrefix: "always",
 });
 
 const normalizeLocale = (locale: string) => locale.trim();
@@ -18,30 +28,45 @@ const normalizeLocale = (locale: string) => locale.trim();
 export function resolveAkanI18nConfig(input: AkanI18nConfigInput = {}): AkanI18nConfig {
   const locales = [...new Set((input.locales ?? DEFAULT_AKAN_I18N.locales).map(normalizeLocale).filter(Boolean))];
   const defaultLocale = normalizeLocale(input.defaultLocale ?? DEFAULT_AKAN_I18N.defaultLocale);
+  const localePrefix = input.localePrefix ?? "always";
 
   if (locales.length === 0) throw new Error("[i18n] locales must include at least one locale");
   if (!defaultLocale) throw new Error("[i18n] defaultLocale must not be empty");
   if (!locales.includes(defaultLocale)) {
     throw new Error(`[i18n] defaultLocale "${defaultLocale}" must be included in locales: ${locales.join(",")}`);
   }
+  if (!akanLocalePrefixes.includes(localePrefix))
+    throw new Error(`[i18n] localePrefix "${localePrefix}" must be one of: ${akanLocalePrefixes.join(", ")}`);
 
-  return { defaultLocale, locales };
+  return { defaultLocale, locales, localePrefix };
 }
 
-let lastParsed: { defaultLocale?: string; locales?: string; config: AkanI18nConfig } | null = null;
+let lastParsed: { defaultLocale?: string; locales?: string; localePrefix?: string; config: AkanI18nConfig } | null =
+  null;
 
 export function parseAkanI18nEnv(
   env: Record<string, string | undefined> = {
     AKAN_PUBLIC_DEFAULT_LOCALE: typeof process !== "undefined" ? process.env.AKAN_PUBLIC_DEFAULT_LOCALE : undefined,
     AKAN_PUBLIC_LOCALES: typeof process !== "undefined" ? process.env.AKAN_PUBLIC_LOCALES : undefined,
+    AKAN_PUBLIC_LOCALE_PREFIX: typeof process !== "undefined" ? process.env.AKAN_PUBLIC_LOCALE_PREFIX : undefined,
   },
 ): AkanI18nConfig {
   const defaultLocale = env.AKAN_PUBLIC_DEFAULT_LOCALE;
   const locales = env.AKAN_PUBLIC_LOCALES;
-  if (lastParsed && lastParsed.defaultLocale === defaultLocale && lastParsed.locales === locales)
+  const localePrefix = env.AKAN_PUBLIC_LOCALE_PREFIX;
+  if (
+    lastParsed &&
+    lastParsed.defaultLocale === defaultLocale &&
+    lastParsed.locales === locales &&
+    lastParsed.localePrefix === localePrefix
+  )
     return lastParsed.config;
-  const resolved = resolveAkanI18nConfig({ defaultLocale, locales: locales?.split(",") });
+  const resolved = resolveAkanI18nConfig({
+    defaultLocale,
+    locales: locales?.split(","),
+    localePrefix: (localePrefix || undefined) as AkanLocalePrefix | undefined,
+  });
   const config = Object.freeze({ ...resolved, locales: Object.freeze(resolved.locales) as unknown as string[] });
-  lastParsed = { defaultLocale, locales, config };
+  lastParsed = { defaultLocale, locales, localePrefix, config };
   return config;
 }

package/common/localePath.ts

@@ -0,0 +1,26 @@
+import type { AkanI18nConfig } from "./localeConfig";
+
+type LocaleRouting = Pick<AkanI18nConfig, "defaultLocale" | "locales" | "localePrefix">;
+
+export class LocalePath {
+  static omits(locale: string, { defaultLocale, localePrefix }: Omit<LocaleRouting, "locales">) {
+    return localePrefix === "as-needed" && locale === defaultLocale;
+  }
+
+  static segmentOf(locale: string, i18n: Omit<LocaleRouting, "locales">) {
+    return LocalePath.omits(locale, i18n) ? "" : `/${locale}`;
+  }
+
+  static split(pathname: string, i18n: LocaleRouting): { locale: string | null; path: string; isPrefixed: boolean } {
+    const [, first = "", ...rest] = pathname.split("/");
+    if (first && i18n.locales.includes(first)) return { locale: first, path: `/${rest.join("/")}`, isPrefixed: true };
+    const locale = i18n.localePrefix === "as-needed" ? i18n.defaultLocale : null;
+    return { locale, path: pathname || "/", isPrefixed: false };
+  }
+
+  static join(locale: string, path: string, i18n: Omit<LocaleRouting, "locales">) {
+    const segment = LocalePath.segmentOf(locale, i18n);
+    if (path === "/" || path === "") return segment || "/";
+    return `${segment}${path.startsWith("/") ? path : `/${path}`}`;
+  }
+}

package/common/markdownSpans.ts

@@ -36,7 +36,9 @@ export class MarkdownSpans {
   }
 
   static isSafeHref(href: string) {
-    return !/^[a-z][a-z0-9+.-]*:/i.test(href) || /^(?:https?|mailto|tel):/i.test(href);
+    
+    const parsed = href.replace(/[\t\n\r]/g, "").replace(/^[\u0000-\u0020]+/, "");
+    return !/^[a-z][a-z0-9+.-]*:/i.test(parsed) || /^(?:https?|mailto|tel):/i.test(parsed);
   }
 
   static plain(text: string): string {

package/common/mcpExposure.ts

@@ -1,4 +1,4 @@
-import { capitalize } from "./capitalize";
+import { modelNames } from "./akanNames";
 
 export interface McpExposureEndpoint {
   type: string;
@@ -24,11 +24,11 @@ export interface McpExposureOption {
 export const isMcpDescribableArg = (arg: { refName: string }) => arg.refName !== "Any";
 
 export const mcpBaseVerbOf = (refName: string, key: string) => {
-  const cap = capitalize(refName);
-  if (key === refName || key === `light${cap}`) return "get" as const;
-  if (key === `create${cap}`) return "create" as const;
-  if (key === `update${cap}`) return "update" as const;
-  if (key === `remove${cap}`) return "remove" as const;
+  const names = modelNames(refName);
+  if (key === names.model || key === names.lightModel) return "get" as const;
+  if (key === names.createModel) return "create" as const;
+  if (key === names.updateModel) return "update" as const;
+  if (key === names.removeModel) return "remove" as const;
   return null;
 };
 
@@ -55,7 +55,7 @@ export const mcpRefusalOf = (
     return `its guards (${(endpoint.guards ?? []).join(", ")}) admit no agent — an act reserved for a person, so it is off the agent shelf. HTTP still serves it.`;
   if (!endpoint.guards?.length)
     return "it declares no guards, and exposure follows them — write `guards: [Public]` if anonymous access is the intent.";
-  if (key === `light${capitalize(refName)}` && !view)
+  if (key === modelNames(refName).lightModel && !view)
     return `it reads the same document as \`${refName}\` in a smaller shape — call \`${refName}\` instead.`;
   if (endpoint.type === "pubsub" || endpoint.type === "message")
     return `\`${endpoint.type}\` rides the websocket, and its internal arguments read a socket an MCP request does not have.`;

package/common/websocketContract.ts

@@ -37,8 +37,58 @@ export const websocketHeartbeatContract = {
   makeAck: (): WebsocketHeartbeatAckData => ({ type: "pong" }),
 } as const;
 
+const canonicalOf = (value: unknown, holding: Set<object>): unknown => {
+  if (typeof value === "bigint") return `${value}n`;
+  if (typeof value === "function" || typeof value === "symbol") return undefined;
+  if (value === null || typeof value !== "object") return value;
+  if (holding.has(value)) throw new Error("A room key cannot be built from a value that contains itself");
+  holding.add(value);
+  try {
+    const toJSON = (value as { toJSON?: unknown }).toJSON;
+    if (typeof toJSON === "function") return canonicalOf(toJSON.call(value), holding);
+    if (ArrayBuffer.isView(value))
+      return { "%bytes": [...new Uint8Array(value.buffer, value.byteOffset, value.byteLength)] };
+    if (value instanceof Map)
+      return { "%map": [...value].map(([key, item]) => [canonicalOf(key, holding), canonicalOf(item, holding)]) };
+    if (value instanceof Set) return { "%set": [...value].map((item) => canonicalOf(item, holding)) };
+    if (value instanceof RegExp) return { "%regexp": [value.source, value.flags] };
+    if (Array.isArray(value)) return value.map((item) => canonicalOf(item, holding) ?? null);
+    const record: Record<string, unknown> = {};
+    for (const key of Object.keys(value).sort()) {
+      const item = canonicalOf((value as Record<string, unknown>)[key], holding);
+      if (item !== undefined) record[key] = item;
+    }
+    return record;
+  } finally {
+    holding.delete(value);
+  }
+};
+
+export const canonicalJson = (value: unknown): string => JSON.stringify(canonicalOf(value, new Set())) ?? "~";
+
+const escapeRoomToken = (text: string) =>
+  text.replace(/[^A-Za-z0-9_.]/g, (char) => {
+    const code = char.charCodeAt(0);
+    return code < 0x100
+      ? `%${code.toString(16).toUpperCase().padStart(2, "0")}`
+      : `%u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+  });
+
 export const websocketRoomContract = {
+  /** The label a client files a subscription under; the server joins `roomOf`, and the ack names both. */
   idOf: (key: string, args: unknown[]) => `${key}${args.length ? "-" : ""}${args.join("-")}`,
+  roomOf: (key: string, tokens: string[]) => (tokens.length ? `${key}-${tokens.join("-")}` : key),
+  /** For an argument of one declared type; `~` is never an escape's output, so it can stand for an absent value. */
+  tokenOf: (value: unknown): string => {
+    if (value === null || value === undefined) return "~";
+    if (typeof value === "string") return escapeRoomToken(value);
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
+      return escapeRoomToken(String(value));
+    const canonical = canonicalOf(value, new Set());
+    return escapeRoomToken(typeof canonical === "string" ? canonical : (JSON.stringify(canonical) ?? "~"));
+  },
+  /** For an `Any` argument, where `"1"` and `1` are different values. */
+  jsonTokenOf: (value: unknown): string => (value === undefined ? "~" : escapeRoomToken(canonicalJson(value))),
 } as const;
 
 export interface WebsocketBinaryFrame {

package/constant/index.ts

@@ -13,6 +13,7 @@ export * from "./invalidInputError";
 export * from "./labelOf";
 export * from "./mask";
 export * from "./purify";
+export * from "./requestValue";
 export * from "./serialize";
 export * from "./textFieldPathSet";
 export * from "./textFieldPaths";

package/constant/inputParser.ts

@@ -17,6 +17,7 @@ import type { ConstantField, FieldObject } from "./fieldInfo";
 import { FieldPlan, type FieldPlanEntry } from "./fieldPlan";
 import { defaultPlanOf } from "./getDefault";
 import { InvalidInputError } from "./invalidInputError";
+import { RequestValue } from "./requestValue";
 import { deserialize } from "./serialize";
 
 type ModelCls = Cls & { [FIELD_META]: FieldObject };
@@ -50,7 +51,11 @@ export class InputParser {
       if (nullable) return null;
       throw new InvalidInputError(key, null);
     }
-    if (PrimitiveRegistry.has(argRef)) return deserialize(argRef, arrDepth, value, option);
+    if (PrimitiveRegistry.has(argRef)) {
+      const parsed = deserialize(argRef, arrDepth, value, option);
+      RequestValue.admit(parsed, key);
+      return parsed;
+    }
     return InputParser.#walk(value, arrDepth, key, (item, path) => InputParser.#value(argRef, item, path));
   }
 
@@ -81,6 +86,7 @@ export class InputParser {
     }
     if (enumRef && !enumRef.has(parsed as never))
       throw new InvalidInputError(path, `one of ${enumRef.values.join(", ")}`);
+    RequestValue.admit(parsed, path);
     return parsed;
   }
 
@@ -130,7 +136,7 @@ export class InputParser {
   static #map(of: Cls | Cls[], value: unknown, path: string) {
     if (!isRecord(value)) throw new InvalidInputError(path, "object");
     const [valueRef, valueArrDepth] = getNonArrayModel(of);
-    return Object.fromEntries(
+    const parsed = Object.fromEntries(
       Object.entries(value).map(([key, item]) => [
         key,
         InputParser.#walk(item, valueArrDepth, `${path}.${key}`, (entry, entryPath) =>
@@ -138,6 +144,8 @@ export class InputParser {
         ),
       ]),
     );
+    RequestValue.admit(parsed, path);
+    return parsed;
   }
 
   static #isRequired(field: ConstantField) {

package/constant/requestValue.ts

@@ -0,0 +1,47 @@
+import { InvalidInputError } from "./invalidInputError";
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+export class RequestValue {
+  
+  static readonly #key = Symbol.for("akanjs.constant.requestValues");
+
+  static get #values(): WeakSet<object> {
+    const holder = globalThis as unknown as Record<symbol, WeakSet<object> | undefined>;
+    const values = holder[RequestValue.#key] ?? new WeakSet<object>();
+    holder[RequestValue.#key] = values;
+    return values;
+  }
+
+  static admit(value: unknown, path: string): void {
+    if (Array.isArray(value)) {
+      value.forEach((item, idx) => {
+        RequestValue.admit(item, `${path}.${idx}`);
+      });
+      return;
+    }
+    if (!isPlainRecord(value)) return;
+    const values = RequestValue.#values;
+    if (values.has(value)) return;
+    if (RequestValue.#isRawSqlShaped(value)) throw new InvalidInputError(path, "a value, not a SQL condition");
+    values.add(value);
+    for (const [key, item] of Object.entries(value)) RequestValue.admit(item, `${path}.${key}`);
+  }
+
+  static isFrom(value: unknown): boolean {
+    return !!value && typeof value === "object" && RequestValue.#values.has(value);
+  }
+
+  static #isRawSqlShaped(value: Record<string, unknown>) {
+    return (
+      value.kind === "raw" &&
+      typeof value.sql === "string" &&
+      Array.isArray(value.params) &&
+      Object.keys(value).every((key) => key === "kind" || key === "sql" || key === "params")
+    );
+  }
+}

package/dictionary/agent.dictionary.ts

@@ -26,8 +26,8 @@ export const agentDictionary = serviceDictionary(["en", "ko"])
     ],
     
     llmRequestFailed: [
-      "{provider} refused this turn with status {status}. Reason: {reason}",
-      "{provider}가 이번 턴을 거절했습니다 (status {status}). 사유: {reason}",
+      "{provider} refused this turn with status {status}",
+      "{provider}가 이번 턴을 거절했습니다 (status {status})",
     ],
     
     contextOverflow: [

package/dictionary/base.dictionary.ts

@@ -44,6 +44,10 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "Too many requests. Please try again in {seconds} seconds.",
       "요청이 너무 많습니다. {seconds}초 후 다시 시도해주세요.",
     ],
+    payloadTooLarge: [
+      "The request is too large for the server to accept.",
+      "요청이 너무 커서 서버가 받을 수 없습니다.",
+    ],
     unexpectedResponse: [
       "The server returned an unexpected response ({status}).",
       "서버가 예상하지 못한 응답을 보냈습니다. ({status})",

package/dictionary/dictInfo.ts

@@ -1,5 +1,5 @@
 import type { GetStateObject } from "akanjs/base";
-import { capitalize } from "akanjs/common";
+import { capitalize, modelNames, sliceNames } from "akanjs/common";
 import type { BaseInsight, BaseObject } from "akanjs/constant";
 import type { BaseFilterQueryKey, BaseFilterSortKey } from "akanjs/document";
 import type { DictArgNames, DictEndpointShape, DictFilterQuery, DictFilterSort, DictSliceShape } from "./dictShape";
@@ -177,23 +177,24 @@ export class ModelDictInfo<
   };
   static getBaseSignalDictionary<T extends string>(refName: T): BaseModelCrudGetSignalTranslation<T, [string, string]> {
     const capRefName = capitalize(refName);
+    const names = modelNames(refName);
     type Translate = (trans: [string, string]) => FieldTranslation<[string, string]>;
     const crud = (en: string, ko: string) => fn([en, ko]).desc([en, ko]);
     const idArg = (t: Translate) => ({
-      [`${refName}Id`]: t(["Id", "아이디"]).desc([`Id of ${capRefName}`, `${capRefName} 아이디`]),
+      [names.modelId]: t(["Id", "아이디"]).desc([`Id of ${capRefName}`, `${capRefName} 아이디`]),
     });
     const dataArg = (t: Translate) => ({
       data: t(["Data", "데이터"]).desc([`Data of ${capRefName}`, `${capRefName} 데이터`]),
     });
     return {
-      [refName]: crud(`Get ${capRefName}`, `${capRefName} 조회`).arg(idArg),
-      [`light${capRefName}`]: crud(`Get light version of ${capRefName}`, `${capRefName} 경량화 버전 조회`).arg(idArg),
-      [`create${capRefName}`]: crud(`Create ${capRefName}`, `${capRefName} 생성`).arg(dataArg),
-      [`update${capRefName}`]: crud(`Update ${capRefName}`, `${capRefName} 수정`).arg((t) => ({
+      [names.model]: crud(`Get ${capRefName}`, `${capRefName} 조회`).arg(idArg),
+      [names.lightModel]: crud(`Get light version of ${capRefName}`, `${capRefName} 경량화 버전 조회`).arg(idArg),
+      [names.createModel]: crud(`Create ${capRefName}`, `${capRefName} 생성`).arg(dataArg),
+      [names.updateModel]: crud(`Update ${capRefName}`, `${capRefName} 수정`).arg((t) => ({
         ...idArg(t),
         ...dataArg(t),
       })),
-      [`remove${capRefName}`]: crud(`Remove ${capRefName}`, `${capRefName} 삭제`).arg(idArg),
+      [names.removeModel]: crud(`Remove ${capRefName}`, `${capRefName} 삭제`).arg(idArg),
     } as unknown as BaseModelCrudGetSignalTranslation<T, [string, string]>;
   }
   static baseSliceDictionary: {
@@ -438,8 +439,7 @@ export class ModelDictInfo<
     for (const [sliceKey, sliceTrans] of Object.entries(
       this.sliceDictionary as { [key: string]: FunctionTranslation<Languages> },
     )) {
-      const listKey = `${refName}List${capitalize(sliceKey)}`;
-      const insightKey = `${refName}Insight${capitalize(sliceKey)}`;
+      const { list: listKey, insight: insightKey } = sliceNames(refName, sliceKey).endpoint;
       root.head(["signal"], listKey, sliceTrans, (t) => `Slice List - ${t}`);
       root.head(["signal"], insightKey, sliceTrans, (t) => `Slice Insight - ${t}`);
       for (const [argKey, argTrans] of Object.entries(sliceTrans.argTrans as { [key: string]: Translated })) {

package/document/database.ts

@@ -152,6 +152,7 @@ export type DatabaseInstanceWithQuerySort<
   __load: (id?: string) => Promise<Doc | null>;
   __loadMany: (ids: string[]) => Promise<Doc[]>;
   __create: (data: _DataInput) => Promise<Doc>;
+  __createMany: (data: _DataInput[]) => Promise<Doc[]>;
   __update: (id: string, data: Partial<Doc>) => Promise<Doc>;
   __remove: (id: string) => Promise<Doc>;
   __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;

package/document/documentQuery.ts

@@ -1,5 +1,6 @@
 import { type Dayjs, dayjs } from "akanjs/base";
 import { isValidDate } from "akanjs/common";
+import { RequestValue } from "akanjs/constant";
 
 export type DocumentId = string & { readonly __brand: "DocumentId" };
 
@@ -170,6 +171,40 @@ export const isDocumentQueryNode = (value: unknown): value is DocumentQueryNode
   }
 };
 
+const builtNodeKey = Symbol.for("akanjs.document.builtQueryNodes");
+const builtNodeHolder = globalThis as unknown as Record<symbol, WeakSet<object> | undefined>;
+const builtNodes = builtNodeHolder[builtNodeKey] ?? new WeakSet<object>();
+builtNodeHolder[builtNodeKey] = builtNodes;
+const built = <Node extends DocumentQueryNode>(node: Node): Node => {
+  builtNodes.add(node);
+  return node;
+};
+export const isBuiltQueryNode = (node: object) => builtNodes.has(node);
+
+export const queryNodeProblem = (node: DocumentQueryNode): string | null => {
+  if (RequestValue.isFrom(node))
+    return `A q.${node.kind}() condition arrived as a request value; build query conditions with q in code`;
+  if ((node.kind === "raw" || node.kind === "search") && !isBuiltQueryNode(node))
+    return `A q.${node.kind}() condition must be built by q.${node.kind}(); an object of the same shape is refused`;
+  return null;
+};
+
+export const fieldValueProblem = (path: string, value: unknown): string | null => {
+  
+  if (
+    RequestValue.isFrom(value) &&
+    (isDocumentQueryNode(value) || Object.keys(value as object).some((key) => queryOperatorKeys.has(key)))
+  )
+    return `The value of "${path}" arrived in a request and holds query operators; build the condition with q from checked values`;
+  if (isDocumentQueryNode(value)) {
+    if (value.kind === "op") return null;
+    if (value.kind === "raw" || value.kind === "search")
+      return `q.${value.kind}() cannot be the value of "${path}"; put it beside the field's condition`;
+    return `q.${value.kind}() cannot be the value of "${path}"; it combines whole conditions, as in q.${value.kind}({ ${path}: ... })`;
+  }
+  return null;
+};
+
 export interface SqlFragment {
   sql: string;
   params: unknown[];
@@ -202,13 +237,14 @@ export const createDocumentQueryHelper = () => ({
   empty: (path: string) => ({ [path]: op("empty") }),
   has: (value: unknown) => op("has", value),
   contains: (value: unknown) => op("contains", value),
-  raw: (sql: string, params: unknown[] = []): DocumentQueryNode => ({ kind: "raw", sql, params }),
+  raw: (sql: string, params: unknown[] = []): DocumentQueryNode => built({ kind: "raw", sql, params }),
   
-  search: (text: string, options: DocumentSearchOptions = {}): DocumentQueryNode => ({
-    kind: "search",
-    text,
-    ...options,
-  }),
+  search: (text: string, options: DocumentSearchOptions = {}): DocumentQueryNode =>
+    built({
+      kind: "search",
+      text,
+      ...options,
+    }),
   when: (condition: unknown, query: DocumentQuery): DocumentQuery => (condition ? query : {}),
 });