@omega.js/backend 0.1.0

package/docs/paypal-sandbox-qa.md

@@ -0,0 +1,105 @@
+# PayPal sandbox QA drives (live sale + refund fixtures)
+
+The repeatable recipe for driving a REAL PayPal sandbox payment through the deployed
+playground backend, proven 2026-08-17 on the [#240](https://github.com/Omega-JS-Stack/omega/issues/240)
+v1 sale fixture drive. Use it whenever a webhook change needs a live delivery instead
+of a fixture replay. [#348](https://github.com/Omega-JS-Stack/omega/issues/348) precreated
+what it could: the QA product's provider objects exist on every provider. The BUYER
+stays hand-made — PayPal retired the sandbox-accounts API (see below).
+
+## The standing fixtures
+
+- **Merchant / API creds** — the sandbox business account (display name
+  "test facilitator's Test Store", PayPal's default; rename in the developer
+  dashboard if the checkout header matters). Creds: `PAYPAL_CLIENT_ID` +
+  `PAYPAL_CLIENT_SECRET` in the playground backend's `.env`
+  (`brands/omega-playground/targets/backend/.env`). The manager wants the client id in
+  config (`payment.providers.paypal.clientId`) and only the secret in `.env`;
+  the backend wants both as env vars.
+- **Webhook** — registered by the manager payment walk, pointing at the deployed
+  playground backend (`api.playground.omegajs.dev/omega/payments/webhook`).
+  Deliveries arrive with real signature headers; the deployed backend is the
+  verification surface (a local emulator receives nothing — no forwarding path).
+- **QA product** — `proof-press` ("Proof Press", $5 monthly, NO trial)
+  in `brands/omega-playground/config/omega.json5`. Trial-free ON PURPOSE: every public
+  tier carries a 14-day trial, which defers a subscription's first sale two weeks.
+  It lists on the playground /pricing page on purpose (Ian 2026-08-19, #348) so
+  real checkouts can be run against it by hand; the `hidden: true` mechanism
+  remains available for products that should stay off /pricing.
+  The manager payment walk owns the provider objects
+  (`npx mgr manage --service=payment` at the playground root); read the current
+  ids from the config write-backs (`stripe.productId`, `paypal.productId`) and
+  list plans via `GET /v1/billing/plans?product_id=<paypal.productId>`.
+- **Sandbox buyer** — `qa-fixture-buyer@playground.omegajs.dev`, created by hand
+  through PayPal's guest checkout during the 2026-08-17 drive. Its wallet holds a
+  working generator-BIN Visa. It is DURABLE — the hoops are one-time, not per
+  drive. If the login is lost, recreate it through the guest flow below, or from
+  the Developer Dashboard (Sandbox → Accounts → Create Account).
+  **There is no API for this** (probed 2026-08-18, #348): the app-credential token
+  carries no sandbox-account scope (asking for one downgrades the token to
+  `openid`), the legacy `/v1/customer/partners/{merchant_id}/accounts` route 404s
+  even with our real merchant id, and every `developer.paypal.com` account path
+  redirects to an interactive login. Don't spend time re-probing it. Because the
+  walk cannot precreate the buyer, it REMINDS instead: a payment walk whose PayPal
+  credentials resolve to sandbox closes `paypal-products` with the buyer note and
+  the Sandbox → Accounts deep link (silent in live mode).
+
+## Two lanes — pick deliberately (Ian's ruling, 2026-08-17)
+
+- **Default: through omega's checkout.** Drive the deployed playground site's
+  checkout page as a user. That exercises the FULL pipeline — payments-intent,
+  cart, provider object, confirmation redirect — and the webhook folds onto an
+  existing trail. Any "does the pipeline work" drive belongs here.
+- **Exception: raw API, only when the test target is the recovery path.** A
+  subscription created straight through PayPal's API arrives at the webhook with
+  no intent and no order, which is precisely what the uid-recovery code
+  (fetchResource + custom_id fold, #224) exists for. Know that this lane mints
+  the order FROM the webhook — the #335 refund-before-order shape — so never
+  mistake its result for proof of the checkout lane.
+
+## The drive (subscription sale → refund, raw-API lane)
+
+All API calls go to `https://api-m.sandbox.paypal.com` with an OAuth token from the
+`.env` creds. A staged helper script from the 2026-08-17 run is described in the
+#240 trail; rebuild it from this sequence if needed.
+
+1. `POST /v1/billing/subscriptions` with the QA plan id,
+   `custom_id: "uid:{uid},orderId:{orderId}"` (the pipeline's parse format —
+   uid must exist on the LIVE project; export one with
+   `npx firebase auth:export --project omegajs-playground`), and an
+   `application_context` carrying `return_url`/`cancel_url` (omit it and PayPal
+   shows its own confirmation page instead of redirecting back).
+2. Open the returned `approve` link in a browser, log in as the sandbox buyer,
+   pick the working card, Agree. Status flips `APPROVAL_PENDING → ACTIVE` and the
+   first REGULAR cycle charges immediately (no trial).
+3. `GET /v1/billing/subscriptions/{id}` for `billing_info.last_payment`, then
+   `GET /v1/billing/subscriptions/{id}/transactions?start_time&end_time` for the
+   sale id. `PAYMENT.SALE.COMPLETED` arrives at the deployed backend.
+4. Refund: `POST /v1/payments/sale/{saleId}/refund` with `{}` (full refund).
+   `PAYMENT.SALE.REFUNDED` arrives; the worker runs `fetchResource('sale')`,
+   resolves the uid, and folds the order to `status=refunded`.
+5. Verify: `GET /v1/notifications/webhooks-events?event_type=...` for deliveries;
+   `npx firebase functions:log --project omegajs-playground` for the parse,
+   fetch, and transition lines.
+6. Cleanup: `POST /v1/billing/subscriptions/{id}/cancel`. Leave the plan and
+   product alone — the manager owns them.
+
+## Gotchas (each cost real time on the first drive)
+
+- `PAYMENT.SALE.*` (v1) events come ONLY from subscription billing. One-time card
+  orders emit `PAYMENT.CAPTURE.*` (v2). Pick the lane for the event you need.
+- The classic 4111/4012 test Visas fail: 4111… is declined at commit, 4012… is
+  claimed by another sandbox account. A Luhn-valid number on PayPal's generator
+  BIN (4032…) works — the buyer's saved card is one.
+- Guest checkout hoops: the expiry mask wants `MM/YY`; the SMS gate accepts any
+  6-digit code in sandbox; a fake street address hard-rejects until PayPal's
+  normalizer can match it (a real street like `2211 N 1st St, San Jose` passes).
+- A subscription created with `payment_source.card` does NOT auto-activate; it
+  still returns an approval link.
+- A real v1 subscription sale carries `custom` + `billing_agreement_id` and no
+  `parent_payment`; the legacy one-time shape (uid via the `parent_payment`
+  fold) is covered by `test/fixtures/paypal/sale-refunded.json`. Both uid paths
+  stay pinned.
+- v1 resources spell status `state`; the pipeline reads both
+  (`resource.status ?? resource.state`, [#347](https://github.com/Omega-JS-Stack/omega/issues/347)),
+  so a successful v1 fetch logs its real status (`status=refunded`).

package/docs/response-headers.md

@@ -0,0 +1,9 @@
+# Response Headers
+
+@omega.js/backend automatically sets `omega-properties` header with:
+- `code`: HTTP status code
+- `tag`: Function name and execution ID
+- `usage`: Current usage stats
+- `schema`: Resolved schema info
+
+The header rides every `ctx.respond()`/`ctx.report()` response (exposed via `Access-Control-Expose-Headers`) and is consumed automatically by @omega.js/client's `omega.request()`, which merges `usage.current` + `usage.limits` into the frontend `usage` bindings key — `data-omega-bind` elements refresh after every API call.

package/docs/routes.md

@@ -0,0 +1,211 @@
+# Creating Routes, Events, Cron Jobs
+
+Recipes for building consumer-side routes plus @omega.js/backend-side event handlers and cron jobs. See also [docs/schemas.md](schemas.md) for schema definitions, [docs/auth-hooks.md](auth-hooks.md) for auth lifecycle hooks, and [docs/common-operations.md](common-operations.md) for inside-the-handler patterns.
+
+## New Route (Consumer Project)
+
+Routes live at `src/routes/{path}/{method}.js` (staged to `dist/` by `omega build` — consumers are src-first, see [build-system.md](build-system.md)) — @omega.js/backend routes requests to the matching method file (`get.js` / `post.js` / `put.js` / `delete.js`), falling back to `index.js` if no method-specific file exists.
+
+A route exports an **async function receiving a context object** (built by the middleware — see `src/manager/helpers/middleware.js`):
+
+```javascript
+/**
+ * POST /items - Create a new item
+ */
+module.exports = async ({ Manager, ctx, analytics, usage, user, settings, libraries, utilities }) => {
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  const { admin } = libraries;
+  const firestore = admin.firestore();
+
+  // Count a use of a metered feature — check, count and write in ONE call
+  await usage.consume('requests');
+
+  // settings strings are whitespace-trimmed by middleware; HTML is preserved.
+  // Call utilities.sanitize() at the HTML-insertion site, or opt the whole
+  // route in to middleware HTML strip via { sanitize: true } on .run().
+  const id = settings.id; // auto-generated by the schema (see schemas.md)
+
+  await firestore.doc(`items/${id}`).set({ id, owner: user.auth.uid, ...settings });
+
+  return ctx.respond({ id });
+};
+```
+
+Context object fields: `Manager`, `ctx`, `user` (from `ctx.getUser()`), `usage`, `settings` (schema-resolved), `analytics`, `libraries`, `utilities`.
+
+### CRUD method files
+
+Every resource endpoint follows proper CRUD with **method-specific files** (plural-noun route names — `items`, not `item`):
+
+| Method | File | Purpose | Path |
+|--------|------|---------|------|
+| GET | `get.js` | List all or fetch one | `/items` or `/items/{id}` |
+| POST | `post.js` | Create new | `/items` |
+| PUT | `put.js` | Update existing | `/items/{id}` |
+| DELETE | `delete.js` | Delete existing | `/items/{id}` |
+
+**GET routes exist for external API consumers.** The dashboard/frontend reads data directly from Firestore (faster, cheaper, no cold starts). POST/PUT/DELETE still go through Cloud Functions for server-side validation, usage tracking, and analytics.
+
+**PUT and DELETE must verify ownership** before mutating:
+
+```javascript
+const existing = docSnap.data();
+
+if (existing.owner !== user.auth.uid) {
+  return ctx.respond('Not authorized', { code: 403 });
+}
+```
+
+Immutable fields (`id`, `owner`, `stats`, `metadata.created`) should NOT be editable via PUT. ID generation (POST) and ID-from-path extraction (GET/PUT/DELETE) happen in the **schema**, not the route — see [schemas.md](schemas.md).
+
+### Key route patterns
+
+- Short-circuit returns for auth/validation checks
+- `settings` contains the parsed + validated request data (from schemas)
+- `ctx.respond()` for ALL responses (success and error)
+- `admin.firestore().doc('collection/id')` shorthand for Firestore access ([firestore.md](firestore.md))
+- Timestamps under `metadata.{created,updated}` ([firestore.md](firestore.md#document-metadata))
+
+### The `test/` route folder is development-only
+
+`routes/test/*` — the framework's own routes AND any a consumer adds under that folder — answers **404 in production**. The guard lives once in `Middleware.run()` (`src/manager/helpers/middleware.js`, `isDevOnlyRouteBlocked()`), the single place both request paths converge (the deployed `omega_api` function and the local express server), so a NEW test route is gated the day it lands instead of the day somebody remembers to copy a guard. Under the emulator (`isDevelopment()`/`isTesting()`) every one of them serves normally.
+
+**Zero carve-outs.** The one route that used to need one — the liveness probe — is a real route now: see below.
+
+Put debug/echo/reset routes in `test/` and they are safe by default. A route that must answer in production does NOT belong there.
+
+Both the gate and the module loader read the route path **normalized** (`path.posix.normalize`, lowercased, `.js` dropped), because it arrives straight off the request URL — `./test/usage`, `.//test/usage` and `x/../test/usage` all resolve to the same handler and are all gated the same. A route path may also never escape the routes directory: a leading `..` or an absolute path is a flat 404, even when it climbs back in (`../routes/test/usage`) — `isRouteOutsideRoutesDir()`, same file.
+
+### `GET /health` — the liveness probe
+
+**`GET /omega/health`** (`src/manager/routes/health/get.js`) is the deployed backend's liveness + version endpoint. It is **public** (no auth) and **echoes no request input** — the payload is a fixed set of fields read from the Manager, never from the request:
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2026-08-14T00:00:00.000Z",
+  "environment": "production",
+  "projectId": "your-project",
+  "version": "1.4.0",
+  "backendVersion": "5.9.0",
+  "testExtendedMode": false
+}
+```
+
+`omega manage`'s live API check reads it on a real host (`@omega.js/manager`'s testing service) and the test runner reads it to confirm the emulator's project and mode. `test/health` still serves the same handler in dev/testing for anything that has not moved yet, but it is a `test/` route — **404 in production** like the rest of the folder. Point liveness checks at `/omega/health`.
+
+### Functions entry point (`src/index.js`)
+
+```javascript
+const Manager = (new (require('@omega.js/backend'))).init(exports, {
+  setupFunctionsIdentity: false,
+});
+const { functions } = Manager.libraries;
+
+/**
+ * @route /items
+ *
+ * @method GET    /items            - List all items
+ * @method GET    /items/:itemId    - Get single item
+ * @method POST   /items            - Create a new item
+ * @method PUT    /items/:itemId    - Update an item
+ * @method DELETE /items/:itemId    - Delete an item
+ */
+exports.items = functions
+.runWith({ memory: '256MB', timeoutSeconds: 120 })
+.https.onRequest((req, res) => Manager.Middleware(req, res).run('items'));
+```
+
+The schema defaults to the route name (`.run('items')` loads `src/schemas/items/`); pass `{ schema: 'custom' }` only when the schema path differs.
+
+For operations that don't fit CRUD (e.g. `/items/:itemId/export`), add an **action sub-path** handled within the same Cloud Function (parsed from the request path) or as a separate function if resource needs differ significantly.
+
+### firebase.json routing
+
+Make routes public with rewrites. Use the bracket syntax so sub-paths like `/items/{id}` route correctly:
+
+```json
+{
+  "hosting": {
+    "rewrites": [
+      { "source": "{/items,/items/**}", "function": "items" }
+    ]
+  }
+}
+```
+
+**CRITICAL**: Without the `/**` wildcard, requests to `/items/{id}` won't reach the function.
+
+**CRITICAL: Rewrite order matters — first match wins.** When multiple functions share a path prefix, the most specific routes MUST come first and the catch-all last, otherwise it swallows all sub-routes:
+
+```json
+{
+  "hosting": {
+    "rewrites": [
+      { "source": "{/agents/*/chat,/agents/*/chat/**}", "function": "agentsChat" },
+      { "source": "/agents/*/conversations/**", "function": "agentsConversations" },
+      { "source": "{/agents,/agents/**}", "function": "agents" }
+    ]
+  }
+}
+```
+
+Order: most specific → least specific → catch-all.
+
+## New Event Handler
+
+Handlers live at `src/manager/events/{type}/{event}.js` — `auth/` (the Identity Platform user lifecycle), `firestore/{collection}/on-write.js` (document triggers), `cron/` (the scheduled runner, below).
+
+A handler exports an **async function receiving a context object**, exactly like a route — `await handler({ Manager, ctx, libraries, user, context, change, snapshot })` is the one call the middleware makes (`src/manager/helpers/event-middleware.js`). A handler exported any other way is called as a plain function: its body never runs and nothing errors.
+
+```javascript
+/**
+ * Notification subscription write handler
+ */
+module.exports = async ({ Manager, ctx, change, context, libraries }) => {
+  const { admin } = libraries;
+
+  ctx.log('Event triggered', context.params);
+
+  // Event logic here
+};
+```
+
+Which payload keys carry a value is the TRIGGER's business — auth events bring `user` + `context`, Firestore document triggers bring `change` (or `snapshot`) + `context`, cron jobs bring `context` alone; the rest arrive `undefined`. `Manager`, `ctx` (a fresh `RouteContext` per event) and `libraries` always ride.
+
+Wire it to its trigger in `src/manager/index.js`, where every framework event runs through `EventMiddleware` (`events` is the absolute `src/manager/events` path):
+
+```javascript
+exporter.omega_notificationsOnWrite =
+fn({memory: '256MB', timeoutSeconds: 60})
+.firestore.document('notifications/{token}')
+.onWrite((change, context) => self.EventMiddleware({ change, context }).run(`${events}/firestore/notifications/on-write.js`));
+```
+
+A **consumer project** wires its own the same way, naming the handler relatively: `Manager.EventMiddleware({ snapshot, context }).run('users/on-create')` loads `{Manager.cwd}/events/users/on-create.js` — the STAGED copy (`dist/events/`, the deployed functions source), so author it at `src/events/users/on-create.js` and let `omega build` stage it. A name starting with `/` is used verbatim, which is how the framework points at its own.
+
+Throwing is the error contract: an `HttpsError` or an explicit numeric 4xx `code` rejects untouched (the trigger's client fault), and anything else is reported — logged AND captured to Sentry — as a server fault.
+
+## New Cron Job (Consumer Project)
+
+Create `src/hooks/cron/daily/{job}.js` — the runner reads the STAGED copy (`dist/hooks/cron/{name}/`, off `Manager.cwd`), so author it in `src/` and let `omega build` stage it.
+
+A job exports an **async function receiving a context object**, exactly like a route — `await handler({ Manager, ctx, context, libraries })` is the one call the runner makes (`src/manager/events/cron/runner.js`). A job exported any other way is called as a plain function: its body never runs and nothing errors.
+
+```javascript
+/**
+ * Daily job
+ */
+module.exports = async ({ Manager, ctx, context, libraries }) => {
+  const { admin } = libraries;
+
+  ctx.log('Running daily job...');
+
+  // Job logic here
+};
+```
+
+Every schedule works the same way — `daily/`, `frequent/` — and the framework's own jobs (`src/manager/events/cron/{name}/`) are written in this exact shape.

package/docs/sanitization.md

@@ -0,0 +1,71 @@
+# Sanitization (XSS Prevention)
+
+@omega.js/backend middleware always **trims** whitespace on incoming string fields (via `utilities.trim()`). HTML sanitization is **opt-in** — it's not run by default because it mangles legitimate input like URL query strings (`&` → `&`) and Markdown.
+
+The expectation is that you sanitize at the **HTML-insertion site** (in the template, in the email body, etc.) — not at the request boundary.
+
+## How It Works
+
+1. **Trimming**: Every string in `settings` is whitespace-trimmed by the middleware (objects + arrays walked recursively). Always on.
+2. **HTML sanitization**: Off by default. Opt in per-route with `{ sanitize: true }` on `Manager.Middleware(...).run(...)`.
+3. **Schemas** can mark individual fields with `sanitize: false` to skip the HTML strip for that field when route-level sanitize is enabled (used for fields that legitimately need raw HTML — rich-text editors, email templates).
+
+## Route-Level Opt-In
+
+```javascript
+// In functions/index.js — enable HTML strip for a specific route
+Manager.Middleware(req, res).run('my-route', { sanitize: true });
+```
+
+When enabled, every string in `settings` is run through `sanitize-html` (strip all tags) unless the schema marks the field with `sanitize: false`.
+
+## Schema Field Opt-Out (when route-level sanitize is on)
+
+```javascript
+// This field will NOT be sanitized — raw HTML is preserved
+htmlContent: {
+  types: ['string'],
+  default: '',
+  sanitize: false,
+},
+// This field IS sanitized when route-level sanitize is enabled
+name: {
+  types: ['string'],
+  default: '',
+},
+```
+
+In zod schemas the same option rides the builder: `f.string({ default: '', sanitize: false })`.
+
+## Manual Sanitization (Recommended)
+
+For most use cases — particularly anywhere you're inserting user-supplied content into HTML — call `utilities.sanitize()` directly at the insertion site:
+
+```javascript
+// Available in route context
+const safeHtml = utilities.sanitize(untrustedData);
+
+// Or via Manager
+const safeHtml = Manager.Utilities().sanitize(untrustedData);
+```
+
+Accepts any data type — strings, objects, arrays, primitives. Walks objects/arrays recursively, strips HTML from strings, passes everything else through unchanged.
+
+## Why HTML Sanitization Is Not the Middleware Default
+
+Stripping HTML from every incoming string at the request boundary is too aggressive — it corrupts legitimate input:
+
+- URL query strings: `https://example.com/?a=1&b=2` becomes `https://example.com/?a=1&b=2`
+- Markdown / code snippets with `<`, `>`, `&` characters get mangled
+- API payloads round-tripped through the system get silently rewritten
+
+Stored XSS comes from rendering, not from receiving. Sanitize at the render site (where you know the output context — HTML body, attribute, URL, JSON) instead of at the front door.
+
+## Route Handler Context
+
+```javascript
+module.exports = async ({ Manager, ctx, analytics, usage, user, settings, libraries, utilities }) => {
+  // settings    — whitespace-trimmed by middleware; HTML preserved unless route opts in via { sanitize: true }
+  // utilities   — Manager.Utilities() instance for manual sanitize()/trim()
+};
+```

package/docs/schemas.md

@@ -0,0 +1,163 @@
+# Schemas
+
+Schemas define and validate the payload your routes accept. They live at `functions/schemas/{name}/{method}.js` — the resolver loads the method-specific file first (`get.js` / `post.js` / …), falling back to `{name}/index.js` (see `src/manager/helpers/settings.js`). The schema name defaults to the route name (`.run('items')` ↔ `functions/schemas/items/`).
+
+## Schema function contract
+
+A schema exports a function that receives a **context object** and returns a **flat schema object**. Plan-based adjustments happen INSIDE the function (there is no tier system):
+
+```javascript
+module.exports = ({ ctx, user, data, method, headers, geolocation, client }) => {
+  const planId = user?.subscription?.product?.id || 'basic';
+  const isPremium = planId !== 'basic';
+
+  const schema = {
+    name: {
+      types: ['string'],
+      default: '',
+      required: true,
+    },
+    limit: {
+      types: ['number'],
+      default: 10,
+      min: 1,
+      max: isPremium ? 1000 : 100,   // plan-based limit
+    },
+  };
+
+  // Premium-only field (not present for basic users)
+  if (isPremium) {
+    schema.premiumOnlyField = {
+      types: ['string'],
+      default: 'premium-feature',
+    };
+  }
+
+  return schema;
+};
+```
+
+Context fields: `ctx`, `user` (resolved user), `data` (raw request data), `method`, `headers`, `geolocation`, `client`.
+
+## Field Properties
+
+- `types` — array of allowed types: `['string']`, `['number']`, `['boolean']`, `['object']`, `['array']`, `['any']`, or multiple (`['string', 'number']`)
+- `default` — default value if not provided; may be a function (`default: () => ...`)
+- `value` — force-set value (ignores user input — e.g. auto-generated IDs)
+- `required` — `true`/`false` or a function `(ctx, settings, options) => bool`. A key counts as missing when it's `undefined` **or `''`** (null/0/false pass). **NEVER combine with `default`** — see the footgun below
+- `min` / `max` — validation bounds (string length, number range, array length), enforced per type. `max`: numbers clamp down, strings/arrays truncate. `min`: numbers clamp up, but a **string or array shorter than `min` is REFUSED** — `400 Invalid settings {field}: must be at least N characters` (`must have at least N items` for arrays), never padded. The length refusal is checked post-resolution at the route boundary, like `enum`, so it sees the value the handler would have gotten; unlike `enum`, it applies even when the caller did not send the field (a `default: ''` with `min: 1` refuses every request that omits it). Enforced **only when declared** — no `min` means negatives and empty strings pass through, and a declared `0` is a real bound
+- `enum` — array of allowed values. Enforced for values the caller sends (checked post-coercion): out-of-list → `400 Invalid settings {field}: must be one of [...]`. Absent fields pass — combine with `required` if the field must also be present
+- `clean` — a RegExp (matched chars removed) or function `(value) => cleaned`
+- `sanitize` — per-field opt-out (`false`) for HTML sanitization; only meaningful when the route opts in via `Manager.Middleware(req, res).run('route', { sanitize: true })`. See [sanitization.md](sanitization.md)
+
+### ⚠️ `required` + `default` footgun
+
+@omega.js/backend checks `required` against the ORIGINAL request value, before defaults apply — so `required: true` on a field with a `default` throws `Required key {field} is missing in settings` before the default is ever used. For fields that must be non-empty but have a derived default (like path-extracted IDs), use `min: 1` instead — it refuses an empty value with a 400 AFTER the default applies.
+
+## Zod schemas
+
+A schema module may return a **zod schema** instead of a declarative node object — `Settings.resolve()` detects it and parses with zod in place of the declarative walk. **All framework route schemas use this form** (except the deliberately-empty provider webhook schemas); the declarative form above remains fully supported for consumer projects — both engines run the SAME field pipeline (`src/manager/helpers/schema-engine.js`), so wire shapes are identical either way (proven by `test/helpers/schema-zod.test.js`). Build with the `fields` helpers for the shared semantics (coerce-never-reject, `max` clamp/truncate, a short string/array refused at `min`, `required` fires on `undefined`/`''`, unknown keys stripped):
+
+```javascript
+const { fields: f } = require('@omega.js/backend/dist/manager/helpers/schema-zod.js'); // framework schemas use a relative path
+
+module.exports = ({ user }) => f.object({
+  name: f.string({ default: undefined, required: true }),
+  limit: f.number({ default: 10, min: 1, max: 100 }),
+  tags: f.array({ default: [] }),
+  config: f.passthrough({ default: {} }),              // types: ['object'] — nested content passes through
+  version: f.multi(['string', 'number'], { default: '5' }),
+  nested: f.object({ level1: f.string({ default: 'x' }) }),
+});
+```
+
+Every builder takes the exact declarative node options (`types` via the builder name, plus `default`, `value`, `min`, `max`, `required`, `enum`, `clean`, `sanitize`); `f.field(opts)` is the generic form. Builders throw on unknown options (catches typos). All declarative quirks are preserved, including the `required`+`default` footgun above; `min`/`max` enforce only when declared (no implicit `0` floor — fixed deliberately, see the field-properties list), and a length `min` refuses with the byte-identical 400 the declarative engine raises.
+
+Exporting **raw zod** (no builders) opts into zod-native semantics instead: invalid input **rejects with 400** rather than coercing. Use deliberately — it's a behavior change from the declarative contract.
+
+Both engines carry two deliberate fixes over the old powertools resolver (documented + asserted in `test/helpers/schema-zod.test.js`): non-empty object/array defaults are returned **clean** (powertools injected `types`/`min`/`max` keys into them) and **cloned per request** (powertools returned the schema's default object by reference). `powertools.defaults()` is no longer used for settings resolution anywhere — node-powertools remains a dependency for its other utilities.
+
+Webhook routes (`payments/webhook`, `marketing/webhook`, …) keep their **empty schemas** by design — the body is the raw provider payload; don't wrap them in zod.
+
+## ID Generation (POST — Create)
+
+IDs are auto-generated in the **schema**, NOT in the route. Use `value` to force-generate via @omega.js/backend's built-in `randomId()` (14-char nanoid, 62-char alphabet, no `-` or `_`):
+
+```javascript
+id: {
+  types: ['string'],
+  value: () => ctx.Manager.Utilities().randomId(),
+},
+```
+
+The route just reads `settings.id` — no ID generation logic needed.
+
+## ID Extraction from Path (GET, PUT, DELETE)
+
+For single-item operations, extract the ID from the URL path in the **schema**:
+
+```javascript
+// /items/{id} → split('/') = ['', 'items', '{id}'] → index 2
+id: {
+  types: ['string'],
+  default: (ctx.request.path || '').split('/')[2] || '',
+  min: 1,     // enforce non-empty (NOT required: true — see footgun above)
+  max: 128,
+},
+```
+
+`min: 1` is a real guard: a request with no ID in the path resolves to `''` and is refused with `400 Invalid settings {id}: must be at least 1 character` before the route runs, so a handler never reads or writes the wrong document.
+
+For GET list endpoints, omit `min` so an empty ID means "list" (a declared `min: 1` would refuse the list call):
+
+```javascript
+id: {
+  types: ['string'],
+  default: (ctx.request.path || '').split('/')[2] || '',
+},
+limit: { types: ['number'], default: 20, min: 1, max: 100 },
+startAfter: { types: ['string'], default: '' },
+```
+
+## Dynamic Schemas
+
+Schemas can branch on request data (e.g. different fields per type):
+
+```javascript
+module.exports = ({ ctx, data }) => {
+  const type = data?.type || '';
+
+  const schema = {
+    name: { types: ['string'], default: undefined, required: true },
+    type: { types: ['string'], default: undefined, required: true },
+    options: {},
+  };
+
+  switch (type) {
+    case 'url':
+      schema.options = { url: { types: ['string'], default: undefined, required: true } };
+      break;
+    case 'text':
+      schema.options = { text: { types: ['string'], default: undefined, required: true } };
+      break;
+    default:
+      schema.options = {};
+  }
+
+  return schema;
+};
+```
+
+## Reference Implementation
+
+The comprehensive test schema exercising every field option (types, function defaults, forced `value`, conditional `required`, min/max clamping, `clean` regex + function, nested objects, plan-based fields): [`src/manager/schemas/test/schema/post.js`](../src/manager/schemas/test/schema/post.js) — in zod `fields` form; its frozen declarative twin (the powertools reference it must keep matching) lives in [`test/helpers/schema-zod.test.js`](../test/helpers/schema-zod.test.js).
+
+## Field Sanitization
+
+Middleware always trims whitespace on string fields. HTML sanitization is **opt-in per route** — `Manager.Middleware(req, res).run('my-route', { sanitize: true })`. When opted in, fields can individually opt back out with `sanitize: false`. See [sanitization.md](sanitization.md).
+
+## See also
+
+- [routes.md](routes.md) — the routes consuming `settings`
+- [sanitization.md](sanitization.md) — trim vs HTML-strip behavior
+- [test-framework.md](test-framework.md) — schema tests (`test/routes/test/schema.test.js`)