@vxil/feature-configs 0.9.1 → 0.10.0

package/dist/hooks.d.ts

@@ -64,6 +64,17 @@ export declare class HookEvalError extends Error {
 /** Thrown by a `validate` hook whose expression is falsy — maps to a clean 422. */
 export declare class HookRejection extends Error {
 }
+/** A WRITE `validate` hook whose expression could not be evaluated (null
+ *  arithmetic, a missing operand, a bad date …). Still a HookEvalError — the
+ *  write is refused, never let through — but it carries the hook's id and its
+ *  declared `message`, so the API can show the end user the tenant's own copy
+ *  while keeping the engine detail for the developer. `message` stays the
+ *  engine detail. */
+export declare class HookValidateFault extends HookEvalError {
+    readonly hookId: string;
+    readonly tenantMessage: string | undefined;
+    constructor(hookId: string, tenantMessage: string | undefined, detail: string);
+}
 /** Parse a hook expression into an AST. Throws HookParseError on any malformed input. */
 export declare function parseExpr(src: string): Node;
 /** Walk the AST and reject anything outside the allow-list, plus depth bounds.
@@ -157,6 +168,36 @@ export type InferredType = 'number' | 'string' | 'boolean' | 'null' | 'unknown';
 /** Best-effort static type of an expression's result (its output). 'unknown' for
  *  member access / coalesce / mixed ternaries — never a false-positive mismatch. */
 export declare function inferType(nd: Node): InferredType;
+/** One declared field, as the typing pass needs it (cms field type + required). */
+export interface HookFieldInfo {
+    type: string;
+    required?: boolean;
+}
+/** collection → field → declared info. */
+export type HookFieldTypes = Record<string, Record<string, HookFieldInfo>>;
+/** Type one parsed expression against one collection's declared fields.
+ *  `errors` are shapes that can never work (refuse); `warnings` are shapes
+ *  that work only for some stored values (json vs a scalar, `+` on a text
+ *  field) and arithmetic on an optional field with no coalesce() — it faults
+ *  the hook whenever the field is missing. `present` lists fields a derive sets first. */
+export declare function checkHookExprTypes(root: Node, fields: Record<string, HookFieldInfo> | undefined, opts: {
+    kind: HookDef['kind'];
+    event: HookDef['event'];
+    present?: ReadonlySet<string> | undefined;
+}): {
+    errors: string[];
+    warnings: string[];
+};
+/** Project declared collections (`{ <name>: { fields: { <f>: { type, required? } } } }`
+ *  — the vxil.config / apply-bundle shape) onto HookFieldTypes. Malformed
+ *  entries are skipped: no declared field means no verdict. */
+export declare function hookFieldTypesOf(collections: unknown): HookFieldTypes;
+/** Type every hook whose collection the caller declares (see checkHookExprTypes).
+ *  Unparseable expressions are skipped — validateHookDef already reports them. */
+export declare function checkHookTypes(hooks: Record<string, HookDef> | undefined, fieldTypes: HookFieldTypes): {
+    errors: string[];
+    warnings: string[];
+};
 export type HlKind = 'num' | 'str' | 'fn' | 'var' | 'kw' | 'op' | 'ident' | 'ws' | 'err';
 /** Token-level highlighter over the FULL source (whitespace + bad chars kept),
  *  so a dashboard editor can render a colored overlay behind a textarea. */

package/dist/hooks.js

@@ -92,6 +92,21 @@ export class HookEvalError extends Error {
 /** Thrown by a `validate` hook whose expression is falsy — maps to a clean 422. */
 export class HookRejection extends Error {
 }
+/** A WRITE `validate` hook whose expression could not be evaluated (null
+ *  arithmetic, a missing operand, a bad date …). Still a HookEvalError — the
+ *  write is refused, never let through — but it carries the hook's id and its
+ *  declared `message`, so the API can show the end user the tenant's own copy
+ *  while keeping the engine detail for the developer. `message` stays the
+ *  engine detail. */
+export class HookValidateFault extends HookEvalError {
+    hookId;
+    tenantMessage;
+    constructor(hookId, tenantMessage, detail) {
+        super(detail);
+        this.hookId = hookId;
+        this.tenantMessage = tenantMessage;
+    }
+}
 const PUNCT = ['||', '&&', '==', '!=', '<=', '>=', '<', '>', '+', '-', '*', '/', '%', '!', '(', ')', ',', '.', '?', ':'];
 function tokenize(src) {
     if (src.length > HOOK_LIMITS.maxSourceLen) {
@@ -675,7 +690,17 @@ export function runWriteHooks(hooks, collection, phase, data, before, now) {
         if (h.kind !== 'validate')
             continue;
         const ast = parseCached(id, h.expr);
-        if (!truthy(evalExpr(ast, ctx))) {
+        let verdict;
+        try {
+            verdict = evalExpr(ast, ctx);
+        }
+        catch (e) {
+            // fail closed with the hook's own message attached (see HookValidateFault)
+            if (e instanceof HookEvalError)
+                throw new HookValidateFault(id, h.message || undefined, e.message);
+            throw e;
+        }
+        if (!truthy(verdict)) {
             throw new HookRejection(h.message || `validation hook '${id}' rejected the write`);
         }
     }
@@ -841,6 +866,207 @@ export function inferType(nd) {
         default: return 'unknown';
     }
 }
+const FIELD_STATIC = {
+    string: 'string', text: 'string', datetime: 'string', relation: 'string', file: 'string',
+    int: 'number', float: 'number', bool: 'boolean', json: 'json',
+};
+const WRITE_EVENTS = new Set(['beforeCreate', 'beforeUpdate', 'beforeWrite']);
+/** `item.<f>` / `before.<f>` (one level) → { root, field }; anything else → null. */
+function fieldRef(nd) {
+    if (nd.t !== 'member' || nd.obj.t !== 'var')
+        return null;
+    if (nd.obj.name !== 'item' && nd.obj.name !== 'before')
+        return null;
+    return { root: nd.obj.name, field: nd.prop };
+}
+function staticTypeOf(nd, fields) {
+    if (nd.t === 'var' && (nd.name === 'item' || nd.name === 'before' || nd.name === 'caller'))
+        return 'object';
+    const ref = fieldRef(nd);
+    if (ref) {
+        const f = fields && Object.prototype.hasOwnProperty.call(fields, ref.field) ? fields[ref.field] : undefined;
+        return f ? FIELD_STATIC[f.type] ?? 'unknown' : 'unknown';
+    }
+    return inferType(nd);
+}
+function describeOperand(nd) {
+    const ref = fieldRef(nd);
+    if (ref)
+        return `${ref.root}.${ref.field}`;
+    if (nd.t === 'var')
+        return nd.name;
+    if (nd.t === 'str')
+        return JSON.stringify(nd.v);
+    return 'a text value';
+}
+/** An operand `+` can never turn into a number (num() → NaN → a fault on
+ *  every evaluation): `now` (an ISO timestamp), a datetime field, or a text
+ *  literal that is not numeric. Text fields are NOT here — "42" + 1 works. */
+function nanOperand(nd, fields) {
+    if (nd.t === 'var' && nd.name === 'now')
+        return nd;
+    if (nd.t === 'str')
+        return Number.isFinite(Number(nd.v)) ? null : nd;
+    const ref = fieldRef(nd);
+    if (ref && fields && Object.prototype.hasOwnProperty.call(fields, ref.field) && fields[ref.field].type === 'datetime')
+        return nd;
+    return null;
+}
+/** Type one parsed expression against one collection's declared fields.
+ *  `errors` are shapes that can never work (refuse); `warnings` are shapes
+ *  that work only for some stored values (json vs a scalar, `+` on a text
+ *  field) and arithmetic on an optional field with no coalesce() — it faults
+ *  the hook whenever the field is missing. `present` lists fields a derive sets first. */
+export function checkHookExprTypes(root, fields, opts) {
+    const errors = [];
+    const warnings = [];
+    const warned = new Set();
+    const writePath = WRITE_EVENTS.has(opts.event);
+    const optionalOperand = (nd) => {
+        if (!writePath || !fields)
+            return;
+        const ref = fieldRef(nd);
+        if (!ref)
+            return;
+        const f = Object.prototype.hasOwnProperty.call(fields, ref.field) ? fields[ref.field] : undefined;
+        if (!f || f.required === true || (ref.root === 'item' && opts.present?.has(ref.field)))
+            return;
+        const name = `${ref.root}.${ref.field}`;
+        if (warned.has(name))
+            return;
+        warned.add(name);
+        warnings.push(`arithmetic on '${name}', which is optional, faults the hook whenever it is missing — write coalesce(${name}, 0)`);
+    };
+    const walk = (nd) => {
+        switch (nd.t) {
+            case 'bin': {
+                let refused = false;
+                if (nd.op === '==' || nd.op === '!=') {
+                    const lt = staticTypeOf(nd.l, fields);
+                    const rt = staticTypeOf(nd.r, fields);
+                    if (nd.l.t !== 'null' && nd.r.t !== 'null') {
+                        const always = nd.op === '==' ? 'always false' : 'always true';
+                        // provably an object on one side: a whole row, or json vs json/row
+                        const objSide = lt === 'object' ? nd.l : rt === 'object' ? nd.r
+                            : (lt === 'json' && rt === 'json') ? nd.l : null;
+                        const jsonSide = lt === 'json' ? nd.l : rt === 'json' ? nd.r : null;
+                        if (objSide) {
+                            errors.push(`'${nd.op}' cannot compare '${describeOperand(objSide)}' (an object or json value: the comparison is ${always}) — compare a scalar inside it (e.g. ${describeOperand(objSide)}.status) or test isNull()`);
+                        }
+                        else if (jsonSide) {
+                            warnings.push(`'${nd.op}' on json field '${describeOperand(jsonSide)}' compares only when it holds a scalar — when it holds an object or array the comparison is ${always}; compare a scalar inside it (e.g. ${describeOperand(jsonSide)}.status)`);
+                        }
+                    }
+                }
+                else if (nd.op === '+') {
+                    const nan = nanOperand(nd.l, fields) ?? nanOperand(nd.r, fields);
+                    if (nan) {
+                        refused = true;
+                        errors.push(`'+' adds numbers only, and '${describeOperand(nan)}' is never a number — use concat() to join text`);
+                    }
+                    else {
+                        const strSide = staticTypeOf(nd.l, fields) === 'string' ? nd.l : staticTypeOf(nd.r, fields) === 'string' ? nd.r : null;
+                        if (strSide) {
+                            warnings.push(`'+' adds numbers only: '${describeOperand(strSide)}' is text, so the hook faults unless it holds a numeric string — use concat() to join text, or number() to add`);
+                        }
+                    }
+                }
+                if (!refused && (nd.op === '+' || nd.op === '-' || nd.op === '*' || nd.op === '/' || nd.op === '%')) {
+                    optionalOperand(nd.l);
+                    optionalOperand(nd.r);
+                }
+                walk(nd.l);
+                walk(nd.r);
+                return;
+            }
+            case 'unary':
+                if (nd.op === '-')
+                    optionalOperand(nd.arg);
+                walk(nd.arg);
+                return;
+            case 'tern':
+                walk(nd.c);
+                walk(nd.a);
+                walk(nd.b);
+                return;
+            case 'call':
+                for (const a of nd.args)
+                    walk(a);
+                return;
+            case 'member':
+                walk(nd.obj);
+                return;
+            default: return;
+        }
+    };
+    walk(root);
+    return { errors, warnings };
+}
+/** Project declared collections (`{ <name>: { fields: { <f>: { type, required? } } } }`
+ *  — the vxil.config / apply-bundle shape) onto HookFieldTypes. Malformed
+ *  entries are skipped: no declared field means no verdict. */
+export function hookFieldTypesOf(collections) {
+    const out = {};
+    if (!collections || typeof collections !== 'object')
+        return out;
+    for (const [name, def] of Object.entries(collections)) {
+        const fields = def?.fields;
+        if (!fields || typeof fields !== 'object')
+            continue;
+        const m = {};
+        for (const [f, fd] of Object.entries(fields)) {
+            const t = fd?.type;
+            if (typeof t !== 'string')
+                continue;
+            m[f] = { type: t, ...(fd.required === true ? { required: true } : {}) };
+        }
+        out[name] = m;
+    }
+    return out;
+}
+/** Type every hook whose collection the caller declares (see checkHookExprTypes).
+ *  Unparseable expressions are skipped — validateHookDef already reports them. */
+export function checkHookTypes(hooks, fieldTypes) {
+    const errors = [];
+    const warnings = [];
+    if (!hooks)
+        return { errors, warnings };
+    // fields a write-path derive sets before the validates run (runWriteHooks pass 1)
+    const derived = new Map();
+    for (const h of Object.values(hooks)) {
+        if (h.kind === 'derive' && h.field && WRITE_EVENTS.has(h.event) && h.enabled !== false) {
+            if (!derived.has(h.collection))
+                derived.set(h.collection, new Set());
+            derived.get(h.collection).add(h.field);
+        }
+    }
+    for (const [id, h] of Object.entries(hooks)) {
+        if (!Object.prototype.hasOwnProperty.call(fieldTypes, h.collection))
+            continue;
+        let ast;
+        try {
+            ast = parseExpr(h.expr ?? '');
+        }
+        catch {
+            continue;
+        }
+        if (validateAst(ast).length)
+            continue;
+        const r = checkHookExprTypes(ast, fieldTypes[h.collection], {
+            kind: h.kind, event: h.event, present: h.kind === 'validate' ? derived.get(h.collection) : undefined,
+        });
+        // a disabled hook never runs: its findings cannot break a write, so they warn
+        if (h.enabled === false)
+            for (const e of r.errors)
+                warnings.push(`hooks.${id}.expr (disabled): ${e}`);
+        else
+            for (const e of r.errors)
+                errors.push(`hooks.${id}.expr: ${e}`);
+        for (const w of r.warnings)
+            warnings.push(`hooks.${id}.expr: ${w}`);
+    }
+    return { errors, warnings };
+}
 /** Token-level highlighter over the FULL source (whitespace + bad chars kept),
  *  so a dashboard editor can render a colored overlay behind a textarea. */
 export function highlightTokens(src) {

package/dist/index.d.ts

@@ -78,9 +78,10 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
         maxAttempts: import("@sinclair/typebox").TInteger;
         backoff: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"exponential">, import("@sinclair/typebox").TLiteral<"linear">]>;
     }>>;
-    suppression: import("@sinclair/typebox").TObject<{
+    suppression: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         softBounceThreshold: import("@sinclair/typebox").TInteger;
-    }>;
+        testRecipients: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    }>>;
     rateLimit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         perDay: import("@sinclair/typebox").TInteger;
         perTenantSec: import("@sinclair/typebox").TInteger;
@@ -832,6 +833,9 @@ export declare const TEST_RECIPIENT_EMAIL_RE: RegExp;
 export declare const TEST_RECIPIENT_GLOB_RE: RegExp;
 export declare const TEST_RECIPIENT_E164_RE: RegExp;
 export declare function isTestRecipientPattern(entry: string): boolean;
+/** The MAIL subset of the grammar (notifications suppression.testRecipients):
+ * an exact email or an `*@domain` glob. */
+export declare function isMailTestRecipientPattern(entry: string): boolean;
 /** True iff `identifier` (an email today) matches one configured entry:
  * exact (case-insensitive) or the `*@domain` glob. +E.164 entries never match
  * an email. */

package/dist/index.js

@@ -231,7 +231,26 @@ export const NotificationsConfigSchema = Type.Object({
             default: 'exponential',
         }),
     }, { default: {} })),
