webspresso 0.0.107 → 0.0.108

package/.agents/AGENTS.md

@@ -25,6 +25,7 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Cloud Migration Jobs (Zero-Downtime DB Deploy)** | [`.agents/MIGRATION_JOBS.md`](MIGRATION_JOBS.md) | `bin/commands/add-migration-job.js`, `core/orm/migrate-cloud.js` |
 | **Rate Limiting Engine (Zero-Dependency & Redis)** | [`.agents/RATE_LIMIT.md`](RATE_LIMIT.md) | `core/rate-limit/` |
 | **Feature Flags & Canary Splitter (`core/flags`)** | [`.agents/FLAGS.md`](FLAGS.md) | `core/flags/` |
+| **Ambient Context & Composable Hooks (`core/context`)** | [`.agents/CONTEXT.md`](CONTEXT.md) | `core/context/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](../index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -51,7 +52,7 @@ This `.agents/` customization root is organized into modular topic guides:
 5. **[Graceful Shutdown & Lifecycle](.agents/SHUTDOWN.md)** — `ShutdownManager`, `NodeHttpAdapter`, connection draining, force close mode, and reverse-order plugin disposer cleanup.
 6. **[HTTP Response Compression](.agents/COMPRESSION.md)** — Native streaming zlib compression (`server.compression`), Brotli/Gzip/Deflate negotiation, threshold handling, and `res.compress(false)` route opt-out.
 7. **[Dual Authentication System](.agents/AUTH.md)** — Stateful Session + Cookie & Stateless HS256 JWT + Refresh Token Rotation, `req.auth` helpers, and `middleware: ['jwt']` guard integrations.
-8. **[ORM & Database Layer](.agents/ORM.md)** — Model definitions with `defineModel`, `zdb` schemas, Repositories API, Query Caching, Relations, Soft Delete, Scopes & Migrations.
+8. **[ORM & Database Layer](.agents/ORM.md)** — Model definitions with `defineModel`, `zdb` schemas, `zdb` vs `z` single source of truth, Repositories API, Query Caching, Relations, Soft Delete, Scopes & Migrations.
 9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 20 built-in official plugins (including `webhooksPlugin`, `apiKeyPlugin`, `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
 10. **[Realtime Layer & Adapters](.agents/REALTIME.md)** — Framework-agnostic realtime layer (`core/realtime`), generic WebSocket, SSE, and Socket.IO adapters, subscription identity, backoff reconnect, and auth lifecycle.
 11. **[Email Plugin Guide](.agents/EMAIL.md)** — MJML template compilation, Nodemailer transport, DB delivery logs, Auth Email bridge, and Admin UI.
@@ -75,6 +76,7 @@ This `.agents/` customization root is organized into modular topic guides:
 29. **[Cloud Migration Jobs & Zero-Downtime Database Deploy](.agents/MIGRATION_JOBS.md)** — Dedicated pre-deploy migration jobs for Cloud Run, AWS ECS, and Kubernetes (`webspresso add:migration-job`), connection retries, and stale lock auto-healing (`webspresso db:migrate --safe`).
 30. **[Native Zero-Dependency Rate Limiting Engine](.agents/RATE_LIMIT.md)** — Framework-agnostic rate limiter (`core/rate-limit`), sliding window in-memory & Redis stores, RFC 6585 standard headers (`RateLimit-*`, `Retry-After`), Express & Hono dual support, and `rateLimit({ window, limit })`.
 31. **[Feature Flags & Canary Traffic Splitter](.agents/FLAGS.md)** — Zero-dependency feature flag and canary rollout engine (`core/flags`), deterministic FNV-1a bucketing, targeting rules (users, roles, email domains), A/B variants, SSR template helpers (`fsy.hasFeature`), and declarative API guards (`defineApi({ flag })`).
+32. **[Ambient Context & Composable Hooks](.agents/CONTEXT.md)** — Zero-dependency execution context powered by `AsyncLocalStorage` (`core/context`), eliminating prop drilling across loaders, services, models, and workers with `useContext`, `useDb`, `useAuth`, `useUser`, `useService`, `useLogger`, `useReq`, `useRes`, `useParams`, `useQuery`, `useTransaction`, and `withContext`.
 
 ---
 
@@ -91,3 +93,4 @@ This `.agents/` customization root is organized into modular topic guides:
 - **Zero Regression Policy**: Always run Vitest tests (`npm test` or `npx vitest run`) before declaring any task complete.
 - **Strict Verification**: Inspect authoritative source files for function signatures and schema definitions before writing consuming code.
 - **Log & Traceback Inspection**: Base all bug fixes strictly on exact runtime error log tracebacks and empirical test output.
