akanjs 3.0.0-alpha.88 → 3.0.0-alpha.89

package/base/baseEnv.ts

@@ -59,6 +59,8 @@ export type ClientEnv = BaseEnv & {
   side: "server" | "client";
   renderMode: "ssr" | "csr";
   websocket: boolean;
+  apiPrefix: string;
+  wsPrefix: string;
   clientHost: string;
   clientPort: number;
   clientHttpProtocol: "http:" | "https:";
@@ -73,6 +75,43 @@ export type ClientEnv = BaseEnv & {
 
 let cachedEnv: ClientEnv | undefined;
 
+type RoutePrefixOverride = { api?: string; ws?: string };
+
+const globalWithPrefix = globalThis as typeof globalThis & { __AKAN_PREFIX__?: RoutePrefixOverride };
+
+/** Leading slash, no trailing slash. A blank value — or a bare `/`, which would swallow every page route — is no prefix at all and falls through to the next source. */
+export const normalizeRoutePrefix = (value: string | undefined | null): string | undefined => {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  const normalized = `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+  return normalized === "/" ? undefined : normalized;
+};
+
+/**
+ * Three sources, narrowest first. The global is what a server-rendered page's bootstrap script writes, so the
+ * browser follows the process that rendered it. `AKAN_API_PREFIX` is deliberately outside the `AKAN_PUBLIC_*`
+ * namespace: only that namespace is inlined into client bundles at build time, so a name inside it could never
+ * act as a runtime override. `AKAN_PUBLIC_API_PREFIX` is the build-time default, and the only one a prebuilt CSR
+ * or mobile bundle can read. Written out rather than looked up by key — a computed `process.env[...]` is opaque
+ * to the bundler's define pass, and the public value would stop being inlined.
+ */
+export const getApiPrefix = (): string =>
+  normalizeRoutePrefix(globalWithPrefix.__AKAN_PREFIX__?.api) ??
+  normalizeRoutePrefix(process.env.AKAN_API_PREFIX) ??
+  normalizeRoutePrefix(process.env.AKAN_PUBLIC_API_PREFIX) ??
+  "/api";
+
+export const getWsPrefix = (): string =>
+  normalizeRoutePrefix(globalWithPrefix.__AKAN_PREFIX__?.ws) ??
+  normalizeRoutePrefix(process.env.AKAN_WS_PREFIX) ??
+  normalizeRoutePrefix(process.env.AKAN_PUBLIC_WS_PREFIX) ??
+  "/ws";
+
+/** `AkanApp` rewrites `process.env` for the replica it runs in-process, after this module may already have cached. */
+export const resetEnvCache = () => {
+  cachedEnv = undefined;
+};
+
 const missingPublicEnv = (key: string) =>
   `getEnv() cannot run at build time: akan build does not inject ${key}. Call it from a runtime function instead of at module scope (e.g. env(() => getEnv()) in adapt(), a method body, or a default thunk).`;
 
@@ -141,7 +180,9 @@ export const getEnv = (): ClientEnv => {
         : side === "client"
           ? (window.location.protocol as "http:" | "https:")
           : ("http:" as const));
-  const serverHttpUri = `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}/api`;
+  const apiPrefix = getApiPrefix();
+  const wsPrefix = getWsPrefix();
+  const serverHttpUri = `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}${apiPrefix}`;
   const serverWsProtocol = serverHttpProtocol === "http:" ? "ws:" : "wss:";
   const serverWsUri = `${serverWsProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}`;
 
@@ -150,6 +191,8 @@ export const getEnv = (): ClientEnv => {
     side,
     renderMode,
     websocket: true,
+    apiPrefix,
+    wsPrefix,
     clientHost,
     clientPort,
     clientHttpProtocol,

package/constant/mask.ts

@@ -65,3 +65,30 @@ export const mask = (model: MaskModel, value: unknown): unknown => {
   }
   return masked;
 };
+
+/**
+ * Drops what a model marks `hidden` or `secret`, and nothing else.
+ *
+ * The sibling of `mask()` for the one caller that is not an AI read: a saved form draft. Two differences matter.
+ * It keeps `visual` — a rendered body is exactly the field a user spent twenty minutes on, and dropping it from a
+ * draft loses the work the draft exists to protect. And it is subtractive rather than reconstructive: `mask()`
+ * builds its result from the field metadata, so a key the metadata does not name — `id`, which is what decides
+ * whether a form creates or updates — would not survive the round trip.
+ *
+ * `for...in` rather than `Object.keys`, because a model instance keeps its Date fields as enumerable prototype
+ * accessors.
+ */
+export const stripSecrets = (model: MaskModel, value: unknown): unknown => {
+  if (value === null || value === undefined || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item: unknown) => stripSecrets(model, item));
+  const fields = maskFieldsOf(model);
+  if (!fields) return value;
+  const source = value as Record<string, unknown>;
+  const stripped: Record<string, unknown> = {};
+  for (const key in source) {
+    const field = fields[key];
+    if (field?.fieldType === "hidden" || field?.fieldType === "secret") continue;
+    stripped[key] = field?.isClass && field.modelRef ? stripSecrets(field.modelRef, source[key]) : source[key];
+  }
+  return stripped;
+};

package/dictionary/base.dictionary.ts

@@ -92,6 +92,11 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "{name}을(를) 더하면 메시지가 너무 커서 보낼 수 없습니다.",
     ],
     agentAnswerNeeded: ["Type an answer to the question above.", "위 질문에 대한 답을 입력하세요."],
+    agentQueue: ["Queue", "예약"],
+    agentQueuePlaceholder: ["Message to send after this turn...", "이 턴이 끝난 뒤 보낼 메시지..."],
+    agentQueued: ["Sends when this turn ends", "진행 중인 턴이 끝나면 전송됩니다"],
+    agentQueueEdit: ["Edit the queued message", "예약된 메시지 수정"],
+    agentQueueCancel: ["Cancel the queued message", "예약된 메시지 취소"],
     agentToolDone: ["Done", "완료"],
     agentToolFailed: ["Failed", "실패"],
     agentToolRunning: ["Running", "실행 중"],
@@ -111,8 +116,8 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       "이 화면에 대해 묻거나 할 일을 지시하세요. 커맨드:",
     ],
     agentHelpNote: [
-      "The agent asks before anything it should not decide alone, and Stop ends a running turn.",
-      "에이전트는 혼자 결정하면 안 되는 일을 하기 전에 물어보며, 중지는 진행 중인 턴을 끝냅니다.",
+      "The agent asks before anything it should not decide alone. Stop ends a running turn, and a message sent during one waits for the next.",
+      "에이전트는 혼자 결정하면 안 되는 일을 하기 전에 물어봅니다. 중지는 진행 중인 턴을 끝내고, 턴 중에 보낸 메시지는 다음 턴에 전송됩니다.",
     ],
     agentNothingToRetry: ["There is no message to send again.", "다시 보낼 메시지가 없습니다."],
     agentNothingToCompact: ["There is nothing to summarize yet.", "아직 요약할 대화가 없습니다."],
@@ -167,6 +172,11 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     exportCsv: ["Export CSV", "CSV 내보내기"],
     exportJson: ["Export JSON", "JSON 내보내기"],
     actions: ["Actions", "작업"],
+    draftConflict: ["You have unsaved changes from", "저장하지 않고 작성 중이던 내용이 있습니다 —"],
+    draftApplied: ["Continuing what you were writing", "이어서 작성 중입니다 —"],
+    draftRestore: ["Continue", "이어서 작성"],
+    draftDiscard: ["Discard", "삭제"],
+    draftStartOver: ["Start over", "새로 작성"],
     new: ["New", "신규"],
     edit: ["Edit", "수정"],
     save: ["Save", "저장"],

package/document/database.ts

@@ -137,8 +137,14 @@ type DatabaseModelWithQuerySort<
   __count(query: _QueryOfDoc): Promise<number>;
   __insight(query: _QueryOfDoc): Promise<Insight>;
   clone(data: _DataInput & { id: string }): Promise<Doc>;
-  listenPre: (type: SaveEventType, listener: (doc: Doc, type: CRUDEventType) => PromiseOrObject<void>) => () => void;
-  listenPost: (type: SaveEventType, listener: (doc: Doc, type: CRUDEventType) => PromiseOrObject<void>) => () => void;
+  listenPre: (
+    type: SaveEventType,
+    listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>,
+  ) => () => void;
+  listenPost: (
+    type: SaveEventType,
+    listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>,
+  ) => () => void;
 } & {
   [key in _CapitalizedRefName]: Mdl<Doc, Obj, _DocumentObj>;
 } & {

package/document/documentQuery.ts

@@ -40,6 +40,9 @@ export type DocumentQueryNode =
   | { kind: "raw"; sql: string; params: unknown[] }
   | ({ kind: "search"; text: string } & DocumentSearchOptions);
 
+/** The four real SQL columns. Everything else lives inside `_doc`, which is what makes the two compile differently. */
+export const baseDocumentColumns = new Set(["id", "createdAt", "updatedAt", "removedAt"]);
+
 export type DocumentQueryOperator =
   | "eq"
   | "ne"
@@ -56,6 +59,24 @@ export type DocumentQueryOperator =
   | "has"
   | "contains";
 
+/** The operator-object shorthand's keys: `{ status: { oneOf: [...] } }` reaches the same operators as `q.oneOf`. */
+export const queryOperatorKeys = new Set<string>([
+  "eq",
+  "ne",
+  "oneOf",
+  "notOneOf",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+  "exists",
+  "missing",
+  "empty",
+  "has",
+  "contains",
+]);
+
 export type DocumentQueryValue =
   | DocumentPrimitive
   | DocumentPrimitive[]

package/document/documentSchema.ts

@@ -20,10 +20,18 @@ export interface DocumentIndexBuilder<Schema> {
   done(): Schema;
 }
 
+/**
+ * `previous` is the document as it was before this write, and is absent on a create.
+ *
+ * A hook that has to answer "did this leave the set it was in" cannot do it from the new value alone — a soft
+ * delete and a field edit that moves a row out of a filter both look like an ordinary document afterwards. It is a
+ * trailing optional parameter, so a listener that ignores it is unaffected.
+ */
 export type DocumentSaveHook<Doc = unknown> = (
   this: Doc,
   next?: () => void,
   type?: CRUDEventType,
+  previous?: Doc,
 ) => PromiseOrObject<void>;
 
 export class DocumentSchema<Doc = unknown> {

package/document/index.ts

@@ -8,5 +8,6 @@ export * from "./filterMeta";
 export * from "./into";
 export * from "./loaderInfo";
 export * from "./noDocumentError";
+export * from "./queryEvaluator";
 export * from "./schema";
 export * from "./types";

package/document/into.ts

@@ -24,21 +24,21 @@ 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) => PromiseOrObject<void>>;
-  postSaveListenerSet: Set<(doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>>;
-  preCreateListenerSet: Set<(doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>>;
-  postCreateListenerSet: Set<(doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>>;
-  preUpdateListenerSet: Set<(doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>>;
-  postUpdateListenerSet: Set<(doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>>;
-  preRemoveListenerSet: Set<(doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>>;
-  postRemoveListenerSet: Set<(doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>>;
+  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) => PromiseOrObject<void>,
+    listener: (doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>,
   ) => () => void;
   listenPost: (
     eventType: SaveEventType,
-    listener: (doc: TDocument, type: CRUDEventType) => PromiseOrObject<void>,
+    listener: (doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>,
   ) => () => void;
 }
 export interface UpdateResult {

package/document/queryEvaluator.ts

@@ -0,0 +1,319 @@
+import {
+  baseDocumentColumns,
+  type DocumentQuery,
+  type DocumentQueryNode,
+  type DocumentQueryOperator,
+  encodeDocumentValue,
+  queryOperatorKeys,
+  sanitizeJson,
+} from "./documentQuery";
+
+/**
+ * A document as the database stores it: base columns as written, everything else inside one JSON payload.
+ *
+ * Membership is evaluated against this rather than against a hydrated model because that is what the SQL the
+ * evaluator has to agree with actually reads. A hydrated instance has already had defaults filled, dates turned
+ * back into `Dayjs`, and absent optional keys materialized as `undefined` — every one of which changes an answer.
+ */
+export interface DocumentRowView {
+  id: unknown;
+  createdAt: unknown;
+  updatedAt: unknown;
+  removedAt: unknown;
+  doc: Record<string, unknown>;
+}
+
+/** Only `isArray` is read; the shape matches the field metadata `QueryCompiler` holds. */
+export type QueryFieldMap = Record<string, { getProps?: () => Record<string, unknown> } & Record<string, unknown>>;
+
+interface PathValue {
+  /** `json_type(...) IS NOT NULL` — the key is in the stored JSON, whatever it holds. */
+  present: boolean;
+  /** What `json_extract(...)` yields: a SQL scalar, or JSON text for an object or array. */
+  value: unknown;
+  /** The value before `json_extract` flattening. `json_each` iterates this one. */
+  raw: unknown;
+}
+
+/**
+ * Answers "does this document match this query" in memory, reproducing what the SQL compiler would have asked the
+ * database. Live sync routes a change to the rooms whose query it belongs to, and asking the database once per room
+ * is not a thing that can be afforded on a write path.
+ *
+ * Every rule here mirrors a specific SQLite behaviour rather than a reasonable JavaScript reading of the same
+ * operator, because the only property that matters is agreeing with `QueryCompiler` — a disagreement shows up as a
+ * list that is quietly wrong, never as an error. `queryEvaluator.parity.test.ts` asks both and compares.
+ */
+export class DocumentQueryEvaluator {
+  readonly #fields: QueryFieldMap;
+
+  constructor(fields: QueryFieldMap = {}) {
+    this.#fields = fields;
+  }
+
+  /**
+   * Why this query cannot be evaluated in memory, or null when it can.
+   *
+   * Three things are genuinely out of reach. `raw` carries SQL only the database can run, and `search` compiles to
+   * an fts5 JOIN whose bm25 ranking has no in-memory equivalent. `exists`/`missing` on a `_doc` field ask whether
+   * the key is in the stored JSON at all, and a document read back has already had every declared nullable field
+   * materialized as `null` (`SqlDocumentStore.decodeDocumentPayload`) — so a value in hand cannot tell an absent
+   * key from a stored null, and answering anyway would be wrong for exactly the rows the operator exists to find.
+   * `empty` covers both cases and is evaluable, which is the operator the guide already directs callers to.
+   *
+   * Callers decide what to do about it — this reports, it does not throw, because refusing a boot is a policy the
+   * signal layer owns.
+   */
+  static unevaluableReason(query: DocumentQuery | undefined): string | null {
+    if (!query || typeof query !== "object") return null;
+    if (DocumentQueryEvaluator.#isNode(query)) {
+      if (query.kind === "raw") return "q.raw() carries SQL that only the database can run";
+      if (query.kind === "search") return "q.search() compiles to a full-text JOIN with no in-memory equivalent";
+      if (query.kind === "all" || query.kind === "any")
+        return query.queries.reduce<string | null>(
+          (found, sub) => found ?? DocumentQueryEvaluator.unevaluableReason(sub),
+          null,
+        );
+      if (query.kind === "not") return DocumentQueryEvaluator.unevaluableReason(query.query);
+      return null;
+    }
+    return Object.entries(query).reduce<string | null>(
+      (found, [path, value]) => found ?? DocumentQueryEvaluator.#unevaluableField(path, value),
+      null,
+    );
+  }
+
+  static #unevaluableField(path: string, value: unknown): string | null {
+    if (!value || typeof value !== "object") return null;
+    if (baseDocumentColumns.has(path)) return null;
+    const keyAbsence = `${path}: exists/missing asks whether the key is in the stored JSON, which a document in hand cannot answer — use q.empty()`;
+    if (DocumentQueryEvaluator.#isNode(value)) {
+      if (value.kind === "op") return value.op === "exists" || value.op === "missing" ? keyAbsence : null;
+      return DocumentQueryEvaluator.unevaluableReason(value as DocumentQuery);
+    }
+    const operators = value as Record<string, unknown>;
+    
+    if ("exists" in operators || "missing" in operators || ("empty" in operators && !operators.empty))
+      return keyAbsence;
+    return DocumentQueryEvaluator.unevaluableReason(value as DocumentQuery);
+  }
+
+  /** Splits a saved document into the row shape above, mirroring `SqlDocumentStore.toRow`. */
+  static rowViewOf(doc: Record<string, unknown>): DocumentRowView {
+    const payload = { ...doc };
+    delete payload.id;
+    delete payload.createdAt;
+    delete payload.updatedAt;
+    delete payload.removedAt;
+    return {
+      id: doc.id ?? null,
+      createdAt: doc.createdAt === undefined ? null : Number(encodeDocumentValue(doc.createdAt)),
+      updatedAt: doc.updatedAt === undefined ? null : Number(encodeDocumentValue(doc.updatedAt)),
+      removedAt: doc.removedAt ? Number(encodeDocumentValue(doc.removedAt)) : null,
+      doc: (sanitizeJson(payload) ?? {}) as Record<string, unknown>,
+    };
+  }
+
+  evaluate(query: DocumentQuery | undefined, row: DocumentRowView): boolean {
+    if (!query || typeof query !== "object") return true;
+    if (DocumentQueryEvaluator.#isNode(query)) return this.#node(query, row);
+    const entries = Object.entries(query);
+    if (!entries.length) return true;
+    return entries.every(([path, value]) => this.#field(path, value, row));
+  }
+
+  #node(node: DocumentQueryNode, row: DocumentRowView): boolean {
+    switch (node.kind) {
+      
+      case "all":
+        return !node.queries.length || node.queries.every((sub) => this.evaluate(sub, row));
+      case "any":
+        return !node.queries.length || node.queries.some((sub) => this.evaluate(sub, row));
+      case "not":
+        return !this.evaluate(node.query, row);
+      case "raw":
+      case "search":
+        throw new Error(`Query cannot be evaluated in memory: ${DocumentQueryEvaluator.unevaluableReason(node)}`);
+      case "op":
+        throw new Error("Operator nodes must be attached to a document path");
+    }
+  }
+
+  #field(path: string, value: unknown, row: DocumentRowView): boolean {
+    if (DocumentQueryEvaluator.#isNode(value)) {
+      if (value.kind !== "op") return this.evaluate({ [path]: value } as DocumentQuery, row);
+      return this.#operator(path, value.op, value.value, row);
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const operators = value as Record<string, unknown>;
+      const keys = Object.keys(operators);
+      if (keys.some((key) => queryOperatorKeys.has(key))) {
+        return keys
+          .filter((key) => queryOperatorKeys.has(key))
+          .every((key) => {
+            
+            if (key === "exists") return this.#operator(path, operators.exists ? "exists" : "missing", undefined, row);
+            if (key === "missing")
+              return this.#operator(path, operators.missing ? "missing" : "exists", undefined, row);
+            if (key === "empty") return this.#operator(path, operators.empty ? "empty" : "exists", undefined, row);
+            return this.#operator(path, key as DocumentQueryOperator, operators[key], row);
+          });
+      }
+    }
+    
+    if (this.#isArrayField(path) && !Array.isArray(value)) return this.#operator(path, "has", value, row);
+    return this.#operator(path, "eq", value, row);
+  }
+
+  #operator(path: string, op: DocumentQueryOperator, operand: unknown, row: DocumentRowView): boolean {
+    const isBase = baseDocumentColumns.has(path);
+    const read = this.#read(path, row);
+    switch (op) {
+      case "eq":
+        return operand === null ? read.value === null : DocumentQueryEvaluator.#equals(read.value, operand);
+      case "ne":
+        
+        if (operand === null) return read.value !== null;
+        return read.value !== null && !DocumentQueryEvaluator.#equals(read.value, operand);
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        const order = DocumentQueryEvaluator.#compare(read.value, DocumentQueryEvaluator.#encode(operand));
+        if (order === null) return false;
+        return op === "gt" ? order > 0 : op === "gte" ? order >= 0 : op === "lt" ? order < 0 : order <= 0;
+      }
+      case "between": {
+        const [from, to] = (operand as [unknown, unknown]) ?? [];
+        const low = DocumentQueryEvaluator.#compare(read.value, DocumentQueryEvaluator.#encode(from));
+        const high = DocumentQueryEvaluator.#compare(read.value, DocumentQueryEvaluator.#encode(to));
+        return low !== null && high !== null && low >= 0 && high <= 0;
+      }
+      case "oneOf": {
+        const values = (operand as unknown[]) ?? [];
+        if (!values.length) return false;
+        if (this.#isArrayField(path)) return values.some((item) => this.#has(read, item));
+        return read.value !== null && values.some((item) => DocumentQueryEvaluator.#equals(read.value, item));
+      }
+      case "notOneOf": {
+        const values = (operand as unknown[]) ?? [];
+        if (!values.length) return true;
+        if (this.#isArrayField(path)) return !values.some((item) => this.#has(read, item));
+        return read.value !== null && !values.some((item) => DocumentQueryEvaluator.#equals(read.value, item));
+      }
+      case "exists":
+      case "missing": {
+
+        if (!isBase)
+          throw new Error(
+            `Query cannot be evaluated in memory: ${DocumentQueryEvaluator.#unevaluableField(path, { kind: "op", op })}`,
+          );
+        return op === "exists" ? read.value !== null : read.value === null;
+      }
+      case "empty":
+        
+        return isBase ? read.value === null : !read.present || read.value === null;
+      case "has":
+        return this.#has(read, operand);
+      case "contains":
+        
+        return read.value !== null && String(read.value).toLowerCase().includes(String(operand).toLowerCase());
+    }
+  }
+
+  /** `EXISTS (SELECT 1 FROM json_each(<extract>) WHERE value = ?)` — an object iterates its values, a scalar itself. */
+  #has(read: PathValue, operand: unknown): boolean {
+    const { raw } = read;
+    if (raw === null || raw === undefined) return false;
+    const items = Array.isArray(raw)
+      ? raw
+      : typeof raw === "object"
+        ? Object.values(raw as Record<string, unknown>)
+        : [raw];
+    return items.some((item) => DocumentQueryEvaluator.#equals(DocumentQueryEvaluator.#extract(item), operand));
+  }
+
+  #read(path: string, row: DocumentRowView): PathValue {
+    if (baseDocumentColumns.has(path)) {
+      const value = (row as unknown as Record<string, unknown>)[path] ?? null;
+      return { present: value !== null, value, raw: value };
+    }
+    let current: unknown = row.doc;
+    for (const segment of path.split(".")) {
+
+      if (current === null || current === undefined || typeof current !== "object" || Array.isArray(current))
+        return { present: false, value: null, raw: undefined };
+      if (!(segment in (current as Record<string, unknown>))) return { present: false, value: null, raw: undefined };
+      current = (current as Record<string, unknown>)[segment];
+    }
+    if (current === undefined) return { present: false, value: null, raw: undefined };
+    return { present: true, value: DocumentQueryEvaluator.#extract(current), raw: current };
+  }
+
+  #isArrayField(path: string): boolean {
+    const field = this.#fields[path.split(".")[0]];
+    const props = field?.getProps?.() ?? field;
+    return !!props?.isArray;
+  }
+
+  /** What `json_extract` yields for a stored value: booleans collapse to 1/0, containers come back as JSON text. */
+  static #extract(value: unknown): unknown {
+    if (value === undefined || value === null) return null;
+    if (typeof value === "boolean") return value ? 1 : 0;
+    if (typeof value === "object") return JSON.stringify(value);
+    return value;
+  }
+
+  /** A query operand as the compiler binds it — dates to epoch ms, containers to JSON text. */
+  static #encode(operand: unknown): unknown {
+    const encoded = encodeDocumentValue(operand);
+    if (typeof encoded === "boolean") return encoded ? 1 : 0;
+    if (encoded === undefined) return null;
+    return encoded;
+  }
+
+  static #equals(value: unknown, operand: unknown): boolean {
+    return DocumentQueryEvaluator.#compare(value, DocumentQueryEvaluator.#encode(operand)) === 0;
+  }
+
+  /**
+   * SQLite's ordering: NULL sorts below every number, which sorts below every text. Comparing across those classes
+   * is never equal, so a query on a field holding the wrong type matches nothing rather than coercing its way to a
+   * match the way JavaScript's `<` would.
+   */
+  static #compare(left: unknown, right: unknown): number | null {
+    const leftClass = DocumentQueryEvaluator.#classOf(left);
+    const rightClass = DocumentQueryEvaluator.#classOf(right);
+    if (leftClass === 0 || rightClass === 0) return null;
+    if (leftClass !== rightClass) return leftClass < rightClass ? -1 : 1;
+    if (leftClass === 1) return Number(left) === Number(right) ? 0 : Number(left) < Number(right) ? -1 : 1;
+    return DocumentQueryEvaluator.#compareText(String(left), String(right));
+  }
+
+  static #classOf(value: unknown): 0 | 1 | 2 {
+    if (value === null || value === undefined) return 0;
+    if (typeof value === "number" || typeof value === "bigint") return 1;
+    if (typeof value === "boolean") return 1;
+    return 2;
+  }
+
+  /**
+   * By code point, which is exactly UTF-8 byte order and therefore SQLite's BINARY collation. JavaScript's own `<`
+   * compares UTF-16 code units, which puts supplementary-plane characters below U+E000 instead of above it.
+   */
+  static #compareText(left: string, right: string): number {
+    const leftPoints = [...left];
+    const rightPoints = [...right];
+    const shared = Math.min(leftPoints.length, rightPoints.length);
+    for (let idx = 0; idx < shared; idx += 1) {
+      const a = leftPoints[idx].codePointAt(0) ?? 0;
+      const b = rightPoints[idx].codePointAt(0) ?? 0;
+      if (a !== b) return a < b ? -1 : 1;
+    }
+    return leftPoints.length === rightPoints.length ? 0 : leftPoints.length < rightPoints.length ? -1 : 1;
+  }
+
+  static #isNode(value: unknown): value is DocumentQueryNode {
+    return !!value && typeof value === "object" && "kind" in value;
+  }
+}

