akanjs 2.3.0 → 2.3.1-rc.0

package/server/webRouter.ts

@@ -12,22 +12,25 @@ import { type AkanRequestStore, createRequestStore, parseCookieHeader } from "ak
 import type { AkanMetricsReport } from "akanjs/service";
 import {
   type BuilderRpc,
+  type ClientManifest,
+  type MergedManifest,
   RouteClientCache,
   type RouteSeedIndex,
   RouteSeedIndexStore,
   RoutesManifestStore,
 } from "./artifact";
 import {
-  createRouteCacheEntry,
   getClientFacingOrigin,
-  isPublicRouteCacheableRequest,
+  hasRouteCacheInvalidationScope,
   isRouteCachePathAllowed,
   LruTtlCache,
-  normalizeRouteCacheTtl,
   parsePositiveInt,
   type RouteCacheEntry,
+  type RouteCacheInvalidation,
   type RouteCacheRenderState,
+  resolvePublicRouteCacheEntryDecision,
   resolveRouteCacheStoreTtl,
+  shouldInvalidateRouteCacheEntry,
   shouldStoreRouteCache,
 } from "./cachePolicy";
 import { DevHmrController } from "./hmr";
@@ -35,13 +38,24 @@ import { HMR_CLIENT_SCRIPT } from "./hmr/clientScript";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { ImageOptimizer } from "./imageOptimizer";
 import { createDefaultRobotsTxt } from "./robots";
+import {
+  AKAN_RSC_PATCH_HEAD_SAFE_HEADER,
+  AKAN_RSC_PATCH_HEAD_SNAPSHOT_HEADER,
+  AKAN_RSC_PATCH_SEGMENT_PATH_HEADER,
+  AKAN_RSC_PATCH_START_INDEX_HEADER,
+  AKAN_RSC_PATCH_START_SEGMENT_HEADER,
+  AKAN_RSC_RESPONSE_STATE_HEADER,
+} from "./routeState";
 import { type RscRedirectMethod, type RscRedirectStatus, type RscRenderResult, RscWorker } from "./rscWorkerHost";
 import { createDefaultSitemapXml, getSitemapBasePath } from "./sitemap";
 import { SsrFromRscRenderer } from "./ssrFromRscRenderer";
+import type { RscTraceMetadata, SsrManifest } from "./ssrTypes";
 import { createSystemPageResponse, getSystemPageHomeHref } from "./systemPages";
 import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types";
 
 const RESERVED_BASE_PATHS = new Set(["admin"]);