+- **`zdb` vs `z` Single Source of Truth (NO `schema: z.object` in Models)**: NEVER wrap model schemas in `z.object({...})`. Pass a clean plain object `schema: { ... }` or functional schema `schema: ({ zdb, z }) => ({ ... })`. ALWAYS use `zdb.*` for persistent database columns in `models/*.js` (`zdb.id()`, `zdb.string()`, `zdb.integer()`, `zdb.email()`, etc.) to generate migrations, query filters, and Admin UI controls. Use pure `z.*` ONLY for in-memory request/service payloads (`pages/api/...`, `services/...`). Access raw Zod primitives in models via `zdb.z` without importing `zod`.

package/.agents/CACHE.md

@@ -10,6 +10,7 @@ Webspresso includes a zero-dependency, memory-bounded, leak-free in-memory cache
 2. **Dual Capacity Boundaries**:
    - **`maxEntries`**: Restricts the maximum number of items stored.
    - **`maxBytes` / `maxMemoryMb`**: Enforces strict memory budgets using `approximateByteSize` to prevent process Out-Of-Memory (OOM) crashes under heavy or large payload loads.
+   - **Zero-Overhead Fast Path**: When `maxBytes` is 0 (unlimited byte budget, count-only LRU), deep recursive byte size calculations are automatically bypassed (`0` byte allocation overhead), maximizing throughput on large query and JSON payloads unless explicitly requested via `trackBytes: true`.
 3. **Symmetrical Tag Cleanup (Zero Leaks)**: When an item is evicted via LRU, expired via TTL, or deleted, all associated tag index sets are automatically pruned. Empty tag sets are deleted immediately, preventing the classic "dangling Set memory leak".
 4. **Stampede / Thundering Herd Protection**: `getOrSet(key, asyncFactory)` coalesces concurrent requests for the same missing key, invoking the expensive calculation or DB query exactly once.
 5. **Universal Integration**:

package/.agents/CONTEXT.md

