@everystack/server 0.4.37 → 0.4.39

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `@everystack/server` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.39] - 2026-10-23
+
+### BREAKING CHANGES
+
+- lifecycle: { deleteWhen } refuses deleting a row its predicate does not allow
+- one lifecycle hook API: (rows, ctx), veto(reason), beforeStamp
+- deleteWhen spliced on its own lines; a deleted reader is not granted deleted_by
+
+## [0.4.38] - 2026-10-23
+
+### Added
+
+- make a broken KVS purge loud with EMF metrics and kvsPurgeCheck
+- cache.htmlByPath, a per-path Cache-Control for unauthenticated HTML
+- db:provision creates the reserved lifecycle role (P2.7)
+- everystack.purge_log, append-only
+- purgeExpired, the core
+- purge refuses a graph it does not understand
+- purge cannot starve, and is bounded
+- db:doctor reports lifecycle rows past the purge window
+
+### Fixed
+
+- sign KVS purges with an explicit SigV4a signer
+- KVS client shares the signer's credentials; prove the send path signs
+- batch KVS purges and retry on ETag conflicts
+- retry KVS purges per path with PutKey, not UpdateKeys
+- a bad metrics setting never stops a KVS purge; check region and retryable faults
+- htmlByPath matches the path the server renders (resolve dot segments)
+- purge_log ensure revokes only from roles that hold a grant
+- check purge deletion before destroy hooks
+- surface purge after-destroy failures
+- purge refuses an undeclared lifecycle child, and the revoke exempts the table owner
+- a DELETE issued from inside a trigger on a lifecycle table is a soft delete
+
 ## [0.4.37] - 2026-10-18
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -125,6 +125,11 @@
       "source": "./src/restore-witness.ts",
       "types": "./src/restore-witness.ts",
       "default": "./src/restore-witness.ts"