package/fetch/client/fetchClient.ts

@@ -1,4 +1,4 @@
-import { getEnv, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
+import { getEnv, getWsPrefix, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
 import {
   capitalize,
   type FetchPolicy,
@@ -90,6 +90,8 @@ export class FetchClient {
   readonly handler: Record<string, FetchHandler>;
   readonly slice: Record<string, SliceMeta> = {};
   readonly sortKeyMap = new Map<string, string[]>();
+  /** refName → sort key → the field map that key orders by. Read by live insertion, which has to place a row. */
+  readonly sortValueMap = new Map<string, { [key: string]: { [path: string]: 1 | -1 } }>();
   readonly filterQueryMap = new Map<string, { [queryKey: string]: SerializedArg[] }>();
   readonly #originWs = new Map<string, WsClient>();
   readonly #handlerStore: Record<string, FetchHandler> = {};
@@ -154,6 +156,7 @@ export class FetchClient {
               ? {
                   filter: { ...current.filter?.filter, ...signal.filter?.filter },
                   sortKeys: [...new Set([...(current.filter?.sortKeys ?? []), ...(signal.filter?.sortKeys ?? [])])],
+                  sorts: { ...current.filter?.sorts, ...signal.filter?.sorts },
                 }
               : undefined,
           getGuards: signal.getGuards ?? current.getGuards,
@@ -190,7 +193,7 @@ export class FetchClient {
       if (signal.filter) {
 
         const filter = this.serializedSignal[refName]?.filter ?? signal.filter;
-        this.#registerFilterSortKey(refName, filter.sortKeys);
+        this.#registerFilterSortKey(refName, filter.sortKeys, filter.sorts);
         this.#registerFilterQuery(refName, filter.filter);
       }
     }
@@ -286,8 +289,9 @@ export class FetchClient {
     }
     return this.jwt ? { Authorization: `Bearer ${this.jwt}` } : {};
   }
-  #registerFilterSortKey(refName: string, sortKeys: string[]) {
+  #registerFilterSortKey(refName: string, sortKeys: string[], sorts?: { [key: string]: { [path: string]: 1 | -1 } }) {
     this.sortKeyMap.set(refName, sortKeys);
+    if (sorts) this.sortValueMap.set(refName, sorts);
   }
   #registerFilterQuery(refName: string, filter: { [queryKey: string]: SerializedArg[] }) {
     this.filterQueryMap.set(refName, filter);
@@ -413,7 +417,7 @@ export class FetchClient {
     }
   }
   static #makeWsUri(origin: string) {
-    return `${origin.replace("http://", "ws://").replace("https://", "wss://")}/ws`;
+    return `${origin.replace("http://", "ws://").replace("https://", "wss://")}${getWsPrefix()}`;
   }
 
   static paginationArgs: SerializedArg[] = [