@@ -0,0 +1,152 @@
+# Webspresso Ambient Request & Execution Context (`core/context`)
+
+[← Back to AGENTS.md](AGENTS.md)
+
+Webspresso features an enterprise-grade, zero-dependency **Ambient Request & Execution Context Engine** powered by Node.js `AsyncLocalStorage`. It enables composable hooks (`useContext`, `useDb`, `useAuth`, `useUser`, `useService`, `useLogger`, `useReq`, `useRes`, `useParams`, `useQuery`, `useBreaker`, `useTransaction`, `withContext`) across API handlers, SSR companion loaders, domain services, ORM models, and background workers without parameter threading or prop drilling.
+
+---
+
+## 🎯 Quick Reference: Composable Hooks Matrix
+
+| Hook | Return Type | Description |
+| :--- | :--- | :--- |
+| `useContext()` | `RequestContextStore` | Returns the entire active context object; throws if called outside context. |
+| `getContext()` | `RequestContextStore \| null` | Safe accessor returning active context or `null` without throwing. |
+| `useDb()` | `Database \| null` | Accesses the active database/ORM instance or active transaction instance. |
+| `useAuth()` / `useUser()` | `User \| null` | Accesses the authenticated user or principal object. |
+| `useReq()` | `Request \| null` | Accesses the ambient HTTP request object (Express or Hono). |
+| `useRes()` | `Response \| null` | Accesses the ambient HTTP response object. |
+| `useParams()` | `Record<string, string>` | Accesses URL route parameters (e.g. `{ id: '123' }`). |
+| `useQuery()` | `Record<string, any>` | Accesses URL query parameters (e.g. `{ filter: 'active' }`). |
+| `useService(name, input, opts)` | `Promise<any>` | Dispatches a service call seamlessly using active ambient dependencies. |
+| `useLogger()` | `Logger` | Accesses the ambient request/child logger or falls back to `console`. |
+| `useQueue()` | `Queue \| null` | Accesses the ambient background job queue. |
+| `useCache()` | `Cache \| null` | Accesses the ambient LRU cache engine. |
+| `useBreaker(name, opts)` | `CircuitBreaker \| null` | Retrieves or creates a Circuit Breaker from registry or context. |
+| `useTransaction(callback)` | `Promise<any>` | Initiates a managed transaction on `useDb()`, binding `txDb` to ambient hooks. |
+| `withContext(overrides, fn)` | `any` | Executes `fn` with shallow-merged overrides on top of active context. |
+
+---
+
+## 1. Zero-Prop-Drilling in Domain Services
+
+In complex applications, threading database connections or user objects across nested helper functions leads to tight coupling. With Webspresso hooks, helper utilities access ambient resources directly:
+
+```javascript
+// services/billing/refund.js
+const { defineService, useDb, useAuth, useLogger, useService } = require('webspresso');
+
+async function auditRefund(orderId, amount) {
+  const logger = useLogger();
+  const user = useAuth();
+  logger.info('Processing refund audit', { orderId, user: user?.id });
+  
+  await useService('audit.log', {
+    action: 'order.refund',
+    actorId: user?.id,
+    orderId,
+    amount,
+  });
+}
+
+module.exports = defineService({
+  transaction: true,
+  handler: async ({ orderId, amount }) => {
+    const db = useDb(); // Inside transaction: true, useDb() automatically returns transactional db!
+    const orderRepo = db.getRepository('Order');
+
+    const order = await orderRepo.findById(orderId);
+    if (!order) {
+      throw new NotFoundError('Order not found');
+    }
+
+    await orderRepo.update(order.id, { status: 'refunded' });
+    await auditRefund(order.id, amount);
+
+    return { success: true };
+  },
+});
+```
+
+---
+
+## 2. Using Hooks in API Routes (`pages/api/...`)
+
+```javascript
+// pages/api/profile.get.js
+const { defineApi, useDb, useUser, useQuery } = require('webspresso');
+
+module.exports = defineApi({
+  middleware: ['auth'],
+  handler: async (req, res) => {
+    const user = useUser();
+    const query = useQuery();
+    const db = useDb();
+
+    const profile = await db.getRepository('UserProfile').findOne({ userId: user.id });
+    return res.json({ profile, query });
+  },
+});
+```
+
+---
+
+## 3. Using Hooks in SSR Page Loaders (`pages/...`)
+
+```javascript
+// pages/dashboard.js
+const { definePage, useDb, useUser, useService } = require('webspresso');
+
+module.exports = definePage({
+  middleware: ['auth'],
+  load: async () => {
+    const user = useUser();
+    const db = useDb();
+    const metrics = await useService('dashboard.metrics', { userId: user.id });
+
+    return {
+      user,
+      metrics,
+    };
+  },
+});
+```
+
+---
+
+## 4. Managed Transactions (`useTransaction`)
+
+When performing multi-step transactional operations outside declarative `transaction: true` services:
+
+```javascript
+const { useTransaction, useDb } = require('webspresso');
+
+const result = await useTransaction(async (trx) => {
+  // Inside this block, useDb() automatically resolves to the transactional repository runner
+  const db = useDb();
+  await db.getRepository('Account').decrement('balance', 100);
+  await db.getRepository('Ledger').create({ amount: 100, type: 'debit' });
+  return { committed: true };
+});
+```
+
+---
+
+## 5. Background Jobs & CLI Commands Integration
+
+When executing background jobs (`jobs/`) or CLI tasks, wrap executions with `runWithContext` or `withContext` to seed ambient dependencies:
+
+```javascript
+const { runWithContext, useDb, useService } = require('webspresso');
+
+async function processWorkerJob(job, app) {
+  return await runWithContext({
+    db: app.db,
+    queue: app.queue,
+    logger: app.logger,
+  }, async () => {
+    // Hooks are fully operational inside background job execution!
+    return await useService('emails.sendWelcome', job.data);
+  });
+}
+```

package/.agents/ORM.md

