@webjsdev/server 0.8.38 → 0.8.40

package/index.d.ts

@@ -59,6 +59,15 @@ export interface CacheStore {
   delete(key: string): Promise<void>;
   /** Atomically increment a counter; returns the new value (TTL set on creation only). */
   increment(key: string, ttlMs?: number): Promise<number>;
+  /**
+   * OPTIONAL atomic set insert for the tag index (#752): add `member` to the set
+   * at `key`, refreshing the key TTL. Eliminates the lost-update race of the
+   * read-modify-write JSON path. A store omitting it falls back to that path.
+   * Paired with `setMembers` (implement both or neither).
+   */
+  setAdd?(key: string, member: string, ttlMs?: number): Promise<void>;
+  /** OPTIONAL set read, the counterpart of `setAdd` (empty array on a miss). */
+  setMembers?(key: string): Promise<string[]>;
 }
 
 /** The pluggable logger interface. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.38",
+  "version": "0.8.40",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/action-error.js

@@ -0,0 +1,56 @@
+/**
+ * Server-action error sanitization (#749).
+ *
+ * A thrown server action must NOT leak its raw error message to the client in
+ * production. Most thrown errors are NOT author-controlled (a Postgres driver
+ * error carries the constraint / column name, an `ECONNREFUSED` carries an
+ * internal host / IP, an fs error carries an absolute server path), and the RPC
+ * client surfaces the message. So in prod we return a GENERIC message plus a
+ * short `digest`, and log the full error server-side keyed by that digest, the
+ * same model as Next.js's server-action errors. An author-facing user-safe
+ * message belongs on the `ActionResult` `{ success: false, error }` envelope
+ * (the expected-failure channel), not on a throw.
+ *
+ * Used by both the buffered RPC error path (`actions.js`) and the streaming
+ * error frame (`action-stream.js`); it is a leaf module so neither importer
+ * creates a cycle.
+ *
+ * @module action-error
+ */
+
+import { isRedirect, isNotFound } from '@webjsdev/core';
+import { digestHex } from './crypto-utils.js';
+
+/** The generic client-facing message for a sanitized prod action error. */
+export const GENERIC_ERROR_MESSAGE = 'Internal server error';
+
+/**
+ * `redirect()` / `notFound()` throw `Error` sentinels tagged with a `__webjs`
+ * SYMBOL VALUE. They are control flow, not errors to sanitize, and their
+ * message is not sensitive, so the error path passes them through unchanged.
+ *
+ * Reuses core's authoritative `isRedirect` / `isNotFound`, which match the exact
+ * sentinel symbol value (`__webjs === REDIRECT` / `=== NOT_FOUND`), NOT mere
+ * property presence: a genuine error that happens to carry a `__webjs` property
+ * must still be sanitized, never passed through.
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isControlFlowThrow(err) {
+  return isRedirect(err) || isNotFound(err);
+}
+
+/**
+ * A short, stable correlation digest for a thrown error (a hash of its message
+ * and stack). The SAME value is logged server-side and returned to the client,
+ * so a generic client error maps back to the full server log line, and two
+ * occurrences of the same error share a digest (groupable in an APM).
+ *
+ * @param {unknown} err
+ * @returns {Promise<string>}
+ */
+export async function errorDigest(err) {
+  const basis = err instanceof Error ? `${err.message}\n${err.stack || ''}` : String(err);
+  return (await digestHex('SHA-256', basis)).slice(0, 10);
+}

package/src/action-seed-bun.js

@@ -26,73 +26,39 @@
  * same module Bun would have loaded.
  */
 
