@vxil/feature-configs 0.1.0

package/src/hooks.ts

@@ -0,0 +1,830 @@
+// CMS lifecycle hooks — the SAFE expression engine (docs/cms-lifecycle-hooks-rung2-design.md, Lane A).
+//
+// A "code-based" lifecycle hook is a small EXPRESSION the tenant authors. Three kinds:
+//   - validate: the expression must evaluate truthy or the write is REJECTED (422)
+//               — or, on `beforeRead`, the ROW IS DROPPED from the response
+//               (a per-row visibility filter; never an error).
+//   - derive:   the expression's value is written to a target field on the item.
+//               On `afterRead` the value is set on the OUTPUT COPY only — read
+//               derives are output shaping and are never persisted.
+//   - redact:   (`afterRead` only) the target field is DELETED from the output
+//               copy when the expression is truthy.
+// Write hooks run IN-TRANSACTION on the cms write path (before INSERT/UPDATE),
+// so a validate failure rolls the whole write back atomically. Read hooks run
+// per row over the PROJECTED page (computed fields + $expand results visible)
+// under ONE shared eval-step budget for the whole request (see runReadHooks).
+//
+// CROSS-ROW AGGREGATION STAYS OUT — BY DESIGN. Read hooks are a pure function
+// of ONE row (+ `now`): there are no new root variables, no array/aggregate
+// functions, no access to sibling rows or other collections. Counts/sums/
+// group-bys across rows are the §5 identity-fork anti-item (docs/features/
+// cms.md §6.7) and must never enter this engine.
+//
+// SAFETY (the "not malicious" guarantee) is structural, not heuristic:
+//   * No JS is executed. `eval`/`Function`/the host runtime are never touched. The
+//     tenant's source is tokenized → parsed into a closed AST → walked by an
+//     interpreter that ONLY supports the node types and built-in functions below.
+//   * No I/O, no network, no DB, no host objects, no `this`, no globals — the
+//     grammar has no syntax for any of them.
+//   * No loops, no recursion, no user-defined functions, no assignment — the
+//     grammar has none, so every expression is total and terminates.
+//   * Deterministic: the only "ambient" input is `now`, injected as a fixed ISO
+//     string; there is no Date.now()/Math.random() reachable.
+//   * Prototype-pollution proof: member access reads OWN enumerable properties of
+//     plain objects only; `__proto__`/`constructor`/`prototype` are rejected at
+//     PARSE time and never traversed at eval time.
+//   * Resource-bounded (defense in depth on top of the closed grammar): source
+//     length, token count, AST node count, AST depth, eval step budget, string
+//     result length, and numeric magnitude are all capped. ReDoS is impossible —
+//     the engine never compiles a tenant regex.
+// Validation runs at CONFIG-WRITE time (validateHookDef, called from
+// validateFeatureConfig) so a malicious/oversized/ill-typed hook is rejected
+// BEFORE it can be published to KV/runtime; the runtime budgets are the second line.
+
+// ── limits ──────────────────────────────────────────────────────────────────
+export const HOOK_LIMITS = {
+  maxSourceLen: 2000,
+  maxTokens: 600,
+  maxNodes: 250,
+  maxDepth: 40,
+  maxEvalSteps: 5000,
+  maxStringLen: 4096,
+  maxNumberMagnitude: 1e15,
+  // READ-path bounds (runReadHooks). The list path evaluates hooks PER ROW over
+  // a query page (≤500 rows), so the per-request cost is bounded by ONE shared
+  // eval-step budget across the whole page — not per expression. Typical hooks
+  // cost tens of steps/row, so 250k covers a max page with the full 10-hook
+  // complement many times over; a pathological page (maximal expressions ×
+  // maximal rows × maximal hooks) exhausts it and the request fails a clean
+  // 422 hook_error rather than pinning the isolate's CPU.
+  maxReadEvalStepsPerRequest: 250_000,
+  maxReadHooksPerCollection: 10,
+} as const;
+
+// ── allow-lists ─────────────────────────────────────────────────────────────
+/** The ONLY root variables an expression may reference. `caller` is the VERIFIED
+ *  end-user principal (docs/end-user-principals-design.md §5.6) — 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. */
+export const HOOK_ROOT_VARS = ['item', 'before', 'now', 'caller'] as const;
+/** The ONLY callable functions. Each is pure + deterministic + bounded. */
+export const HOOK_FUNCTIONS = [
+  // math
+  'min', 'max', 'abs', 'round', 'floor', 'ceil', 'sqrt', 'pow', 'sign',
+  // string
+  'len', 'lower', 'upper', 'trim', 'substr', 'contains', 'startsWith', 'endsWith', 'concat',
+  // logic / null
+  'coalesce', 'ifNull', 'not', 'isNull',
+  // convert
+  'number', 'string', 'bool',
+  // date (operate on ISO strings; deterministic)
+  'daysBetween', 'yearsBetween',
+] as const;
+const FN_SET = new Set<string>(HOOK_FUNCTIONS);
+const ROOT_SET = new Set<string>(HOOK_ROOT_VARS);
+const FORBIDDEN_PROPS = new Set(['__proto__', 'constructor', 'prototype']);
+const PROP_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// ── AST ─────────────────────────────────────────────────────────────────────
+export type Node =
+  | { t: 'num'; v: number }
+  | { t: 'str'; v: string }
+  | { t: 'bool'; v: boolean }
+  | { t: 'null' }
+  | { t: 'var'; name: string }
+  | { t: 'member'; obj: Node; prop: string }
+  | { t: 'unary'; op: '!' | '-'; arg: Node }
+  | { t: 'bin'; op: BinOp; l: Node; r: Node }
+  | { t: 'tern'; c: Node; a: Node; b: Node }
+  | { t: 'call'; fn: string; args: Node[] };
+
+type BinOp = '||' | '&&' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '+' | '-' | '*' | '/' | '%';
+
+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 {}
+
+// ── tokenizer ───────────────────────────────────────────────────────────────
+type Tok =
+  | { k: 'num'; v: number }
+  | { k: 'str'; v: string }
+  | { k: 'name'; v: string }
+  | { k: 'op'; v: string }
+  | { k: 'eof' };
+
+const PUNCT = ['||', '&&', '==', '!=', '<=', '>=', '<', '>', '+', '-', '*', '/', '%', '!', '(', ')', ',', '.', '?', ':'];
+
+function tokenize(src: string): Tok[] {
+  if (src.length > HOOK_LIMITS.maxSourceLen) {
+    throw new HookParseError(`expression exceeds ${HOOK_LIMITS.maxSourceLen} chars`);
+  }
+  const toks: Tok[] = [];
+  let i = 0;
+  const n = src.length;
+  while (i < n) {
+    const c = src[i]!;
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') { i++; continue; }
+    // string literal — single or double quotes, backslash escapes for \ ' " n t
+    if (c === '"' || c === "'") {
+      const quote = c;
+      let s = '';
+      i++;
+      while (i < n && src[i] !== quote) {
+        let ch = src[i]!;
+        if (ch === '\\') {
+          const e = src[i + 1];
+          if (e === 'n') ch = '\n';
+          else if (e === 't') ch = '\t';
+          else if (e === '\\' || e === '"' || e === "'") ch = e;
+          else throw new HookParseError(`bad string escape \\${e ?? ''}`);
+          i += 2;
+        } else { i++; }
+        s += ch;
+        if (s.length > HOOK_LIMITS.maxStringLen) throw new HookParseError('string literal too long');
+      }
+      if (i >= n) throw new HookParseError('unterminated string');
+      i++; // closing quote
+      toks.push({ k: 'str', v: s });
+    } else if (c >= '0' && c <= '9') {
+      let j = i;
+      while (j < n && /[0-9]/.test(src[j]!)) j++;
+      if (src[j] === '.') { j++; while (j < n && /[0-9]/.test(src[j]!)) j++; }
+      const num = Number(src.slice(i, j));
+      if (!Number.isFinite(num)) throw new HookParseError(`bad number near ${src.slice(i, j)}`);
+      toks.push({ k: 'num', v: num });
+      i = j;
+    } else if (/[A-Za-z_]/.test(c)) {
+      let j = i;
+      while (j < n && /[A-Za-z0-9_]/.test(src[j]!)) j++;
+      toks.push({ k: 'name', v: src.slice(i, j) });
+      i = j;
+    } else {
+      const two = src.slice(i, i + 2);
+      const one = c;
+      const m = PUNCT.includes(two) ? two : PUNCT.includes(one) ? one : null;
+      if (!m) throw new HookParseError(`unexpected character '${c}'`);
+      toks.push({ k: 'op', v: m });
+      i += m.length;
+    }
+    if (toks.length > HOOK_LIMITS.maxTokens) throw new HookParseError('expression too long (token cap)');
+  }
+  toks.push({ k: 'eof' });
+  return toks;
+}
+
+// ── parser (Pratt) ──────────────────────────────────────────────────────────
+// precedence: ternary < || < && < equality < comparison < add < mul < unary < postfix(member/call)
+const BIN_PREC: Record<string, number> = {
+  '||': 1, '&&': 2, '==': 3, '!=': 3, '<': 4, '<=': 4, '>': 4, '>=': 4,
+  '+': 5, '-': 5, '*': 6, '/': 6, '%': 6,
+};
+
+class Parser {
+  private p = 0;
+  private nodes = 0;
+  constructor(private readonly toks: Tok[]) {}
+
+  private peek(): Tok { return this.toks[this.p]!; }
+  private next(): Tok { return this.toks[this.p++]!; }
+  private isOp(v: string): boolean { const t = this.peek(); return t.k === 'op' && t.v === v; }
+  private eatOp(v: string): void {
+    if (!this.isOp(v)) throw new HookParseError(`expected '${v}'`);
+    this.p++;
+  }
+  private node<T extends Node>(nd: T): T {
+    if (++this.nodes > HOOK_LIMITS.maxNodes) throw new HookParseError('expression too complex (node cap)');
+    return nd;
+  }
+
+  parse(): Node {
+    const e = this.ternary();
+    if (this.peek().k !== 'eof') throw new HookParseError('trailing tokens after expression');
+    return e;
+  }
+
+  private ternary(): Node {
+    const c = this.binary(0);
+    if (this.isOp('?')) {
+      this.next();
+      const a = this.ternary();
+      this.eatOp(':');
+      const b = this.ternary();
+      return this.node({ t: 'tern', c, a, b });
+    }
+    return c;
+  }
+
+  private binary(minPrec: number): Node {
+    let left = this.unary();
+    for (;;) {
+      const t = this.peek();
+      if (t.k !== 'op') break;
+      const prec = BIN_PREC[t.v];
+      if (prec === undefined || prec < minPrec) break;
+      this.next();
+      const right = this.binary(prec + 1); // left-assoc
+      left = this.node({ t: 'bin', op: t.v as BinOp, l: left, r: right });
+    }
+    return left;
+  }
+
+  private unary(): Node {
+    if (this.isOp('!')) { this.next(); return this.node({ t: 'unary', op: '!', arg: this.unary() }); }
+    if (this.isOp('-')) { this.next(); return this.node({ t: 'unary', op: '-', arg: this.unary() }); }
+    return this.postfix();
+  }
+
+  private postfix(): Node {
+    let e = this.primary();
+    for (;;) {
+      if (this.isOp('.')) {
+        this.next();
+        const t = this.next();
+        if (t.k !== 'name') throw new HookParseError('expected property name after .');
+        if (!PROP_RE.test(t.v) || FORBIDDEN_PROPS.has(t.v)) {
+          throw new HookParseError(`forbidden property '${t.v}'`);
+        }
+        e = this.node({ t: 'member', obj: e, prop: t.v });
+      } else break;
+    }
+    return e;
+  }
+
+  private primary(): Node {
+    const t = this.next();
+    if (t.k === 'num') return this.node({ t: 'num', v: t.v });
+    if (t.k === 'str') return this.node({ t: 'str', v: t.v });
+    if (t.k === 'op' && t.v === '(') {
+      const e = this.ternary();
+      this.eatOp(')');
+      return e;
+    }
+    if (t.k === 'name') {
+      if (t.v === 'true') return this.node({ t: 'bool', v: true });
+      if (t.v === 'false') return this.node({ t: 'bool', v: false });
+      if (t.v === 'null') return this.node({ t: 'null' });
+      // function call?
+      if (this.isOp('(')) {
+        this.next();
+        const args: Node[] = [];
+        if (!this.isOp(')')) {
+          args.push(this.ternary());
+          while (this.isOp(',')) { this.next(); args.push(this.ternary()); }
+        }
+        this.eatOp(')');
+        return this.node({ t: 'call', fn: t.v, args });
+      }
+      return this.node({ t: 'var', name: t.v });
+    }
+    throw new HookParseError('unexpected token');
+  }
+}
+
+/** Parse a hook expression into an AST. Throws HookParseError on any malformed input. */
+export function parseExpr(src: string): Node {
+  return new Parser(tokenize(src)).parse();
+}
+
+// ── AST validator (the closed-allow-list "not malicious" gate) ──────────────
+/** 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 function validateAst(root: Node): string[] {
+  const errors: string[] = [];
+  const walk = (nd: Node, depth: number): void => {
+    if (depth > HOOK_LIMITS.maxDepth) { errors.push('expression nests too deeply'); return; }
+    switch (nd.t) {
+      case 'num':
+        if (!Number.isFinite(nd.v) || Math.abs(nd.v) > HOOK_LIMITS.maxNumberMagnitude) errors.push('numeric literal out of range');
+        return;
+      case 'str':
+        if (nd.v.length > HOOK_LIMITS.maxStringLen) errors.push('string literal too long');
+        return;
+      case 'bool': case 'null': return;
+      case 'var':
+        if (!ROOT_SET.has(nd.name)) errors.push(`unknown variable '${nd.name}' (allowed: ${HOOK_ROOT_VARS.join(', ')})`);
+        return;
+      case 'member':
+        if (FORBIDDEN_PROPS.has(nd.prop) || !PROP_RE.test(nd.prop)) errors.push(`forbidden property '${nd.prop}'`);
+        walk(nd.obj, depth + 1);
+        return;
+      case 'unary': walk(nd.arg, depth + 1); return;
+      case 'bin': walk(nd.l, depth + 1); walk(nd.r, depth + 1); return;
+      case 'tern': walk(nd.c, depth + 1); walk(nd.a, depth + 1); walk(nd.b, depth + 1); return;
+      case 'call':
+        if (!FN_SET.has(nd.fn)) errors.push(`unknown function '${nd.fn}'`);
+        if (nd.args.length > 16) errors.push(`function '${nd.fn}' has too many arguments`);
+        for (const a of nd.args) walk(a, depth + 1);
+        return;
+      default: {
+        // exhaustiveness guard: an unknown node type is a bug/forbidden shape.
+        errors.push('unsupported expression node');
+      }
+    }
+  };
+  walk(root, 0);
+  return errors;
+}
+
+// ── evaluator (bounded, deterministic interpreter) ──────────────────────────
+/** The VERIFIED caller/session context for read hooks (design §5.6). Read-only;
+ *  present only on the read path in end-user mode. In server mode / write path
+ *  the whole object is null. */
+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';
+}
+
+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. */
+  caller?: HookCaller | null;
+}
+
+function num(x: unknown): number {
+  const v = typeof x === 'number' ? x : typeof x === 'string' || typeof x === 'boolean' ? Number(x) : NaN;
+  if (!Number.isFinite(v)) throw new HookEvalError('expected a finite number');
+  if (Math.abs(v) > HOOK_LIMITS.maxNumberMagnitude) throw new HookEvalError('number out of range');
+  return v;
+}
+function str(x: unknown): string {
+  let v: string;
+  if (x == null) v = '';
+  else if (typeof x === 'object') {
+    // Safety net: a circular/unserializable object must surface as a contained
+    // HookEvalError, never a raw TypeError that escapes the 422 contract.
+    try { v = JSON.stringify(x) ?? ''; } catch { throw new HookEvalError('value is not serializable'); }
+  } else v = String(x);
+  if (v.length > HOOK_LIMITS.maxStringLen) throw new HookEvalError('string too long');
+  return v;
+}
+function truthy(x: unknown): boolean {
+  if (typeof x === 'boolean') return x;
+  if (x == null) return false;
+  if (typeof x === 'number') return x !== 0 && !Number.isNaN(x);
+  if (typeof x === 'string') return x.length > 0;
+  return true;
+}
+function isoDays(iso: unknown): number {
+  const ms = Date.parse(str(iso));
+  if (!Number.isFinite(ms)) throw new HookEvalError('invalid date string');
+  return ms / 86_400_000;
+}
+function ownGet(obj: unknown, prop: string): unknown {
+  if (obj == null || typeof obj !== 'object') return undefined;
+  if (FORBIDDEN_PROPS.has(prop)) return undefined;
+  // OWN enumerable only — never walk the prototype chain.
+  return Object.prototype.hasOwnProperty.call(obj, prop) ? (obj as Record<string, unknown>)[prop] : undefined;
+}
+
+const FUNCS: Record<string, (a: unknown[]) => unknown> = {
+  min: (a) => { if (!a.length) throw new HookEvalError('min requires at least one argument'); return Math.min(...a.map(num)); },
+  max: (a) => { if (!a.length) throw new HookEvalError('max requires at least one argument'); return Math.max(...a.map(num)); },
+  abs: (a) => Math.abs(num(a[0])),
+  round: (a) => Math.round(num(a[0])),
+  floor: (a) => Math.floor(num(a[0])),
+  ceil: (a) => Math.ceil(num(a[0])),
+  sqrt: (a) => { const v = num(a[0]); if (v < 0) throw new HookEvalError('sqrt of negative'); return Math.sqrt(v); },
+  pow: (a) => { const r = Math.pow(num(a[0]), num(a[1])); if (!Number.isFinite(r) || Math.abs(r) > HOOK_LIMITS.maxNumberMagnitude) throw new HookEvalError('pow out of range'); return r; },
+  sign: (a) => Math.sign(num(a[0])),
+  len: (a) => str(a[0]).length,
+  lower: (a) => str(a[0]).toLowerCase(),
+  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])),
+  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; },
+  coalesce: (a) => { for (const v of a) if (v != null) return v; return null; },
+  ifNull: (a) => (a[0] == null ? a[1] ?? null : a[0]),
+  isNull: (a) => a[0] == null,
+  not: (a) => !truthy(a[0]),
+  number: (a) => num(a[0]),
+  string: (a) => str(a[0]),
+  bool: (a) => truthy(a[0]),
+  // num() re-applies the finite + magnitude guard so date math obeys the same
+  // numeric invariant as every other numeric result (no unbounded escape).
+  daysBetween: (a) => num(isoDays(a[0]) - isoDays(a[1])),
+  yearsBetween: (a) => num((isoDays(a[0]) - isoDays(a[1])) / 365.2425),
+};
+
+/** A mutable step counter SHARED across many evalExpr calls (the read path's
+ *  whole-page budget). Checked against maxReadEvalStepsPerRequest. */
+export interface EvalBudget { steps: number }
+
+/** Evaluate a validated AST against the context. Bounded by a per-expression
+ *  eval-step budget, plus an optional SHARED budget spanning many evaluations
+ *  (runReadHooks passes one per request so a page of rows shares one bound). */
+export function evalExpr(root: Node, ctx: HookContext, shared?: EvalBudget): unknown {
+  let steps = 0;
+  const ev = (nd: Node): unknown => {
+    if (++steps > HOOK_LIMITS.maxEvalSteps) throw new HookEvalError('evaluation budget exceeded');
+    if (shared && ++shared.steps > HOOK_LIMITS.maxReadEvalStepsPerRequest) {
+      throw new HookEvalError('read evaluation budget exceeded for this request (simplify read hooks or lower the page size)');
+    }
+    switch (nd.t) {
+      case 'num': return nd.v;
+      case 'str': return nd.v;
+      case 'bool': return nd.v;
+      case 'null': return null;
+      case 'var':
+        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.
+        if (nd.name === 'caller') return ctx.caller ?? null;
+        throw new HookEvalError(`unknown variable '${nd.name}'`);
+      case 'member': return ownGet(ev(nd.obj), nd.prop);
+      case 'unary': {
+        const v = ev(nd.arg);
+        return nd.op === '!' ? !truthy(v) : -num(v);
+      }
+      case 'bin': return binOp(nd.op, nd.l, nd.r, ev);
+      case 'tern': return truthy(ev(nd.c)) ? ev(nd.a) : ev(nd.b);
+      case 'call': {
+        const fn = FUNCS[nd.fn];
+        if (!fn) throw new HookEvalError(`unknown function '${nd.fn}'`);
+        return fn(nd.args.map(ev));
+      }
+      default:
+        throw new HookEvalError('unsupported node');
+    }
+  };
+  return ev(root);
+}
+
+function binOp(op: BinOp, ln: Node, rn: Node, ev: (n: Node) => unknown): unknown {
+  // short-circuit booleans
+  if (op === '&&') return truthy(ev(ln)) ? truthy(ev(rn)) : false;
+  if (op === '||') return truthy(ev(ln)) ? true : truthy(ev(rn));
+  const l = ev(ln);
+  const r = ev(rn);
+  switch (op) {
+    case '==': return eq(l, r);
+    case '!=': return !eq(l, r);
+    case '<': case '<=': case '>': case '>=': return compare(op, l, r);
+    case '+': return num(l) + num(r);
+    case '-': return num(l) - num(r);
+    case '*': { const v = num(l) * num(r); if (Math.abs(v) > HOOK_LIMITS.maxNumberMagnitude) throw new HookEvalError('multiply overflow'); return v; }
+    case '/': { const d = num(r); if (d === 0) throw new HookEvalError('division by zero'); return num(l) / d; }
+    case '%': { const d = num(r); if (d === 0) throw new HookEvalError('modulo by zero'); return num(l) % d; }
+    default: throw new HookEvalError(`bad operator ${op as string}`);
+  }
+}
+function eq(l: unknown, r: unknown): boolean {
+  if (l == null || r == null) return l == null && r == null;
+  if (typeof l === 'object' || typeof r === 'object') return false; // no deep equality on objects
+  return l === r;
+}
+function compare(op: string, l: unknown, r: unknown): boolean {
+  // numbers compare numerically; strings lexically; mixed → coerce to number.
+  let a: number | string;
+  let b: number | string;
+  if (typeof l === 'string' && typeof r === 'string') { a = l; b = r; }
+  else { a = num(l); b = num(r); }
+  switch (op) {
+    case '<': return a < b;
+    case '<=': return a <= b;
+    case '>': return a > b;
+    case '>=': return a >= b;
+    default: return false;
+  }
+}
+
+// ── hook definitions + write-/read-time runners ─────────────────────────────
+export interface HookDef {
+  collection: string;
+  event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite' | 'beforeRead' | 'afterRead';
+  kind: 'validate' | 'derive' | 'redact';
+  expr: string;
+  field?: string; // derive/redact target
+  message?: string; // validate rejection message
+  enabled?: boolean;
+}
+
+const READ_EVENTS = new Set<HookDef['event']>(['beforeRead', 'afterRead']);
+
+/** Config-WRITE-time validation of one hook (the anti-malice gate). Returns
+ *  errors (empty = safe to publish). Does NOT need the collection's field list. */
+export function validateHookDef(id: string, def: HookDef): string[] {
+  const errs: string[] = [];
+  const where = `hooks.${id}`;
+  if (!def.collection || typeof def.collection !== 'string') errs.push(`${where}.collection is required`);
+  if (def.kind === 'derive' && !def.field) errs.push(`${where}.field is required for a derive hook`);
+  if (def.field !== undefined && !PROP_RE.test(def.field)) errs.push(`${where}.field '${def.field}' is not a valid field name`);
+  if (def.field !== undefined && FORBIDDEN_PROPS.has(def.field)) errs.push(`${where}.field '${def.field}' is forbidden`);
+  // kind ↔ event compatibility matrix:
+  //   validate → any write event (rejects the write) or beforeRead (drops the row); never afterRead.
+  //   derive   → any write event (persists the field) or afterRead (output copy only); never beforeRead.
+  //   redact   → afterRead ONLY (deletes a field from the output copy); requires `field`.
+  if (def.kind === 'redact') {
+    if (def.event !== 'afterRead') errs.push(`${where}: a redact hook is only valid on afterRead (got '${def.event}')`);
+    if (!def.field) errs.push(`${where}.field is required for a redact hook`);
+  }
+  if (def.kind === 'validate' && def.event === 'afterRead') {
+    errs.push(`${where}: a validate hook cannot run on afterRead (use beforeRead to drop rows)`);
+  }
+  if (def.kind === 'derive' && def.event === 'beforeRead') {
+    errs.push(`${where}: a derive hook cannot run on beforeRead (use afterRead to shape the output)`);
+  }
+  let ast: Node | null = null;
+  try {
+    ast = parseExpr(def.expr ?? '');
+  } catch (e) {
+    errs.push(`${where}.expr: ${(e as Error).message}`);
+  }
+  if (ast) {
+    for (const e of validateAst(ast)) errs.push(`${where}.expr: ${e}`);
+  }
+  return errs;
+}
+
+/** Validate a whole hooks bag (CmsConfig.hooks) at config time. */
+export function validateHooksConfig(hooks: Record<string, HookDef> | undefined): string[] {
+  if (!hooks) return [];
+  const errs: string[] = [];
+  const ids = Object.keys(hooks);
+  if (ids.length > 50) errs.push(`too many hooks (${ids.length}); cap is 50`);
+  for (const id of ids) errs.push(...validateHookDef(id, hooks[id]!));
+  // Read hooks run PER ROW over a query page, so their count is part of the
+  // per-request CPU bound (with the shared eval budget) — cap them per collection.
+  const readCounts = new Map<string, number>();
+  for (const id of ids) {
+    const h = hooks[id]!;
+    if (READ_EVENTS.has(h.event)) {
+      readCounts.set(h.collection, (readCounts.get(h.collection) ?? 0) + 1);
+    }
+  }
+  for (const [coll, n] of readCounts) {
+    if (n > HOOK_LIMITS.maxReadHooksPerCollection) {
+      errs.push(`too many read hooks on collection '${coll}' (${n}); cap is ${HOOK_LIMITS.maxReadHooksPerCollection}`);
+    }
+  }
+  return errs;
+}
+
+function eventMatches(event: HookDef['event'], phase: 'create' | 'update'): boolean {
+  if (READ_EVENTS.has(event)) return false; // a read hook NEVER fires on a write
+  if (event === 'beforeWrite') return true;
+  return phase === 'create' ? event === 'beforeCreate' : event === 'beforeUpdate';
+}
+
+export interface HookRunResult {
+  data: Record<string, unknown>;
+  derived: string[]; // fields a derive hook set
+}
+
+/** Run all matching write hooks for (collection, phase) over the candidate data.
+ *  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: Record<string, HookDef> | undefined,
+  collection: string,
+  phase: 'create' | 'update',
+  data: Record<string, unknown>,
+  before: Record<string, unknown> | null,
+  now: string,
+): HookRunResult {
+  const out: Record<string, unknown> = { ...data };
+  const derived: string[] = [];
+  if (!hooks) return { data: out, derived };
+  const ctx: HookContext = { item: out, before, now };
+  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) {
+    if (h.kind !== 'derive') continue;
+    const field = h.field!;
+    // belt-and-braces: even though validateHookDef rejects these at config time,
+    // runWriteHooks is a public export a future caller could feed an unvetted bag.
+    if (FORBIDDEN_PROPS.has(field) || !PROP_RE.test(field)) {
+      throw new HookEvalError(`derive '${id}' targets a forbidden field`);
+    }
+    const ast = parseCached(id, h.expr);
+    const v = evalExpr(ast, ctx);
+    // A derive MUST produce a scalar. Returning an object/array (e.g. `item`,
+    // `before`, `item.sub`, `coalesce(item, …)`) would alias or circularize the
+    // persisted row by reference — a data leak + an unserializable structure.
+    if (v !== null && typeof v === 'object') {
+      throw new HookEvalError(`derive '${id}' must produce a scalar (got ${Array.isArray(v) ? 'array' : 'object'})`);
+    }
+    out[field] = v;
+    derived.push(field);
+  }
+  for (const [id, h] of entries) {
+    if (h.kind !== 'validate') continue;
+    const ast = parseCached(id, h.expr);
+    if (!truthy(evalExpr(ast, ctx))) {
+      throw new HookRejection(h.message || `validation hook '${id}' rejected the write`);
+    }
+  }
+  return { data: out, derived };
+}
+
+// ── read-time runner (beforeRead visibility + afterRead output shaping) ─────
+
+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. */
+  rows: Record<string, unknown>[];
+  /** Rows removed by a falsy beforeRead validate (the visibility filter). */
+  dropped: number;
+}
+
+/** Run the tenant's READ hooks for a collection over a page of PROJECTED rows
+ *  (each row an item envelope whose `data` already carries computed fields and
+ *  $expand results — that is the cross-field surface an expression reads).
+ *
+ *  Per row, in order:
+ *    1. beforeRead `validate` — a falsy expression DROPS the row (visibility
+ *       filter; a dropped row is indistinguishable from a missing one).
+ *    2. afterRead `derive`   — sets data[field] on the OUTPUT copy only
+ *       (scalar-only, same guard as the write path; NEVER persisted).
+ *    3. afterRead `redact`   — deletes data[field] when the expression is truthy.
+ *
+ *  Context per row: { item: the projected data, before: null, now: ONE ISO
+ *  string for the whole request } — deterministic across the page. The entire
+ *  page shares ONE eval-step budget (HOOK_LIMITS.maxReadEvalStepsPerRequest),
+ *  which is the list path's per-request CPU bound; exhausting it throws
+ *  HookEvalError (→ a clean 422, never a pinned isolate). Write events never
+ *  fire here, and read events never fire in runWriteHooks. */
+export function runReadHooks(
+  hooks: Record<string, HookDef> | undefined,
+  collection: string,
+  rows: ReadonlyArray<Record<string, unknown>>,
+  now: string,
+  /** verified caller/session context (design §5.6) — read-only, exposed to
+   *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
+   *  (server-caller mode). */
+  caller?: HookCaller | null,
+): ReadHookResult {
+  if (!hooks) return { rows: [...rows], dropped: 0 };
+  const entries = Object.entries(hooks).filter(
+    ([, h]) => h.collection === collection && h.enabled !== false && READ_EVENTS.has(h.event),
+  );
+  if (entries.length === 0) return { rows: [...rows], dropped: 0 };
+  const visibility = entries.filter(([, h]) => h.event === 'beforeRead' && h.kind === 'validate');
+  const derives = entries.filter(([, h]) => h.event === 'afterRead' && h.kind === 'derive');
+  const redacts = entries.filter(([, h]) => h.event === 'afterRead' && h.kind === 'redact');
+  const budget: EvalBudget = { steps: 0 }; // ONE budget for the whole page
+  const out: Record<string, unknown>[] = [];
+  let dropped = 0;
+  const checkTarget = (id: string, kind: string, field: string | undefined): string => {
+    // belt-and-braces (mirrors runWriteHooks): validateHookDef rejects these at
+    // config time, but this is a public export a future caller could misfeed.
+    if (!field || FORBIDDEN_PROPS.has(field) || !PROP_RE.test(field)) {
+      throw new HookEvalError(`${kind} '${id}' targets a forbidden field`);
+    }
+    return field;
+  };
+  for (const row of rows) {
+    const raw = row.data;
+    const data: Record<string, unknown> =
+      raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? { ...(raw as Record<string, unknown>) }
+        : {};
+    const ctx: HookContext = { item: data, before: null, now, caller: caller ?? null };
+    let drop = false;
+    for (const [id, h] of visibility) {
+      if (!truthy(evalExpr(parseCached(id, h.expr), ctx, budget))) { drop = true; break; }
+    }
+    if (drop) { dropped += 1; continue; }
+    // derives BEFORE redacts, so a derive can read a field a redact then hides.
+    for (const [id, h] of derives) {
+      const field = checkTarget(id, 'derive', h.field);
+      const v = evalExpr(parseCached(id, h.expr), ctx, budget);
+      // Same scalar guard as the write path: an object/array result would alias
+      // the row by reference into the response (a leak + unserializable shape).
+      if (v !== null && typeof v === 'object') {
+        throw new HookEvalError(`derive '${id}' must produce a scalar (got ${Array.isArray(v) ? 'array' : 'object'})`);
+      }
+      data[field] = v;
+    }
+    for (const [id, h] of redacts) {
+      const field = checkTarget(id, 'redact', h.field);
+      if (truthy(evalExpr(parseCached(id, h.expr), ctx, budget))) delete data[field];
+    }
+    out.push({ ...row, data });
+  }
+  return { rows: out, dropped };
+}
+
+// ── editor support: inputs (refs), output (inferred type), highlighting ─────
+// These power a FIELD-AWARE dashboard editor: which fields the expression reads
+// (its INPUTS), the type it produces (its OUTPUT — checked against the derive
+// target field), and token-level syntax highlighting. All pure + dependency-free.
+
+export interface ExprRef {
+  root: 'item' | 'before' | 'now' | 'caller';
+  /** dotted path under the root, e.g. item.profile.age → ['profile','age']. */
+  path: string[];
+}
+
+/** Collect every variable reference an expression reads (its inputs). */
+export function extractRefs(root: Node): ExprRef[] {
+  const out: ExprRef[] = [];
+  const seen = new Set<string>();
+  const add = (r: ExprRef): void => {
+    const k = `${r.root}.${r.path.join('.')}`;
+    if (!seen.has(k)) { seen.add(k); out.push(r); }
+  };
+  const walk = (nd: Node): void => {
+    switch (nd.t) {
+      case 'member': {
+        const path: string[] = [];
+        let cur: Node = nd;
+        while (cur.t === 'member') { path.unshift(cur.prop); cur = cur.obj; }
+        if (cur.t === 'var') add({ root: cur.name as ExprRef['root'], path });
+        else walk(cur);
+        return;
+      }
+      case 'var': add({ root: nd.name as ExprRef['root'], path: [] }); return;
+      case 'unary': walk(nd.arg); return;
+      case 'bin': walk(nd.l); walk(nd.r); return;
+      case 'tern': walk(nd.c); walk(nd.a); walk(nd.b); return;
+      case 'call': nd.args.forEach(walk); return;
+      default: return;
+    }
+  };
+  walk(root);
+  return out;
+}
+
+export type InferredType = 'number' | 'string' | 'boolean' | 'null' | 'unknown';
+const NUM_FNS = new Set(['min', 'max', 'abs', 'round', 'floor', 'ceil', 'sqrt', 'pow', 'sign', 'len', 'number', 'daysBetween', 'yearsBetween']);
+const STR_FNS = new Set(['lower', 'upper', 'trim', 'substr', 'concat', 'string']);
+const BOOL_FNS = new Set(['contains', 'startsWith', 'endsWith', 'not', 'isNull', 'bool']);
+
+/** Best-effort static type of an expression's result (its output). 'unknown' for
+ *  member access / coalesce / mixed ternaries — never a false-positive mismatch. */
+export function inferType(nd: Node): InferredType {
+  switch (nd.t) {
+    case 'num': return 'number';
+    case 'str': return 'string';
+    case 'bool': return 'boolean';
+    case 'null': return 'null';
+    case 'var': return nd.name === 'now' ? 'string' : 'unknown';
+    case 'member': return 'unknown';
+    case 'unary': return nd.op === '!' ? 'boolean' : 'number';
+    case 'bin':
+      return ['==', '!=', '<', '<=', '>', '>=', '&&', '||'].includes(nd.op) ? 'boolean' : 'number';
+    case 'tern': {
+      const a = inferType(nd.a); const b = inferType(nd.b);
+      return a === b ? a : 'unknown';
+    }
+    case 'call':
+      if (NUM_FNS.has(nd.fn)) return 'number';
+      if (STR_FNS.has(nd.fn)) return 'string';
+      if (BOOL_FNS.has(nd.fn)) return 'boolean';
+      return 'unknown'; // coalesce / ifNull
+    default: return 'unknown';
+  }
+}
+
+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. */
+export function highlightTokens(src: string): Array<{ value: string; kind: HlKind }> {
+  const out: Array<{ value: string; kind: HlKind }> = [];
+  let i = 0; const n = src.length;
+  const push = (value: string, kind: HlKind): void => { if (value) out.push({ value, kind }); };
+  while (i < n) {
+    const c = src[i]!;
+    if (/\s/.test(c)) { let j = i; while (j < n && /\s/.test(src[j]!)) j++; push(src.slice(i, j), 'ws'); i = j; continue; }
+    if (c === '"' || c === "'") { let j = i + 1; while (j < n && src[j] !== c) { if (src[j] === '\\') j++; j++; } j = Math.min(j + 1, n); push(src.slice(i, j), 'str'); i = j; continue; }
+    if (/[0-9]/.test(c)) { let j = i; while (j < n && /[0-9.]/.test(src[j]!)) j++; push(src.slice(i, j), 'num'); i = j; continue; }
+    if (/[A-Za-z_]/.test(c)) {
+      let j = i; while (j < n && /[A-Za-z0-9_]/.test(src[j]!)) j++;
+      const w = src.slice(i, j);
+      const kind: HlKind = (w === 'true' || w === 'false' || w === 'null') ? 'kw' : FN_SET.has(w) ? 'fn' : ROOT_SET.has(w) ? 'var' : 'ident';
+      push(w, kind); i = j; continue;
+    }
+    const two = src.slice(i, i + 2);
+    if (['||', '&&', '==', '!=', '<=', '>='].includes(two)) { push(two, 'op'); i += 2; continue; }
+    push(c, /[+\-*/%<>!?:().,]/.test(c) ? 'op' : 'err'); i += 1;
+  }
+  return out;
+}
+
+// small bounded parse cache (exprs are tiny + capped); keyed by source string.
+const PARSE_CACHE = new Map<string, Node>();
+function parseCached(_id: string, expr: string): Node {
+  let ast = PARSE_CACHE.get(expr);
+  if (!ast) {
+    ast = parseExpr(expr);
+    if (PARSE_CACHE.size > 500) PARSE_CACHE.clear();
+    PARSE_CACHE.set(expr, ast);
+  }
+  return ast;
+}