+const CLIENT_CLOSED_REQUEST_STATUS = 499;
+export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
 
 export function createRscRedirectResponse(
   location: string,
@@ -74,10 +88,36 @@ export function createRscNotFoundFallbackResponse(): Response {
   return createRscStreamResponse("0:null\n", 404);
 }
 
+function appendRscTraceHeaders(headers: Headers, trace?: RscTraceMetadata): void {
+  if (!trace) return;
+  if (trace.navId) headers.set("X-Akan-Rsc-Nav-Id", trace.navId);
+  headers.set("X-Akan-Rsc-Pathname", trace.pathname);
+  headers.set("X-Akan-Rsc-Route", trace.routeId);
+  headers.set("X-Akan-Rsc-Cache", trace.cache);
+  if (trace.cacheReason) headers.set("X-Akan-Rsc-Cache-Reason", trace.cacheReason);
+  if (trace.cacheKeyHash) headers.set("X-Akan-Rsc-Cache-Key", trace.cacheKeyHash);
+  if (trace.partial) headers.set("X-Akan-Rsc-Partial", trace.partial);
+  if (trace.partialReason) headers.set("X-Akan-Rsc-Partial-Reason", trace.partialReason);
+  if (trace.partialCommonPrefixLength !== undefined) {
+    headers.set("X-Akan-Rsc-Partial-Common-Prefix", String(trace.partialCommonPrefixLength));
+  }
+  if (trace.patchStartIndex !== undefined)
+    headers.set(AKAN_RSC_PATCH_START_INDEX_HEADER, String(trace.patchStartIndex));
+  if (trace.patchSegmentPath) headers.set(AKAN_RSC_PATCH_SEGMENT_PATH_HEADER, trace.patchSegmentPath);
+  if (trace.patchStartSegment) headers.set(AKAN_RSC_PATCH_START_SEGMENT_HEADER, trace.patchStartSegment);
+  if (trace.patchHeadSafe) headers.set(AKAN_RSC_PATCH_HEAD_SAFE_HEADER, "1");
+  if (trace.patchHeadSnapshot) headers.set(AKAN_RSC_PATCH_HEAD_SNAPSHOT_HEADER, trace.patchHeadSnapshot);
+  if (trace.routeState) headers.set(AKAN_RSC_RESPONSE_STATE_HEADER, trace.routeState);
+}
+
 export function cacheHtmlWhileStreaming(
   stream: ReadableStream<Uint8Array>,
   onComplete: (html: string) => void,
-  options: { shouldCache?: () => boolean | Promise<boolean>; maxBodyBytes?: number | null } = {},
+  options: {
+    shouldCache?: () => boolean | Promise<boolean>;
+    maxBodyBytes?: number | null;
+    onSkip?: (reason: "body-too-large" | "store-skip") => void;
+  } = {},
 ): ReadableStream<Uint8Array> {
   const chunks: Uint8Array[] = [];
   let byteLength = 0;
@@ -99,7 +139,10 @@ export function cacheHtmlWhileStreaming(
         controller.enqueue(chunk);
       },
       async flush() {
-        if (exceededMaxBodyBytes) return;
+        if (exceededMaxBodyBytes) {
+          options.onSkip?.("body-too-large");
+          return;
+        }
         const body = new Uint8Array(byteLength);
         let offset = 0;
         for (const chunk of chunks) {
@@ -107,7 +150,10 @@ export function cacheHtmlWhileStreaming(
           offset += chunk.byteLength;
         }
         try {
-          if (options.shouldCache && !(await options.shouldCache())) return;
+          if (options.shouldCache && !(await options.shouldCache())) {
+            options.onSkip?.("store-skip");
+            return;
+          }
           onComplete(decoder.decode(body));
         } catch {
         }
@@ -144,10 +190,12 @@ export function isHtmlRouteCachePathAllowed(
     AKAN_HTML_RESULT_CACHE_PATHS?: string;
     AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS?: string;
   } = process.env as Record<string, string | undefined>,
+  options: { defaultAllow?: boolean } = {},
 ): boolean {
   return isRouteCachePathAllowed(pathname, {
     allow: env.AKAN_HTML_RESULT_CACHE_PATHS,
     deny: env.AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS,
+    defaultAllow: options.defaultAllow,
   });
 }
 
@@ -155,7 +203,9 @@ export async function createRscNavigationStreamResponse(
   result: Extract<RscRenderResult, { type: "stream" }>,
 ): Promise<Response> {
 
-  return createRscStreamResponse(result.stream, result.status ?? 200);
+  const response = createRscStreamResponse(result.stream, result.status ?? 200);
+  appendRscTraceHeaders(response.headers, result.trace);
+  return response;
 }
 
 export function normalizeRscTargetUrlForHostBasePath(
@@ -209,6 +259,9 @@ interface WebRouterOptions {
 
 interface CachedHtmlResult {
   html: string;
+  pathname: string;
+  routeId?: string;
+  tags?: string[];
 }
 
 export class WebRouter {
@@ -217,7 +270,7 @@ export class WebRouter {
   #artifact: BaseBuildArtifact;
   #rsc: RscWorker;
   #hub: HmrWsHub | null = null;
-  #prodMode = process.env.NODE_ENV === "production" || typeof process.send !== "function";
+  #prodMode = process.env.NODE_ENV === "production";
   #builderRpc: BuilderRpc | null;
   #routeCache: RouteClientCache;
   #devHmr: DevHmrController | null = null;
@@ -267,7 +320,7 @@ export class WebRouter {
     if (prebuilt) {
       this.#routeCache.seed(prebuilt);
       await this.#rsc.reload({
-        clientManifest: this.#routeCache.merged.clientManifest,
+        clientManifest: this.#mergeRuntimeManifest(this.#routeCache.merged).clientManifest,
         cssAssets: this.renderState.cssAssets,
         buildId: this.renderState.buildId,
       });
@@ -480,7 +533,8 @@ export class WebRouter {
         try {
           this.#requestStats.fullSsr += 1;
           const manifest = await this.#ensureRoute(url);
-          const htmlCacheEntry = this.#getHtmlCacheEntry(req, url);
+          const htmlCacheDecision = this.#getHtmlCacheEntry(req, url);
+          const htmlCacheEntry = htmlCacheDecision.entry;
           const cachedHtml = htmlCacheEntry ? this.#getCachedHtml(htmlCacheEntry.key) : null;
           if (cachedHtml) {
             return new Response(cachedHtml, {
@@ -496,16 +550,24 @@ export class WebRouter {
           });
           if (rscResult.type === "redirect")
             return Response.redirect(new URL(rscResult.location, url.origin), rscResult.status);
-          if (rscResult.type === "not-found") return this.#renderNotFoundResponse(req, url);
+          if (rscResult.type === "not-found") return this.#renderSystemNotFoundFallbackResponse(req, url);
           const themeCookieExists = WebRouter.#hasCookie(req, "theme");
           const hostRequestStore = createRequestStore(req);
+          const extraBootstrapInline = [
+            rscResult.trace?.routeState
+              ? `self.__AKAN_RSC_INITIAL_STATE__=${JSON.stringify(rscResult.trace.routeState)};`
+              : "",
+            !this.#prodMode ? HMR_CLIENT_SCRIPT : "",
+          ]
+            .filter(Boolean)
+            .join("\n");
           const htmlStream = await new SsrFromRscRenderer().render({
             request: req,
             requestStore: hostRequestStore,
             rscStream: rscResult.stream,
             ssrManifest: manifest.ssrManifest,
             bootstrapModules: [this.#artifact.rscClientUrl],
-            extraBootstrapInline: !this.#prodMode ? HMR_CLIENT_SCRIPT : undefined,
+            extraBootstrapInline: extraBootstrapInline || undefined,
             importmap: this.#artifact.vendorMap,
             theme: themeCookieExists ? undefined : (rscResult.theme ?? "system"),
             lateControl: rscResult.lateControl,
@@ -518,6 +580,10 @@ export class WebRouter {
           if (req.method === "HEAD") {
             const headers = new Headers(responseHeaders);
             if (htmlCacheEntry && responseStatus === 200) headers.set("X-Akan-Cache", "MISS");
+            else if (htmlCacheDecision.reason) {
+              headers.set("X-Akan-Cache", "BYPASS");
+              headers.set("X-Akan-Cache-Reason", htmlCacheDecision.reason);
+            }
             cancelStreamForHeadResponse(htmlStream, new Error("HEAD response does not consume body"));
             return new Response(null, { status: responseStatus, headers });
           }
@@ -525,6 +591,7 @@ export class WebRouter {
             const headers = new Headers(responseHeaders);
             headers.set("X-Akan-Cache", "MISS");
             let htmlStoreTtl = htmlCacheEntry.ttl;
+            let htmlCacheMetadata: Omit<CachedHtmlResult, "html"> = { pathname: url.pathname };
             const shouldCacheHtml = Promise.all([rscResult.lateControl, rscResult.cacheState]).then(
               ([control, cacheState]) => {
                 const storeTtl = resolveHtmlRouteCacheStoreTtl({
@@ -535,6 +602,11 @@ export class WebRouter {
                 });
                 if (storeTtl === null) return false;
                 htmlStoreTtl = storeTtl;
+                htmlCacheMetadata = {
+                  pathname: url.pathname,
+                  routeId: cacheState.routeId,
+                  tags: cacheState.tags,
+                };
                 return true;
               },
             );
@@ -542,11 +614,16 @@ export class WebRouter {
               cacheHtmlWhileStreaming(
                 htmlStream,
                 (html) => {
-                  this.#setCachedHtml(htmlCacheEntry.key, html, htmlStoreTtl);
+                  this.#setCachedHtml(htmlCacheEntry.key, html, htmlStoreTtl, htmlCacheMetadata);
                 },
                 {
                   shouldCache: () => shouldCacheHtml,
-                  maxBodyBytes: parsePositiveInt(process.env.AKAN_HTML_RESULT_CACHE_MAX_BODY_BYTES),
+                  maxBodyBytes:
+                    parsePositiveInt(process.env.AKAN_HTML_RESULT_CACHE_MAX_BODY_BYTES) ??
+                    DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES,
+                  onSkip: (reason) => {
+                    this.#logger.verbose(`html cache store skipped pathname=${url.pathname} reason=${reason}`);
+                  },
                 },
               ),
               {
@@ -555,9 +632,14 @@ export class WebRouter {
               },
             );
           }
+          const headers = new Headers(responseHeaders);
+          if (htmlCacheDecision.reason) {
+            headers.set("X-Akan-Cache", "BYPASS");
+            headers.set("X-Akan-Cache-Reason", htmlCacheDecision.reason);
+          }
           return new Response(htmlStream, {
             status: responseStatus,
-            headers: responseHeaders,
+            headers,
           });
         } catch (err) {
           return this.#renderErrorResponse(req, url.pathname, err);
@@ -593,10 +675,24 @@ export class WebRouter {
     };
   }
 
-  /** @internal Clears local route result caches owned by the host and RSC worker. */
-  invalidateRouteCaches(reason?: string): void {
-    this.#htmlCache.clear();
-    this.#rsc.invalidateRouteResultCache(reason);
+  /** @internal Clears or scopes invalidation for local route result caches owned by the host and RSC worker. */
+  invalidateRouteCaches(invalidation?: string | RouteCacheInvalidation): void {
+    const payload = typeof invalidation === "string" ? { reason: invalidation } : invalidation;
+    if (!hasRouteCacheInvalidationScope(payload)) {
+      this.#htmlCache.clear();
+    } else if (payload) {
+      this.#htmlCache.invalidate((_key, value) =>
+        shouldInvalidateRouteCacheEntry(
+          {
+            pathname: value.pathname,
+            routeId: value.routeId,
+            tags: value.tags,
+          },
+          payload,
+        ),
+      );
+    }
+    this.#rsc.invalidateRouteResultCache(invalidation);
   }
 
   /**
@@ -631,25 +727,22 @@ export class WebRouter {
   static #hasCookie(req: Request, name: string): boolean {
     return parseCookieHeader(req.headers.get("cookie") ?? "").has(name);
   }
-  #getHtmlCacheEntry(req: Request, url: URL): RouteCacheEntry | null {
-    if (!this.#prodMode || process.env.AKAN_HTML_RESULT_CACHE !== "1") {
-      this.#htmlCacheBypass += 1;
-      return null;
-    }
-    if (!isPublicRouteCacheableRequest(req)) {
-      this.#htmlCacheBypass += 1;
-      return null;
-    }
-    if (!isHtmlRouteCachePathAllowed(url.pathname)) {
-      this.#htmlCacheBypass += 1;
-      return null;
-    }
-    const ttl = normalizeRouteCacheTtl(process.env.AKAN_HTML_RESULT_CACHE_TTL);
-    if (ttl === null) {
-      this.#htmlCacheBypass += 1;
-      return null;
-    }
-    return createRouteCacheEntry({ request: req, url, theme: WebRouter.#cookieValue(req, "theme"), ttl });
+  #getHtmlCacheEntry(req: Request, url: URL): { entry: RouteCacheEntry | null; reason?: string } {
+    const decision = resolvePublicRouteCacheEntryDecision({
+      request: req,
+      url,
+      theme: WebRouter.#cookieValue(req, "theme"),
+      defaultEnabled: this.#prodMode,
+      defaultAllow: this.#prodMode,
+      env: {
+        enabled: process.env.AKAN_HTML_RESULT_CACHE,
+        ttl: process.env.AKAN_HTML_RESULT_CACHE_TTL,
+        allow: process.env.AKAN_HTML_RESULT_CACHE_PATHS,
+        deny: process.env.AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS,
+      },
+    });
+    if (!decision.entry) this.#htmlCacheBypass += 1;
+    return decision;
   }
 
   #getCachedHtml(cacheKey: string): string | null {
@@ -662,8 +755,8 @@ export class WebRouter {
     return cached.html;
   }
 
-  #setCachedHtml(cacheKey: string, html: string, ttl: number): void {
-    this.#htmlCache.set(cacheKey, { html }, ttl);
+  #setCachedHtml(cacheKey: string, html: string, ttl: number, metadata: Omit<CachedHtmlResult, "html">): void {
+    this.#htmlCache.set(cacheKey, { html, ...metadata }, ttl);
   }
 
   static #cookieValue(req: Request, name: string): string | undefined {
@@ -683,9 +776,17 @@ export class WebRouter {
     this.#logger.verbose(
       `[route-cache] ensure pathname=${url.pathname} routeId=${matched?.entry.routeId ?? "(none)"} in ${Date.now() - started}ms`,
     );
-    return this.#routeCache.snapshot();
+    return this.#mergeRuntimeManifest(this.#routeCache.snapshot());
+  }
+
+  #mergeRuntimeManifest(manifest: MergedManifest): MergedManifest {
+    return {
+      ...manifest,
+      clientManifest: WebRouter.#mergeClientManifest(this.#artifact.rscRuntimeClientManifest, manifest.clientManifest),
+      ssrManifest: WebRouter.#mergeSsrManifest(this.#artifact.rscRuntimeSsrManifest, manifest.ssrManifest),
+    };
   }
-  #renderNotFoundResponse(req: Request, url: URL): Promise<Response> {
+  #renderSystemNotFoundFallbackResponse(req: Request, url: URL): Promise<Response> {
     return createSystemPageResponse({
       kind: "not-found",
       method: req.method,
@@ -697,6 +798,7 @@ export class WebRouter {
   }
 
   #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);
     this.#logger.error(`[SSR] render failed scope=${scope}: ${message}`);
     this.#hub?.broadcast({ type: "error", message });
@@ -713,6 +815,7 @@ export class WebRouter {
   }
 
   #renderRscErrorResponse(scope: string, err: unknown): Response {
+    if (WebRouter.#isExpectedRequestAbort(err)) return WebRouter.#clientClosedResponse();
     const message = err instanceof Error ? err.message : String(err);
     this.#logger.error(`[SSR] render failed scope=${scope}: ${message}`);
     this.#hub?.broadcast({ type: "error", message });
@@ -722,6 +825,23 @@ export class WebRouter {
     });
   }
 
+  static #clientClosedResponse(): Response {
+    return new Response(null, {
+      status: CLIENT_CLOSED_REQUEST_STATUS,
+      headers: { "Cache-Control": "no-store" },
+    });
+  }
+
+  static #isExpectedRequestAbort(error: unknown): boolean {
+    if (!(error instanceof Error)) return false;
+    return (
+      error.name === "AbortError" ||
+      error.message === "The connection was closed." ||
+      error.message === "Connection closed." ||
+      error.message.includes("The connection was closed")
+    );
+  }
+
   #getSystemPageHomeHref(req: Request, pathname: string): string {
     return getSystemPageHomeHref({
       pathname,
@@ -811,10 +931,46 @@ export class WebRouter {
       ...artifact,
       cssAssets: artifact.cssAssets ?? {},
       pagesBundlePath,
+      rscRuntimeSsrManifest: artifact.rscRuntimeSsrManifest
+        ? WebRouter.#normalizeSsrManifest(artifact.rscRuntimeSsrManifest, normalizedArtifactDir)
+        : undefined,
       i18n: artifact.i18n ?? DEFAULT_AKAN_I18N,
     };
   }
 
+  static #mergeClientManifest(...manifests: Array<ClientManifest | undefined>): ClientManifest {
+    return Object.assign({}, ...manifests.filter(Boolean));
+  }
+
+  static #mergeSsrManifest(...manifests: Array<SsrManifest | undefined>): SsrManifest {
+    const definedManifests = manifests.filter((manifest): manifest is SsrManifest => Boolean(manifest));
+    return {
+      moduleLoading: null,
+      moduleMap: Object.assign({}, ...definedManifests.map((manifest) => manifest.moduleMap)),
+    };
+  }
+
+  static #normalizeSsrManifest(ssrManifest: SsrManifest, artifactDir: string): SsrManifest {
+    return {
+      ...ssrManifest,
+      moduleMap: Object.fromEntries(
+        Object.entries(ssrManifest.moduleMap).map(([entryUrl, byName]) => [
+          entryUrl,
+          Object.fromEntries(
+            Object.entries(byName).map(([name, entry]) => [
+              name,
+              {
+                ...entry,
+                id: WebRouter.#resolveArtifactPath(entry.id, artifactDir),
+                chunks: entry.chunks.map((chunk) => WebRouter.#resolveArtifactPath(chunk, artifactDir)),
+              },
+            ]),
+          ),
+        ]),
+      ),
+    };
+  }
+
   static async #loadCssBytesByUrl(
     artifact: BaseBuildArtifact,
     artifactDir: string,

package/service/predefinedAdaptor/database.adaptor.ts

@@ -593,20 +593,8 @@ export class SqliteDocumentStore {
   }
 
   async update(id: string, patch: DocumentRecord) {
-    const current = await this.pickById(id);
-    const doc = this.hydrate(this.prepareDocument({ ...current, ...patch, id, updatedAt: dayjs() }), current);
-    await this.runHooks("save", "update", doc, "pre");
-    await this.runHooks("update", "update", doc, "pre");
-    const row = this.toRow(doc);
-    await this.owner
-      .getConnection()
-      .prepare(
-        `UPDATE ${quoteIdent(this.table)} SET "createdAt" = ?, "updatedAt" = ?, "removedAt" = ?, "_doc" = ? WHERE "id" = ?`,
-      )
-      .run(row.createdAt, row.updatedAt, row.removedAt, row._doc, id);
-    await this.runHooks("update", "update", doc, "post");
-    await this.runHooks("save", "update", doc, "post");
-    return doc;
+    const current = await this.pickByIdForWrite(id);
+    return await this.writeUpdatedDocument(id, { ...current, ...patch, id, updatedAt: dayjs() }, current);
   }
 
   async remove(id: string) {
@@ -614,19 +602,20 @@ export class SqliteDocumentStore {
   }
 
   async updateOneByQuery(query: DocumentQuery, update: DocumentUpdate, options: DocumentUpdateOptions = {}) {
-    const doc = await this.findOne(query);
+    const doc = await this.findOneForWrite(query);
     if (!doc) {
       if (!options.upsert) return { acknowledged: true, matchedCount: 0, modifiedCount: 0, upsertedId: null };
       const inserted = await this.create(this.applyDocumentUpdate(this.extractInsertBase(query), update, true));
       return { acknowledged: true, matchedCount: 0, modifiedCount: 1, upsertedId: inserted.id };
     }
-    await this.update(doc.id, this.applyDocumentUpdate(doc, update));
+    await this.writeUpdatedDocument(doc.id as string, this.applyDocumentUpdate(doc, update), doc);
     return { acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null };
   }
 
   async updateManyByQuery(query: DocumentQuery, update: DocumentUpdate) {
-    const docs = await this.find(query);
-    for (const doc of docs) await this.update(doc.id, this.applyDocumentUpdate(doc, update));
+    const docs = await this.findForWrite(query);
+    for (const doc of docs)
+      await this.writeUpdatedDocument(doc.id as string, this.applyDocumentUpdate(doc, update), doc);
     return { acknowledged: true, matchedCount: docs.length, modifiedCount: docs.length };
   }
 
@@ -656,12 +645,12 @@ export class SqliteDocumentStore {
     const limit = limitValue ? ` LIMIT ${limitValue}` : "";
     const offset = skipValue ? ` OFFSET ${skipValue}` : "";
     const order = options.sample ? "ORDER BY random()" : `ORDER BY ${this.compiler.orderBy(options.sort ?? undefined)}`;
-    const projection = this.normalizeProjection(options.select);
+    const projection = this.resolveProjection(options.select);
     if (projection) {
       const rows = await this.prepareReadStmt(
         `SELECT ${this.projectionSql(projection)} FROM ${quoteIdent(this.table)} WHERE ${where} ${order}${limit}${offset}`,
       ).all<ProjectedSqliteDocumentRow>(...params);
-      return rows.map((row) => this.fromProjectedRow(row, projection));
+      return rows.map((row) => this.hydrate(this.fromProjectedRow(row, projection)));
     }
     const rows = await this.prepareReadStmt(
       `SELECT * FROM ${quoteIdent(this.table)} WHERE ${where} ${order}${limit}${offset}`,
@@ -922,10 +911,22 @@ export class SqliteDocumentStore {
     const fields = Object.entries(select)
       .filter(([, included]) => included)
       .map(([field]) => field);
-    if (!fields.length) return null;
     return [...new Set(fields.filter((field) => field !== "_doc"))];
   }
 
+  private resolveProjection(select: ProjectionOption): string[] | null {
+    const projection = this.normalizeProjection(select);
+    if (projection !== null) return projection;
+    return this.defaultProjection();
+  }
+
+  private defaultProjection(): string[] | null {
+    const fields = this.database.doc[FIELD_META] as unknown as FieldMap;
+    const entries = Object.entries(fields).filter(([key]) => !BASE_COLUMNS.has(key));
+    if (!entries.some(([, field]) => field.getProps().select === false)) return null;
+    return entries.flatMap(([key, field]) => (field.getProps().select === false ? [] : [key]));
+  }
+
   private projectionSql(fields: string[]) {
     const jsonFields = fields.filter((field) => !BASE_COLUMNS.has(field));
     const baseColumns = [...BASE_COLUMNS].map((field) => quoteIdent(field));
@@ -942,19 +943,65 @@ export class SqliteDocumentStore {
   private fromProjectedRow(row: ProjectedSqliteDocumentRow, fields: string[]) {
     const doc: DocumentRecord = {
       id: row.id,
-      createdAt: Number(row.createdAt),
-      updatedAt: Number(row.updatedAt),
-      removedAt: row.removedAt ? Number(row.removedAt) : undefined,
+      createdAt: dayjs(Number(row.createdAt)),
+      updatedAt: dayjs(Number(row.updatedAt)),
+      removedAt: row.removedAt ? dayjs(Number(row.removedAt)) : undefined,
     };
     const jsonFields = fields.filter((field) => !BASE_COLUMNS.has(field));
     for (const [idx, field] of jsonFields.entries()) {
       const value = this.parseProjectedValue(row[this.projectionAlias(idx)]);
       const props = (this.database.doc[FIELD_META] as unknown as FieldMap)[field]?.getProps?.();
-      doc[field] = props ? this.decodeFieldValue(value, props) : value;
+      if (value === null && props?.default !== undefined && props.default !== null && !props.nullable) {
+        doc[field] =
+          typeof props.default === "function" ? (props.default as (data: unknown) => unknown)(doc) : props.default;
+      } else {
+        doc[field] = props ? this.decodeFieldValue(value, props) : value;
+      }
     }
     return doc;
   }
 
+  private async findForWrite(query?: DocumentQuery, options: FindManyOptions = {}) {
+    const { where, params } = this.safeQuery(query);
+    const limitValue = Number(options.limit ?? 0);
+    const skipValue = Number(options.skip ?? 0);
+    const limit = limitValue ? ` LIMIT ${limitValue}` : "";
+    const offset = skipValue ? ` OFFSET ${skipValue}` : "";
+    const order = options.sample ? "ORDER BY random()" : `ORDER BY ${this.compiler.orderBy(options.sort ?? undefined)}`;
+    const rows = await this.prepareReadStmt(
+      `SELECT * FROM ${quoteIdent(this.table)} WHERE ${where} ${order}${limit}${offset}`,
+    ).all<SqliteDocumentRow>(...params);
+    return rows.map((row) => this.hydrate(this.fromRow(row)));
+  }
+
+  private async findOneForWrite(query?: DocumentQuery, options: FindOneOptions = {}) {
+    return (
+      (await this.findForWrite(query, { ...options, limit: 1, sample: options.sample ? 1 : undefined })).at(0) ?? null
+    );
+  }
+
+  private async pickByIdForWrite(id: string) {
+    const doc = await this.findOneForWrite({ id } as DocumentQuery);
+    if (!doc) throw new Error(`No Document (${this.table}): ${id}`);
+    return doc;
+  }
+
+  private async writeUpdatedDocument(id: string, data: DocumentRecord, originalData: DocumentRecord) {
+    const doc = this.hydrate(this.prepareDocument({ ...data, id, updatedAt: dayjs() }), originalData);
+    await this.runHooks("save", "update", doc, "pre");
+    await this.runHooks("update", "update", doc, "pre");
+    const row = this.toRow(doc);
+    await this.owner
+      .getConnection()
+      .prepare(
+        `UPDATE ${quoteIdent(this.table)} SET "createdAt" = ?, "updatedAt" = ?, "removedAt" = ?, "_doc" = ? WHERE "id" = ?`,
+      )
+      .run(row.createdAt, row.updatedAt, row.removedAt, row._doc, id);
+    await this.runHooks("update", "update", doc, "post");
+    await this.runHooks("save", "update", doc, "post");
+    return doc;
+  }
+
   private parseProjectedValue(value: unknown) {
     if (typeof value !== "string") return value;
     const trimmed = value.trim();

package/signal/signalContext.ts

@@ -249,7 +249,7 @@ export class SignalContext<
     const resolvedValue = {} as RuntimeRecord;
     await Promise.all(
       Object.entries((returnRef as ConstantCls)[FIELD_META]).map(async ([key, field]) => {
-        if (field.fieldType === "hidden") return;
+        if (field.fieldType === "hidden" || field.fieldType === "secret") return;
         else if (field.fieldType === "resolve") {
           const refName = ConstantRegistry.getRefName(returnRef as ConstantCls);
           const internal = live.internal.get(`${refName}Internal`);

package/types/client/csrTypes.d.ts

@@ -16,6 +16,12 @@ export interface PageConfig {
     bottomInset?: boolean | number;
     gesture?: boolean;
     cache?: boolean;
+    /**
+     * Opt in to guarded RSC page suffix commits when the page does not require
+     * head/metadata updates and the retained route chain head is invariant for
+     * sibling navigations under the same layout.
+     */
+    rscPatchHeadSafe?: boolean;
     topSafeAreaColor?: string;
     bottomSafeAreaColor?: string;
 }
@@ -61,9 +67,19 @@ export interface LayoutErrorProps extends LayoutNotFoundProps {
 }
 export type Head = ReactNode;
 export type GenerateHead = (props: PageProps) => PromiseOrObject<Head | null | undefined>;
+export interface AkanHeadSnapshotNode {
+    tag: "title" | "meta" | "link";
+    attrs?: Record<string, string>;
+    text?: string;
+}
+export interface AkanHeadSnapshotV1 {
+    version: 1;
+    nodes: AkanHeadSnapshotNode[];
+}
 export interface ResolvedHead {
     node: Head | null | undefined;
     hasExplicitLanguageAlternates: boolean;
+    headSnapshot?: AkanHeadSnapshotV1;
 }
 export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
 export type ResolveHead = (props: PageProps) => PromiseOrObject<ResolveHeadResult>;