-/** Bun's global install cache + node_modules: a dep, never an app file to rewrite. */
-const DEP_PATH_RE = /[\\/](?:node_modules|install[\\/]cache|\.bun)[\\/]/;
-
 /**
- * Install the webjs `Bun.plugin` `onLoad`. It carries two independent transforms
- * on ONE handler (Bun `onLoad` is first-match-wins, so a second overlapping
- * plugin would starve one of them):
- *
- *   - **Pin rewrite (#685)**, when `pinTransform` is supplied: rewrite bare
- *     specifiers of declared deps to inline-versioned ones so Bun zero-install
- *     fetches the pinned version, not latest. Applies to APP files only (a dep
- *     in `node_modules` / the global cache is returned raw). This broadens the
- *     filter to all JS/TS; without it the filter stays the cheap `*.server.*`
- *     pre-screen.
- *   - **Seed facade (#472)**, when `seedEnabled`: facet a `'use server'`
- *     candidate into the SSR action-result seed facade, built from the
- *     (already pin-rewritten) source.
- *
- * Idempotency is the caller's responsibility (`registerSeedHooks` guards on
- * `_registered`).
+ * Install the `Bun.plugin` seed `onLoad`. Idempotency is the caller's
+ * responsibility (`registerSeedHooks` guards on `_registered`).
  *
  * @param {{
  *   isSeedCandidate: (specifier: string) => boolean,
  *   buildSeedFacade: (origSpec: string, absPath: string, src: string) => (string | null),
  *   serverFileRe: RegExp,
- *   seedEnabled?: boolean,
- *   pinTransform?: ((src: string, loader: 'ts' | 'js') => string) | null,
  * }} helpers
  */