-    suppression: Type.Object({ softBounceThreshold: Type.Integer({ default: 3 }) }, { default: {} }),
+    // `suppression` became an OPTIONAL bag (1 leaf either way — it held the one
+    // leaf softBounceThreshold) on 2026-10-04 so the
+    // `testRecipients` list rides inside it at zero leaf cost (the schema is AT
+    // the cap). It KEEPS `default: {}`, so Value.Default still materializes
+    // suppression.softBounceThreshold into every persisted manifest exactly as
+    // before (byte-identical); only the TS type is optional (workers read via
+    // `config.suppression?.…` with the shipped fallback).
+    suppression: Type.Optional(Type.Object({
+        softBounceThreshold: Type.Integer({ default: 3 }),
+        // TEST-RECIPIENT SINK (2026-10-04) — the auth `otp.testRecipients` grammar and
+        // matcher (matchesTestRecipient): an exact email or a `*@domain` glob,
+        // ≤20 (validateFeatureConfig refuses anything else — a +E.164 entry
+        // could never match a mail recipient). A send whose recipient matches is
+        // rendered in full and recorded as a delivery with status `test_sink`
+        // (the render readable at GET /v1/notifications/deliveries/{id}); NO
+        // provider is called and the send is not billed. Optional, no default:
+        // absent = no sink. CI / store-review / QA addresses only — never a real
+        // user's address.
+        testRecipients: Type.Optional(Type.Array(Type.String({ minLength: 3, maxLength: 320 }), { maxItems: 20 })),
+    }, { default: {} })),
     // `rateLimit` became an OPTIONAL bag (2 leaves → 1, the `retry` trick)
     // on 2026-09-19 to fund the `ses` credential bag above. It KEEPS
     // `default: {}`, so Value.Default still materializes
