akanjs 3.0.0 → 3.0.2-rc.0

package/server/rscWorker.tsx

@@ -17,6 +17,7 @@ import {
   pushRequestFallback,
   requestStorage,
   setRequestFrameState,
+  setRequestTheme,
   untrackedCookies,
   untrackedRequest,
   updateRequestPolicy,
@@ -36,12 +37,7 @@ import {
   resolveRouteCacheStoreTtl,
   shouldStoreRouteCache,
 } from "./cachePolicy";
-import {
-  createAkanLocaleAlternateHeadSnapshot,
-  mergeAkanHeadSnapshots,
-  renderAkanHeadSnapshot,
-  shouldRenderLocaleAlternates,
-} from "./head";
+import { createAkanLocaleAlternateHeadSnapshot, mergeAkanHeadSnapshots, renderAkanHeadSnapshot } from "./head";
 import { LogForwarder } from "./logging/logForwarder";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { RouteElementComposer } from "./routeElementComposer";
@@ -1223,7 +1219,7 @@ export class RscRenderer {
             searchParams,
           })
         : { node: undefined };
-    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead, {});
+    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead);
     return (
       <html lang={params.lang ?? getPathnameLocale(pathname, this.#i18n)} suppressHydrationWarning>
         <head key="head">
@@ -1254,14 +1250,16 @@ export class RscRenderer {
       basePath: this.#getBasePath(url),
     });
     setRequestFrameState(pathRoute.pageState);
+    
+    const rootThemes = await Promise.all(pathRoute.renderRootLayouts.map((render) => render.getLayoutTheme?.()));
+    const rootTheme = rootThemes.find((theme) => theme !== undefined);
+    if (rootTheme) setRequestTheme(rootTheme);
     const routeHead = await RouteElementComposer.resolveHeadWithSnapshot({
       pathRoute,
       params: match.params,
       searchParams,
     });
-    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead, {
-      isSpecialRoute: pathRoute.isSpecialRoute,
-    });
+    const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead);
     const body = RouteElementComposer.compose({
       pathRoute,
       params: match.params,
@@ -1277,9 +1275,7 @@ export class RscRenderer {
           {routeHeadSnapshot
             ? renderAkanHeadSnapshot(routeHeadSnapshot)
             : (routeHead.node ?? this.#renderDefaultHead())}
-          {!routeHeadSnapshot && shouldRenderLocaleAlternates({ isSpecialRoute: pathRoute.isSpecialRoute })
-            ? this.#renderLocaleAlternates(url)
-            : null}
+          {routeHeadSnapshot ? null : this.#renderLocaleAlternates(url)}
           {this.#renderStylesheet(url.pathname)}
         </head>
         <body key="body">{body}</body>
@@ -1370,22 +1366,14 @@ export class RscRenderer {
       params: match.params,
       searchParams,
     });
-    return this.#createRouteHeadSnapshot(url, routeHead, {
-      isSpecialRoute: match.pathRoute.isSpecialRoute,
-    });
+    return this.#createRouteHeadSnapshot(url, routeHead);
   }
 
-  #createRouteHeadSnapshot(
-    url: URL,
-    routeHead: ResolvedHead,
-    options: { isSpecialRoute?: boolean },
-  ): ResolvedHead["headSnapshot"] {
+  #createRouteHeadSnapshot(url: URL, routeHead: ResolvedHead): ResolvedHead["headSnapshot"] {
     if (!routeHead.headSnapshot) return undefined;
     return mergeAkanHeadSnapshots(
       routeHead.headSnapshot,
-      shouldRenderLocaleAlternates(options)
-        ? createAkanLocaleAlternateHeadSnapshot(this.#getLocaleAlternateLanguages(url))
-        : undefined,
+      createAkanLocaleAlternateHeadSnapshot(this.#getLocaleAlternateLanguages(url)),
     );
   }
 

package/server/rscWorkerHost.ts

@@ -452,13 +452,13 @@ export class RscWorker {
 
   renderWithMeta(
     req: Request,
-    options: { clientManifest?: ClientManifest; signal?: AbortSignal } = {},
+    options: { clientManifest?: ClientManifest; signal?: AbortSignal; clientIp?: string | null } = {},
   ): Promise<RscRenderResult> {
     const requestId = crypto.randomUUID();
     return createRscHostRenderStream({
       setPending: (pending) => this.#pending.set(requestId, pending),
       deletePending: () => this.#pending.delete(requestId),
-      sendRenderOrQueue: () => this.#sendRenderOrQueue(requestId, req, options.clientManifest),
+      sendRenderOrQueue: () => this.#sendRenderOrQueue(requestId, req, options.clientManifest, options.clientIp),
       cancelRender: () => this.#cancelRender(requestId),
       signal: options.signal,
       onPendingChunkOverflow: () => {
@@ -851,14 +851,23 @@ export class RscWorker {
     this.#pending.delete(requestId);
   }
 
-  #sendRenderOrQueue(requestId: string, req: Request, clientManifest?: ClientManifest): void {
+  /** The page request's headers as the worker sees them, `x-real-ip` being only the address the host resolved. */
+  static workerHeaders(req: Request, clientIp: string | null | undefined): Record<string, string> {
+    const headers: Record<string, string> = {};
+    req.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    
+    delete headers["x-real-ip"];
+    if (clientIp) headers["x-real-ip"] = clientIp;
+    return headers;
+  }
+
+  #sendRenderOrQueue(requestId: string, req: Request, clientManifest?: ClientManifest, clientIp?: string | null): void {
     const send = () => {
       if (!this.#pending.has(requestId)) return;
       try {
-        const headers: Record<string, string> = {};
-        req.headers.forEach((value, key) => {
-          headers[key] = value;
-        });
+        const headers = RscWorker.workerHeaders(req, clientIp);
         this.#proc.send({ type: "render", requestId, url: req.url, method: req.method, headers, clientManifest });
       } catch (err) {
         this.#resolvePending(requestId, (p) =>

package/server/ssrFromRscRenderer.tsx

@@ -9,7 +9,7 @@ import { renderToReadableStream } from "react-dom/server.browser";
 import { createFromNodeStream } from "react-server-dom-webpack/client.node";
 import { parsePositiveInt } from "./cachePolicy";
 import { concatBytes } from "./rscHttp";
-import type { SsrChunkRegistryStats, SsrFromRscInput, SsrLateRedirect } from "./ssrTypes";
+import type { SsrChunkRegistryStats, SsrDocumentOptions, SsrFromRscInput, SsrLateRedirect } from "./ssrTypes";
 
 const DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES = 1024;
 const DEFAULT_MAX_PENDING_INLINE_RSC_SCRIPTS = 32;
@@ -593,21 +593,13 @@ export class SsrFromRscRenderer {
     const base = `${SsrFromRscRenderer.#clientBootstrap}${SsrFromRscRenderer.#prefixBootstrap()}`;
     const bootstrap = input.extraBootstrapInline ? `${base}\n${input.extraBootstrapInline}` : base;
 
-    const waitForAllReady = input.waitForAllReady || process.env.AKAN_SSR_WAIT_FOR_ALL_READY === "1";
-    const renderHtml = async () => {
-      const root = await thenable;
-      const stream = await renderToReadableStream(root, {
-        bootstrapScriptContent: bootstrap,
-        onError: (error) => SsrFromRscRenderer.#reportRenderError(error, input),
+    const renderHtml = async () =>
+      await SsrFromRscRenderer.renderDocument(await thenable, {
+        bootstrap,
+        waitForAllReady: input.waitForAllReady || process.env.AKAN_SSR_WAIT_FOR_ALL_READY === "1",
+        inlineBoundaries: input.inlineBoundaries,
+        onError: (error, phase) => SsrFromRscRenderer.#reportRenderError(error, input, phase),
       });
-      if (waitForAllReady) await stream.allReady;
-      else {
-        SsrFromRscRenderer.holdPostShellErrors(stream, (error) =>
-          SsrFromRscRenderer.#reportRenderError(error, input, "post-shell"),
-        );
-      }
-      return stream;
-    };
     const requestContext = input.requestStore ?? input.request;
     const htmlStream =
       requestContext && requestStorage ? await requestStorage.run(requestContext, renderHtml) : await renderHtml();
@@ -661,6 +653,18 @@ export class SsrFromRscRenderer {
     };
   }
 
+  static async renderDocument(root: ReactNode, options: SsrDocumentOptions): Promise<ReadableStream<Uint8Array>> {
+    const stream = await renderToReadableStream(root, {
+      bootstrapScriptContent: options.bootstrap,
+      
+      ...(options.inlineBoundaries ? { progressiveChunkSize: Number.POSITIVE_INFINITY } : {}),
+      onError: (error) => options.onError(error),
+    });
+    if (options.waitForAllReady || options.inlineBoundaries) await stream.allReady;
+    else SsrFromRscRenderer.holdPostShellErrors(stream, (error) => options.onError(error, "post-shell"));
+    return stream;
+  }
+
   static holdPostShellErrors(stream: { allReady: Promise<void> }, report: (error: unknown) => void): void {
     void stream.allReady.catch(report);
   }

package/server/ssrTypes.ts

@@ -61,4 +61,13 @@ export interface SsrFromRscInput {
   onCancel?: (reason?: unknown) => void;
   /** Buffers until `stream.allReady` (`pageConfig.ssr: "block"`); `AKAN_SSR_WAIT_FOR_ALL_READY=1` forces it globally. */
   waitForAllReady?: boolean;
+  /** Buffers like `waitForAllReady` and writes every Suspense boundary in place, for a reader that runs no script. */
+  inlineBoundaries?: boolean;
+}
+
+export interface SsrDocumentOptions {
+  bootstrap: string;
+  waitForAllReady?: boolean;
+  inlineBoundaries?: boolean;
+  onError: (error: unknown, phase?: string) => void;
 }

package/server/webRouter.ts

@@ -13,6 +13,7 @@ import {
 import { type AkanRequestStore, createRequestStore, parseCookieHeader } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { PagePromptSource } from "../signal/mcp/pagePrompt";
+import { SignalContext } from "../signal/signalContext";
 import {
   type BuilderRpc,
   type MergedManifest,
@@ -36,6 +37,7 @@ import {
   shouldStoreRouteCache,
 } from "./cachePolicy";
 import { encodedFileResponse } from "./contentEncoding";
+import { isCrawlerUserAgent } from "./crawler";
 import { HMR_CLIENT_SCRIPT } from "./hmr/clientScript";
 import { CSR_DEV_ROUTE_PREFIX, resolveDevCsrMode, SSR_DEV_DIRNAME, SSR_DEV_ROUTE_PREFIX } from "./hmr/csrDevManifest";
 import { CsrDevShell } from "./hmr/csrDevShell";
@@ -501,6 +503,7 @@ export class WebRouter {
           const result = await this.#rsc.renderWithMeta(rscReq, {
             clientManifest: manifest.clientManifest,
             signal: req.signal,
+            clientIp: SignalContext.clientIpOf(req),
           });
           if (result.type === "redirect")
             return createRscRedirectResponse(result.location, result.method, result.status);
@@ -600,7 +603,8 @@ export class WebRouter {
         try {
           this.#requestStats.fullSsr += 1;
           const manifest = await this.#ensureRoute(url);
-          const htmlCacheDecision = this.#getHtmlCacheEntry(req, url);
+          const isCrawler = isCrawlerUserAgent(req.headers.get("user-agent"));
+          const htmlCacheDecision = this.#getHtmlCacheEntry(req, url, isCrawler);
           const htmlCacheEntry = htmlCacheDecision.entry;
           const cachedHtml = htmlCacheEntry ? this.#getCachedHtml(htmlCacheEntry.key) : null;
           if (cachedHtml) {
@@ -611,6 +615,7 @@ export class WebRouter {
           const rscResult = await this.#rsc.renderWithMeta(req, {
             clientManifest: manifest.clientManifest,
             signal: req.signal,
+            clientIp: SignalContext.clientIpOf(req),
           });
           if (rscResult.type === "redirect")
             return Response.redirect(new URL(rscResult.location, url.origin), rscResult.status);
@@ -643,6 +648,7 @@ export class WebRouter {
             },
             lateControl: rscResult.lateControl,
             waitForAllReady: rscResult.trace?.ssrBlocking ?? false,
+            inlineBoundaries: isCrawler,
             onCancel: (reason: unknown) => {
               rscResult.cancel(reason);
             },
@@ -814,7 +820,7 @@ export class WebRouter {
     }
   }
 
-  #getHtmlCacheEntry(req: Request, url: URL): { entry: RouteCacheEntry | null; reason?: string } {
+  #getHtmlCacheEntry(req: Request, url: URL, isCrawler: boolean): { entry: RouteCacheEntry | null; reason?: string } {
 
     if (this.#ssrDevShell) {
       this.#htmlCacheBypass += 1;
@@ -824,6 +830,7 @@ export class WebRouter {
       request: req,
       url,
       theme: WebRouter.#cookieValue(req, "theme"),
+      variant: isCrawler ? "crawler" : undefined,
       defaultEnabled: this.#prodMode,
       defaultAllow: this.#prodMode,
       env: {

package/service/index.ts

@@ -5,6 +5,7 @@ export * from "./injectInfo";
 export * from "./ipcTypes";
 export * from "./liveSyncHub";
 export * from "./predefinedAdaptor";
+export * from "./rateLimiter";
 export * from "./serve";
 export * from "./serviceModule";
 export * from "./serviceRegistry";

package/service/predefinedAdaptor/index.ts

@@ -10,6 +10,7 @@ export * from "./logging.adaptor";
 export * from "./openaiDialect";
 export * from "./openaiLlm";
 export * from "./queue.adaptor";
+export * from "./rateLimit.adaptor";
 export * from "./role.adaptor";
 export * from "./schedule.adaptor";
 export * from "./searchIndex";

package/service/predefinedAdaptor/rateLimit.adaptor.ts

@@ -0,0 +1,15 @@
+import { adapt } from "../adapt";
+import { type RateBudget, RateLimiter, type RateVerdict } from "../rateLimiter";
+import { CacheAdaptorRole } from "./role.adaptor";
+
+/** Counts a business key (a phone number, an email) across instances; unlike an endpoint's budget, no env turns it off. */
+export class RateLimit extends adapt("rateLimit", ({ plug }) => ({
+  cache: plug(CacheAdaptorRole),
+})) {
+  #limiter: RateLimiter | null = null;
+
+  async consume(key: string, budget: RateBudget): Promise<RateVerdict> {
+    this.#limiter ??= new RateLimiter(this.cache, { topic: "rateLimit" });
+    return await this.#limiter.consume(key, budget);
+  }
+}

package/service/predefinedAdaptor/sql/SqlDocumentStore.ts

@@ -1,11 +1,13 @@
 import { DEFAULT_VALUE, dayjs, FIELD_META } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import { type ConstantModel, freshPrimitiveValue, getDefault } from "akanjs/constant";
+import { Err } from "akanjs/dictionary";
 import {
   createDocumentId,
   type DatabaseModel,
   type DocumentQuery,
   type DocumentSchema,
+  type DocumentScopeOptions,
   type DocumentUpdate,
   type DocumentUpdateInput,
   type DocumentUpdateNode,
@@ -13,6 +15,7 @@ import {
   documentQueryHelper,
   isDocumentId,
   isDocumentUpdateNode,
+  LiveRowScope,
   NoDocumentError,
   resolveDocumentUpdate,
   sanitizeJson,
@@ -26,6 +29,7 @@ import {
   type DocumentDatabaseOwner,
   type DocumentRecord,
   type FieldMap,
+  type FindIdOptions,
   type FindManyOptions,
   type FindOneOptions,
   MODIFICATION_STATE,
@@ -59,6 +63,9 @@ interface DeclaredIndex {
   next: string;
   metaKey: string;
   hash: string;
+  fields: Record<string, unknown>;
+  /** A key ordered neither 1 nor -1, as MongoDB's `"text"`: no SQL index here stands for it. */
+  unbuilt: boolean;
   create: (name: string, concurrently: boolean) => string;
 }
 
@@ -79,6 +86,8 @@ export class SqlDocumentStore {
   static readonly #logger = new Logger("SqlDocumentStore");
   /** The row a document was read or last written as. */
   static readonly #storedRow = Symbol("akan.storedRow");
+  /** Set on a document read as removed, which only a `withRemoved` read hands out. */
+  static readonly #readRemoved = Symbol("akan.readRemoved");
 
   constructor(
     private readonly owner: DocumentDatabaseOwner,
@@ -102,7 +111,8 @@ export class SqlDocumentStore {
 
   async #ensure() {
     this.assertValidRefName(this.table);
-    const indexes = await this.#declaredIndexes();
+    const declared = await this.#declaredIndexes();
+    const indexes = declared.filter((index) => !index.unbuilt);
     const createSchema = async () => {
       const db = this.owner.getConnection();
       const existed = !!this.owner.buildIndexConcurrently && !!(await this.owner.hasTable?.(this.table));
@@ -121,6 +131,7 @@ export class SqlDocumentStore {
         `table:${this.table}`,
         await descriptorHash({ table: this.table, columns: ["id", "createdAt", "updatedAt", "removedAt", "_doc"] }),
       );
+      for (const index of declared) if (index.unbuilt) await this.#skipUnbuiltIndex(index, indexes);
       const concurrent: (DeclaredIndex & { replace: boolean })[] = [];
       for (const index of indexes) {
         const stored = await this.owner.getMeta(index.metaKey);
@@ -157,16 +168,21 @@ export class SqlDocumentStore {
         const declared = index.name ?? `${this.table}_${Object.keys(index.fields).map(toSafeRefName).join("_")}_${idx}`;
         this.assertValidRefName(declared);
         const name = this.dialect.indexName(declared);
-        const columns = Object.keys(index.fields).map((path) => ({
-          path,
-          expr: this.compiler.fieldExpr(path),
-          isArray: this.compiler.isArrayPath(path),
-        }));
+        const unbuilt = Object.values(index.fields).some((order) => order !== 1 && order !== -1);
+        const columns = unbuilt
+          ? []
+          : Object.keys(index.fields).map((path) => ({
+              path,
+              expr: this.compiler.fieldExpr(path),
+              isArray: this.compiler.isArrayPath(path),
+            }));
         return {
           name,
           next: this.dialect.indexName(`${declared}_next`),
           metaKey: `index:${this.table}:${name}`,
           hash: await descriptorHash(index),
+          fields: index.fields,
+          unbuilt,
           create: (target: string, concurrently: boolean) =>
             this.dialect.createIndex({
               name: target,
@@ -180,6 +196,23 @@ export class SqlDocumentStore {
     );
   }
 
+  async #skipUnbuiltIndex(index: DeclaredIndex, built: DeclaredIndex[]) {
+    const dropped =
+      (await this.owner.getMeta(index.metaKey)) === index.hash && !built.some(({ name }) => name === index.name);
+    if (dropped) {
+      await this.owner.getConnection().execute(`DROP INDEX IF EXISTS ${quoteIdent(index.name)}`);
+      
+      await this.owner.setMeta(index.metaKey, "");
+    }
+    const paths = Object.keys(index.fields);
+    SqlDocumentStore.#logger.warn(
+      `Index ${JSON.stringify(index.fields)} on ${this.table} is not built: only 1 and -1 order a key, and "text" is ` +
+        `MongoDB's text index, which as a B-tree would copy each whole value and fail long writes on Postgres. Search ` +
+        `${paths.join(", ")} through the full-text role, field(String, { text: "desc" }), or declare ` +
+        `{ ${paths[0]}: 1 } to look it up by equality.${dropped ? ` Dropped ${index.name}, which an earlier boot built from it.` : ""}`,
+    );
+  }
+
   async #replaceIndex(index: DeclaredIndex) {
     const rebuild = async () => {
       const db = this.owner.getConnection();
@@ -263,9 +296,22 @@ export class SqlDocumentStore {
   }
 
   async updateOneByQuery(query: DocumentQuery, update: DocumentUpdateInput, options: DocumentUpdateOptions = {}) {
+    if (options.upsert && options.withRemoved)
+      throw new Error(
+        `updateOneByQuery on "${this.table}" takes upsert or { withRemoved: true }, not both: a match would stay removed while a miss inserts a live row`,
+      );
+    return await this.#updateOne(query, update, options, "updateOneByQuery");
+  }
+
+  async #updateOne(
+    query: DocumentQuery,
+    update: DocumentUpdateInput,
+    options: DocumentUpdateOptions,
+    operation: string,
+  ) {
     const resolved = resolveDocumentUpdate(update);
     const { assignments, params } = this.compiledUpdate(resolved);
-    const { where, params: whereParams } = this.writeQuery(query, "updateOneByQuery");
+    const { where, params: whereParams } = this.writeQuery(query, operation, options);
     const subquery = `SELECT ${quoteIdent("id")} FROM ${quoteIdent(this.table)} WHERE ${where} ORDER BY ${this.compiler.orderBy()} LIMIT 1`;
     const sql = `UPDATE ${quoteIdent(this.table)} SET ${assignments.join(", ")} WHERE ${quoteIdent("id")} IN (${subquery})`;
     const changes = this.dialect.affectedRows(
@@ -282,9 +328,18 @@ export class SqlDocumentStore {
     return { acknowledged: true, matchedCount: 0, modifiedCount: 1, upsertedId: inserted.id };
   }
 
-  async updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput) {
+  async updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput, options: DocumentScopeOptions = {}) {
+    return await this.#updateMany(query, update, options, "updateManyByQuery");
+  }
+
+  async #updateMany(
+    query: DocumentQuery,
+    update: DocumentUpdateInput,
+    options: DocumentScopeOptions,
+    operation: string,
+  ) {
     const { assignments, params } = this.compiledUpdate(resolveDocumentUpdate(update));
-    const { where, params: whereParams } = this.writeQuery(query, "updateManyByQuery");
+    const { where, params: whereParams } = this.writeQuery(query, operation, options);
     const sql = `UPDATE ${quoteIdent(this.table)} SET ${assignments.join(", ")} WHERE ${where}`;
     const changes = this.dialect.affectedRows(
       await this.owner
@@ -297,12 +352,12 @@ export class SqlDocumentStore {
 
   async removeManyByQuery(query: DocumentQuery) {
     
-    return this.updateManyByQuery(query, { removedAt: dayjs() });
+    return await this.#updateMany(query, { removedAt: dayjs() }, {}, "removeManyByQuery");
   }
 
   async removeOneByQuery(query: DocumentQuery) {
     
-    return this.updateOneByQuery(query, { removedAt: dayjs() });
+    return await this.#updateOne(query, { removedAt: dayjs() }, {}, "removeOneByQuery");
   }
 
   private compiledUpdate(update: DocumentUpdate) {
@@ -339,20 +394,24 @@ export class SqlDocumentStore {
       const rows = await this.prepareStmt(
         `SELECT ${this.projectionSql(projection)} ${tail}`,
       ).all<ProjectedSqliteDocumentRow>(...args);
-      return rows.map((row) => this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }));
+      return rows.map((row) =>
+        this.#readAs(this.hydrate(this.fromProjectedRow(row, projection), undefined, { track: false }), row),
+      );
     }
     const rows = await this.prepareStmt(`SELECT ${star} ${tail}`).all<SqliteDocumentRow>(...args);
-    return rows.map((row) => this.#withStoredRow(this.hydrate(this.fromRow(row), undefined, { track: false }), row));
+    return rows.map((row) =>
+      this.#readAs(this.#withStoredRow(this.hydrate(this.fromRow(row), undefined, { track: false }), row), row),
+    );
   }
 
   async findIds(query?: DocumentQuery, options: Omit<FindManyOptions, "select"> = {}) {
-    const { tail, args } = this.listQuery(query, options);
+    const { tail, args } = this.listQuery(query, options, "findIds");
     const rows = await this.prepareStmt(`SELECT ${quoteIdent(this.table)}."id" ${tail}`).all<{ id: string }>(...args);
     return rows.map((row) => row.id);
   }
 
-  private listQuery(query: DocumentQuery | undefined, options: FindManyOptions) {
-    const { where, params, joins } = this.safeQuery(query);
+  private listQuery(query: DocumentQuery | undefined, options: FindManyOptions, operation = "find") {
+    const { where, params, joins } = this.safeQuery(query, operation, options);
     const limitValue = Number(options.limit ?? 0);
     const skipValue = Number(options.skip ?? 0);
     const order = options.sample ? "ORDER BY random()" : `ORDER BY ${this.orderBy(options.sort, joins)}`;
@@ -369,7 +428,7 @@ export class SqlDocumentStore {
     return (await this.find(query, { ...options, limit: 1, sample: options.sample ? 1 : undefined })).at(0) ?? null;
   }
 
-  async findId(query?: DocumentQuery, options: { sort?: SortOption; skip?: number | null; sample?: boolean } = {}) {
+  async findId(query?: DocumentQuery, options: FindIdOptions = {}) {
     return (await this.findIds(query, { ...options, limit: 1, sample: options.sample ? 1 : undefined })).at(0) ?? null;
   }
 
@@ -385,12 +444,12 @@ export class SqlDocumentStore {
     return doc;
   }
 
-  async exists(query?: DocumentQuery) {
-    return this.findId(query);
+  async exists(query?: DocumentQuery, options: DocumentScopeOptions = {}) {
+    return this.findId(query, options);
   }
 
-  async count(query?: DocumentQuery) {
-    const { where, params, joins } = this.safeQuery(query);
+  async count(query?: DocumentQuery, options: DocumentScopeOptions = {}) {
+    const { where, params, joins } = this.safeQuery(query, "count", options);
     const row = await this.prepareStmt(
       `SELECT count(*) as count FROM ${quoteIdent(this.table)}${this.joinSql(joins)} WHERE ${where}`,
     ).get<{ count: number }>(...this.joinParams(joins), ...params);
@@ -416,12 +475,27 @@ export class SqlDocumentStore {
     return result;
   }
 
-  private safeQuery(query?: DocumentQuery) {
+  private safeQuery(
+    query: DocumentQuery | undefined,
+    operation: string,
+    { withRemoved = false }: DocumentScopeOptions,
+  ) {
+    if (withRemoved) {
+      const compiled = this.compiler.compile(query ?? {});
+      
+      if (compiled.joins.length) throw new Error(`q.search() cannot see removed rows on "${this.table}"`);
+      return compiled;
+    }
+    const conflict = LiveRowScope.conflictOf(query);
+    if (conflict)
+      throw new Error(
+        `${operation} on "${this.table}" can never match (${conflict}); ${operation.startsWith("remove") ? "a remove reaches live rows only" : "pass { withRemoved: true }"}`,
+      );
     return this.compiler.compile(documentQueryHelper.all(documentQueryHelper.empty("removedAt"), query ?? {}));
   }
 
-  private writeQuery(query: DocumentQuery | undefined, operation: string) {
-    const compiled = this.safeQuery(query);
+  private writeQuery(query: DocumentQuery | undefined, operation: string, options: DocumentScopeOptions) {
+    const compiled = this.safeQuery(query, operation, options);
     if (compiled.joins.length)
       throw new Error(`q.search() cannot be used in ${operation} on "${this.table}"; query-level writes take no join.`);
     return compiled;
@@ -738,6 +812,19 @@ export class SqlDocumentStore {
     return doc;
   }
 
+  #readAs<Doc extends object>(doc: Doc, { removedAt }: { removedAt?: unknown }): Doc {
+    if (removedAt != null)
+      Object.defineProperty(doc, SqlDocumentStore.#readRemoved, { value: true, configurable: true });
+    return doc;
+  }
+
+  #assertLiveRow(doc: DocumentRecord) {
+    if (!(doc as Record<symbol, unknown>)[SqlDocumentStore.#readRemoved]) return;
+    throw new Error(
+      `read-only: a removed ${this.table} is revived with updateById(id, { removedAt: null }, { withRemoved: true })`,
+    );
+  }
+
   #assertImmutableUnchanged(prepared: DocumentRecord, originalData: DocumentRecord) {
     this.#immutableKeys ??= Object.entries(this.database.doc[FIELD_META] as unknown as FieldMap)
       .filter(([, fieldMeta]) => fieldMeta.getProps().immutable)
@@ -746,8 +833,10 @@ export class SqlDocumentStore {
     const changed = this.#immutableKeys.filter((key) => jsonStr(prepared[key]) !== jsonStr(originalData[key]));
     if (!changed.length) return;
     
-    throw new Error(
-      `Cannot modify immutable field${changed.length > 1 ? "s" : ""} on ${this.table} (${String(prepared.id)}): ${changed.join(", ")}`,
+    throw new Err(
+      "base.error.immutableField",
+      { field: changed.join(", ") },
+      { details: { model: this.table, id: String(prepared.id) } },
     );
   }
 
@@ -887,13 +976,16 @@ export class SqlDocumentStore {
       },
       save: {
         async value(this: DocumentRecord) {
-          return this.id ? store.update(this.id as string, store.#changesOf(this)) : store.create(this);
+          if (!this.id) return store.create(this);
+          store.#assertLiveRow(this);
+          return store.update(this.id as string, store.#changesOf(this));
         },
       },
       refresh: {
         async value(this: DocumentRecord) {
           const fresh = (await store.pickById(this.id as string)) as DocumentRecord & Record<symbol, StoredRow>;
           Object.assign(this, fresh);
+          Reflect.deleteProperty(this, SqlDocumentStore.#readRemoved);
           return store.#withStoredRow(this, fresh[SqlDocumentStore.#storedRow]);
         },
       },