-export function installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe, seedEnabled = true, pinTransform = null }) {
-  // Pinning needs to see every app module's imports, so broaden the filter when
-  // it is active; otherwise keep the narrow `*.server.*` seed pre-screen.
-  const filter = pinTransform ? /\.m?[jt]s(\?|$)/ : serverFileRe;
+export function installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe }) {
   Bun.plugin({
-    name: 'webjs-onload',
+    name: 'webjs-action-seed',
     setup(build) {
-      build.onLoad({ filter }, async (args) => {
+      // The filter is a cheap path pre-screen (`*.server.*`, optional query).
+      build.onLoad({ filter: serverFileRe }, async (args) => {
         const absPath = args.path.split('?')[0];
         // `.ts` / `.mts` strip via the `ts` loader; `.js` / `.mjs` via `js`.
         const loader = /\.m?ts$/.test(absPath) ? 'ts' : 'js';
-        // A dependency (node_modules or Bun's global cache): never rewrite it
-        // (the app's package.json does not pin transitive deps; they follow from
-        // the pinned direct deps' own manifests). Return the raw source unchanged.
-        if (pinTransform && DEP_PATH_RE.test(absPath)) {
-          return { contents: await Bun.file(absPath).text(), loader };
-        }
         // Read the real source. A genuine read failure (missing file) propagates,
         // which Bun reports as a load error exactly as it would without the plugin.
-        let src = await Bun.file(absPath).text();
-        // Pin rewrite. For a NON-`.server` module this is where its specifiers get
-        // pinned. A `.server` candidate's REAL module is pinned on its
-        // `?webjs-seed-orig` passthrough load (which re-enters this onLoad); the
-        // facade itself only reads export names, unaffected by the rewrite.
-        if (pinTransform) {
-          try { src = pinTransform(src, loader); } catch { /* fail-open: raw source */ }
-        }
+        const src = await Bun.file(absPath).text();
         try {
           // Facet only a `'use server'` candidate (not the `?webjs-seed-orig`
           // passthrough); a non-candidate or a passthrough falls through to the
-          // (possibly pin-rewritten) source below.
-          if (seedEnabled && isSeedCandidate(args.path)) {
+          // raw source below.
+          if (isSeedCandidate(args.path)) {
             const source = buildSeedFacade(args.path, absPath, src);
             if (source != null) return { contents: source, loader: 'js' };
           }
         } catch {
-          // Fail-open: any faceting error serves the source (no seeding for this
-          // module), the Bun analog of the Node hook's `nextLoad` fallback.
+          // Fail-open: any faceting error serves the raw source (no seeding for
+          // this module), the Bun analog of the Node hook's `nextLoad` fallback.
         }
         return { contents: src, loader };
       });

package/src/action-seed.js

@@ -50,14 +50,12 @@
 
 import * as nodeModule from 'node:module';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { stringify } from '@webjsdev/core';
 import { hashFile } from './actions.js';
 import { isStreamable } from './action-stream.js';
 import { serverRuntime } from './listener-core.js';
-import { resolveDepVersions, rewriteDepSpecifiers } from './bun-pin-rewrite.js';
 
 /** Ambient per-render seed collector. `Map<key, value>` or undefined. */
 const als = new AsyncLocalStorage();
@@ -298,73 +296,27 @@ function seedLoadHook(url, context, nextLoad) {
 }
 
 /**
- * Build the per-file pin transform for Bun (#685): read the app's declared dep
- * versions (package.json, with `bun.lock` exact pins preferred) and return a
- * function that rewrites a module's bare dep specifiers to inline-versioned ones
- * so Bun zero-install fetches the pinned version, not latest. Returns null when
- * there is nothing to pin (no package.json, or no declared deps). Bun-only: it
- * references `Bun.Transpiler`, so it is invoked only on the Bun branch.
- * @param {string} appDir
- * @returns {((src: string, loader: 'ts' | 'js') => string) | null}
- */
-export function buildBunPinTransform(appDir) {
-  // Pinning is for TRUE zero-install only. When `node_modules` exists (an
-  // installed app, or a workspace member like this repo's own examples), Bun
-  // resolves bare specifiers from it, so injecting an inline version would
-  // bypass that. Worse, for a workspace-linked dep it would swap the local
-  // package for the published one (the #698 blog-on-Bun regression). So skip
-  // pinning entirely when node_modules is present; Bun uses the installed copy.
-  if (existsSync(join(appDir, 'node_modules'))) return null;
-  let pkgText;
-  try { pkgText = readFileSync(join(appDir, 'package.json'), 'utf8'); } catch { return null; }
-  let lockText = null;
-  try { lockText = readFileSync(join(appDir, 'bun.lock'), 'utf8'); } catch { /* optional */ }
-  const versions = resolveDepVersions(pkgText, lockText);
-  if (Object.keys(versions).length === 0) return null;
-  return (src, loader) => {
-    const imports = new Bun.Transpiler({ loader }).scanImports(src);
-    return rewriteDepSpecifiers(src, imports, versions);
-  };
-}
-
-/**
- * Install the boot-time load hook(s) (idempotent). Called once from `dev.js`,
- * BEFORE any app module is imported (a module loaded before the hook would
- * already be cached untransformed). Two concerns ride here:
- *
- *   - **Seeding (#472)** when `seedEnabled`: facet `'use server'` modules into
- *     the SSR action-result seed facade. Node uses `module.registerHooks`; Bun a
- *     `Bun.plugin` `onLoad`.
- *   - **Pinning (#685)** when `pinEnabled` (Bun only): rewrite bare dep
- *     specifiers to the package.json/bun.lock version so zero-install fetches the
- *     pinned version, not latest. Independent of seeding, so the Bun plugin is
- *     installed when EITHER is on (they share the one first-match-wins onLoad).
- *
- * No-op on a second call. Async because the Bun path dynamically imports
- * `action-seed-bun.js` (so the `Bun.*` global is never referenced on Node).
- *
- * @param {{ appDir?: string | null, seedEnabled?: boolean, pinEnabled?: boolean }} [opts]
+ * Install the seed load hook (idempotent). Called once at boot from `dev.js`
+ * when seeding is enabled, BEFORE any action module is imported (a module loaded
+ * before the hook would already be cached unwrapped). The install mechanism is
+ * chosen by `serverRuntime()` (#529): Node's synchronous `module.registerHooks`,
+ * or a `Bun.plugin` `onLoad` on Bun. A no-op on a second call. Async because the
+ * Bun path dynamically imports `action-seed-bun.js` (so the `Bun.*` global is
+ * never referenced on Node); the Node path resolves synchronously.
  * @returns {Promise<void>}
  */
-export async function registerSeedHooks({ appDir = null, seedEnabled = true, pinEnabled = false } = {}) {
+export async function registerSeedHooks() {
   if (_registered) return;
   _registered = true;
 
   if (serverRuntime() === 'bun') {
-    // Bun has no module.registerHooks; install the facade + pin rewrite via one
-    // Bun.plugin onLoad (first-match-wins, so the two transforms must share it).
+    // Bun has no module.registerHooks; install the same facade via Bun.plugin.
     const { installBunSeedPlugin } = await import('./action-seed-bun.js');
-    const pinTransform = (pinEnabled && appDir) ? buildBunPinTransform(appDir) : null;
-    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE, seedEnabled, pinTransform });
-    if (seedEnabled) _enabled = true;
+    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE });
+    _enabled = true;
     return;
   }
 
-  // Node: seeding only (Bun-specific inline-version pinning does not apply; the
-  // Node zero-install resolve-hook is #669's separate concern). Nothing to
-  // install when seeding is off.
-  if (!seedEnabled) return;
-
   // A runtime that is neither Node-with-registerHooks nor Bun: seeding stays
   // OFF (fail-open). `seedingEnabled()` is false, ssr.js emits no seed block,
   // and the client RPC stub falls back to a normal fetch. Never wrong data.

package/src/action-stream.js

@@ -21,6 +21,7 @@
  */
 import { encodeFrame, FRAME_CHUNK, FRAME_END, FRAME_ERROR, STREAM_CONTENT_TYPE } from '@webjsdev/core';
 import { getSerializer } from './serializer.js';
+import { isControlFlowThrow, errorDigest, GENERIC_ERROR_MESSAGE } from './action-error.js';
 
 /**
  * Whether an action's return value should stream over the RPC wire rather than
@@ -73,11 +74,11 @@ function toAsyncIterator(source) {
  * iterator, stopping a server generator.
  *
  * @param {any} source the streamable action return value
- * @param {{ signal?: AbortSignal, onError?: (e: unknown) => void, headers?: Record<string,string> }} [opts]
+ * @param {{ signal?: AbortSignal, onError?: (e: unknown) => void, headers?: Record<string,string>, dev?: boolean }} [opts]
  * @returns {Response}
  */
 export function streamActionResponse(source, opts = {}) {
-  const { signal, onError, headers } = opts;
+  const { signal, onError, headers, dev } = opts;
   const s = getSerializer();
   const enc = new TextEncoder();
   const iter = toAsyncIterator(source);
@@ -125,8 +126,23 @@ export function streamActionResponse(source, opts = {}) {
         // like the buffered error path, then ship the author-controlled message
         // on the frame channel (the status is already 200, mid-stream).
         if (typeof onError === 'function') { try { onError(e); } catch {} }
-        console.error('[webjs] streaming action threw:', e);
-        const msg = e instanceof Error && e.message ? e.message : 'Internal server error';
+        // Sanitize like the buffered path (#749): dev ships the real message,
+        // prod ships a generic message + correlation digest (logged with the
+        // full error), never the raw message. A redirect()/notFound() sentinel
+        // passes through. The status is already 200 here, so the error rides the
+        // frame channel; the client stub throws Error(frame text).
+        let msg;
+        if (dev) {
+          msg = e instanceof Error && e.message ? e.message : GENERIC_ERROR_MESSAGE;
+          console.error('[webjs] streaming action threw:', e);
+        } else if (isControlFlowThrow(e)) {
+          msg = e instanceof Error ? e.message : String(e);
+          console.error('[webjs] streaming action threw:', e);
+        } else {
+          const digest = await errorDigest(e);
+          msg = `${GENERIC_ERROR_MESSAGE} [digest=${digest}]`;
+          console.error(`[webjs] streaming action threw [digest=${digest}]:`, e);
+        }
         try { controller.enqueue(encodeFrame(FRAME_ERROR, enc.encode(msg))); } catch {}
         await releaseSource(e);
         detach();

package/src/actions.js

@@ -15,6 +15,7 @@ import { revalidateTags } from './cache-tags.js';
 import { runWithActionSignal } from './action-signal.js';
 import { runActionChain } from './action-middleware.js';
 import { isStreamable, streamActionResponse } from './action-stream.js';
+import { isControlFlowThrow, errorDigest, GENERIC_ERROR_MESSAGE } from './action-error.js';
 import { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
@@ -349,7 +350,7 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   lines.push(`  if (ct.includes(__STREAM_CT)) return __readStream(res, fn);`);
   lines.push(`  const text = await res.text();`);
   lines.push(`  const parsed = ct.includes(__CT) ? __p(text) : (ct.includes('application/json') ? JSON.parse(text) : text);`);
-  lines.push(`  if (!res.ok) throw new Error((parsed && parsed.error) || ('webjs action ' + fn + ' -> ' + res.status));`);
+  lines.push(`  if (!res.ok) { const __e = new Error((parsed && parsed.error) || ('webjs action ' + fn + ' -> ' + res.status)); if (parsed && parsed.digest) __e.digest = parsed.digest; throw __e; }`);
   lines.push(`  return parsed;`);
   lines.push(`}`);
   // Decode a framed streamed body into an async generator of rich-deserialized
@@ -533,7 +534,7 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
         const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
         if (inv.length) { await revalidateTags(inv); headers['x-webjs-invalidate'] = inv.join(','); }
       }
-      return streamActionResponse(result, { signal: req.signal, onError, headers });
+      return streamActionResponse(result, { signal: req.signal, onError, headers, dev: idx.dev });
     }
     if (method === 'GET') {
       // A short-circuit (the action did not run, e.g. an auth denial) is NEVER
@@ -588,27 +589,38 @@ async function getActionResponse(result, mod, args, req) {
 }
 
 /**
- * Return a JSON error response with dev-vs-prod sanitization.
- * In prod we return only the error message (not the stack), and we log the
- * full error server-side. Internal errors with no message become a generic
- * 500.
+ * Return a JSON error response with dev-vs-prod sanitization (#749).
+ *
+ * Dev returns the real message + stack. PROD returns a GENERIC message plus a
+ * short `digest`, and logs the full error server-side keyed by that digest, so
+ * a raw error (a DB driver message with a constraint name, an `ECONNREFUSED`
+ * with an internal IP, an fs path) never reaches the client while staying
+ * diagnosable from the logs. `redirect()` / `notFound()` control-flow sentinels
+ * pass through unchanged (not errors, message not sensitive). An author-facing
+ * user-safe message belongs on the `ActionResult` `{ success: false, error }`
+ * envelope, not on a throw.
  *
  * @param {unknown} err
  * @param {boolean} dev
+ * @returns {Promise<Response>}
  */
-function actionErrorResponse(err, dev) {
-  console.error('[webjs] action threw:', err);
+async function actionErrorResponse(err, dev) {
   if (dev) {
+    console.error('[webjs] action threw:', err);
     const msg = err instanceof Error ? err.message : String(err);
     const stack = err instanceof Error ? err.stack : undefined;
     return rpcResponse({ error: msg, stack }, { status: 500 });
   }
-  // Prod: only expose the thrown message (author-controlled), never the stack.
-  const msg =
-    err instanceof Error && typeof err.message === 'string' && err.message
-      ? err.message
-      : 'Internal server error';
-  return rpcResponse({ error: msg }, { status: 500 });
+  // Control-flow sentinels (redirect/notFound) are not errors to sanitize.
+  if (isControlFlowThrow(err)) {
+    console.error('[webjs] action threw:', err);
+    const msg = err instanceof Error ? err.message : String(err);
+    return rpcResponse({ error: msg }, { status: 500 });
+  }
+  // Prod genuine error: generic message + correlation digest, full error logged.
+  const digest = await errorDigest(err);
+  console.error(`[webjs] action threw [digest=${digest}]:`, err);
+  return rpcResponse({ error: GENERIC_ERROR_MESSAGE, digest }, { status: 500 });
 }
 
 /**

package/src/cache-fn.js

@@ -23,9 +23,21 @@
  * @module cache-fn
  */
 
+import { stringify, parse } from '@webjsdev/core';
 import { getStore } from './cache.js';
 import { addKeyToTags } from './cache-tags.js';
 
+// Cache value/key encoding version. Entries written by an older encoding used
+// a DIFFERENT key namespace, so a reader never deserializes them with the new
+// format. Before this segment existed, values were JSON and keys were the
+// unversioned `cache:<prefix>`; a JSON-format entry is still valid JSON that
+// `parse` would silently accept as a lossy value (a Date as a string) without
+// recomputing, so the version segment forces those pre-upgrade entries to miss
+// and expire by their own TTL instead of being served stale. Bump it whenever
+// the value/key encoding changes. Distinct from the `cache:tag:` tag-index
+// namespace in cache-tags.js.
+const CACHE_FORMAT = 'r1';
+
 /**
  * Wrap an async function with server-side caching.
  *
@@ -70,17 +82,28 @@ export function cache(fn, opts) {
   const wrapped = /** @type {T & { invalidate: () => Promise<void> }} */ (
     async function (...args) {
       const store = getStore();
+      // Both the key fingerprint and the stored value go through the same
+      // rich serializer the RPC wire uses (@webjsdev/core stringify/parse),
+      // NOT JSON. JSON collapses Date to a string and Map/Set to {} / [], so
+      // (a) a cached value would change shape between a cold miss (the real
+      // value) and a warm hit (the lossy JSON value), and (b) two distinct
+      // Map/Set args would collide to the same key. Going through core's
+      // serializer makes a hit byte-faithful to a miss and keys collision-safe.
+      // We use core stringify/parse DIRECTLY rather than getSerializer() so the
+      // cache preserves full fidelity even when an app swaps the wire format to
+      // a lossy one (e.g. plain JSON); cache fidelity is a storage concern, not
+      // a wire concern.
       const cacheKey = args.length
-        ? `cache:${prefix}:${JSON.stringify(args)}`
-        : `cache:${prefix}`;
+        ? `cache:${CACHE_FORMAT}:${prefix}:${await stringify(args)}`
+        : `cache:${CACHE_FORMAT}:${prefix}`;
 
       const hit = await store.get(cacheKey);
       if (hit !== null) {
-        try { return JSON.parse(hit); } catch { /* corrupted: recompute */ }
+        try { return parse(hit); } catch { /* corrupted: recompute */ }
       }
 
       const result = await fn(...args);
-      await store.set(cacheKey, JSON.stringify(result), ttlMs);
+      await store.set(cacheKey, await stringify(result), ttlMs);
       // Record tag -> cacheKey in the thin tag index so a later
       // revalidateTag can find and evict this entry (including
       // arg-specific keys the no-args invalidate() cannot reach).
@@ -115,7 +138,7 @@ export function cache(fn, opts) {
   wrapped.invalidate = async function () {
     const store = getStore();
     // Delete the base key (no-args call)
-    await store.delete(`cache:${prefix}`);
+    await store.delete(`cache:${CACHE_FORMAT}:${prefix}`);
     // Note: arg-specific keys are not tracked. If the cached function
     // is called with different arguments, those entries expire via TTL.
     // For full invalidation of arg-specific keys, use a short TTL.

package/src/cache-tags.js

@@ -16,20 +16,22 @@
  * clears the index entry. A mutation in ANY module can therefore evict every
  * read tagged `'posts'` across modules with one explicit call.
  *
- * It stays a thin index over `store.get/set/delete`: no new store method, a
- * plain JSON array (a Set is trivial in the memory store; the same get/set of
- * a JSON array works for Redis). The cohesive companion for HTML paths is
- * `revalidatePath` in `html-cache.js`; together they are the server cache
- * invalidation surface (this one for `cache()` DATA, that one for cached HTML).
+ * The cohesive companion for HTML paths is `revalidatePath` in
+ * `html-cache.js`; together they are the server cache invalidation surface
+ * (this one for `cache()` DATA, that one for cached HTML).
  *
- * MULTI-INSTANCE CAVEAT (mirrors #241): the index is a plain read-modify-write
- * of a JSON array, NOT atomic across processes. With a shared Redis store,
- * `revalidateTag` deletes the keys it can see and reaches every instance for
- * those keys, but two instances appending to the same tag concurrently can
- * lose an append (last write wins), so a freshly-stored key on a peer might
- * miss eviction and live until its TTL. The tag index entry itself also
- * carries the cache TTL, so the index self-prunes and never grows unbounded.
- * For strict cross-instance invalidation, prefer a short `ttl` as the floor.
+ * ATOMICITY (#752): when the store exposes the optional `setAdd` / `setMembers`
+ * primitives, the tag index is a real SET, so adding a cache key is an atomic
+ * insert (`SADD` on Redis, a native `Set` in the single-process memory store).
+ * This eliminates the lost-update race the previous JSON-array read-modify-write
+ * had: two concurrent mutations appending to the same tag (whether across Redis
+ * instances or interleaved in one process at the read/write await gap) no longer
+ * drop an entry, so `revalidateTag` reliably evicts every tagged key. The index
+ * key carries the cache TTL (refreshed on each add), so it self-prunes. A custom
+ * store WITHOUT the primitives falls back to the old JSON-array path, which keeps
+ * the documented non-atomic caveat (prefer a short `ttl` as the cross-instance
+ * floor there). The HTML-side analog `revalidatePath` (#241) still carries the
+ * older caveat and is a separate follow-up.
  *
  * @module cache-tags
  */
@@ -44,16 +46,30 @@ function tagKey(tag) {
   return `${TAG_PREFIX}${tag}`;
 }
 
+/** @param {import('./cache.js').CacheStore} store */
+function supportsAtomicSets(store) {
+  return typeof store.setAdd === 'function' && typeof store.setMembers === 'function';
+}
+
 /**
  * Read the cache-key set stored under one tag. Returns a plain array (empty
- * on a miss / parse error, failing open). The store holds a JSON array.
+ * on a miss / parse error, failing open). Reads via the store's SET primitive
+ * when available (the atomic path), else parses the legacy JSON array.
  *
  * @param {string} tag
  * @returns {Promise<string[]>}
  */
 async function readTagKeys(tag) {
+  const store = getStore();
+  if (supportsAtomicSets(store)) {
+    try {
+      return await store.setMembers(tagKey(tag));
+    } catch {
+      return [];
+    }
+  }
   try {
-    const raw = await getStore().get(tagKey(tag));
+    const raw = await store.get(tagKey(tag));
     if (!raw) return [];
     const arr = JSON.parse(raw);
     return Array.isArray(arr) ? arr : [];
@@ -79,13 +95,21 @@ async function readTagKeys(tag) {
 export async function addKeyToTags(tags, cacheKey, ttlMs) {
   if (!Array.isArray(tags) || tags.length === 0) return;
   const store = getStore();
+  const atomic = supportsAtomicSets(store);
   for (const tag of tags) {
     if (typeof tag !== 'string' || !tag) continue;
     try {
-      const keys = await readTagKeys(tag);
-      if (keys.includes(cacheKey)) continue;
-      keys.push(cacheKey);
-      await store.set(tagKey(tag), JSON.stringify(keys), ttlMs);
+      if (atomic) {
+        // Atomic set insert: no read-modify-write, so a concurrent add to the
+        // same tag (across instances or interleaved in-process) cannot lose
+        // this key. SADD dedups, so no membership pre-check is needed.
+        await store.setAdd(tagKey(tag), cacheKey, ttlMs);
+      } else {
+        const keys = await readTagKeys(tag);
+        if (keys.includes(cacheKey)) continue;
+        keys.push(cacheKey);
+        await store.set(tagKey(tag), JSON.stringify(keys), ttlMs);
+      }
     } catch {
       /* a tag-index write failure must never affect the cached value */
     }

package/src/cache.js

@@ -23,6 +23,15 @@
  * @property {(key: string, ttlMs?: number) => Promise<number>} increment
  *   Atomically increment a counter. Returns the new value. Creates the
  *   key with value 1 if it doesn't exist. TTL is set on creation only.
+ * @property {((key: string, member: string, ttlMs?: number) => Promise<void>)} [setAdd]
+ *   OPTIONAL. Atomically add `member` to the SET stored at `key`, refreshing the
+ *   key's TTL. Eliminates the lost-update race of a read-modify-write JSON array
+ *   (the tag index in `cache-tags.js`, #752). A store WITHOUT this method makes
+ *   the tag index fall back to the non-atomic JSON path (the documented caveat).
+ *   Paired with `setMembers`; implement both or neither.
+ * @property {((key: string) => Promise<string[]>)} [setMembers]
+ *   OPTIONAL. Return the members of the SET stored at `key` (empty array on a
+ *   miss). The read counterpart of `setAdd`.
  */
 
 /**
@@ -98,6 +107,28 @@ export function memoryStore(opts = {}) {
       map.set(key, entry);
       return next;
     },
+    // Atomic SET ops (#752). The entry value for a set key is a native `Set`
+    // (not a JSON string), so the add is a single synchronous mutation with no
+    // read-modify-write await gap: concurrent `setAdd` calls in one process
+    // cannot lose an entry. Only the tag index uses these keys, so the mixed
+    // value type (string for normal keys, Set for set keys) never collides with
+    // `get`/`increment`. The key still rides the same LRU + TTL machinery.
+    async setAdd(key, member, ttlMs) {
+      const entry = map.get(key);
+      const set = entry && !isExpired(entry) && entry.value instanceof Set
+        ? entry.value
+        : new Set();
+      set.add(member);
+      map.delete(key); // re-insert at the end (LRU) + refresh TTL like Redis EXPIRE
+      map.set(key, { value: set, expiresAt: expiresAtFrom(ttlMs) });
+      evict();
+    },
+    async setMembers(key) {
+      const entry = map.get(key);
+      if (!entry) return [];
+      if (isExpired(entry)) { map.delete(key); return []; }
+      return entry.value instanceof Set ? [...entry.value] : [];
+    },
   };
 }
 
@@ -172,6 +203,28 @@ export function redisStore(opts = {}) {
       }
       return val;
     },
+    // Atomic SET ops (#752): SADD is an atomic set insert across instances, so
+    // the tag index no longer loses a concurrent append the way a JSON-array
+    // read-modify-write did. A per-member TTL is not native to a Redis set, so
+    // refresh the whole key's expiry on each add (PEXPIRE), keeping the
+    // short-TTL floor as defense-in-depth. ioredis uses lowercase command names
+    // (`sadd`); node-redis v4 uses camelCase (`sAdd`), so probe both.
+    async setAdd(key, member, ttlMs) {
+      const c = await getClient();
+      if (typeof c.sadd === 'function') await c.sadd(key, member);
+      else await c.sAdd(key, member);
+      if (ttlMs) {
+        if (typeof c.pexpire === 'function') await c.pexpire(key, ttlMs);
+        else await c.pExpire(key, ttlMs);
+      }
+    },
+    async setMembers(key) {
+      const c = await getClient();
+      const members = typeof c.smembers === 'function'
+        ? await c.smembers(key)
+        : await c.sMembers(key);
+      return Array.isArray(members) ? members : [];
+    },
   };
 }