+    },
+    "./purge": {
+      "source": "./src/purge.ts",
+      "types": "./src/purge.ts",
+      "default": "./src/purge.ts"
     }
   },
   "peerDependencies": {
@@ -192,8 +197,11 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/auth": "0.4.9",
-    "@everystack/cli": "0.4.100"
+    "@everystack/cli": "0.4.103",
+    "@everystack/auth": "0.4.9"
+  },
+  "dependencies": {
+    "@everystack/model": "0.4.24"
   },
   "scripts": {
     "test": "jest",

package/src/cache-control.ts

@@ -0,0 +1,36 @@
+import type { ServerCacheConfig } from './index';
+
+const DEFAULT_HTML = 'public, max-age=0, s-maxage=60';
+
+function normalize(path: string): string {
+  let p = path;
+  try { p = decodeURIComponent(path); } catch { /* malformed escape: match the raw path */ }
+  // The server renders the URL after dot segments are resolved (eventToRequest -> new URL), so
+  // `/x/../admin` is the admin shell. Collapse leading slashes first: `//admin` would otherwise
+  // parse as a host. Over-matching here only ever picks the stricter rule.
+  p = '/' + p.split('/').filter(Boolean).join('/');
+  try { p = new URL(p, 'http://h').pathname; } catch { /* keep the collapsed path */ }
+  return '/' + p.split('/').filter(Boolean).join('/');
+}
+
+/**
+ * Cache-Control for an unauthenticated HTML GET: the longest `htmlByPath` prefix that matches
+ * whole path segments, else `html`, else the built-in default. The path is decoded, its slashes
+ * collapsed and its dot segments resolved first, so `/%61dmin`, `//admin` and `/x/../admin` cannot
+ * slip past a rule on `/admin`. Keys that normalize alike: the first declared wins.
+ */
+export function htmlCacheControl(path: string, cache: ServerCacheConfig | undefined): string {
+  const rules = cache?.htmlByPath;
+  if (rules) {
+    const target = normalize(path);
+    let best = '';
+    let value: string | undefined;
+    for (const [prefix, cc] of Object.entries(rules)) {
+      const p = normalize(prefix);
+      const hit = p === '/' || target === p || target.startsWith(p + '/');
+      if (hit && (value === undefined || p.length > best.length)) { best = p; value = cc; }
+    }
+    if (value !== undefined) return value;
+  }
+  return cache?.html ?? DEFAULT_HTML;
+}

package/src/index.ts

@@ -18,6 +18,7 @@ import type {
 import { log } from './log';
 import { buildTimingHeaders } from './timing';
 import { DEFAULT_STRIP_QUERY_PARAMS, stripQueryParams } from './strip-query-params';
+import { htmlCacheControl } from './cache-control';
 
 export { buildTimingHeaders } from './timing';
 export type { TimingHeaderOptions } from './timing';
@@ -72,6 +73,11 @@ export interface ServerCacheConfig {
    *  with no CloudFront invalidation. No stale-while-revalidate: the cap is hard.
    *  Default: 'public, max-age=0, s-maxage=60' */
   html?: string;
+  /** Per-path override of `html`: path prefix → Cache-Control, for unauthenticated HTML.
+   *  Keys match whole path segments (`/admin` covers `/admin` and `/admin/x`, not
+   *  `/administrator`); the longest match wins; no match falls back to `html`.
+   *  Example: `{ '/admin': 'private, no-store' }`. */
+  htmlByPath?: Record<string, string>;
   /** Authenticated GET/HEAD responses.
    *  Default: 'private, no-store' */
   private?: string;
@@ -295,7 +301,7 @@ export function createLambdaHandler(
             // GETs are version-keyed and can cache long.
             const isHtml = String(result.headers['content-type'] || '').includes('text/html');
             result.headers['cache-control'] = isHtml
-              ? (options.cache?.html ?? 'public, max-age=0, s-maxage=60')
+              ? htmlCacheControl(path, options.cache)
               : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
           }
         } else {

package/src/kvs-metrics.ts

@@ -0,0 +1,153 @@
+/**
+ * CloudWatch embedded metric format (EMF) lines for the KVS purge path.
+ *
+ * A line written to stdout in Lambda becomes a CloudWatch metric with no SDK
+ * call and no extra IAM. It is written with `process.stdout.write`, never a
+ * `console` method: under the Lambda JSON log format, Lambda wraps console
+ * output in its own JSON event and CloudWatch does not extract metrics from
+ * the wrapped object.
+ */
+
+export const DEFAULT_KVS_METRICS_NAMESPACE = 'Everystack/Cache';
+export const MAX_KVS_METRIC_DIMENSIONS = 2;
+/** The unpurgedPaths property keeps this many entries; the metric keeps the full count. */
+export const MAX_LOGGED_UNPURGED_PATHS = 20;
+
+export type KvsMetricName =
+  | 'KvsPurgeFailure'
+  | 'KvsPurgePaths'
+  | 'KvsPurgeUnpurgedPaths'
+  | 'KvsPurgeCheckFailure';
+
+export interface KvsMetricsOptions {
+  /** CloudWatch namespace. Default `Everystack/Cache`. */
+  namespace?: string;
+  /**
+   * Replaces the default dimension (`FunctionName` from
+   * AWS_LAMBDA_FUNCTION_NAME). At most 2 keys; `{}` means no dimension.
+   */
+  dimensions?: Record<string, string>;
+  /** Written as a property so one request can be found in Logs Insights. */
+  requestId?: string;
+}
+
+/** `false` turns emission off. */
+export type KvsMetricsSetting = false | KvsMetricsOptions;
+
+export interface ResolvedKvsMetrics {
+  namespace: string;
+  dimensions: Record<string, string>;
+  requestId?: string;
+}
+
+export interface KvsMetricPoint {
+  kvsArn: string;
+  metrics: Partial<Record<KvsMetricName, number>>;
+  unpurgedPaths?: string[];
+}
+
+const PROPERTY_NAMES = ['_aws', 'kvsArn', 'source', 'unpurgedPaths', 'requestId'];
+const METRIC_NAMES: KvsMetricName[] = [
+  'KvsPurgeFailure',
+  'KvsPurgePaths',
+  'KvsPurgeUnpurgedPaths',
+  'KvsPurgeCheckFailure',
+];
+const RESERVED = new Set<string>([...PROPERTY_NAMES, ...METRIC_NAMES]);
+
+/**
+ * Resolve the namespace and dimensions once, at call time. Returns null when
+ * metrics are off. Throws on more than 2 dimensions or a reserved dimension
+ * name; the purge and the check catch that through resolveKvsMetricsOrDefault.
+ */
+export function resolveKvsMetrics(
+  setting?: KvsMetricsSetting,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedKvsMetrics | null {
+  if (setting === false) return null;
+  const options = setting ?? {};
+
+  let dimensions: Record<string, string>;
+  if (options.dimensions) {
+    const names = Object.keys(options.dimensions);
+    if (names.length > MAX_KVS_METRIC_DIMENSIONS) {
+      throw new Error(
+        `KVS metrics: at most ${MAX_KVS_METRIC_DIMENSIONS} dimensions, got ${names.length} `
+          + `(${names.join(', ')}). Put high-cardinality values in properties, not dimensions.`,
+      );
+    }
+    const reserved = names.filter((n) => RESERVED.has(n));
+    if (reserved.length > 0) {
+      throw new Error(
+        `KVS metrics: dimension name ${reserved.join(', ')} is reserved for a property or metric.`,
+      );
+    }
+    dimensions = { ...options.dimensions };
+  } else {
+    const fn = env.AWS_LAMBDA_FUNCTION_NAME;
+    dimensions = fn ? { FunctionName: fn } : {};
+  }
+
+  return {
+    namespace: options.namespace ?? DEFAULT_KVS_METRICS_NAMESPACE,
+    dimensions,
+    ...(options.requestId ? { requestId: options.requestId } : {}),
+  };
+}
+
+/**
+ * Resolve the setting for a purge or a check. A bad setting must never stop a
+ * purge (stale beats down): log one error line naming the problem and fall
+ * back to the default metrics.
+ */
+export function resolveKvsMetricsOrDefault(
+  setting?: KvsMetricsSetting,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedKvsMetrics | null {
+  try {
+    return resolveKvsMetrics(setting, env);
+  } catch (err) {
+    console.error(`KVS metrics setting ignored, using the defaults: ${(err as Error).message}`);
+    return resolveKvsMetrics(undefined, env);
+  }
+}
+
+/** Build one EMF object. Dimensions and metrics are top-level members. */
+export function buildKvsEmf(
+  resolved: ResolvedKvsMetrics,
+  point: KvsMetricPoint,
+  now: number = Date.now(),
+): Record<string, unknown> {
+  const names = METRIC_NAMES.filter((n) => point.metrics[n] !== undefined);
+  return {
+    _aws: {
+      Timestamp: now,
+      CloudWatchMetrics: [{
+        Namespace: resolved.namespace,
+        Dimensions: [Object.keys(resolved.dimensions)],
+        Metrics: names.map((Name) => ({ Name, Unit: 'Count' })),
+      }],
+    },
+    ...resolved.dimensions,
+    ...Object.fromEntries(names.map((n) => [n, point.metrics[n]])),
+    kvsArn: point.kvsArn,
+    source: 'server',
+    ...(point.unpurgedPaths
+      ? { unpurgedPaths: point.unpurgedPaths.slice(0, MAX_LOGGED_UNPURGED_PATHS) }
+      : {}),
+    ...(resolved.requestId ? { requestId: resolved.requestId } : {}),
+  };
+}
+
+/**
+ * Write one EMF line to stdout. Never throws: a metric that cannot be written
+ * must not turn a purge, or a purge failure, into a different error.
+ */
+export function emitKvsMetrics(resolved: ResolvedKvsMetrics | null, point: KvsMetricPoint): void {
+  if (!resolved) return;
+  try {
+    process.stdout.write(JSON.stringify(buildKvsEmf(resolved, point)) + '\n');
+  } catch {
+    // Nothing to do: the metric is lost, the caller's outcome is not.
+  }
+}

package/src/kvs.ts

@@ -9,42 +9,339 @@
  *   import { invalidateKvsPaths } from '@everystack/server/kvs';
  *   await invalidateKvsPaths(kvsArn, ['/api/posts', '/api/profiles']);
  */
+import type { CloudFrontKeyValueStoreClient } from '@aws-sdk/client-cloudfront-keyvaluestore';
+import { emitKvsMetrics, resolveKvsMetricsOrDefault, type KvsMetricsSetting } from './kvs-metrics';
+
+export {
+  buildKvsEmf,
+  DEFAULT_KVS_METRICS_NAMESPACE,
+  emitKvsMetrics,
+  resolveKvsMetrics,
+  resolveKvsMetricsOrDefault,
+  type KvsMetricName,
+  type KvsMetricPoint,
+  type KvsMetricsOptions,
+  type KvsMetricsSetting,
+  type ResolvedKvsMetrics,
+} from './kvs-metrics';
+
+/**
+ * Build a KVS client that signs with an explicit SigV4a signer.
+ *
+ * KVS endpoints require SigV4a. A side-effect `import('@aws-sdk/signature-v4a')`
+ * registers the signer into one copy of @smithy/signature-v4, but the KVS client
+ * can carry a nested copy whose container is empty, and every request then fails
+ * with "Neither CRT nor JS SigV4a implementation is available". When
+ * `config.signer` is set the SDK uses it directly and reads no container.
+ *
+ * The credentials provider and sha256 come from a throwaway client, so the
+ * signer uses the same default chain and hash the SDK would have used.
+ * Same fix as `putKvsKey` in packages/cli/src/cli/aws.ts.
+ */
+export async function createKvsClient(region?: string): Promise<CloudFrontKeyValueStoreClient> {
+  const { SignatureV4a } = await import('@aws-sdk/signature-v4a');
+  const { CloudFrontKeyValueStoreClient } = await import('@aws-sdk/client-cloudfront-keyvaluestore');
+
+  const { credentials, sha256 } = new CloudFrontKeyValueStoreClient({ region }).config;
+  const signer = new SignatureV4a({
+    credentials,
+    region: '*',
+    service: 'cloudfront-keyvaluestore',
+    sha256,
+  });
+  // Same provider on the kept client, so there is one credential chain, not two.
+  return new CloudFrontKeyValueStoreClient({ region, signer, credentials });
+}
+
+/**
+ * One cached client promise per region. The credentials provider refreshes
+ * itself, so a long-lived client is safe; a build that fails is evicted so the
+ * next call tries again.
+ */
+const clients = new Map<string, Promise<CloudFrontKeyValueStoreClient>>();
+
+function getKvsClient(region?: string): Promise<CloudFrontKeyValueStoreClient> {
+  const key = region ?? '';
+  let client = clients.get(key);
+  if (!client) {
+    client = createKvsClient(region);
+    const built = client;
+    built.catch(() => {
+      if (clients.get(key) === built) clients.delete(key);
+    });
+    clients.set(key, client);
+  }
+  return client;
+}
+
+/** Test-only: drop the cached KVS clients so the next purge builds a new one. */
+export function resetKvsClientForTests(): void {
+  clients.clear();
+}
+
+const DEFAULT_MAX_ATTEMPTS = 5;
+const BACKOFF_BASE_MS = 25;
+const BACKOFF_CAP_MS = 400;
+
+export interface InvalidateKvsOptions {
+  /** Wait between conflict retries. Injected by tests. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Attempts per path before giving up. Default 5. */
+  maxAttempts?: number;
+  /**
+   * One EMF line per call, success and failure. `false` turns it off. A bad
+   * setting (more than 2 dimensions, a reserved name) never stops the purge:
+   * it logs one error line and the default metrics are used.
+   */
+  metrics?: KvsMetricsSetting;
+  /**
+   * Region for the KVS client. Default: the SDK's own resolution. Give
+   * `kvsPurgeCheck` the same value so both test and use one client.
+   */
+  region?: string;
+  /**
+   * Called once on failure, before the KvsPurgeError is thrown. Never on
+   * success. If it throws or rejects, the KvsPurgeError is still thrown.
+   */
+  onError?: (error: KvsPurgeError) => void | Promise<void>;
+}
+
+/** A purge that stopped part way. `unpurgedPaths` are the keys NOT written. */
+export class KvsPurgeError extends Error {
+  readonly unpurgedPaths: string[];
+  readonly writtenPaths: string[];
+
+  constructor(
+    message: string,
+    details: { unpurgedPaths: string[]; writtenPaths: string[]; cause: unknown },
+  ) {
+    super(message, { cause: details.cause });
+    this.name = 'KvsPurgeError';
+    this.unpurgedPaths = details.unpurgedPaths;
+    this.writtenPaths = details.writtenPaths;
+  }
+}
+
+/**
+ * A write refused because another writer moved the ETag first. The KVS API
+ * models this as ConflictException (409); 412 PreconditionFailed is matched
+ * too in case the service ever answers with the HTTP precondition status.
+ */
+function isEtagConflict(err: unknown): boolean {
+  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } } | null;
+  const status = e?.$metadata?.httpStatusCode;
+  return status === 409 || status === 412
+    || e?.name === 'ConflictException'
+    || e?.name === 'PreconditionFailed'
+    || e?.name === 'PreconditionFailedException';
+}
+
+function backoffMs(attempt: number): number {
+  const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));
+  return ceiling / 2 + Math.random() * (ceiling / 2);
+}
+
+const realSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
 /**
  * Write a fresh timestamp to each KVS path, invalidating CloudFront caches.
  *
- * Each put changes the ETag, so we re-describe after each write.
- * Dynamically imports AWS SDK to avoid bundling when unused.
+ * Paths are deduped. Each put reads the current ETag and writes with IfMatch.
+ * When another writer moved the ETag first, that path re-reads and retries
+ * with a short jittered backoff. When a path cannot be written, or the client
+ * cannot be built, this throws a KvsPurgeError that lists the paths not
+ * written. Dynamically imports the AWS SDK to avoid bundling it when unused.
+ *
+ * Every call writes ONE EMF metric line after the retries are done, on success
+ * too (`KvsPurgeFailure` 0 or 1, `KvsPurgePaths`, `KvsPurgeUnpurgedPaths`), so
+ * a missing data point means the purge never ran, not that it was healthy.
  */
-export async function invalidateKvsPaths(kvsArn: string, paths: string[]): Promise<void> {
+export async function invalidateKvsPaths(
+  kvsArn: string,
+  paths: string[],
+  options: InvalidateKvsOptions = {},
+): Promise<void> {
   if (!kvsArn || paths.length === 0) return;
 
-  await import('@aws-sdk/signature-v4a');
-  const {
-    CloudFrontKeyValueStoreClient,
-    DescribeKeyValueStoreCommand,
-    PutKeyCommand,
-  } = await import('@aws-sdk/client-cloudfront-keyvaluestore');
-
-  const client = new CloudFrontKeyValueStoreClient({});
-  const desc = await client.send(
-    new DescribeKeyValueStoreCommand({ KvsARN: kvsArn })
-  );
-  let etag = desc.ETag!;
-
-  for (const path of paths) {
-    await client.send(
-      new PutKeyCommand({
-        KvsARN: kvsArn,
-        Key: path,
-        Value: String(Math.floor(Date.now() / 1000)),
-        IfMatch: etag,
-      })
-    );
-    // KVS etag changes after each put — re-describe for next iteration
-    const newDesc = await client.send(
-      new DescribeKeyValueStoreCommand({ KvsARN: kvsArn })
+  const metrics = resolveKvsMetricsOrDefault(options.metrics);
+  const sleep = options.sleep ?? realSleep;
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const unique = [...new Set(paths)];
+
+  let written = 0;
+  try {
+    const {
+      DescribeKeyValueStoreCommand,
+      PutKeyCommand,
+    } = await import('@aws-sdk/client-cloudfront-keyvaluestore');
+
+    const client = await getKvsClient(options.region);
+    const value = String(Math.floor(Date.now() / 1000));
+
+    for (; written < unique.length; written++) {
+      for (let attempt = 1; ; attempt++) {
+        // The ETag moves after every put, ours or another writer's: read it fresh.
+        const desc = await client.send(new DescribeKeyValueStoreCommand({ KvsARN: kvsArn }));
+        try {
+          await client.send(new PutKeyCommand({
+            KvsARN: kvsArn,
+            Key: unique[written],
+            Value: value,
+            IfMatch: desc.ETag!,
+          }));
+          break;
+        } catch (err) {
+          if (!isEtagConflict(err) || attempt >= maxAttempts) throw err;
+          await sleep(backoffMs(attempt));
+        }
+      }
+    }
+  } catch (err) {
+    const unpurged = unique.slice(written);
+    const error = new KvsPurgeError(
+      `KVS purge stopped: ${written} of ${unique.length} paths written; `
+        + `${unpurged.length} ${unpurged.length === 1 ? 'path' : 'paths'} not purged`,
+      { unpurgedPaths: unpurged, writtenPaths: unique.slice(0, written), cause: err },
     );
-    etag = newDesc.ETag!;
+    emitKvsMetrics(metrics, {
+      kvsArn,
+      metrics: { KvsPurgeFailure: 1, KvsPurgePaths: written, KvsPurgeUnpurgedPaths: unpurged.length },
+      unpurgedPaths: unpurged,
+    });
+    if (options.onError) {
+      try {
+        await options.onError(error);
+      } catch {
+        // The purge failure is the error the caller needs; a broken hook must not replace it.
+      }
+    }
+    throw error;
+  }
+
+  emitKvsMetrics(metrics, {
+    kvsArn,
+    metrics: { KvsPurgeFailure: 0, KvsPurgePaths: unique.length, KvsPurgeUnpurgedPaths: 0 },
+    unpurgedPaths: [],
+  });
+}
+
+const DEFAULT_CHECK_TIMEOUT_MS = 3000;
+
+export interface KvsPurgeCheckOptions {
+  /** Give up after this many ms; a timeout is retryable. Default 3000. */
+  timeout?: number;
+  /**
+   * Region for the KVS client. Default: the SDK's own resolution. The check
+   * tests the same client the purges use only when both get the same region:
+   * none here and none on `invalidateKvsPaths`, or the same value on both.
+   */
+  region?: string;
+  /** Same setting as `invalidateKvsPaths`, with the same bad-setting fallback. */
+  metrics?: KvsMetricsSetting;
+}
+
+export type KvsPurgeCheckResult =
+  | { ok: true }
+  | { ok: false; retryable: boolean; error: unknown };
+
+class KvsCheckTimeoutError extends Error {
+  constructor(ms: number) {
+    super(`KVS purge check timed out after ${ms}ms`);
+    this.name = 'KvsCheckTimeoutError';
+  }
+}
+
+const RETRYABLE_NAMES = new Set([
+  'Throttling',
+  'ThrottlingException',
+  'TooManyRequestsException',
+  'RequestTimeout',
+  'RequestTimeoutException',
+  'TimeoutError',
+  'KvsCheckTimeoutError',
+]);
+const NETWORK_CODES = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ETIMEDOUT',
+  'EPIPE',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ENETUNREACH',
+  'EHOSTUNREACH',
+  'ECONNABORTED',
+]);
+
+/**
+ * Retryable: timeout, throttling, 429, 5xx, a server fault, an error the SDK
+ * marks retryable, network. Everything else (403, signer errors, validation,
+ * not found) is a broken purge path.
+ */
+function isRetryableCheckError(err: unknown): boolean {
+  const e = err as {
+    name?: string;
+    code?: string;
+    $fault?: string;
+    $retryable?: unknown;
+    $metadata?: { httpStatusCode?: number };
+  } | null;
+  const status = e?.$metadata?.httpStatusCode;
+  if (status === 429 || (status !== undefined && status >= 500)) return true;
+  if (e?.$fault === 'server' || e?.$retryable) return true;
+  if (e?.name && RETRYABLE_NAMES.has(e.name)) return true;
+  return !!e?.code && NETWORK_CODES.has(e.code);
+}
+
+/**
+ * A read-only check that this Lambda can reach and sign for the store: ONE
+ * DescribeKeyValueStore through the cached client for `region`. With no
+ * `region`, that is the same client purges with no `region` use; pass the
+ * same `region` to both otherwise. It never writes, since a test write would
+ * change the store and race live purges. It never throws.
+ *
+ * Emits `KvsPurgeCheckFailure` 0 on a pass and 1 on a hard failure. A
+ * retryable failure emits nothing, so a cold-start burst does not page.
+ * Nothing calls it for you: call it from your Lambda `init` or a deploy smoke test.
+ */
+export async function kvsPurgeCheck(
+  kvsArn: string,
+  options: KvsPurgeCheckOptions = {},
+): Promise<KvsPurgeCheckResult> {
+  const metrics = resolveKvsMetricsOrDefault(options.metrics);
+
+  const fail = (error: unknown): KvsPurgeCheckResult => {
+    const retryable = isRetryableCheckError(error);
+    if (!retryable) emitKvsMetrics(metrics, { kvsArn, metrics: { KvsPurgeCheckFailure: 1 } });
+    return { ok: false, retryable, error };
+  };
+
+  if (!kvsArn) return fail(new Error('kvsPurgeCheck: kvsArn is empty; purges would do nothing'));
+
+  const ms = options.timeout ?? DEFAULT_CHECK_TIMEOUT_MS;
+  const abort = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      // Reject first so the race settles on the timeout, not on the abort it causes.
+      reject(new KvsCheckTimeoutError(ms));
+      abort.abort();
+    }, ms);
+  });
+
+  const describe = async (): Promise<void> => {
+    const { DescribeKeyValueStoreCommand } = await import('@aws-sdk/client-cloudfront-keyvaluestore');
+    const client = await getKvsClient(options.region);
+    await client.send(new DescribeKeyValueStoreCommand({ KvsARN: kvsArn }), { abortSignal: abort.signal });
+  };
+
+  try {
+    await Promise.race([describe(), timedOut]);
+  } catch (error) {
+    return fail(error);
+  } finally {
+    clearTimeout(timer);
   }
+
+  emitKvsMetrics(metrics, { kvsArn, metrics: { KvsPurgeCheckFailure: 0 } });
+  return { ok: true };
 }