@@ -102,6 +102,80 @@ Instead of manually defining boilerplate timestamp and soft delete columns in `s
 
 *Note: All `zdb` types support chainable `.config({ sortable: boolean })` or options object `{ sortable: boolean }`.*
 
+### 1.1 `zdb` vs `z`: Understanding the Distinction (Single Source of Truth)
+
+It is common for developers new to Webspresso to ask: *"Why does `zdb` exist alongside `z` (Zod)? What is the difference between `zdb.string()` and `z.string()`?"*
+
+#### The Architectural Difference: Decorator over Validator
+
+| Dimension | `z.string()` (Pure Zod Validator) | `zdb.string()` (ORM Column Descriptor + Validator) |
+| :--- | :--- | :--- |
+| **Output Type** | Pure validation rule (`ZodString`) | Database column metadata + Zod validation (`SchemaBuilder`) |
+| **Database & SQL Knowledge** | **None.** Has no awareness of tables, SQL dialects, or migrations. | **Full.** Knows column type (`VARCHAR(255)`), max length, nullability, uniqueness, defaults. |
+| **Auto Migrations (`db:makemigrations`)** | Invisible. Ignored by `diffSchema`. | Generates Knex migrations (`table.string('name', 255)`). |
+| **Admin Panel SPA** | Cannot configure UI form controls. | Auto-renders `<input type="text">`, configures grid sortability, labels, placeholders. |
+| **REST & Query Filters** | Not indexed in column whitelist. | Whitelisted in `model.columns` for safe parameter filtering (`?name[like]=webspresso`). |
+| **JSON Auto-Hydration** | Manual JSON parsing needed. | Auto-serializes on insert/update and auto-deserializes on query. |
+
+#### Why `zdb` Exists: Eliminating 3x Schema Duplication
+In traditional Node.js setups, you must declare column definitions in three separate places:
+1. In a Knex/SQL migration (`table.string('title', 100).notNullable()`)
+2. In an ORM model/entity definition (`title: { type: DataTypes.STRING, ... }`)
+3. In a validation schema (`title: z.string().min(1).max(100)`)
+
+Webspresso uses `zdb` as a **Single Source of Truth**: by writing `title: zdb.string({ maxLength: 100 }).min(1)`, the ORM automatically handles validation, database column generation, query filtering, and admin UI rendering from a single declaration.
+
+#### 💡 The Golden Rule: When to Use Which
+* 🗄️ **Database Models (`models/*.js`):** **ALWAYS use `zdb.*`** (`zdb.id()`, `zdb.string()`, `zdb.integer()`, `zdb.email()`, etc.).
+* 🌐 **API Endpoints (`pages/api/...`) & Services (`services/...`):** **ALWAYS use `z.*`** (`z.object({ email: z.string().email() })`). Here you are validating incoming JSON payloads in RAM, not defining persistent database tables.
+
+#### Accessing Raw Zod Primitives in Models (`zdb.z` or Functional Schema)
+When you need raw Zod features in a model (such as `z.enum()`, `z.union()`, `z.literal()`), you **never need to `require('zod')`**:
+1. **Via Functional Schema (Recommended):**
+   ```javascript
+   module.exports = defineModel({
+     name: 'Article',
+     table: 'articles',
+     schema: ({ zdb, z }) => ({
+       id: zdb.id(),
+       title: zdb.string(),
+       status: z.enum(['draft', 'published', 'archived']),
+     }),
+   });
+   ```
+2. **Via `zdb.z`:**
+   ```javascript
+   const { defineModel, zdb } = require('webspresso');
+
+   module.exports = defineModel({
+     name: 'Article',
+     table: 'articles',
+     schema: {
+       id: zdb.id(),
+       title: zdb.string(),
+       status: zdb.z.enum(['draft', 'published', 'archived']),
+     },
+   });
+   ```
+
+#### ⚠️ Anti-Pattern: Never Wrap Model Schemas in `z.object({...})`
+```javascript
+// ❌ WRONG (Anti-Pattern: forces require('zod'), causes redundant schema wrapping)
+const { z } = require('zod');
+defineModel({
+  schema: z.object({
+    name: zdb.string(),
+  }),
+});
+
+// ✅ CORRECT (Webspresso standard: plain object or functional schema)
+defineModel({
+  schema: {
+    name: zdb.string(),
+  },
+});
+```
+
 ---
 
 ## 2. Repository API

package/.agents/SHUTDOWN.md

@@ -23,6 +23,9 @@ const { app } = createApp({
       mode: 'graceful',      // 'graceful' | 'force'
       timeout: 10_000,       // Max time in ms to wait for active requests (Default: 10000)
       signals: ['SIGINT', 'SIGTERM'],
+      parallel: false,       // Set true to execute async disposers & hooks concurrently (Default: false)
+      parallelDisposers: false, // Fine-grained control over plugin disposers
+      parallelHooks: false,     // Fine-grained control over app.onShutdown hooks
     },
   },
 });
@@ -32,6 +35,10 @@ const { app } = createApp({
 - **`graceful` (Default)**: Rejects new connections, drains active in-flight requests, and closes idle/keep-alive connections.
 - **`force`**: Immediately destroys all active and idle sockets (`forceClose`). Recommended for rapid development/watch server reloads to avoid port lock.
 
+### Concurrency & Performance:
+- **Synchronous Fast-Path**: Synchronous disposers and shutdown hooks execute immediately without creating timers or `Promise.race` wrappers, eliminating microtask delays and timer allocations during exit.
+- **Parallel Mode (`parallel: true`)**: When enabled, asynchronous plugin disposers and hooks are initiated in reverse registration order and awaited concurrently via `Promise.allSettled`, drastically reducing shutdown latency for apps with multiple independent resources (DB, Redis, SQS, WebSockets).
+
 ---
 
 ## 3. Application Lifecycle Hooks
@@ -64,4 +71,4 @@ const customPlugin = {
   },
 };
 ```
-During shutdown, plugin disposers are executed sequentially in **reverse dependency order**.
+During shutdown, plugin disposers are executed in **reverse dependency order** (`reverseDisposers`). When `parallel` is enabled, their initiation order is strictly preserved while awaiting resolution concurrently.

package/.agents/skills/webspresso-framework/SKILL.md

@@ -82,7 +82,8 @@ npx webspresso add tailwind --upgrade
 ## 🏗️ Core Architecture Overview
 
 - **`pages/` & `pages/api/`**: File-based SSR templates (`.njk`), companion data loaders (`.js`), and method-suffixed API endpoints (`.get.js`, `.post.js`).
-- **`services/`**: Auto-discovered domain services mapping to dot-separated names (`'user.create'`).
+- **`services/`**: Auto-discovered domain services mapping to dot-separated names (`'user.create'`), with declarative validation, RBAC, timeouts, and transaction propagation.
+- **Ambient Context & Composable Hooks (`core/context`)**: Zero-dependency `AsyncLocalStorage` hooks (`useContext`, `useDb`, `useAuth`, `useUser`, `useService`, `useLogger`, `useReq`, `useRes`, `useParams`, `useQuery`, `useTransaction`, `useBreaker`, `withContext`) eliminating prop drilling across services, loaders, and background jobs.
 - **`models/`**: Schema-driven ORM models with `zdb` definitions, repositories, relations, scopes, and query cache.
 - **`plugins/`**: Modular extension ecosystem (Admin Panel, Media Library, Polar Billing, CSV/XLSX, Realtime, CSRF, CORS, Basic Auth).
 - **`views/`**: Nunjucks layouts, partials, and `fsy` template helpers.

package/.agents/skills/webspresso-orm-and-database/SKILL.md

@@ -69,6 +69,15 @@ module.exports = defineModel({
 
 ---
 
+## 1.1 `zdb` vs `z` Distinction & Best Practices
+
+- **`zdb.*` (Single Source of Truth for Models):** Decorates Zod with SQL column types, migration info, query filtering, and Admin UI controls. Always use `zdb` for persistent table columns in `models/*.js`.
+- **`z.*` (Pure Validation):** Use only for in-memory request/service validation (`pages/api/...`, `services/...`).
+- **Never wrap in `z.object({...})`:** Pass a plain object `schema: { ... }` or functional schema `schema: ({ zdb, z }) => ({ ... })`.
+- **Raw Zod Types in Models:** Access Zod primitives directly via `zdb.z` or functional schema without importing `zod`.
+
+---
+
 ## 2. Repositories API
 
 ```javascript

package/.agents/skills/webspresso-routing-and-api/SKILL.md

@@ -52,6 +52,20 @@ module.exports = defineApi({
 });
 ```
 
+### Composable Hooks in API Endpoints:
+```javascript
+const { defineApi, useDb, useAuth, useService } = require('webspresso');
+
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const db = useDb();
+    const user = useAuth();
+    const summary = await useService('analytics.userSummary', { userId: user.id });
+    return res.json({ user, summary });
+  },
+});
+```
+
 ---
 
 ## 2. SSR HTML Pages & Data Loaders (`pages/...`)
@@ -62,7 +76,7 @@ module.exports = defineApi({
 ### Companion Loader (`definePage`)
 
 ```javascript
-const { definePage } = require('webspresso');
+const { definePage, useDb, useParams } = require('webspresso');
 
 module.exports = definePage({
   middleware: ['auth'], // optional
@@ -70,7 +84,9 @@ module.exports = definePage({
     title: 'Product Details',
   },
   load: async ({ req, res, db, ctx }) => {
-    const product = await db.getRepository('Product').findById(req.params.id);
+    // Both parameter injection ({ req, db }) and hooks (useDb(), useParams()) are fully supported
+    const params = useParams();
+    const product = await (db || useDb()).getRepository('Product').findById(params.id);
     if (!product) {
       throw new ctx.errors.NotFoundError('Product not found');
     }

package/.agents/skills/webspresso-services/SKILL.md

@@ -45,7 +45,7 @@ module.exports = defineService({
     key: (input) => `refund:${input.userId}:${input.amount}`,
   },
 
-  // Execution Handler
+  // Execution Handler (aliases: handler, execute, run)
   handler: async (input, ctx) => {
     // ctx.db, ctx.service, ctx.user, ctx.logger are automatically injected
     const userRepo = ctx.db.getRepository('User');
@@ -78,13 +78,46 @@ module.exports = defineService({
 
 ---
 
-## 3. Invoking Services
+## 3. Composable Ambient Context Hooks (Zero-Prop-Drilling)
+
+Webspresso provides zero-dependency ambient context hooks via `AsyncLocalStorage`. You can access the database, authenticated user, logger, and other services directly without threading `ctx` through helper functions:
+
+```javascript
+const { useDb, useAuth, useService, useLogger, useTransaction } = require('webspresso');
+
+async function verifyAccountStatus(userId) {
+  const db = useDb();
+  const logger = useLogger();
+  logger.info('Verifying account status', { userId });
+  return await db.getRepository('Account').findOne({ userId });
+}
+
+module.exports = defineService({
+  handler: async (input) => {
+    // Zero-prop-drilling: helper functions access ambient db/logger directly
+    const account = await verifyAccountStatus(input.userId);
+    const currentUser = useAuth();
+    
+    // Invoke sibling services directly via hook
+    await useService('audit.log', { user: currentUser?.id });
+
+    return { account };
+  },
+});
+```
+
+---
+
+## 4. Invoking Services
 
 From SSR Companion Loaders:
 ```javascript
+// Via ctx.service or useService() hook
+const { useService } = require('webspresso');
+
 module.exports = definePage({
   load: async ({ ctx }) => {
-    const data = await ctx.service('order.summary', { userId: ctx.user.id });
+    const data = await useService('order.summary', { userId: ctx.user.id });
     return { data };
   },
 });

package/AGENTS.md

@@ -25,6 +25,7 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Cloud Migration Jobs (Zero-Downtime DB Deploy)** | [`.agents/MIGRATION_JOBS.md`](.agents/MIGRATION_JOBS.md) | `bin/commands/add-migration-job.js`, `core/orm/migrate-cloud.js` |
 | **Rate Limiting Engine (Zero-Dependency & Redis)** | [`.agents/RATE_LIMIT.md`](.agents/RATE_LIMIT.md) | `core/rate-limit/` |
 | **Feature Flags & Canary Splitter (`core/flags`)** | [`.agents/FLAGS.md`](.agents/FLAGS.md) | `core/flags/` |
+| **Ambient Context & Composable Hooks (`core/context`)** | [`.agents/CONTEXT.md`](.agents/CONTEXT.md) | `core/context/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -51,6 +52,7 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
 | **SSR Rendering**| `res.render('profile.njk', data)` inside custom handlers | Companion loader `pages/profile.js` exporting `async function load()` |
 | **Exceptions** | `res.status(404).json({ error: 'Not found' })` | `throw new NotFoundError('User not found')` |
 | **Background** | `setTimeout(...)`, `npm i bullmq` | `jobs/user/welcome.js` → `req.queue.dispatch('user.welcome', data)` |
+| **Model Schemas** | `schema: z.object({ ... })` (raw zod wrapping in models) | `schema: { id: zdb.id(), ... }` or `schema: ({ zdb, z }) => ({ ... })` |
 
 ---
 
@@ -110,7 +112,7 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
     - Encapsulate domain features using `defineModule({ name, pages, api, services, middlewares })`.
     - Auto-registers routes (`/auth/login`, `/api/auth/login`), services (`'auth.login'`), and scoped middlewares without manual router glue.
 
-### 1.2 Services Layer (`services/`, `src/services/`)
+### 1.2 Services Layer (`services/`, `core/services/`)
 - **File-based Auto-Discovery**: Services located in `services/` map directly to dot-separated service names (e.g. `services/user/create.js` → `'user.create'`) and camelCase aliases (`'user.reset-password'` & `'user.resetPassword'`).
 - **Declarative Validation & Authorization**: Define optional Zod `schema`, `auth` (boolean, role string/array, predicate), `timeout` (ms), `transaction: true` (ACID transaction propagation across nested calls), and `cache: { ttl, key }`.
 - **Unified Invocation**: Consumed via `ctx.service('service.name', input)` from SSR loaders, `req.service()` in API routes, or standalone `createServiceRegistry()`.
@@ -126,8 +128,8 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
   - `await repo.delete(id)` *(respects soft deletes)*
   - `await repo.query().where('price', '>', 50).paginate({ page, limit })`
   - `await repo.query().include('user', 'tags').find()` *(eager loading)*
-- **Model Definition**: Defined in `models/*.js` using `defineModel({ name, table, schema, relations, scopes, hidden, admin, cache })`.
-- **Schema & Types**: Built with `zdb` schema builder (`zdb.id()`, `zdb.string()`, `zdb.integer()`, `zdb.boolean()`, `zdb.file()`, `zdb.json()`).
+- **Model Definition**: Defined in `models/*.js` using `defineModel({ name, table, schema, relations, scopes, hidden, admin, cache })`. Accepts clean plain object `schema: { ... }` or functional schema `schema: ({ zdb, z }) => ({ ... })`.
+- **`zdb` vs `z` Single Source of Truth**: NEVER wrap model schemas in `z.object({...})`. ALWAYS use `zdb.*` (`zdb.id()`, `zdb.string()`, `zdb.integer()`, `zdb.email()`, `zdb.boolean()`, `zdb.file()`, `zdb.json()`) to decorate models with SQL column types, Knex migrations, Admin UI metadata, and query filters. Use pure `z.*` ONLY for in-memory request/service payloads (`pages/api/...`, `services/...`). Access raw Zod primitives in models via `zdb.z` or functional schema without importing `zod`.
 - **Ambient Transactions**: Repositories automatically bind to ambient transactions (`AsyncLocalStorage`) inside `db.transaction()` and services (`transaction: true`) without manual `trx` passing.
 - **Query Caching**: Memory/provider query cache configured per database instance or model (`cache: 'auto'|'smart'|true`).
 - **Migrations**: Database schema changes managed via Knex migrations in `migrations/` (`webspresso db:migrate`).
@@ -198,3 +200,4 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 8. **Page Data Loaders (NO Manual `res.render()`)**: Never call `res.render()` inside custom handlers for web pages. Use companion loaders `pages/*.js` exporting `async function load({ req, res, db, ctx })`.
 9. **Semantic Exceptions (NO Generic Errors / Manual Responses)**: Never return manual `res.status(404).json(...)` inside services or loaders. Always throw semantic errors: `NotFoundError`, `ValidationError`, `UnauthorizedError`, `ForbiddenError`.
 10. **Background Jobs (NO BullMQ / `setTimeout`)**: Never use unmanaged `setTimeout` or external queues. Place job workers in `jobs/` and dispatch via `req.queue.dispatch()`.
+11. **`zdb` vs `z` Single Source of Truth (NO `schema: z.object` in Models)**: Never wrap model schemas in `z.object({...})`. Always use `zdb.*` for persistent database columns in `models/*.js`. Use pure `z.*` ONLY for in-memory request/service payloads (`pages/api/...`, `services/...`). Access raw Zod primitives in models via `zdb.z` or functional schema `schema: ({ zdb, z }) => ({ ... })` without importing `zod`.

package/core/app.js

@@ -22,8 +22,9 @@ const {
 } = require('./resilience');
 const { createTaggedLruCache } = require('./cache');
 const { createEventDispatcher, loadListeners } = require('./events');
-const { createPluginManager } = require('../src/plugin-manager');
-const { createServiceRegistry } = require('../src/services');
+const { createPluginManager } = require('./plugins');
+const { createServiceRegistry } = require('./services');
+const { getContext } = require('./context/request');
 
 let isWebspressoPackageCache = null;
 function checkIsWebspressoPackage() {
@@ -153,7 +154,7 @@ class CoreApp {
 
     // Auto-register built-in auth services if database is present
     if (options.db) {
-      const { createAuthServices } = require('../src/services/builtins/auth');
+      const { createAuthServices } = require('./services/builtins/auth');
       const authServices = createAuthServices({ db: options.db });
       for (const [name, def] of Object.entries(authServices)) {
         if (!this.serviceRegistry.has(name)) {
@@ -163,7 +164,7 @@ class CoreApp {
     }
 
     // Auto-register built-in system services (health, cleanup, cache flush, info)
-    const { createSystemServices } = require('../src/services/builtins/system');
+    const { createSystemServices } = require('./services/builtins/system');
     const systemServices = createSystemServices({
       db: options.db ?? null,
       serviceRegistry: this.serviceRegistry,
@@ -414,7 +415,8 @@ class CoreApp {
       callOpts = maybeOpts || {};
     } else {
       callOpts = ctxOrOpts || {};
-      const base = callOpts.context || callOpts.ctx || this.context;
+      const ambientStore = getContext();
+      const base = callOpts.context || callOpts.ctx || ambientStore || this.context;
       if (callOpts.user !== undefined || callOpts.auth !== undefined) {
         callCtx = Object.create(base);
         if (callOpts.user !== undefined) callCtx.user = callOpts.user;

package/core/applySchema.js

@@ -1,73 +1,4 @@
-/**
- * Schema Applicator
- * Parses and validates request input against compiled schemas
- */
-
-const EMPTY_INPUT = Object.freeze({
-  body: undefined,
-  params: undefined,
-  query: undefined,
-});
-
-/**
- * Apply compiled schema to request
- * Parses body, params, and query against their respective schemas
- * Stores validated results in req.input
- * 
- * @param {Object} req - Express request object
- * @param {Object|null} compiledSchema - Compiled schema from compileSchema
- * @returns {void}
- * @throws {ZodError} If validation fails
- */
-function applySchema(req, compiledSchema) {
-  // No schema means no validation
-  if (!compiledSchema) {
-    req.input = EMPTY_INPUT;
-    return;
-  }
-
-  // Initialize req.input
-  req.input = {
-    body: undefined,
-    params: undefined,
-    query: undefined,
-  };
-
-  // Parse body if schema exists
-  if (compiledSchema.body) {
-    req.input.body = compiledSchema.body.parse(req.body);
-  }
-
-  // Parse params if schema exists
-  if (compiledSchema.params) {
-    req.input.params = compiledSchema.params.parse(req.params);
-  }
-
-  // Parse query if schema exists
-  if (compiledSchema.query) {
-    req.input.query = compiledSchema.query.parse(req.query);
-  }
-}
-
-let _translateValidationIssues = null;
-function getTranslateValidationIssues() {
-  if (!_translateValidationIssues) {
-    try {
-      _translateValidationIssues = require('../src/api/validation-i18n').translateValidationIssues;
-    } catch {
-      _translateValidationIssues = (issues) => issues;
-    }
-  }
-  return _translateValidationIssues;
-}
-
-function translateValidationIssues(issues, options) {
-  return getTranslateValidationIssues()(issues, options);
-}
-
-module.exports = {
-  applySchema,
-  translateValidationIssues,
-};
-
+'use strict';
 
