@vxil/feature-configs 0.9.1 → 0.11.0

package/dist/hooks.d.ts

@@ -10,12 +10,16 @@ export declare const HOOK_LIMITS: {
     readonly maxReadHooksPerCollection: 10;
 };
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
- *  populated ONLY on the READ path (runReadHooks); on the write path and in
- *  server-caller mode it is null, exactly like `before` on a create. It carries
- *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`
- *  ('end_user' | 'tenant'). It is the missing "caller/session context" a read
- *  hook keys on to redact/derive per-viewer. */
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only.
+ *  It carries `caller.endUserId` (the verified session sub, or null),
+ *  `caller.principal` ('end_user' | 'tenant') and `caller.roles` (the VERIFIED
+ *  session role claims of the signed-in session — never a body or header
+ *  value; null in server-caller mode). READ hooks always get it
+ *  (server mode: `{ endUserId: null, principal: 'tenant', roles: null }`).
+ *  WRITE hooks get it in verified end-user mode only; on a
+ *  server write it is null, exactly like `before` on a create — so a role rule
+ *  reads `isNull(caller) || contains(caller.roles, 'manager')`. `contains` on
+ *  an array is exact element membership. */
 export declare const HOOK_ROOT_VARS: readonly ["item", "before", "now", "caller"];
 /** The ONLY callable functions. Each is pure + deterministic + bounded. */
 export declare const HOOK_FUNCTIONS: readonly ["min", "max", "abs", "round", "floor", "ceil", "sqrt", "pow", "sign", "len", "lower", "upper", "trim", "substr", "contains", "startsWith", "endsWith", "concat", "coalesce", "ifNull", "not", "isNull", "number", "string", "bool", "daysBetween", "yearsBetween"];
@@ -64,25 +68,41 @@ 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.
  *  Returns an array of human-readable errors (empty = safe). Pure, no eval. */
 export declare function validateAst(root: Node): string[];
-/** The VERIFIED caller/session context for read hooks (guide ch. 7). Read-only;
- *  present only on the read path in end-user mode. In server mode / write path
- *  the whole object is null. */
+/** The VERIFIED caller/session context for Lane-A hooks (guide ch. 7).
+ *  Read-only. Read hooks always get it; write hooks get it in verified end-user
+ *  mode only (a server write passes null — see HOOK_ROOT_VARS). */
 export interface HookCaller {
     /** the verified end-user session sub, or null in server-caller mode. */
     endUserId: string | null;
     /** 'end_user' when a session was verified at the edge, else 'tenant'. */
     principal: 'end_user' | 'tenant';
+    /** the VERIFIED session role claims of the signed-in session; `[]` for a
+     *  session without roles, null in server-caller mode. Optional so an older
+     *  caller object still reads
+     *  as "no roles". */
+    roles?: readonly string[] | null;
 }
 export interface HookContext {
     item: Record<string, unknown>;
     before: Record<string, unknown> | null;
     now: string;
-    /** verified caller/session context (read path only); null otherwise. */
+    /** verified caller/session context; null on a server write. */
     caller?: HookCaller | null;
 }
 /** A mutable step counter SHARED across many evalExpr calls (the read path's
@@ -116,7 +136,10 @@ export interface HookRunResult {
  *  Mutates a CLONE: derive hooks set fields; a validate hook that returns falsy
  *  throws HookRejection (→ the caller maps to a 422 and the tx rolls back).
  *  Throws HookEvalError on a runtime fault (also a clean 422, never a 500). */
-export declare function runWriteHooks(hooks: Record<string, HookDef> | undefined, collection: string, phase: 'create' | 'update', data: Record<string, unknown>, before: Record<string, unknown> | null, now: string): HookRunResult;
+export declare function runWriteHooks(hooks: Record<string, HookDef> | undefined, collection: string, phase: 'create' | 'update', data: Record<string, unknown>, before: Record<string, unknown> | null, now: string, 
+/** the VERIFIED end-user caller (endUserId + principal + roles) in
+ *  end-user mode; omitted / null on a server write (expressions see null). */
+caller?: HookCaller | null): HookRunResult;
 export interface ReadHookResult {
     /** Surviving rows in input order. Each is a SHALLOW COPY with a copied `data`
      *  bag — the caller's rows are never mutated and nothing here is persisted. */
@@ -143,8 +166,8 @@ export interface ReadHookResult {
  *  fire here, and read events never fire in runWriteHooks. */
 export declare function runReadHooks(hooks: Record<string, HookDef> | undefined, collection: string, rows: ReadonlyArray<Record<string, unknown>>, now: string, 
 /** verified caller/session context (guide ch. 7) — read-only, exposed to
- *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
- *  (server-caller mode). */
+ *  expressions as `caller.endUserId` / `caller.principal` / `caller.roles`.
+ *  Omitted ⇒ null (server-caller mode). */
 caller?: HookCaller | null): ReadHookResult;
 export interface ExprRef {
     root: 'item' | 'before' | 'now' | 'caller';
@@ -157,6 +180,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

@@ -61,12 +61,16 @@ export const HOOK_LIMITS = {
 };
 // ── allow-lists ─────────────────────────────────────────────────────────────
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
- *  populated ONLY on the READ path (runReadHooks); on the write path and in
- *  server-caller mode it is null, exactly like `before` on a create. It carries
- *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`
- *  ('end_user' | 'tenant'). It is the missing "caller/session context" a read
- *  hook keys on to redact/derive per-viewer. */
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only.
+ *  It carries `caller.endUserId` (the verified session sub, or null),
+ *  `caller.principal` ('end_user' | 'tenant') and `caller.roles` (the VERIFIED
+ *  session role claims of the signed-in session — never a body or header
+ *  value; null in server-caller mode). READ hooks always get it
+ *  (server mode: `{ endUserId: null, principal: 'tenant', roles: null }`).
+ *  WRITE hooks get it in verified end-user mode only; on a
+ *  server write it is null, exactly like `before` on a create — so a role rule
+ *  reads `isNull(caller) || contains(caller.roles, 'manager')`. `contains` on
+ *  an array is exact element membership. */
 export const HOOK_ROOT_VARS = ['item', 'before', 'now', 'caller'];
 /** The ONLY callable functions. Each is pure + deterministic + bounded. */
 export const HOOK_FUNCTIONS = [
@@ -92,6 +96,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) {
@@ -433,7 +452,16 @@ const FUNCS = {
     upper: (a) => str(a[0]).toUpperCase(),
     trim: (a) => str(a[0]).trim(),
     substr: (a) => { const s = str(a[0]); const start = Math.max(0, Math.trunc(num(a[1]))); const length = a[2] === undefined ? undefined : Math.max(0, Math.trunc(num(a[2]))); return s.substring(start, length === undefined ? undefined : start + length); },
-    contains: (a) => str(a[0]).includes(str(a[1])),
+    // An ARRAY haystack is exact element membership (`contains(caller.roles,
+    // 'manager')` must never match 'man' or 'managers'); a scalar haystack keeps
+    // the substring test. Elements compare as strings; objects never match.
+    contains: (a) => {
+        const needle = str(a[1]);
+        if (Array.isArray(a[0])) {
+            return a[0].some((el) => el !== null && typeof el !== 'object' && String(el) === needle);
+        }
+        return str(a[0]).includes(needle);
+    },
     startsWith: (a) => str(a[0]).startsWith(str(a[1])),
     endsWith: (a) => str(a[0]).endsWith(str(a[1])),
     concat: (a) => { const out = a.map(str).join(''); if (out.length > HOOK_LIMITS.maxStringLen)
@@ -475,7 +503,7 @@ export function evalExpr(root, ctx, shared) {
                     return ctx.before;
                 if (nd.name === 'now')
                     return ctx.now;
-                // caller (read path only) — null on the write path / server mode.
+                // caller — null on a server write (and on any path that passes none).
                 if (nd.name === 'caller')
                     return ctx.caller ?? null;
                 throw new HookEvalError(`unknown variable '${nd.name}'`);
@@ -643,12 +671,15 @@ function eventMatches(event, phase) {
  *  Mutates a CLONE: derive hooks set fields; a validate hook that returns falsy
  *  throws HookRejection (→ the caller maps to a 422 and the tx rolls back).
  *  Throws HookEvalError on a runtime fault (also a clean 422, never a 500). */
-export function runWriteHooks(hooks, collection, phase, data, before, now) {
+export function runWriteHooks(hooks, collection, phase, data, before, now, 
+/** the VERIFIED end-user caller (endUserId + principal + roles) in
+ *  end-user mode; omitted / null on a server write (expressions see null). */
+caller) {
     const out = { ...data };
     const derived = [];
     if (!hooks)
         return { data: out, derived };
-    const ctx = { item: out, before, now };
+    const ctx = { item: out, before, now, caller: caller ?? null };
     const entries = Object.entries(hooks).filter(([, h]) => h.collection === collection && h.enabled !== false && eventMatches(h.event, phase));
     // pass 1: derives (so validates can read derived values); pass 2: validates.
     for (const [id, h] of entries) {
@@ -675,7 +706,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`);
         }
     }
@@ -700,8 +741,8 @@ export function runWriteHooks(hooks, collection, phase, data, before, now) {
  *  fire here, and read events never fire in runWriteHooks. */
 export function runReadHooks(hooks, collection, rows, now, 
 /** verified caller/session context (guide ch. 7) — read-only, exposed to
- *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
- *  (server-caller mode). */
+ *  expressions as `caller.endUserId` / `caller.principal` / `caller.roles`.
+ *  Omitted ⇒ null (server-caller mode). */
 caller) {
     if (!hooks)
         return { rows: [...rows], dropped: 0 };
@@ -841,6 +882,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;
@@ -217,6 +218,7 @@ declare const OidcProviderSchema: import("@sinclair/typebox").TObject<{
         email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        rolePrefix: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -274,6 +276,7 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
                 email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                 name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                 roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                rolePrefix: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             }>>;
             allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
             autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -318,6 +321,8 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
         breachedPasswords: import("@sinclair/typebox").TBoolean;
         captchaSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         allowedRedirectOrigins: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        inviteOnly: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        allowedEmailDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>>;
 }>;
 /** The security bag as persisted (present ⇒ leaf defaults applied). */
@@ -632,6 +637,7 @@ export declare const RagConfigSchema: import("@sinclair/typebox").TObject<{
         topK: import("@sinclair/typebox").TInteger;
         mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"hybrid">, import("@sinclair/typebox").TLiteral<"vector">, import("@sinclair/typebox").TLiteral<"keyword">]>;
         minScore: import("@sinclair/typebox").TNumber;
+        minSimilarity: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
         rerank: import("@sinclair/typebox").TBoolean;
     }>;
     boosts: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
@@ -832,6 +838,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
@@ -444,6 +463,15 @@ const OidcProviderSchema = Type.Object({
         email: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
         name: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
         roles: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
+        // G-38b: an optional namespace prepended to every mapped IdP role (e.g.
+        // `idp-`), so an IdP group named like an app role (`finance`, `owner`)
+        // arrives as `idp-finance` and cannot pass a `readRoles: ['finance']`
+        // gate. Absent = the raw group names (the shipped behaviour). The prefixed
+        // role still obeys the 32-char role bound (longer ones are dropped).
+        // The alphabet is the cms readRoles / orgs role slug alphabet
+        // (`^[a-z0-9][a-z0-9_-]*$`, cms-v1 READ_ROLE_RE), so a prefixed role can
+        // itself be named in a gate — a `:`/`.`/uppercase prefix never could.
+        rolePrefix: Type.Optional(Type.String({ minLength: 1, maxLength: 16, pattern: '^[a-z0-9][a-z0-9_-]{0,15}$' })),
     })),
     // when non-empty, the asserted email's domain MUST be listed (fail-closed:
     // no email ⇒ refused) → 403 oidc_domain_not_allowed; a listed domain also
@@ -648,6 +676,23 @@ export const AuthConfigSchema = Type.Object({
         breachedPasswords: Type.Boolean({ default: false }),
         captchaSecretRef: Type.Optional(Type.String({ minLength: 1, maxLength: 200 })),
         allowedRedirectOrigins: Type.Optional(Type.Array(Type.String({ minLength: 8, maxLength: 253, pattern: REDIRECT_ORIGIN_PATTERN }), { maxItems: 32 })),
+        // G-3 sign-up gating (2026-10-05). Both Optional with NO default, so an
+        // existing manifest folds byte-identically and the gate is opt-in. When
+        // EITHER is set, every self-service account-create path (password sign-up,
+        // magic-link / OTP pre-register, the guest → email claim, social sign-in
+        // with google/github/apple/facebook) is checked, fail-closed:
+        //   • inviteOnly — a new account only for an address the tenant already
+        //     put in its user registry server-side (POST /v1/users, an import);
+        //   • allowedEmailDomains — otherwise, only for an address at one of these
+        //     domains (exact, lowercase; a provider must assert the address
+        //     VERIFIED).
+        // With either set, password sign-up is refused (it proves nothing about
+        // the address — a stranger could squat an invitee's address), guest
+        // sign-in is refused (a guest is nobody's invitee), and an existing
+        // account is never affected. The generic OIDC issuer keeps its own gate
+        // (providers.oidc.allowedDomains + IdP assignment). auth-v1 signupGate.ts.
+        inviteOnly: Type.Optional(Type.Boolean()),
+        allowedEmailDomains: Type.Optional(Type.Array(Type.String({ minLength: 3, maxLength: 253, pattern: '^[a-z0-9][a-z0-9.-]*\\.[a-z]{2,}$' }), { maxItems: 32 })),
     })),
 });
 // ── DECLARED API STATE (2026-09-23) ──────────────────────────────────────────
@@ -824,7 +869,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 }),
@@ -1164,6 +1211,12 @@ export const RagConfigSchema = Type.Object({
         mode: Type.Union([Type.Literal('hybrid'), Type.Literal('vector'), Type.Literal('keyword')], { default: 'hybrid' }),
         // drop retrieved chunks below this score BEFORE budgeting (0 = keep all).
         minScore: Type.Number({ default: 0 }),
+        // drop retrieved chunks whose cosine `similarity` to the query is
+        // below this floor (-1..1). Unlike minScore (a floor on the RRF rank
+        // value, ~0.016-0.033 at the top) this is the relevance threshold a RAG
+        // app means. Absent = no floor; a hit with no measured similarity (no
+        // query vector: keyword mode) is never dropped by it.
+        minSimilarity: Type.Optional(Type.Number({ minimum: -1, maximum: 1 })),
         // forward rerank:true to vector-search's post-RRF BYO rerank pass (it owns
         // the provider + key); inert until that pass exists/is configured there.
         rerank: Type.Boolean({ default: false }),
@@ -1659,6 +1712,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 +2165,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/dist/readmodels.d.ts

@@ -35,4 +35,22 @@ interface CdcRuleLike {
 }
 /** Cross-field rule for CmsConfig.cdc (called from validateFeatureConfig). */
 export declare function validateCdcConfig(cdc: Record<string, CdcRuleLike> | undefined): string[];
+/** What a payload:'full' change-data rule must know about its target
+ *  collection's read gates. `readRoleFields`: fields with a non-empty
+ *  `readRoles`; `endUserAccess`: the collection's end-user access mode. */
+export interface CdcCollectionGates {
+    readRoleFields?: readonly string[];
+    endUserAccess?: 'readwrite' | 'read' | 'none';
+}
+/**
+ * A `payload: 'full'` change-data rule inlines the stored row into a realtime
+ * frame that every subscriber of the channel receives — it does not go through
+ * the read projection. So it must never target a collection whose reads are
+ * gated: a field with `readRoles` (the frame would carry the gated value), or
+ * an `endUserAccess` of 'read' / 'none' (the frame would bypass the
+ * collection's end-user gate). Pure; one problem line per offending ENABLED
+ * rule (an unknown collection is skipped). The safe shape is `payload: 'ids'`
+ * and a re-read through the cms, where every gate applies.
+ */
+export declare function cdcFullFramesOverGatedCollections(cdc: unknown, collections: Record<string, CdcCollectionGates>): string[];
 export {};

package/dist/readmodels.js

@@ -227,3 +227,35 @@ export function validateCdcConfig(cdc) {
     }
     return errs;
 }
+/**
+ * A `payload: 'full'` change-data rule inlines the stored row into a realtime
+ * frame that every subscriber of the channel receives — it does not go through
+ * the read projection. So it must never target a collection whose reads are
+ * gated: a field with `readRoles` (the frame would carry the gated value), or
+ * an `endUserAccess` of 'read' / 'none' (the frame would bypass the
+ * collection's end-user gate). Pure; one problem line per offending ENABLED
+ * rule (an unknown collection is skipped). The safe shape is `payload: 'ids'`
+ * and a re-read through the cms, where every gate applies.
+ */
+export function cdcFullFramesOverGatedCollections(cdc, collections) {
+    if (!cdc || typeof cdc !== 'object' || Array.isArray(cdc))
+        return [];
+    const problems = [];
+    for (const [name, raw] of Object.entries(cdc)) {
+        const r = raw;
+        if (!r || r.payload !== 'full' || r.enabled === false || typeof r.collection !== 'string')
+            continue;
+        const g = Object.prototype.hasOwnProperty.call(collections, r.collection) ? collections[r.collection] : undefined;
+        if (!g)
+            continue;
+        const gated = (g.readRoleFields ?? []).filter((f) => typeof f === 'string');
+        const access = g.endUserAccess ?? 'readwrite';
+        if (gated.length > 0) {
+            problems.push(`cdc '${name}' publishes full '${r.collection}' rows, but field(s) ${gated.join(', ')} declare readRoles — every subscriber would receive them; use payload: 'ids' and re-read`);
+        }
+        else if (access !== 'readwrite') {
+            problems.push(`cdc '${name}' publishes full '${r.collection}' rows, but the collection's endUserAccess is '${access}' — a full frame would bypass that gate for every subscriber; use payload: 'ids' and re-read`);
+        }
+    }
+    return problems;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.9.1",
+  "version": "0.11.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

@@ -63,12 +63,16 @@ export const HOOK_LIMITS = {
 
 // ── allow-lists ─────────────────────────────────────────────────────────────
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
- *  populated ONLY on the READ path (runReadHooks); on the write path and in
- *  server-caller mode it is null, exactly like `before` on a create. It carries
- *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`
- *  ('end_user' | 'tenant'). It is the missing "caller/session context" a read
- *  hook keys on to redact/derive per-viewer. */
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only.
+ *  It carries `caller.endUserId` (the verified session sub, or null),
+ *  `caller.principal` ('end_user' | 'tenant') and `caller.roles` (the VERIFIED
+ *  session role claims of the signed-in session — never a body or header
+ *  value; null in server-caller mode). READ hooks always get it
+ *  (server mode: `{ endUserId: null, principal: 'tenant', roles: null }`).
+ *  WRITE hooks get it in verified end-user mode only; on a
+ *  server write it is null, exactly like `before` on a create — so a role rule
+ *  reads `isNull(caller) || contains(caller.roles, 'manager')`. `contains` on
+ *  an array is exact element membership. */
 export const HOOK_ROOT_VARS = ['item', 'before', 'now', 'caller'] as const;
 /** The ONLY callable functions. Each is pure + deterministic + bounded. */
 export const HOOK_FUNCTIONS = [
@@ -107,6 +111,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 =
@@ -330,21 +349,26 @@ export function validateAst(root: Node): string[] {
 }
 
 // ── evaluator (bounded, deterministic interpreter) ──────────────────────────
-/** The VERIFIED caller/session context for read hooks (guide ch. 7). Read-only;
- *  present only on the read path in end-user mode. In server mode / write path
- *  the whole object is null. */
+/** The VERIFIED caller/session context for Lane-A hooks (guide ch. 7).
+ *  Read-only. Read hooks always get it; write hooks get it in verified end-user
+ *  mode only (a server write passes null — see HOOK_ROOT_VARS). */
 export interface HookCaller {
   /** the verified end-user session sub, or null in server-caller mode. */
   endUserId: string | null;
   /** 'end_user' when a session was verified at the edge, else 'tenant'. */
   principal: 'end_user' | 'tenant';
+  /** the VERIFIED session role claims of the signed-in session; `[]` for a
+   *  session without roles, null in server-caller mode. Optional so an older
+   *  caller object still reads
+   *  as "no roles". */
+  roles?: readonly string[] | null;
 }
 
 export interface HookContext {
   item: Record<string, unknown>;
   before: Record<string, unknown> | null;
   now: string; // injected ISO timestamp — the only ambient input
-  /** verified caller/session context (read path only); null otherwise. */
+  /** verified caller/session context; null on a server write. */
   caller?: HookCaller | null;
 }
 
@@ -399,7 +423,16 @@ const FUNCS: Record<string, (a: unknown[]) => unknown> = {
   upper: (a) => str(a[0]).toUpperCase(),
   trim: (a) => str(a[0]).trim(),
   substr: (a) => { const s = str(a[0]); const start = Math.max(0, Math.trunc(num(a[1]))); const length = a[2] === undefined ? undefined : Math.max(0, Math.trunc(num(a[2]))); return s.substring(start, length === undefined ? undefined : start + length); },
-  contains: (a) => str(a[0]).includes(str(a[1])),
+  // An ARRAY haystack is exact element membership (`contains(caller.roles,
+  // 'manager')` must never match 'man' or 'managers'); a scalar haystack keeps
+  // the substring test. Elements compare as strings; objects never match.
+  contains: (a) => {
+    const needle = str(a[1]);
+    if (Array.isArray(a[0])) {
+      return a[0].some((el) => el !== null && typeof el !== 'object' && String(el) === needle);
+    }
+    return str(a[0]).includes(needle);
+  },
   startsWith: (a) => str(a[0]).startsWith(str(a[1])),
   endsWith: (a) => str(a[0]).endsWith(str(a[1])),
   concat: (a) => { const out = a.map(str).join(''); if (out.length > HOOK_LIMITS.maxStringLen) throw new HookEvalError('concat result too long'); return out; },
@@ -439,7 +472,7 @@ export function evalExpr(root: Node, ctx: HookContext, shared?: EvalBudget): unk
         if (nd.name === 'item') return ctx.item;
         if (nd.name === 'before') return ctx.before;
         if (nd.name === 'now') return ctx.now;
-        // caller (read path only) — null on the write path / server mode.
+        // caller — null on a server write (and on any path that passes none).
         if (nd.name === 'caller') return ctx.caller ?? null;
         throw new HookEvalError(`unknown variable '${nd.name}'`);
       case 'member': return ownGet(ev(nd.obj), nd.prop);
@@ -593,11 +626,14 @@ export function runWriteHooks(
   data: Record<string, unknown>,
   before: Record<string, unknown> | null,
   now: string,
+  /** the VERIFIED end-user caller (endUserId + principal + roles) in
+   *  end-user mode; omitted / null on a server write (expressions see null). */
+  caller?: HookCaller | null,
 ): HookRunResult {
   const out: Record<string, unknown> = { ...data };
   const derived: string[] = [];
   if (!hooks) return { data: out, derived };
-  const ctx: HookContext = { item: out, before, now };
+  const ctx: HookContext = { item: out, before, now, caller: caller ?? null };
   const entries = Object.entries(hooks).filter(
     ([, h]) => h.collection === collection && h.enabled !== false && eventMatches(h.event, phase),
   );
@@ -624,7 +660,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`);
     }
   }
@@ -664,8 +708,8 @@ export function runReadHooks(
   rows: ReadonlyArray<Record<string, unknown>>,
   now: string,
   /** verified caller/session context (guide ch. 7) — read-only, exposed to
-   *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
-   *  (server-caller mode). */
+   *  expressions as `caller.endUserId` / `caller.principal` / `caller.roles`.
+   *  Omitted ⇒ null (server-caller mode). */
   caller?: HookCaller | null,
 ): ReadHookResult {
   if (!hooks) return { rows: [...rows], dropped: 0 };
@@ -791,6 +835,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
@@ -512,6 +534,15 @@ const OidcProviderSchema = Type.Object({
     email: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
     name: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
     roles: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
+    // G-38b: an optional namespace prepended to every mapped IdP role (e.g.
+    // `idp-`), so an IdP group named like an app role (`finance`, `owner`)
+    // arrives as `idp-finance` and cannot pass a `readRoles: ['finance']`
+    // gate. Absent = the raw group names (the shipped behaviour). The prefixed
+    // role still obeys the 32-char role bound (longer ones are dropped).
+    // The alphabet is the cms readRoles / orgs role slug alphabet
+    // (`^[a-z0-9][a-z0-9_-]*$`, cms-v1 READ_ROLE_RE), so a prefixed role can
+    // itself be named in a gate — a `:`/`.`/uppercase prefix never could.
+    rolePrefix: Type.Optional(Type.String({ minLength: 1, maxLength: 16, pattern: '^[a-z0-9][a-z0-9_-]{0,15}$' })),
   })),
   // when non-empty, the asserted email's domain MUST be listed (fail-closed:
   // no email ⇒ refused) → 403 oidc_domain_not_allowed; a listed domain also
@@ -741,6 +772,26 @@ export const AuthConfigSchema = Type.Object({
       Type.String({ minLength: 8, maxLength: 253, pattern: REDIRECT_ORIGIN_PATTERN }),
       { maxItems: 32 },
     )),
+    // G-3 sign-up gating (2026-10-05). Both Optional with NO default, so an
+    // existing manifest folds byte-identically and the gate is opt-in. When
+    // EITHER is set, every self-service account-create path (password sign-up,
+    // magic-link / OTP pre-register, the guest → email claim, social sign-in
+    // with google/github/apple/facebook) is checked, fail-closed:
+    //   • inviteOnly — a new account only for an address the tenant already
+    //     put in its user registry server-side (POST /v1/users, an import);
+    //   • allowedEmailDomains — otherwise, only for an address at one of these
+    //     domains (exact, lowercase; a provider must assert the address
+    //     VERIFIED).
+    // With either set, password sign-up is refused (it proves nothing about
+    // the address — a stranger could squat an invitee's address), guest
+    // sign-in is refused (a guest is nobody's invitee), and an existing
+    // account is never affected. The generic OIDC issuer keeps its own gate
+    // (providers.oidc.allowedDomains + IdP assignment). auth-v1 signupGate.ts.
+    inviteOnly: Type.Optional(Type.Boolean()),
+    allowedEmailDomains: Type.Optional(Type.Array(
+      Type.String({ minLength: 3, maxLength: 253, pattern: '^[a-z0-9][a-z0-9.-]*\\.[a-z]{2,}$' }),
+      { maxItems: 32 },
+    )),
   })),
 });
 /** The security bag as persisted (present ⇒ leaf defaults applied). */
@@ -971,7 +1022,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: {} },
   ),
@@ -1465,6 +1518,12 @@ export const RagConfigSchema = Type.Object({
       ),
       // drop retrieved chunks below this score BEFORE budgeting (0 = keep all).
       minScore: Type.Number({ default: 0 }),
+      // drop retrieved chunks whose cosine `similarity` to the query is
+      // below this floor (-1..1). Unlike minScore (a floor on the RRF rank
+      // value, ~0.016-0.033 at the top) this is the relevance threshold a RAG
+      // app means. Absent = no floor; a hit with no measured similarity (no
+      // query vector: keyword mode) is never dropped by it.
+      minSimilarity: Type.Optional(Type.Number({ minimum: -1, maximum: 1 })),
       // forward rerank:true to vector-search's post-RRF BYO rerank pass (it owns
       // the provider + key); inert until that pass exists/is configured there.
       rerank: Type.Boolean({ default: false }),
@@ -1506,9 +1565,9 @@ export const RagConfigSchema = Type.Object({
   streaming: Type.Boolean({ default: true }),
 });
 // Leaves: enabled(1), defaultCollection(2),
-//   retrieval.{topK,mode,minScore,rerank}(+4=6), boosts(7 — Type.Record = ONE leaf),
-//   context.{maxTokens,strategy,tokenizer}(+3=10), defaultTemplate(11),
-//   citations(12), streaming(13). countLeaves → 13. Cap = 15.
+//   retrieval.{topK,mode,minScore,minSimilarity,rerank}(+5=7), boosts(8 — Type.Record = ONE
+//   leaf), context.{maxTokens,strategy,tokenizer}(+3=11), defaultTemplate(12),
+//   citations(13), streaming(14). countLeaves → 14. Cap = 15.
 
 export type RagConfig = Static<typeof RagConfigSchema>;
 
@@ -2048,6 +2107,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 +2599,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.

package/src/readmodels.ts

@@ -246,3 +246,42 @@ export function validateCdcConfig(
   }
   return errs;
 }
+
+/** What a payload:'full' change-data rule must know about its target
+ *  collection's read gates. `readRoleFields`: fields with a non-empty
+ *  `readRoles`; `endUserAccess`: the collection's end-user access mode. */
+export interface CdcCollectionGates {
+  readRoleFields?: readonly string[];
+  endUserAccess?: 'readwrite' | 'read' | 'none';
+}
+
+/**
+ * A `payload: 'full'` change-data rule inlines the stored row into a realtime
+ * frame that every subscriber of the channel receives — it does not go through
+ * the read projection. So it must never target a collection whose reads are
+ * gated: a field with `readRoles` (the frame would carry the gated value), or
+ * an `endUserAccess` of 'read' / 'none' (the frame would bypass the
+ * collection's end-user gate). Pure; one problem line per offending ENABLED
+ * rule (an unknown collection is skipped). The safe shape is `payload: 'ids'`
+ * and a re-read through the cms, where every gate applies.
+ */
+export function cdcFullFramesOverGatedCollections(
+  cdc: unknown, collections: Record<string, CdcCollectionGates>,
+): string[] {
+  if (!cdc || typeof cdc !== 'object' || Array.isArray(cdc)) return [];
+  const problems: string[] = [];
+  for (const [name, raw] of Object.entries(cdc as Record<string, unknown>)) {
+    const r = raw as { collection?: unknown; payload?: unknown; enabled?: unknown } | null;
+    if (!r || r.payload !== 'full' || r.enabled === false || typeof r.collection !== 'string') continue;
+    const g = Object.prototype.hasOwnProperty.call(collections, r.collection) ? collections[r.collection] : undefined;
+    if (!g) continue;
+    const gated = (g.readRoleFields ?? []).filter((f) => typeof f === 'string');
+    const access = g.endUserAccess ?? 'readwrite';
+    if (gated.length > 0) {
+      problems.push(`cdc '${name}' publishes full '${r.collection}' rows, but field(s) ${gated.join(', ')} declare readRoles — every subscriber would receive them; use payload: 'ids' and re-read`);
+    } else if (access !== 'readwrite') {
+      problems.push(`cdc '${name}' publishes full '${r.collection}' rows, but the collection's endUserAccess is '${access}' — a full frame would bypass that gate for every subscriber; use payload: 'ids' and re-read`);
+    }
+  }
+  return problems;
+}