@@ -824,7 +843,9 @@ export const CmsConfigSchema = Type.Object({
         maxCollections: Type.Integer({ default: 25, minimum: 1, maximum: 200 }),
         maxFieldsPerCollection: Type.Integer({ default: 50, minimum: 1, maximum: 200 }),
         maxItemBytes: Type.Integer({ default: 256 * 1024, minimum: 1024, maximum: 1024 * 1024 }),
-        maxItemsPerCollection: Type.Integer({ default: 100_000, minimum: 1 }),
+        // Capped at 10 M: every create counts the collection's live rows, so
+        // the cap also bounds what each create pays.
+        maxItemsPerCollection: Type.Integer({ default: 100_000, minimum: 1, maximum: 10_000_000 }),
     }, { default: {} }),
     query: Type.Object({
         maxPageSize: Type.Integer({ default: 100, minimum: 1, maximum: 500 }),
@@ -1659,6 +1680,11 @@ export const TEST_RECIPIENT_E164_RE = /^\+[1-9]\d{1,14}$/;
 export function isTestRecipientPattern(entry) {
     return TEST_RECIPIENT_EMAIL_RE.test(entry) || TEST_RECIPIENT_GLOB_RE.test(entry) || TEST_RECIPIENT_E164_RE.test(entry);
 }
+/** The MAIL subset of the grammar (notifications suppression.testRecipients):
+ * an exact email or an `*@domain` glob. */
+export function isMailTestRecipientPattern(entry) {
+    return TEST_RECIPIENT_EMAIL_RE.test(entry) || TEST_RECIPIENT_GLOB_RE.test(entry);
+}
 /** True iff `identifier` (an email today) matches one configured entry:
  * exact (case-insensitive) or the `*@domain` glob. +E.164 entries never match
  * an email. */
@@ -2107,6 +2133,17 @@ export function validateFeatureConfig(feature, raw) {
         if (errs.length)
             return { ok: false, errors: errs.slice(0, 10) };
     }
+    // Cross-field rule (2026-10-04): notifications suppression.testRecipients — every
+    // entry must be an email or an `*@domain` glob (the auth grammar minus
+    // +E.164: a phone number can never match a mail recipient, so it would sit
+    // in the list doing nothing).
+    if (feature === 'notifications') {
+        const v = withDefaults;
+        const bad = (v.suppression?.testRecipients ?? []).filter((e) => !isMailTestRecipientPattern(e));
+        if (bad.length) {
+            return { ok: false, errors: bad.slice(0, 10).map((e) => `/suppression/testRecipients: '${e}' is not an email or an *@domain glob`) };
+        }
+    }
     // Cross-field rule: auth otp.testRecipients — every entry must be an
     // email, an `*@domain` glob, or a +E.164 number; anything else would never
     // match and silently do nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "The per-feature configuration schemas and validators behind vxil.config.ts (published for @vxil/cli and @vxil/config).",
   "license": "MIT",
   "homepage": "https://vxil.com",

package/src/hooks.ts

@@ -107,6 +107,21 @@ export class HookParseError extends Error {}
 export class HookEvalError extends Error {}
 /** Thrown by a `validate` hook whose expression is falsy — maps to a clean 422. */
 export class HookRejection extends Error {}
+/** A WRITE `validate` hook whose expression could not be evaluated (null
+ *  arithmetic, a missing operand, a bad date …). Still a HookEvalError — the
+ *  write is refused, never let through — but it carries the hook's id and its
+ *  declared `message`, so the API can show the end user the tenant's own copy
+ *  while keeping the engine detail for the developer. `message` stays the
+ *  engine detail. */
+export class HookValidateFault extends HookEvalError {
+  constructor(
+    readonly hookId: string,
+    readonly tenantMessage: string | undefined,
+    detail: string,
+  ) {
+    super(detail);
+  }
+}
 
 // ── tokenizer ───────────────────────────────────────────────────────────────
 type Tok =
@@ -624,7 +639,15 @@ export function runWriteHooks(
   for (const [id, h] of entries) {
     if (h.kind !== 'validate') continue;
     const ast = parseCached(id, h.expr);
-    if (!truthy(evalExpr(ast, ctx))) {
+    let verdict: unknown;
+    try {
+      verdict = evalExpr(ast, ctx);
+    } catch (e) {
+      // fail closed with the hook's own message attached (see HookValidateFault)
+      if (e instanceof HookEvalError) throw new HookValidateFault(id, h.message || undefined, e.message);
+      throw e;
+    }
+    if (!truthy(verdict)) {
       throw new HookRejection(h.message || `validation hook '${id}' rejected the write`);
     }
   }
@@ -791,6 +814,203 @@ export function inferType(nd: Node): InferredType {
   }
 }
 
+// ── push-time typing against the declared fields ────────────────────────────
+// validateHookDef is purely syntactic: it cannot know that `item.meta` is a
+// json field, so `item.meta != before.meta` (ALWAYS true — eq() never compares
+// objects) or `item.title + '!'` (ALWAYS a fault — `+` is numeric) pass it and
+// fail on every write. Where the caller knows the collection's fields (a push
+// or apply that declares them, the dashboard editor) this resolves `item.<f>` /
+// `before.<f>` to the declared type. It REFUSES only shapes that fault or
+// mis-evaluate for every value the field can hold:
+//   - `==` / `!=` on a whole row (`item`, `before`, `caller`), or a json field
+//     against another json field or a whole row (eq() never compares objects);
+//   - `+` with `now`, a datetime field, or a non-numeric text literal (`+` is
+//     numeric and num() turns those into NaN → a fault on every write).
+// Shapes that work for SOME stored values are WARNINGS, never refusals: a json
+// field against a scalar (`item.meta == 'active'` is right when meta holds a
+// string — json accepts any value), and `+` on a text-typed field (num()
+// coerces a numeric string such as "42"). Anything it cannot type (an
+// undeclared collection or field, a nested path, coalesce, a mixed ternary)
+// gets no verdict. Disabled hooks (enabled: false) only ever warn.
+
+/** One declared field, as the typing pass needs it (cms field type + required). */
+export interface HookFieldInfo { type: string; required?: boolean }
+/** collection → field → declared info. */
+export type HookFieldTypes = Record<string, Record<string, HookFieldInfo>>;
+
+type StaticType = 'number' | 'string' | 'boolean' | 'null' | 'json' | 'object' | 'unknown';
+const FIELD_STATIC: Record<string, StaticType> = {
+  string: 'string', text: 'string', datetime: 'string', relation: 'string', file: 'string',
+  int: 'number', float: 'number', bool: 'boolean', json: 'json',
+};
+const WRITE_EVENTS = new Set<HookDef['event']>(['beforeCreate', 'beforeUpdate', 'beforeWrite']);
+
+/** `item.<f>` / `before.<f>` (one level) → { root, field }; anything else → null. */
+function fieldRef(nd: Node): { root: 'item' | 'before'; field: string } | null {
+  if (nd.t !== 'member' || nd.obj.t !== 'var') return null;
+  if (nd.obj.name !== 'item' && nd.obj.name !== 'before') return null;
+  return { root: nd.obj.name, field: nd.prop };
+}
+
+function staticTypeOf(nd: Node, fields: Record<string, HookFieldInfo> | undefined): StaticType {
+  if (nd.t === 'var' && (nd.name === 'item' || nd.name === 'before' || nd.name === 'caller')) return 'object';
+  const ref = fieldRef(nd);
+  if (ref) {
+    const f = fields && Object.prototype.hasOwnProperty.call(fields, ref.field) ? fields[ref.field] : undefined;
+    return f ? FIELD_STATIC[f.type] ?? 'unknown' : 'unknown';
+  }
+  return inferType(nd);
+}
+
+function describeOperand(nd: Node): string {
+  const ref = fieldRef(nd);
+  if (ref) return `${ref.root}.${ref.field}`;
+  if (nd.t === 'var') return nd.name;
+  if (nd.t === 'str') return JSON.stringify(nd.v);
+  return 'a text value';
+}
+
+/** An operand `+` can never turn into a number (num() → NaN → a fault on
+ *  every evaluation): `now` (an ISO timestamp), a datetime field, or a text
+ *  literal that is not numeric. Text fields are NOT here — "42" + 1 works. */
+function nanOperand(nd: Node, fields: Record<string, HookFieldInfo> | undefined): Node | null {
+  if (nd.t === 'var' && nd.name === 'now') return nd;
+  if (nd.t === 'str') return Number.isFinite(Number(nd.v)) ? null : nd;
+  const ref = fieldRef(nd);
+  if (ref && fields && Object.prototype.hasOwnProperty.call(fields, ref.field) && fields[ref.field]!.type === 'datetime') return nd;
+  return null;
+}
+
+/** Type one parsed expression against one collection's declared fields.
+ *  `errors` are shapes that can never work (refuse); `warnings` are shapes
+ *  that work only for some stored values (json vs a scalar, `+` on a text
+ *  field) and arithmetic on an optional field with no coalesce() — it faults
+ *  the hook whenever the field is missing. `present` lists fields a derive sets first. */
+export function checkHookExprTypes(
+  root: Node,
+  fields: Record<string, HookFieldInfo> | undefined,
+  opts: { kind: HookDef['kind']; event: HookDef['event']; present?: ReadonlySet<string> | undefined },
+): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const warned = new Set<string>();
+  const writePath = WRITE_EVENTS.has(opts.event);
+  const optionalOperand = (nd: Node): void => {
+    if (!writePath || !fields) return;
+    const ref = fieldRef(nd);
+    if (!ref) return;
+    const f = Object.prototype.hasOwnProperty.call(fields, ref.field) ? fields[ref.field] : undefined;
+    if (!f || f.required === true || (ref.root === 'item' && opts.present?.has(ref.field))) return;
+    const name = `${ref.root}.${ref.field}`;
+    if (warned.has(name)) return;
+    warned.add(name);
+    warnings.push(`arithmetic on '${name}', which is optional, faults the hook whenever it is missing — write coalesce(${name}, 0)`);
+  };
+  const walk = (nd: Node): void => {
+    switch (nd.t) {
+      case 'bin': {
+        let refused = false;
+        if (nd.op === '==' || nd.op === '!=') {
+          const lt = staticTypeOf(nd.l, fields);
+          const rt = staticTypeOf(nd.r, fields);
+          if (nd.l.t !== 'null' && nd.r.t !== 'null') {
+            const always = nd.op === '==' ? 'always false' : 'always true';
+            // provably an object on one side: a whole row, or json vs json/row
+            const objSide = lt === 'object' ? nd.l : rt === 'object' ? nd.r
+              : (lt === 'json' && rt === 'json') ? nd.l : null;
+            const jsonSide = lt === 'json' ? nd.l : rt === 'json' ? nd.r : null;
+            if (objSide) {
+              errors.push(`'${nd.op}' cannot compare '${describeOperand(objSide)}' (an object or json value: the comparison is ${always}) — compare a scalar inside it (e.g. ${describeOperand(objSide)}.status) or test isNull()`);
+            } else if (jsonSide) {
+              warnings.push(`'${nd.op}' on json field '${describeOperand(jsonSide)}' compares only when it holds a scalar — when it holds an object or array the comparison is ${always}; compare a scalar inside it (e.g. ${describeOperand(jsonSide)}.status)`);
+            }
+          }
+        } else if (nd.op === '+') {
+          const nan = nanOperand(nd.l, fields) ?? nanOperand(nd.r, fields);
+          if (nan) {
+            refused = true;
+            errors.push(`'+' adds numbers only, and '${describeOperand(nan)}' is never a number — use concat() to join text`);
+          } else {
+            const strSide = staticTypeOf(nd.l, fields) === 'string' ? nd.l : staticTypeOf(nd.r, fields) === 'string' ? nd.r : null;
+            if (strSide) {
+              warnings.push(`'+' adds numbers only: '${describeOperand(strSide)}' is text, so the hook faults unless it holds a numeric string — use concat() to join text, or number() to add`);
+            }
+          }
+        }
+        if (!refused && (nd.op === '+' || nd.op === '-' || nd.op === '*' || nd.op === '/' || nd.op === '%')) {
+          optionalOperand(nd.l);
+          optionalOperand(nd.r);
+        }
+        walk(nd.l); walk(nd.r);
+        return;
+      }
+      case 'unary':
+        if (nd.op === '-') optionalOperand(nd.arg);
+        walk(nd.arg);
+        return;
+      case 'tern': walk(nd.c); walk(nd.a); walk(nd.b); return;
+      case 'call': for (const a of nd.args) walk(a); return;
+      case 'member': walk(nd.obj); return;
+      default: return;
+    }
+  };
+  walk(root);
+  return { errors, warnings };
+}
+
+/** Project declared collections (`{ <name>: { fields: { <f>: { type, required? } } } }`
+ *  — the vxil.config / apply-bundle shape) onto HookFieldTypes. Malformed
+ *  entries are skipped: no declared field means no verdict. */
+export function hookFieldTypesOf(collections: unknown): HookFieldTypes {
+  const out: HookFieldTypes = {};
+  if (!collections || typeof collections !== 'object') return out;
+  for (const [name, def] of Object.entries(collections as Record<string, unknown>)) {
+    const fields = (def as { fields?: unknown } | null)?.fields;
+    if (!fields || typeof fields !== 'object') continue;
+    const m: Record<string, HookFieldInfo> = {};
+    for (const [f, fd] of Object.entries(fields as Record<string, unknown>)) {
+      const t = (fd as { type?: unknown } | null)?.type;
+      if (typeof t !== 'string') continue;
+      m[f] = { type: t, ...((fd as { required?: unknown }).required === true ? { required: true } : {}) };
+    }
+    out[name] = m;
+  }
+  return out;
+}
+
+/** Type every hook whose collection the caller declares (see checkHookExprTypes).
+ *  Unparseable expressions are skipped — validateHookDef already reports them. */
+export function checkHookTypes(
+  hooks: Record<string, HookDef> | undefined,
+  fieldTypes: HookFieldTypes,
+): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (!hooks) return { errors, warnings };
+  // fields a write-path derive sets before the validates run (runWriteHooks pass 1)
+  const derived = new Map<string, Set<string>>();
+  for (const h of Object.values(hooks)) {
+    if (h.kind === 'derive' && h.field && WRITE_EVENTS.has(h.event) && h.enabled !== false) {
+      if (!derived.has(h.collection)) derived.set(h.collection, new Set());
+      derived.get(h.collection)!.add(h.field);
+    }
+  }
+  for (const [id, h] of Object.entries(hooks)) {
+    if (!Object.prototype.hasOwnProperty.call(fieldTypes, h.collection)) continue;
+    let ast: Node;
+    try { ast = parseExpr(h.expr ?? ''); } catch { continue; }
+    if (validateAst(ast).length) continue;
+    const r = checkHookExprTypes(ast, fieldTypes[h.collection], {
+      kind: h.kind, event: h.event, present: h.kind === 'validate' ? derived.get(h.collection) : undefined,
+    });
+    // a disabled hook never runs: its findings cannot break a write, so they warn
+    if (h.enabled === false) for (const e of r.errors) warnings.push(`hooks.${id}.expr (disabled): ${e}`);
+    else for (const e of r.errors) errors.push(`hooks.${id}.expr: ${e}`);
+    for (const w of r.warnings) warnings.push(`hooks.${id}.expr: ${w}`);
+  }
+  return { errors, warnings };
+}
+
 export type HlKind = 'num' | 'str' | 'fn' | 'var' | 'kw' | 'op' | 'ident' | 'ws' | 'err';
 
 /** Token-level highlighter over the FULL source (whitespace + bad chars kept),

package/src/index.ts

@@ -250,10 +250,31 @@ export const NotificationsConfigSchema = Type.Object({
     },
     { default: {} },
   )),
-  suppression: Type.Object(
-    { softBounceThreshold: Type.Integer({ default: 3 }) },
+  // `suppression` became an OPTIONAL bag (1 leaf either way — it held the one
+  // leaf softBounceThreshold) on 2026-10-04 so the
+  // `testRecipients` list rides inside it at zero leaf cost (the schema is AT
+  // the cap). It KEEPS `default: {}`, so Value.Default still materializes
+  // suppression.softBounceThreshold into every persisted manifest exactly as
+  // before (byte-identical); only the TS type is optional (workers read via
+  // `config.suppression?.…` with the shipped fallback).
+  suppression: Type.Optional(Type.Object(
+    {
+      softBounceThreshold: Type.Integer({ default: 3 }),
+      // TEST-RECIPIENT SINK (2026-10-04) — the auth `otp.testRecipients` grammar and
+      // matcher (matchesTestRecipient): an exact email or a `*@domain` glob,
+      // ≤20 (validateFeatureConfig refuses anything else — a +E.164 entry
+      // could never match a mail recipient). A send whose recipient matches is
+      // rendered in full and recorded as a delivery with status `test_sink`
+      // (the render readable at GET /v1/notifications/deliveries/{id}); NO
+      // provider is called and the send is not billed. Optional, no default:
+      // absent = no sink. CI / store-review / QA addresses only — never a real
+      // user's address.
+      testRecipients: Type.Optional(Type.Array(
+        Type.String({ minLength: 3, maxLength: 320 }), { maxItems: 20 },
+      )),
+    },
     { default: {} },
-  ),
+  )),
   // `rateLimit` became an OPTIONAL bag (2 leaves → 1, the `retry` trick)
   // on 2026-09-19 to fund the `ses` credential bag above. It KEEPS
   // `default: {}`, so Value.Default still materializes
@@ -329,7 +350,8 @@ export const NotificationsConfigSchema = Type.Object({
 });
 // Leaves: enabled, fromEmail, fromName, replyTo, resendApiKeyRef,
 // webhookSecretRef, provider, ses (Optional bag = 1, 2026-09-19), defaultLocale,
-// retry (Optional bag = 1), suppression.softBounceThreshold,
+// retry (Optional bag = 1), suppression (Optional bag = 1 since 2026-10-04 —
+// was suppression.softBounceThreshold; now also carries testRecipients),
 // rateLimit (Optional bag = 1 — was rateLimit.{perDay,perTenantSec}, collapsed
 // 2026-09-19 to fund `ses` at zero net cost), templates (Optional bag = 1 — was
 // templates.allowOverride, collapsed 2026-09-10 to fund the `overrides` map
@@ -971,7 +993,9 @@ export const CmsConfigSchema = Type.Object({
       maxCollections: Type.Integer({ default: 25, minimum: 1, maximum: 200 }),
       maxFieldsPerCollection: Type.Integer({ default: 50, minimum: 1, maximum: 200 }),
       maxItemBytes: Type.Integer({ default: 256 * 1024, minimum: 1024, maximum: 1024 * 1024 }),
-      maxItemsPerCollection: Type.Integer({ default: 100_000, minimum: 1 }),
+      // Capped at 10 M: every create counts the collection's live rows, so
+      // the cap also bounds what each create pays.
+      maxItemsPerCollection: Type.Integer({ default: 100_000, minimum: 1, maximum: 10_000_000 }),
     },
     { default: {} },
   ),
@@ -2048,6 +2072,11 @@ export const TEST_RECIPIENT_E164_RE = /^\+[1-9]\d{1,14}$/;
 export function isTestRecipientPattern(entry: string): boolean {
   return TEST_RECIPIENT_EMAIL_RE.test(entry) || TEST_RECIPIENT_GLOB_RE.test(entry) || TEST_RECIPIENT_E164_RE.test(entry);
 }
+/** The MAIL subset of the grammar (notifications suppression.testRecipients):
+ * an exact email or an `*@domain` glob. */
+export function isMailTestRecipientPattern(entry: string): boolean {
+  return TEST_RECIPIENT_EMAIL_RE.test(entry) || TEST_RECIPIENT_GLOB_RE.test(entry);
+}
 /** True iff `identifier` (an email today) matches one configured entry:
  * exact (case-insensitive) or the `*@domain` glob. +E.164 entries never match
  * an email. */
@@ -2535,6 +2564,17 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     const errs = validateDeclaredWebhookSubscriptions(v.subscriptions, v.maxSubscriptions);
     if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
   }
+  // Cross-field rule (2026-10-04): notifications suppression.testRecipients — every
+  // entry must be an email or an `*@domain` glob (the auth grammar minus
+  // +E.164: a phone number can never match a mail recipient, so it would sit
+  // in the list doing nothing).
+  if (feature === 'notifications') {
+    const v = withDefaults as { suppression?: { testRecipients?: string[] } };
+    const bad = (v.suppression?.testRecipients ?? []).filter((e) => !isMailTestRecipientPattern(e));
+    if (bad.length) {
+      return { ok: false, errors: bad.slice(0, 10).map((e) => `/suppression/testRecipients: '${e}' is not an email or an *@domain glob`) };
+    }
+  }
   // Cross-field rule: auth otp.testRecipients — every entry must be an
   // email, an `*@domain` glob, or a +E.164 number; anything else would never
   // match and silently do nothing.