akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/server/webRouter.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { getEnv } from "akanjs/base";
 import {
   type AkanI18nConfig,
@@ -20,6 +21,7 @@ import {
   RouteSeedIndexStore,
   RoutesManifestStore,
 } from "./artifact";
+import { resolveEncodedSidecar } from "./assetEncoding";
 import {
   getClientFacingOrigin,
   hasRouteCacheInvalidationScope,
@@ -51,7 +53,7 @@ import { type RscRedirectMethod, type RscRedirectStatus, type RscRenderResult, R
 import { createDefaultSitemapXml, getSitemapBasePath } from "./sitemap";
 import { SsrFromRscRenderer } from "./ssrFromRscRenderer";
 import type { RscTraceMetadata, SsrManifest } from "./ssrTypes";
-import { createSystemPageResponse, getSystemPageHomeHref } from "./systemPages";
+import { createSubRouteIndexResponse, createSystemPageResponse, getSystemPageHomeHref } from "./systemPages";
 import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types";
 
 const CLIENT_CLOSED_REQUEST_STATUS = 499;
@@ -60,6 +62,18 @@ export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
 const ROUTE_CACHE_SWEEP_INTERVAL_MS = 60_000;
 const APPLE_APP_SITE_ASSOCIATION_PATH = "/.well-known/apple-app-site-association";
 const ANDROID_ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
+const FIREBASE_MESSAGING_SW_PATH = "/firebase-messaging-sw.js";
+const FIREBASE_WEB_SDK_VERSION = "12.13.0";
+
+interface FirebaseClientEnvConfig {
+  apiKey: string;
+  authDomain?: string;
+  projectId: string;
+  storageBucket?: string;
+  messagingSenderId: string;
+  appId: string;
+  vapidKey?: string;
+}
 
 export function createRscRedirectResponse(
   location: string,
@@ -273,7 +287,13 @@ export class WebRouter {
   #subRoutes: Record<string, string[]>;
   #rsc: RscWorker;
   #hub: HmrWsHub | null = null;
-  #prodMode = process.env.NODE_ENV === "production";
+  /**
+   * `akan start` is the dev server whatever the environment claims. Its artifact directory carries no routes
+   * manifest — only `akan build` writes one — so the production branch cannot build a route on demand and
+   * throws on every request instead. `NODE_ENV` arrives by accident often enough (a workspace `.env` Bun loads
+   * on its own, a CI image default) that the command which started this process has to outrank it.
+   */
+  #prodMode = process.env.NODE_ENV === "production" && process.env.AKAN_COMMAND_TYPE !== "start";
   #builderRpc: BuilderRpc | null;
   #routeCache: RouteClientCache;
   #devHmr: DevHmrController | null = null;
@@ -297,10 +317,13 @@ export class WebRouter {
   #htmlCacheHits = 0;
   #htmlCacheMisses = 0;
   #htmlCacheBypass = 0;
+  #runtimeManifest: { revision: number; manifest: MergedManifest } | null = null;
   renderState: RenderState;
   #seedIndex: RouteSeedIndex;
   constructor({ artifact, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions) {
     this.#logger.verbose(`[SSR] loaded ${Object.keys(cssBytesByUrl).length} CSS assets`);
+    if (process.env.NODE_ENV === "production" && !this.#prodMode)
+      this.#logger.warn("[SSR] NODE_ENV=production ignored under `akan start`; serving in dev mode");
     this.#artifact = artifact;
     const { subRoutes, ignoredBasePaths } = resolveSubRouteHosts({
       subRoutes: artifact.subRoutes,
@@ -340,7 +363,7 @@ export class WebRouter {
     if (prebuilt) {
       this.#routeCache.seed(prebuilt);
       await this.#rsc.reload({
-        clientManifest: this.#mergeRuntimeManifest(this.#routeCache.merged).clientManifest,
+        clientManifest: this.#mergeRuntimeManifest().clientManifest,
         cssAssets: this.renderState.cssAssets,
         buildId: this.renderState.buildId,
       });
@@ -486,6 +509,16 @@ export class WebRouter {
         WebRouter.#deepLinkAssociationResponse(ANDROID_ASSET_LINKS_PATH, this.#artifact, {
           cacheControl: this.#prodMode ? "public, max-age=3600" : "no-store",
         }) ?? new Response("Not Found", { status: 404 }),
+      [FIREBASE_MESSAGING_SW_PATH]: async () => {
+        this.#requestStats.staticAsset += 1;
+        const firebaseConfig = await WebRouter.#resolveFirebaseClientConfig();
+        return new Response(WebRouter.#createFirebaseMessagingServiceWorker(firebaseConfig), {
+          headers: {
+            "Content-Type": "application/javascript; charset=utf-8",
+            "Cache-Control": "no-store",
+          },
+        });
+      },
       "/*": async (req) => {
         const url = new URL(req.url);
         if (WebRouter.#isImageOptimizerPath(url.pathname)) {
@@ -553,6 +586,9 @@ export class WebRouter {
           );
         }
 
+        const subRouteIndex = this.#localSubRouteIndexResponse(req, url);
+        if (subRouteIndex) return await subRouteIndex;
+
         try {
           this.#requestStats.fullSsr += 1;
           const manifest = await this.#ensureRoute(url);
@@ -813,15 +849,27 @@ export class WebRouter {
     this.#logger.verbose(
       `[route-cache] ensure pathname=${url.pathname} routeId=${matched?.entry.routeId ?? "(none)"} in ${Date.now() - started}ms`,
     );
-    return this.#mergeRuntimeManifest(this.#routeCache.snapshot());
+    return this.#mergeRuntimeManifest();
   }
 
-  #mergeRuntimeManifest(manifest: MergedManifest): MergedManifest {
-    return {
-      ...manifest,
-      clientManifest: WebRouter.#mergeClientManifest(this.#artifact.rscRuntimeClientManifest, manifest.clientManifest),
-      ssrManifest: WebRouter.#mergeSsrManifest(this.#artifact.rscRuntimeSsrManifest, manifest.ssrManifest),
+  /**
+   * Memoized on the route cache's revision. Both the snapshot and the runtime merge copy the whole client manifest
+   * and SSR module map, which is a few hundred KB of structure for a small app — and this ran on every request. In
+   * production the revision never moves after `seed`, so the manifest is built once; in dev a rebuild bumps it and
+   * the next request pays for one fresh copy. The cached object is still a copy, so an in-flight request keeps
+   * consuming a stable manifest across an invalidate exactly as the per-request snapshot made it.
+   */
+  #mergeRuntimeManifest(): MergedManifest {
+    const revision = this.#routeCache.revision;
+    if (this.#runtimeManifest?.revision === revision) return this.#runtimeManifest.manifest;
+    const snapshot = this.#routeCache.snapshot();
+    const manifest: MergedManifest = {
+      ...snapshot,
+      clientManifest: WebRouter.#mergeClientManifest(this.#artifact.rscRuntimeClientManifest, snapshot.clientManifest),
+      ssrManifest: WebRouter.#mergeSsrManifest(this.#artifact.rscRuntimeSsrManifest, snapshot.ssrManifest),
     };
+    this.#runtimeManifest = { revision, manifest };
+    return manifest;
   }
   #renderSystemNotFoundFallbackResponse(req: Request, url: URL): Promise<Response> {
     return createSystemPageResponse({
@@ -834,6 +882,29 @@ export class WebRouter {
     });
   }
 
+  /**
+   * A build with subRoutes must keep every route file under `page/<basePath>`, so the site root owns no page and
+   * answers 404 — including the URL `akan start` opens a browser on. Locally that reads as a broken app, so serve a
+   * picker of the basePaths this build carries instead. Deployed hosts never reach it: `HostBasePathWebProxy`
+   * rewrites the root onto the basePath its host maps to before the router sees it.
+   */
+  #localSubRouteIndexResponse(req: Request, url: URL): Promise<Response> | null {
+    if (process.env.AKAN_PUBLIC_ENV !== "local" || !this.#artifact.basePaths.length) return null;
+    if (!WebRouter.#isSiteRootPathname(url.pathname, this.#artifact.i18n)) return null;
+    return createSubRouteIndexResponse({
+      method: req.method,
+      locale: WebRouter.#getLocale(url.pathname, this.#artifact.i18n),
+      basePaths: this.#artifact.basePaths,
+      subRoutes: this.#subRoutes,
+    });
+  }
+
+  static #isSiteRootPathname(pathname: string, i18n: AkanI18nConfig): boolean {
+    const segments = pathname.split("/").filter(Boolean);
+    if (!segments.length) return true;
+    return segments.length === 1 && i18n.locales.includes(segments[0] ?? "");
+  }
+
   #renderErrorResponse(req: Request, scope: string, err: unknown): Promise<Response> {
     if (WebRouter.#isExpectedRequestAbort(err)) return Promise.resolve(WebRouter.#clientClosedResponse());
     const message = err instanceof Error ? err.message : String(err);
@@ -994,6 +1065,79 @@ export class WebRouter {
     return process.env.AKAN_APP_DIR ?? path.dirname(Bun.main);
   }
 
+  static async #resolveFirebaseClientConfig(): Promise<FirebaseClientEnvConfig | null> {
+    const envPath = path.join(WebRouter.#resolveAppDir(), "env", "env.client.ts");
+    if (!fs.existsSync(envPath)) return null;
+    try {
+      const envUrl = pathToFileURL(envPath);
+      envUrl.searchParams.set("t", String(Date.now()));
+      const envModule = (await import(envUrl.href)) as { env?: { firebase?: unknown } };
+      return WebRouter.#normalizeFirebaseClientConfig(envModule.env?.firebase);
+    } catch {
+      return null;
+    }
+  }
+
+  static #normalizeFirebaseClientConfig(config: unknown): FirebaseClientEnvConfig | null {
+    if (!config || typeof config !== "object") return null;
+    const value = config as Partial<Record<keyof FirebaseClientEnvConfig, unknown>>;
+    if (
+      typeof value.apiKey !== "string" ||
+      typeof value.projectId !== "string" ||
+      typeof value.messagingSenderId !== "string" ||
+      typeof value.appId !== "string"
+    ) {
+      return null;
+    }
+    return {
+      apiKey: value.apiKey,
+      ...(typeof value.authDomain === "string" ? { authDomain: value.authDomain } : {}),
+      projectId: value.projectId,
+      ...(typeof value.storageBucket === "string" ? { storageBucket: value.storageBucket } : {}),
+      messagingSenderId: value.messagingSenderId,
+      appId: value.appId,
+    };
+  }
+
+  static #createFirebaseMessagingServiceWorker(config: FirebaseClientEnvConfig | null): string {
+    const configJson = JSON.stringify(config);
+    return `/* Generated by Akan.js. Do not edit. */
+const firebaseConfig = ${configJson};
+
+if (firebaseConfig) {
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-app-compat.js");
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-messaging-compat.js");
+
+  firebase.initializeApp(firebaseConfig);
+  const messaging = firebase.messaging();
+
+  const notificationUrl = (payload) =>
+    payload?.data?.url || payload?.fcmOptions?.link || payload?.notification?.click_action;
+
+  messaging.onBackgroundMessage((payload) => {
+    const title = payload?.notification?.title || "";
+    const options = {
+      body: payload?.notification?.body,
+      icon: payload?.notification?.icon,
+      image: payload?.notification?.image,
+      data: {
+        url: notificationUrl(payload),
+        FCM_MSG: payload,
+      },
+    };
+    self.registration.showNotification(title, options);
+  });
+}
+
+self.addEventListener("notificationclick", (event) => {
+  const url = event.notification?.data?.url || event.notification?.data?.FCM_MSG?.data?.url;
+  event.notification?.close();
+  if (!url) return;
+  event.waitUntil(clients.openWindow(url));
+});
+`;
+  }
+
   static #normalizeArtifact(artifact: BaseBuildArtifact, artifactDir: string): BaseBuildArtifact {
     const normalizedArtifactDir = path.resolve(artifactDir);
     const pagesBundlePath = WebRouter.#resolveArtifactPath(artifact.pagesBundlePath, normalizedArtifactDir);
@@ -1101,16 +1245,12 @@ export class WebRouter {
     headers.set("Last-Modified", new Date(lastModifiedMs).toUTCString());
     if (WebRouter.#isNotModified(req, etag, lastModifiedMs)) return new Response(null, { status: 304, headers });
 
-    const gzipPath = `${filePath}.gz`;
-    if (WebRouter.#acceptsGzip(req) && WebRouter.#isCompressible(options.contentType)) {
-      const gzipFile = Bun.file(gzipPath);
-      if (await gzipFile.exists()) {
-        const gzipBytes = await gzipFile.bytes();
-        headers.set("Content-Encoding", "gzip");
-        headers.set("Content-Length", String(gzipBytes.byteLength));
-        headers.set("Vary", "Accept-Encoding");
-        return new Response(WebRouter.#toArrayBuffer(gzipBytes), { headers });
-      }
+    const sidecar = await resolveEncodedSidecar(req, filePath, options.contentType);
+    if (sidecar) {
+      headers.set("Content-Encoding", sidecar.encoding);
+      headers.set("Content-Length", String(sidecar.bytes.byteLength));
+      headers.set("Vary", "Accept-Encoding");
+      return new Response(sidecar.bytes, { headers });
     }
 
     return new Response(file.stream(), { headers });
@@ -1197,22 +1337,6 @@ export class WebRouter {
     return Number.isFinite(sinceMs) && sinceMs >= lastModifiedMs;
   }
 
-  static #acceptsGzip(req: Request): boolean {
-    const acceptEncoding = req.headers.get("accept-encoding") ?? "";
-    return /\bgzip\b/.test(acceptEncoding);
-  }
-
-  static #isCompressible(contentType: string): boolean {
-    const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
-    return (
-      type.startsWith("text/") ||
-      type === "application/javascript" ||
-      type === "application/json" ||
-      type === "application/manifest+json" ||
-      type === "image/svg+xml"
-    );
-  }
-
   static #safeResolve(baseDir: string, urlPath: string): string | null {
     let decoded: string;
     try {

package/service/agent.service.ts

@@ -0,0 +1,14 @@
+import { Err } from "akanjs/dictionary";
+import type { LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
+import { LlmAdaptorRole } from "./predefinedAdaptor/role.adaptor";
+import { serve } from "./serve";
+
+export class AgentService extends serve("agent" as const, ({ plug }) => ({
+  llm: plug(LlmAdaptorRole),
+})) {
+  async runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void) {
+    const answer = await this.llm.chat(request, onDelta);
+    if (!answer) throw new Err("agent.error.llmUnavailable");
+    return { text: answer.text ?? "", toolCalls: answer.toolCalls ?? [], stop: answer.stop };
+  }
+}

package/service/base.service.ts

@@ -1,4 +1,5 @@
 import type { Base } from "akanjs/signal";
+import { AgentService } from "./agent.service";
 import { serve } from "./serve";
 import { ServiceModel } from "./serviceModule";
 
@@ -11,4 +12,4 @@ export class BaseService extends serve("base" as const, ({ env, signal, memory }
   }
 }
 
-export const srv = { base: new ServiceModel(BaseService) };
+export const srv = { base: new ServiceModel(BaseService), agent: new ServiceModel(AgentService) };

package/service/index.ts

@@ -1,4 +1,5 @@
 export * from "./adapt";
+export * from "./agent.service";
 export * from "./base.service";
 export * from "./injectInfo";
 export * from "./injectInfo";

package/service/predefinedAdaptor/database.adaptor.ts

@@ -19,6 +19,7 @@ import {
   documentQueryHelper,
   encodeDocumentValue,
   isDocumentUpdateNode,
+  NoDocumentError,
   resolveDocumentUpdate,
   type SchemaOf,
   sanitizeJson,
@@ -98,6 +99,9 @@ export interface DocumentStore {
   removeManyByQuery(
     query: DocumentQuery,
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;
+  removeOneByQuery(
+    query: DocumentQuery,
+  ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number; upsertedId: string | null }>;
   bulkWrite(
     operations: { updateOne: { filter: DocumentQuery; update: DocumentUpdateInput; upsert?: boolean } }[],
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number; upsertedId: string | null }>;
@@ -116,7 +120,7 @@ export interface DocumentStore {
   exists(query?: DocumentQuery): Promise<string | null>;
   count(query?: DocumentQuery): Promise<number>;
   insight(query?: DocumentQuery): Promise<any>;
-  hydrate(data: DocumentRecord, originalData?: DocumentRecord): any;
+  hydrate(data: DocumentRecord, originalData?: DocumentRecord, options?: { track?: boolean }): any;
 }
 
 export interface SqlResultRows<Row = Record<string, unknown>> {
@@ -957,6 +961,17 @@ class UpdateCompiler {
   }
 }
 
+/**
+ * Per-document modification state, attached only when a document is hydrated for writing.
+ * Non-enumerable so `{ ...doc }` in `toRow` and `Object.entries` in `sanitizeJson` never see it.
+ */
+const MODIFICATION_STATE = Symbol("akan.document.modificationState");
+
+interface ModificationState {
+  isNew: boolean;
+  original: Record<string, unknown>;
+}
+
 export class SqlDocumentStore {
   readonly schema: DocumentSchema;
   readonly table: string;
@@ -964,6 +979,7 @@ export class SqlDocumentStore {
   readonly updateCompiler: UpdateCompiler;
   #insertStmt: AkanSqlStatement | null = null;
   #readStmtCache = new Map<string, AkanSqlStatement>();
+  #docPrototype: object | null = null;
 
   constructor(
     private readonly owner: DocumentDatabaseOwner,
@@ -1086,6 +1102,11 @@ export class SqlDocumentStore {
     return this.updateManyByQuery(query, { removedAt: dayjs() });
   }
 
+  async removeOneByQuery(query: DocumentQuery) {
+
+    return this.updateOneByQuery(query, { removedAt: dayjs() });
+  }
+
   private compiledUpdate(update: DocumentUpdate) {
     const compiled = this.updateCompiler.compile(update);
     return {
@@ -1125,14 +1146,14 @@ export class SqlDocumentStore {
       const rows = await this.prepareReadStmt(
         `SELECT ${this.projectionSql(projection)} FROM ${quoteIdent(this.table)}${join} WHERE ${where} ${order}${limit}${offset}`,
       ).all<ProjectedSqliteDocumentRow>(...args);
-      return rows.map((row) => this.hydrate(this.fromProjectedRow(row, projection)));
+      return rows.map((row) => this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }));
     }
 
     const star = joins.length ? `${quoteIdent(this.table)}.*` : "*";
     const rows = await this.prepareReadStmt(
       `SELECT ${star} FROM ${quoteIdent(this.table)}${join} WHERE ${where} ${order}${limit}${offset}`,
     ).all<SqliteDocumentRow>(...args);
-    return rows.map((row) => this.hydrate(this.fromRow(row)));
+    return rows.map((row) => this.hydrate(this.fromRow(row), undefined, { track: false }));
   }
 
   async findIds(
@@ -1162,13 +1183,13 @@ export class SqlDocumentStore {
 
   async pickOne(query?: DocumentQuery, options: FindOneOptions = {}) {
     const doc = await this.findOne(query, options);
-    if (!doc) throw new Error(`No Document (${this.table}): ${JSON.stringify(query)}`);
+    if (!doc) throw new NoDocumentError(`No Document (${this.table}): ${JSON.stringify(query)}`);
     return doc;
   }
 
   async pickById(id: string) {
     const doc = await this.findOne({ id } as DocumentQuery);
-    if (!doc) throw new Error(`No Document (${this.table}): ${id}`);
+    if (!doc) throw new NoDocumentError(`No Document (${this.table}): ${id}`);
     return doc;
   }
 
@@ -1450,7 +1471,7 @@ export class SqlDocumentStore {
 
   private async pickByIdForWrite(id: string) {
     const doc = await this.findOneForWrite({ id } as DocumentQuery);
-    if (!doc) throw new Error(`No Document (${this.table}): ${id}`);
+    if (!doc) throw new NoDocumentError(`No Document (${this.table}): ${id}`);
     return doc;
   }
 
@@ -1580,49 +1601,82 @@ export class SqlDocumentStore {
     return result;
   }
 
-  hydrate(data: DocumentRecord, originalData: DocumentRecord = data) {
-    const store = this;
-    const original = JSON.parse(JSON.stringify(sanitizeJson(originalData) ?? {})) as Record<string, unknown>;
+  /**
+   * `track` buys `isModified()` and costs a deep clone of the row, so it is decided per call site rather than
+   * paid everywhere. Only the read paths (`find`, and the projected read behind it) opt out — that clone was 42%
+   * of a list query, and a listed document is never the one a save hook runs on. Everything else keeps it, so an
+   * external caller of `hydrate` sees no change.
+   */
+  hydrate(data: DocumentRecord, originalData: DocumentRecord = data, { track = true }: { track?: boolean } = {}) {
     const isNew = !originalData.id;
     const hydratedData = isNew ? this.prepareDocument(data) : data;
-    const doc = Object.assign(Object.create(this.database.doc.prototype), hydratedData);
-    Object.defineProperties(doc, {
+    const doc = Object.assign(Object.create(this.#documentPrototype()), hydratedData);
+    if (!track) return doc;
+    Object.defineProperty(doc, MODIFICATION_STATE, {
+      value: {
+        isNew,
+
+        original: JSON.parse(JSON.stringify(sanitizeJson(originalData) ?? {})) as Record<string, unknown>,
+      } satisfies ModificationState,
+    });
+    return doc;
+  }
+
+  /**
+   * One prototype per store instead of six closures per document. It extends the model's own document prototype,
+   * so declared chain methods and `instanceof` are unaffected, and every method here is non-enumerable exactly as
+   * the previous per-document `defineProperties` made them.
+   */
+  #documentPrototype() {
+    if (this.#docPrototype) return this.#docPrototype;
+    const store = this;
+    this.#docPrototype = Object.create(this.database.doc.prototype, {
       set: {
-        value(patch: DocumentRecord) {
+        value(this: DocumentRecord, patch: DocumentRecord) {
           Object.assign(this, patch);
           return this;
         },
       },
       save: {
-        async value() {
-          return this.id ? store.update(this.id, this) : store.create(this);
+        async value(this: DocumentRecord) {
+          return this.id ? store.update(this.id as string, this) : store.create(this);
         },
       },
       refresh: {
-        async value() {
-          Object.assign(this, await store.pickById(this.id));
+        async value(this: DocumentRecord) {
+          Object.assign(this, await store.pickById(this.id as string));
           return this;
         },
       },
       isModified: {
-        value(field?: string) {
-          if (isNew) return true;
-          if (!field) return JSON.stringify(sanitizeJson(this)) !== JSON.stringify(original);
-          return JSON.stringify(sanitizeJson(this[field])) !== JSON.stringify(original[field]);
+        value(this: DocumentRecord & { [MODIFICATION_STATE]?: ModificationState }, field?: string) {
+          const state = this[MODIFICATION_STATE];
+          if (!state) throw new Error(SqlDocumentStore.#untrackedModificationMessage(store.table));
+          if (state.isNew) return true;
+          if (!field) return JSON.stringify(sanitizeJson(this)) !== JSON.stringify(state.original);
+          return JSON.stringify(sanitizeJson(this[field])) !== JSON.stringify(state.original[field]);
         },
       },
       toJSON: {
-        value() {
+        value(this: DocumentRecord) {
           return sanitizeJson(this);
         },
       },
       toObject: {
-        value() {
+        value(this: DocumentRecord) {
           return sanitizeJson(this);
         },
       },
-    });
-    return doc;
+    }) as object;
+    return this.#docPrototype;
+  }
+
+  static #untrackedModificationMessage(table: string) {
+    return (
+      `isModified() is unavailable on this ${table} document: it was loaded through a read query, which does not ` +
+      `snapshot the row. Call it inside a save hook, or re-load the document through the write path (\`save()\`, ` +
+      `\`update()\`) before comparing.`
+    );
   }
 
   private async runHooks(