+// Backward-compatibility shim
+module.exports = require('./validation/apply');

package/core/cache/lru.js

@@ -47,6 +47,7 @@ function safeClone(value) {
  * @property {string|number} [defaultTtl=0] - Default TTL in ms or string duration ('5m', '1h', 0 = no expiry)
  * @property {function(*, string): number} [sizeCalculation] - Custom byte sizer function
  * @property {boolean} [clone=false] - Whether to deep-clone items on read/write
+ * @property {boolean} [trackBytes=false] - Whether to track approximate bytes when maxBytes is 0
  * @property {function(string, *, 'evict'|'expire'|'delete'|'clear'): void} [onEvict] - Eviction callback
  */
 
@@ -71,6 +72,11 @@ class LruCache {
     this.clone = options.clone === true;
     this.onEvict = typeof options.onEvict === 'function' ? options.onEvict : null;
 
+    // Track bytes only when explicit memory limit exists, custom sizer provided, or trackBytes is explicitly requested
+    this.trackBytes = options.trackBytes !== undefined
+      ? options.trackBytes === true
+      : (this.maxBytes > 0 || typeof options.sizeCalculation === 'function');
+
     /** @type {Map<string, { value: *, size: number, expiresAt: number }>} */
     this._store = new Map();
 
@@ -115,6 +121,10 @@ class LruCache {
     if (this.sizeCalculation) {
       return Math.max(0, this.sizeCalculation(value, key));
     }
+    // Fast path: if byte tracking is disabled, avoid expensive recursive object graph traversal
+    if (!this.trackBytes) {
+      return 0;
+    }
     return Math.max(0, approximateByteSize(value));
   }
 

package/core/cache/tagged-lru.js

@@ -60,6 +60,10 @@ class TaggedLruCache {
     return this.lru.maxBytes;
   }
 
+  get trackBytes() {
+    return this.lru.trackBytes;
+  }
+
   get maxEntries() {
     return this.lru.maxEntries;
   }