webspresso 0.0.65 → 0.0.67

package/README.md

@@ -15,7 +15,9 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **Lifecycle Hooks**: Global and route-level hooks for request processing
 - **Template Helpers**: Laravel-inspired helper functions available in templates
 - **Plugin System**: Extensible architecture with version control and inter-plugin communication
-- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint, optional REST CRUD routes from ORM models
+- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint, optional REST CRUD routes from ORM models, optional admin UI for ORM query cache metrics and purge
+- **Session authentication** (optional): `createAuth` / `quickAuth` in **`webspresso/core/auth`** — pass the manager to **`createApp({ auth })`** for `express-session`, `req.user` / `req.auth`, remember-me tokens, and policy-style authorization. Full walkthrough: **[`doc/index.html#authentication`](doc/index.html#authentication)**.
+- **Optional client runtime** (Alpine.js + [swup](https://swup.js.org/)): **`createApp({ clientRuntime: { alpine, swup } })`** serves scripts under **`/__webspresso/client-runtime/`** and exposes **`clientRuntime`** in Nunjucks; layouts can include **`views/partials/webspresso-client-runtime.njk`**. Env overrides: **`WEBSPRESSO_ALPINE`**, **`WEBSPRESSO_SWUP`**. Demo: **`examples/alpine-swup-demo/`**. Details: **[`doc/index.html#client-runtime`](doc/index.html#client-runtime)**.
 - **TypeScript**: Published **`index.d.ts`** (via `package.json` `"types"`) for `createApp`, ORM, plugins, and router helpers — use from TS/JS with IDE autocomplete; runtime stays CommonJS
 
 ## Installation
@@ -356,6 +358,9 @@ Creates and configures the Express app.
   - `false`: Disable Helmet
   - `Object`: Custom Helmet configuration (merged with defaults)
 - `middlewares` (optional): Named middleware registry for routes
+- `clientRuntime` (optional): **`{ alpine?: boolean | object, swup?: boolean | object }`**. When either flag is enabled, mounts vendored Alpine 3 / swup 4 (+ Head + Scripts plugins) at **`/__webspresso/client-runtime/*`** and passes resolved **`{ alpine, swup }`** into SSR templates as **`clientRuntime`**. Override with env **`WEBSPRESSO_ALPINE`** / **`WEBSPRESSO_SWUP`** (`1` or `true`). Package exports **`resolveClientRuntime`** and **`CLIENT_RUNTIME_BASE`**. See **[Client runtime](#client-runtime)** below and **[`doc/index.html#client-runtime`](doc/index.html#client-runtime)**.
+- `auth` (optional): `AuthManager` from **`createAuth()`** / **`quickAuth()`** (`require('webspresso/core/auth')`). Registers session + cookie parsing, attaches **`req.auth`** / **`req.user`**, and injects named route middleware **`auth`** and **`guest`** (do not reuse those names for custom handlers if you pass `auth`). See **[`doc/index.html#authentication`](doc/index.html#authentication)**.
+- `setupRoutes(app, ctx)` (optional): Register custom Express routes after file routes and plugin `onRoutesReady`, before the 404 handler — use for login/logout handlers when using the auth module; **`ctx.authMiddleware`** exposes `requireAuth`, `requireGuest`, etc.; **`ctx.clientRuntime`** is **`{ alpine, swup }`**
 
 **Example with middlewares:**
 
@@ -399,6 +404,48 @@ module.exports = {
 };
 ```
 
+**Parameterized named middleware:** entries in `middlewares` can be **factories** `(options) => (req, res, next) => …`. A bare string calls the factory with `{}`; a **tuple** passes options:
+
+```javascript
+// pages/api/account.get.js
+module.exports = {
+  middleware: [['auth', { api: true }], 'rateLimit'], // JSON 401 instead of redirect when using createApp({ auth })
+  handler: (req, res) => res.json({ ok: true }),
+};
+
+// server.js — custom factory
+middlewares: {
+  oauth: (opts) => (req, res, next) => {
+    if (opts.google && !req.headers['x-google']) return res.status(401).end();
+    next();
+  },
+};
+// pages/example/index.js → middleware: [['oauth', { google: true }], 'auth']
+```
+
+Plain `(req, res, next) => …` handlers still work as today. Tuple form **requires** a factory for that name (you get a clear error if you mix a plain handler with `['name', opts]`).
+
+### Client runtime
+
+Alpine.js + swup — opt-in progressive enhancement for SSR pages:
+
+- **`clientRuntime: { alpine: true, swup: true }`** (each can be toggled independently). Default is off; no scripts are injected when both are disabled.
+- Include **`{% include "partials/webspresso-client-runtime.njk" %}`** in your layout (copy from the npm package’s **`views/partials/`** or the framework repo). When **swup** is on, wrap the main content in **`<main id="swup">…</main>`** so transitions replace the correct region.
+- **swup** uses Head + Scripts plugins; **Alpine** is re-bound after each visit via **`Alpine.initTree`** on the container. Use **`data-no-swup`** on links for a full page load. Paths **`/_admin`** and **`/_webspresso`** are ignored by the default bootstrap; the admin panel and dev dashboard stay separate Mithril apps.
+- Dynamic UI can call **`pages/api/*`** from Alpine with **`fetch`** (see **`examples/alpine-swup-demo/`**).
+- **Helmet / CSP**: production **`script-src 'self'`** works for **`/__webspresso/client-runtime/`**; some Alpine builds may need **`unsafe-eval`** — validate for your version or use a stricter build.
+
+```javascript
+const { createApp } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  publicDir: './public',
+  clientRuntime: { alpine: true, swup: true },
+});
+```
+
 ### App context (`req.db`, `getDb`, `attachDbMiddleware`)
 
 With **`createApp({ db })`**, file-based **API** routes (`pages/api/*.js`) get the same ORM instance on **`req.db`** before your **`middleware`** array and the handler run — no extra `require` in the handler:
@@ -549,7 +596,15 @@ Works with Vite and Webpack manifest formats:
 }
 ```
 
-**Returns:** `{ app, nunjucksEnv, pluginManager }`
+**Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware }` — `authMiddleware` is `null` when `auth` was not passed.
+
+### Authentication (session)
+
+Optional **session-based** auth lives under **`webspresso/core/auth`**: **`createAuth`**, **`quickAuth`**, **`hash`** / **`verify`**, **`setupAuthMiddleware`**, **`createRememberTokensTable`**, and policy helpers. Pass the manager to **`createApp({ auth })`** so routes can use **`middleware: ['auth']`** or **`['guest']`** and handlers can call **`req.auth.attempt()`**, **`req.auth.logout()`**, **`req.auth.can()`**, etc.
+
+The **admin panel** plugin uses its **own** session and `/api/auth/*` routes (`req.session.adminUser`) — it is separate from **`createApp({ auth })`**.
+
+For integration patterns (remember-me table, `setupRoutes`, file-router ordering), see **[`doc/index.html#authentication`](doc/index.html#authentication)**.
 
 ## Plugin System
 
@@ -838,6 +893,23 @@ const { app } = createApp({
 
 Programmatic API (other plugins): `ctx.usePlugin('audit-log')` exposes `queryLogs`, `purgeAuditLogs`, and `getMigrationTemplate()`.
 
+**ORM cache admin plugin:**
+- Depends on **`adminPanelPlugin`** and a database instance created with **`createDatabase({ cache: true | { … } })`** so **`db.cache`** is non-null
+- Registers an **ORM Cache** admin page (metrics, full purge, per-model invalidation, reset counters) backed by **`db.cache`**
+- If `db.cache` is disabled, the plugin logs a warning and skips registration
+
+```javascript
+const { adminPanelPlugin, ormCacheAdminPlugin } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  plugins: [
+    adminPanelPlugin({ db }),
+    ormCacheAdminPlugin({ db }),
+  ],
+});
+```
+
 **reCAPTCHA plugin:**
 - Google reCAPTCHA **v2** (checkbox) or **v3** (score): server verification via `https://www.google.com/recaptcha/api/siteverify` (no extra npm dependency; Node 18+ `fetch`)
 - Registers CSP entries for Google scripts/iframes; Nunjucks helpers: `recaptchaScript`, `recaptchaWidget` (v2), `recaptchaV3Token` (hidden input + execute for v3 — use with `version: 'v3'` and `recaptchaScript` loads `api.js?render=siteKey`)
@@ -1562,6 +1634,52 @@ await db.transaction(async (trx) => {
 });
 ```
 
+**ORM reads inside `db.transaction()` always bypass the query cache** (Knex transaction client), so you never serve stale rows mid-transaction.
+
+### ORM query cache (optional)
+
+Enable an in-process, tag-based cache for common read paths. Default provider is in-memory (`createMemoryCacheProvider`); you can pass a custom **`provider`** with the same shape (`get`, `set` with optional `tags` / `ttlMs`, `invalidateTags`, `clear`, `getSizeStats`).
+
+**Turn it on:**
+
+```javascript
+const db = createDatabase({
+  client: 'pg',
+  connection: process.env.DATABASE_URL,
+  models: './models',
+  cache: true, // same as { enabled: true, defaultStrategy: 'auto', memory provider }
+  // cache: {
+  //   enabled: true,
+  //   defaultStrategy: 'auto', // or 'smart'
+  //   memory: { maxEntries: 50_000, defaultTtlMs: undefined },
+  //   // provider: myRedisLikeAdapter,
+  // },
+});
+```
+
+When enabled, **`db.cache`** exposes **`purge()`**, **`invalidateTags(string[])`**, **`invalidateModel('ModelName')`**, **`getMetrics()`**, and **`resetMetrics()`**. When the cache is off, **`db.cache`** is **`null`**.
+
+**Per-model opt-in / strategy** (inherits the database **`defaultStrategy`** when set to `true`):
+
+```javascript
+defineModel({
+  name: 'User',
+  table: 'users',
+  schema: UserSchema,
+  cache: true,              // use db defaultStrategy
+  // cache: 'auto', // invalidate all cached reads for this model on any row change
+  // cache: 'smart', // finer-grained tags: PK reads vs list/collection queries
+  // cache: { strategy: 'smart' },
+  // cache: false,         // never cache this model
+});
+```
+
+**What gets cached:** **`findById`**, **`findOne`**, **`findAll`**, and query builder **`first`**, **`list`**, **`count`**, **`paginate`** — only when the model participates in caching and the read is not on a transaction connection. Some query shapes are never cached (e.g. raw `where` fragments); the layer increments a **`bypassed`** metric for those.
+
+**Invalidation:** Hooks on **`afterCreate`**, **`afterUpdate`**, **`afterDelete`**, and **`afterRestore`** schedule tag invalidation after the Knex transaction commits (when applicable). With **`auto`**, every mutation clears all cache entries tagged for that model. With **`smart`**, creates invalidate collection query tags; updates/deletes target the row’s primary key tag plus collection tags when the record exposes an id (falls back to full-model invalidation if the id is missing). Bulk **`updateWhere`** / query-builder **`update`** / **`delete`** that affect rows call **`invalidateModelAll`** for safety.
+
+**Exports:** **`createMemoryCacheProvider`**, **`OrmCacheLayer`**, and **`createOrmCacheFromConfig`** are available from **`webspresso`** for advanced/testing setups.
+
 ### Migrations
 
 **CLI Commands:**

package/core/auth/middleware.js

@@ -223,9 +223,9 @@ function createAuthMiddleware(authManager) {
     // Utility
     parseMiddlewareString,
     
-    // Aliases for route config
-    auth: requireAuth(),
-    guest: requireGuest(),
+    // Aliases for route config (factories — file-router calls requireAuth(opts) / requireGuest(opts))
+    auth: requireAuth,
+    guest: requireGuest,
   };
 }
 

package/core/orm/cache/fingerprint.js

@@ -0,0 +1,73 @@
+/**
+ * Stable cache key fingerprint for ORM reads
+ * @module core/orm/cache/fingerprint
+ */
+
+const crypto = require('crypto');
+
+/**
+ * @param {*} v
+ * @returns {*}
+ */
+function stableValue(v) {
+  if (v === null || v === undefined) return v;
+  if (typeof v !== 'object') return v;
+  if (Array.isArray(v)) return v.map(stableValue);
+  const keys = Object.keys(v).sort();
+  const out = {};
+  for (const k of keys) out[k] = stableValue(v[k]);
+  return out;
+}
+
+/**
+ * @param {import('../types').ScopeContext} scopeContext
+ */
+function scopeFingerprint(scopeContext) {
+  return {
+    tenantId: scopeContext.tenantId,
+    withTrashed: !!scopeContext.withTrashed,
+    onlyTrashed: !!scopeContext.onlyTrashed,
+  };
+}
+
+/**
+ * @param {import('../types').QueryState} state
+ */
+function serializeWheres(wheres) {
+  return wheres.map((w) => {
+    if (w.raw) {
+      return { raw: true, sql: w.sql, bindings: w.bindings, boolean: w.boolean };
+    }
+    return {
+      column: w.column,
+      operator: w.operator,
+      value: w.value,
+      boolean: w.boolean,
+    };
+  });
+}
+
+/**
+ * @param {import('../model').ModelDefinition} model
+ * @param {import('../types').ScopeContext} scopeContext
+ * @param {object} parts
+ * @returns {string} hex key
+ */
+function hashKey(model, scopeContext, parts) {
+  const payload = stableValue({
+    model: model.name,
+    table: model.table,
+    pk: model.primaryKey,
+    scope: scopeFingerprint(scopeContext),
+    ...parts,
+  });
+  const json = JSON.stringify(payload);
+  return crypto.createHash('sha256').update(json).digest('hex').slice(0, 40);
+}
+
+module.exports = {
+  stableValue,
+  scopeFingerprint,
+  serializeWheres,
+  hashKey,
+};

package/core/orm/cache/index.js

@@ -0,0 +1,73 @@
+/**
+ * ORM query cache (memory provider + tag invalidation)
+ * @module core/orm/cache
+ */
+
+const { createMemoryCacheProvider } = require('./memory-provider');
+const { OrmCacheLayer } = require('./layer');
+const { registerOrmCacheListeners, unregisterOrmCacheListeners } = require('./listeners');
+
+/**
+ * @param {boolean|object} cacheConfig - true | { enabled, defaultStrategy, provider, memory }
+ * @returns {{ layer: OrmCacheLayer|null, publicApi: object|null }}
+ */
+function createOrmCacheFromConfig(cacheConfig) {
+  const normalized = normalizeCacheConfig(cacheConfig);
+  if (!normalized) {
+    return { layer: null, publicApi: null };
+  }
+
+  const provider =
+    normalized.provider || createMemoryCacheProvider(normalized.memory || {});
+
+  const layer = new OrmCacheLayer(provider, {
+    defaultStrategy: normalized.defaultStrategy,
+    providerKind: normalized.provider ? 'custom' : 'memory',
+  });
+
+  registerOrmCacheListeners(layer);
+
+  const publicApi = {
+    purge: () => layer.purge(),
+    invalidateTags: (tags) => layer.invalidateTags(tags),
+    invalidateModel: (modelName) => {
+      const { getModel } = require('../model');
+      const model = getModel(modelName);
+      if (model) layer.invalidateModelAll(model);
+    },
+    getMetrics: () => ({
+      ...layer.getMetrics(),
+      providerKind: layer.providerKind || 'memory',
+    }),
+    resetMetrics: () => layer.resetMetrics(),
+  };
+
+  return { layer, publicApi };
+}
+
+/**
+ * @param {boolean|object|undefined} cacheConfig
+ */
+function normalizeCacheConfig(cacheConfig) {
+  if (cacheConfig === true) {
+    return { enabled: true, defaultStrategy: 'auto', provider: null, memory: {} };
+  }
+  if (!cacheConfig || cacheConfig.enabled === false) {
+    return null;
+  }
+  return {
+    enabled: true,
+    defaultStrategy: cacheConfig.defaultStrategy === 'smart' ? 'smart' : 'auto',
+    provider: cacheConfig.provider || null,
+    memory: cacheConfig.memory || {},
+  };
+}
+
+module.exports = {
+  createOrmCacheFromConfig,
+  normalizeCacheConfig,
+  createMemoryCacheProvider,
+  OrmCacheLayer,
+  registerOrmCacheListeners,
+  unregisterOrmCacheListeners,
+};

package/core/orm/cache/layer.js

@@ -0,0 +1,314 @@
+/**
+ * ORM cache orchestration: metrics, strategy, read wrapper, invalidation helpers
+ * @module core/orm/cache/layer
+ */
+
+const { hashKey, serializeWheres } = require('./fingerprint');
+
+/**
+ * @param {*} knex
+ */
+function isTransactionKnex(knex) {
+  return !!(knex && knex.isTransaction);
+}
+
+/**
+ * @param {import('../model').ModelDefinition} model
+ * @returns {'auto'|'smart'|null}
+ */
+function modelCacheStrategy(model, defaultStrategy) {
+  const c = model.cache;
+  if (c === false || c === undefined || c === null) return null;
+  if (c === true) return defaultStrategy;
+  if (c === 'auto' || c === 'smart') return c;
+  if (typeof c === 'object' && c.strategy) {
+    return c.strategy === 'smart' ? 'smart' : 'auto';
+  }
+  return defaultStrategy;
+}
+
+function cloneForCache(value) {
+  if (value === undefined) return undefined;
+  if (typeof structuredClone === 'function') return structuredClone(value);
+  return JSON.parse(JSON.stringify(value));
+}
+
+class OrmCacheLayer {
+  /**
+   * @param {import('./types').CacheProvider} provider
+   * @param {object} [options]
+   * @param {'auto'|'smart'} [options.defaultStrategy='auto']
+   */
+  constructor(provider, options = {}) {
+    this.provider = provider;
+    this.providerKind = options.providerKind || 'memory';
+    this.defaultStrategy = options.defaultStrategy || 'auto';
+    this.metrics = {
+      hits: 0,
+      misses: 0,
+      sets: 0,
+      invalidations: 0,
+      bypassed: 0,
+    };
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   */
+  strategyFor(model) {
+    return modelCacheStrategy(model, this.defaultStrategy);
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {*} knex
+   */
+  shouldBypassRead(model, knex) {
+    if (!this.provider) return true;
+    if (!this.strategyFor(model)) return true;
+    if (isTransactionKnex(knex)) return true;
+    return false;
+  }
+
+  resetMetrics() {
+    this.metrics.hits = 0;
+    this.metrics.misses = 0;
+    this.metrics.sets = 0;
+    this.metrics.invalidations = 0;
+    this.metrics.bypassed = 0;
+  }
+
+  getMetrics() {
+    const { entries, tags } = this.provider.getSizeStats();
+    const { hits, misses, sets, invalidations, bypassed } = this.metrics;
+    const lookups = hits + misses;
+    const hitRate = lookups > 0 ? hits / lookups : null;
+    return {
+      hits,
+      misses,
+      sets,
+      invalidations,
+      bypassed,
+      hitRate,
+      approxKeys: entries,
+      approxTags: tags,
+      enabled: true,
+      providerKind: this.providerKind,
+    };
+  }
+
+  invalidateTags(tags) {
+    const uniq = [...new Set(tags.filter(Boolean))];
+    if (uniq.length === 0) return;
+    this.provider.invalidateTags(uniq);
+    this.metrics.invalidations += 1;
+  }
+
+  purge() {
+    this.provider.clear();
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {string} fingerprintKey
+   * @param {string[]} tags
+   * @param {() => Promise<*>} executor
+   * @param {(*)=>boolean} [shouldCache]
+   */
+  async wrapRead(model, knex, scopeContext, fingerprintKey, tags, executor, shouldCache = () => true) {
+    if (this.shouldBypassRead(model, knex)) {
+      this.metrics.bypassed += 1;
+      return executor();
+    }
+
+    const cached = this.provider.get(fingerprintKey);
+    if (cached !== undefined) {
+      this.metrics.hits += 1;
+      return cloneForCache(cached);
+    }
+
+    this.metrics.misses += 1;
+    const result = await executor();
+
+    if (shouldCache(result)) {
+      this.provider.set(fingerprintKey, cloneForCache(result), { tags });
+      this.metrics.sets += 1;
+    }
+
+    return result;
+  }
+
+  /**
+   * Deferred invalidation after Knex transaction commit
+   * @param {*} ctxTrx - createEventContext trx
+   * @param {string[]} tags
+   */
+  scheduleInvalidate(ctxTrx, tags) {
+    const uniq = [...new Set(tags.filter(Boolean))];
+    if (uniq.length === 0) return;
+
+    if (!ctxTrx) {
+      this.invalidateTags(uniq);
+      return;
+    }
+
+    const p = ctxTrx.executionPromise;
+    if (p && typeof p.then === 'function') {
+      p.then(() => {
+        this.invalidateTags(uniq);
+      }).catch(() => {});
+    } else {
+      this.invalidateTags(uniq);
+    }
+  }
+
+  /**
+   * Build tags for a read operation
+   * @param {import('../model').ModelDefinition} model
+   * @param {'auto'|'smart'} strategy
+   * @param {'pk'|'collection'} kind
+   * @param {string|number|null} [pkValue]
+   */
+  buildReadTags(model, strategy, kind, pkValue) {
+    const base = [`model:${model.name}`, `table:${model.table}`];
+    if (strategy === 'auto') return base;
+    if (kind === 'pk' && pkValue != null) {
+      return [...base, `pk:${model.name}:${pkValue}`];
+    }
+    return [...base, `q:${model.name}`];
+  }
+
+  /**
+   * Classify query builder state for smart caching
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').QueryState} state
+   * @param {'first'|'list'|'count'|'paginate'} op
+   */
+  classifyQueryBuilder(model, state, op) {
+    const hasRaw = state.wheres.some((w) => w.raw);
+    if (hasRaw) return { cacheable: false, kind: 'collection' };
+
+    if (state.withs.length > 0) return { cacheable: true, kind: 'collection' };
+
+    if (op === 'count' || op === 'paginate' || op === 'list') {
+      return { cacheable: true, kind: 'collection' };
+    }
+
+    // first()
+    if (state.wheres.length !== 1) return { cacheable: true, kind: 'collection' };
+
+    const w = state.wheres[0];
+    if (w.raw || w.boolean === 'or') return { cacheable: true, kind: 'collection' };
+    if (w.column !== model.primaryKey || w.operator !== '=') {
+      return { cacheable: true, kind: 'collection' };
+    }
+
+    return { cacheable: true, kind: 'pk', pkValue: w.value };
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {import('../types').QueryState} state
+   * @param {'first'|'list'|'count'|'paginate'} op
+   * @param {object} [extra] e.g. { page, perPage } for paginate
+   */
+  queryBuilderFingerprint(model, scopeContext, state, op, extra = {}) {
+    return hashKey(model, scopeContext, {
+      op,
+      selects: [...state.selects].sort(),
+      wheres: serializeWheres(state.wheres),
+      orderBys: state.orderBys,
+      limit: state.limitValue,
+      offset: state.offsetValue,
+      withs: [...state.withs].sort(),
+      extra,
+    });
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {string|number} id
+   * @param {string[]} [select]
+   * @param {string[]} [withs]
+   */
+  findByIdFingerprint(model, scopeContext, id, select = [], withs = []) {
+    return hashKey(model, scopeContext, {
+      op: 'findById',
+      id: String(id),
+      select: [...select].sort(),
+      withs: [...withs].sort(),
+    });
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {Record<string, *>} conditions
+   * @param {string[]} [select]
+   * @param {string[]} [withs]
+   */
+  findOneFingerprint(model, scopeContext, conditions, select = [], withs = []) {
+    return hashKey(model, scopeContext, {
+      op: 'findOne',
+      conditions: Object.keys(conditions)
+        .sort()
+        .reduce((acc, k) => {
+          acc[k] = conditions[k];
+          return acc;
+        }, {}),
+      select: [...select].sort(),
+      withs: [...withs].sort(),
+    });
+  }
+
+  /**
+   * @param {import('../model').ModelDefinition} model
+   * @param {import('../types').ScopeContext} scopeContext
+   * @param {string[]} [select]
+   */
+  findAllFingerprint(model, scopeContext, select = []) {
+    return hashKey(model, scopeContext, {
+      op: 'findAll',
+      select: [...select].sort(),
+    });
+  }
+
+  /**
+   * Conservative invalidation for a model (auto-equivalent)
+   * @param {import('../model').ModelDefinition} model
+   */
+  invalidateModelAll(model) {
+    this.invalidateTags([`model:${model.name}`, `table:${model.table}`]);
+  }
+
+  /**
+   * Smart / auto write tags
+   * @param {import('../model').ModelDefinition} model
+   * @param {'auto'|'smart'} strategy
+   * @param {'create'|'update'|'delete'|'restore'} op
+   * @param {*} [record] for pk
+   */
+  tagsForMutation(model, strategy, op, record) {
+    const name = model.name;
+    const table = model.table;
+    if (strategy === 'auto') {
+      return [`model:${name}`, `table:${table}`];
+    }
+    // smart: avoid invalidating `model:` / `table:` on every row write (would flush all PK rows)
+    if (op === 'create') {
+      return [`q:${name}`];
+    }
+    const id = record && record[model.primaryKey];
+    if (id == null) return [`model:${name}`, `table:${table}`];
+    return [`pk:${name}:${id}`, `q:${name}`];
+  }
+}
+
+module.exports = {
+  OrmCacheLayer,
+  modelCacheStrategy,
+  isTransactionKnex,
+};