@vxil/feature-configs 0.10.0 → 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"];
@@ -80,20 +84,25 @@ 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
@@ -127,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. */
@@ -154,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';

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 = [
@@ -448,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)
@@ -490,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}'`);
@@ -658,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) {
@@ -725,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 };

package/dist/index.d.ts

@@ -218,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>;
@@ -275,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>;
@@ -319,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). */
@@ -633,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<{

package/dist/index.js

@@ -463,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
@@ -667,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) ──────────────────────────────────────────
@@ -1185,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 }),

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.10.0",
+  "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 = [
@@ -345,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;
 }
 
@@ -414,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; },
@@ -454,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);
@@ -608,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),
   );
@@ -687,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 };

package/src/index.ts

@@ -534,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
@@ -763,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). */
@@ -1489,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 }),
@@ -1530,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>;
 

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;
+}