@vxil/feature-configs 0.1.1 → 0.3.0

package/src/index.ts

@@ -21,6 +21,108 @@ if (!FormatRegistry.Has('email')) {
   FormatRegistry.Set('email', (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v));
 }
 
+// ── RESERVED (vxil-COGS) CREDIT TYPES — single source of truth (audit F2) ─────
+// `fn_cpu_ms` funds vxil's OWN function-compute cost-of-goods (the
+// functions "recover-by-price" meter). It must NEVER be grantable or consumable
+// by a tenant's own `payments:write` key, NOR mapped-in via ledger config — a
+// tenant that self-grants `fn_cpu_ms` (directly, or by routing a product/tier
+// through the webhook/subscription grant reducers) runs vxil-billed function CPU
+// for free. Defined HERE (the typebox-only shared package both the control-plane
+// config-write gate AND payments-v1 import) so the runtime choke point and the
+// config-write refusal share ONE list. payments-v1/core.ts re-exports these.
+export const RESERVED_CREDIT_TYPES: ReadonlySet<string> = new Set<string>(['fn_cpu_ms']);
+
+/** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
+ *  of which is restricted to internal platform machinery). */
+export function isReservedCreditType(creditType: string): boolean {
+  return RESERVED_CREDIT_TYPES.has(creditType);
+}
+
+// ── notifications template catalog (D4 per-locale overrides) ─────────────────
+// The SHIPPED template ids and the placeholders each body may interpolate. The
+// renderer itself lives in workers/notifications-v1/src/templates.ts (templates
+// are code, not rows); this table is the CONFIG-TIME half so a `vxil push` that
+// overrides a template with a typo'd `{{placholder}}` is rejected at write time
+// instead of silently rendering an empty string into a customer's email.
+// Parity with the real renderer is asserted by the worker's templates.test.ts.
+export const NOTIFICATION_TEMPLATE_PLACEHOLDERS: Readonly<Record<string, readonly string[]>> = {
+  'magic-link': ['url', 'expires_minutes'],
+  'otp-code': ['code', 'expires_minutes'],
+  welcome: ['app_name', 'first_name', 'first_name_greeting'],
+  transactional: ['subject', 'paragraph', 'cta_label', 'cta_url'],
+};
+
+/** Per-override caps (D4). Bodies are emails, not documents. */
+export const NOTIF_OVERRIDE_SUBJECT_MAX = 500;
+export const NOTIF_OVERRIDE_BODY_MAX = 20_000;
+/** Whole-map caps: keeps one manifest (and the KV row every send reads) small. */
+export const NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE = 20;
+export const NOTIF_OVERRIDE_MAX_BYTES = 64 * 1024;
+
+/** `{{ placeholder }}` occurrences in one override body (the worker renderer's
+ * grammar verbatim — templates.ts `interpolate`). */
+const NOTIF_PLACEHOLDER_RE = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
+/** Same permissive BCP-47-ish shape the worker's auto-locale resolver accepts. */
+const NOTIF_LOCALE_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$/;
+
+/**
+ * D4 — validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
+ * bag is absent or clean. Every rule fails LOUD rather than shipping something
+ * that silently renders wrong in a customer's inbox:
+ *   • overrides present with `allowOverride:false` → rejected (never inert);
+ *   • an unknown template id / locale tag → rejected;
+ *   • an unknown `{{placeholder}}` in subject/html/text → rejected (the class of
+ *     typo that renders as an empty string in a live email);
+ *   • size caps (per-locale count, whole-map bytes) → rejected.
+ * Pure, so it is unit-tested without a control plane.
+ */
+export function validateNotificationOverrides(
+  templates: {
+    allowOverride?: boolean;
+    overrides?: Record<string, Record<string, { subject?: string; html?: string; text?: string }>>;
+  } | undefined,
+): string[] {
+  const overrides = templates?.overrides;
+  if (!overrides || Object.keys(overrides).length === 0) return [];
+  const errs: string[] = [];
+  if (templates?.allowOverride !== true) {
+    errs.push('/templates/overrides: set templates.allowOverride: true to use per-locale template overrides (an override map with allowOverride:false would never be rendered)');
+  }
+  const bytes = new TextEncoder().encode(JSON.stringify(overrides)).byteLength;
+  if (bytes > NOTIF_OVERRIDE_MAX_BYTES) {
+    errs.push(`/templates/overrides: ${bytes} bytes exceeds the ${NOTIF_OVERRIDE_MAX_BYTES}-byte cap`);
+  }
+  for (const [templateId, byLocale] of Object.entries(overrides)) {
+    const allowed = NOTIFICATION_TEMPLATE_PLACEHOLDERS[templateId];
+    if (!allowed) {
+      errs.push(`/templates/overrides/${templateId}: unknown template id (one of: ${Object.keys(NOTIFICATION_TEMPLATE_PLACEHOLDERS).join(', ')})`);
+      continue;
+    }
+    const locales = Object.keys(byLocale ?? {});
+    if (locales.length > NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE) {
+      errs.push(`/templates/overrides/${templateId}: ${locales.length} locales exceeds the ${NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE}-per-template cap`);
+    }
+    for (const locale of locales) {
+      if (!NOTIF_LOCALE_RE.test(locale)) {
+        errs.push(`/templates/overrides/${templateId}/${locale}: not a BCP-47 locale tag (e.g. 'en-GB')`);
+        continue;
+      }
+      const variant = byLocale![locale]!;
+      for (const part of ['subject', 'html', 'text'] as const) {
+        const body = variant[part];
+        if (typeof body !== 'string') continue;
+        for (const m of body.matchAll(NOTIF_PLACEHOLDER_RE)) {
+          const key = m[1]!;
+          if (!allowed.includes(key)) {
+            errs.push(`/templates/overrides/${templateId}/${locale}/${part}: unknown placeholder '{{${key}}}' (allowed: ${allowed.join(', ')})`);
+          }
+        }
+      }
+    }
+  }
+  return errs;
+}
+
 export const NotificationsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
   fromEmail: Type.String({ format: 'email' }),
@@ -30,14 +132,27 @@ export const NotificationsConfigSchema = Type.Object({
   // need no email account, so the mock path is zero-config. A cross-field
   // check in validateFeatureConfig requires it only when provider === 'resend'.
   resendApiKeyRef: Type.Optional(Type.String()),
+  // Optional per-tenant Resend/Svix ENDPOINT secret ref (public.tenant_secrets,
+  // envelope-encrypted under KEK_NOTIFICATIONS — same store as resendApiKeyRef).
+  // When set, inbound Resend webhooks are verified with THIS tenant's secret
+  // instead of the platform-wide PROVIDER_WEBHOOK_SECRET, binding the signature
+  // to the tenant so a signed event for tenant A can never validate at tenant
+  // B's webhook URL (audit H6 — mirrors payments revenuecat.webhookSecretRef).
+  webhookSecretRef: Type.Optional(Type.String()),
   // 'mock' exists for staging/e2e (deterministic provider); 'resend' is MVP.
   provider: Type.Union([Type.Literal('resend'), Type.Literal('mock')], {
     default: 'resend',
   }),
   defaultLocale: Type.String({ default: 'en-US' }),
   // nested objects carry `default: {}` so Value.Default can materialize them
-  // and then recurse into the leaf defaults
-  retry: Type.Object(
+  // and then recurse into the leaf defaults.
+  // `retry` became an OPTIONAL bag (2 leaves → 1, countLeaves counts an
+  // Optional object as ONE) to fund `broadcast` below (M21/#4, 2026-07-18).
+  // It KEEPS `default: {}`, which Value.Default still materializes — so every
+  // persisted manifest carries retry.{maxAttempts,backoff} exactly as before
+  // (zero behavioral delta); only the TS type is now optional (workers read
+  // via retryOf()'s fallback).
+  retry: Type.Optional(Type.Object(
     {
       maxAttempts: Type.Integer({ default: 5, minimum: 1, maximum: 20 }),
       backoff: Type.Union([Type.Literal('exponential'), Type.Literal('linear')], {
@@ -45,7 +160,7 @@ export const NotificationsConfigSchema = Type.Object({
       }),
     },
     { default: {} },
-  ),
+  )),
   suppression: Type.Object(
     { softBounceThreshold: Type.Integer({ default: 3 }) },
     { default: {} },
@@ -57,19 +172,71 @@ export const NotificationsConfigSchema = Type.Object({
     },
     { default: {} },
   ),
-  templates: Type.Object(
-    { allowOverride: Type.Boolean({ default: false }) },
+  // `templates` became an OPTIONAL bag (1 leaf, the same M21 trick `retry`
+  // uses) to fund the D4 per-locale `overrides` map WITHOUT moving the count:
+  // countLeaves scores an Optional object as ONE. `default: {}` is KEPT, so
+  // Value.Default still materializes `templates.allowOverride` into every
+  // persisted manifest exactly as before — zero behavioral delta; only the TS
+  // type is optional (workers read via core.ts `templatesOf()`).
+  templates: Type.Optional(Type.Object(
+    {
+      allowOverride: Type.Boolean({ default: false }),
+      // D4 (2026-09-10) — TENANT-AUTHORED PER-LOCALE OVERRIDES of the SHIPPED
+      // template ids, as config DATA (a Record = 1 leaf, catalog size never
+      // moves the count). Shape: { [templateId]: { [locale]: { subject,
+      // html?, text? } } }. Same escaped `{{placeholder}}` grammar as the
+      // built-ins — the worker reuses ONE renderer, so escaping/URL-scheme
+      // sanitisation are identical and there is no raw-output syntax.
+      // validateFeatureConfig rejects: an unknown template id, an unknown
+      // placeholder, a malformed locale tag, an over-size body, and (fail
+      // LOUD, never silently inert) overrides present with allowOverride:false.
+      overrides: Type.Optional(Type.Record(
+        Type.String(),
+        Type.Record(Type.String(), Type.Object({
+          subject: Type.String({ minLength: 1, maxLength: NOTIF_OVERRIDE_SUBJECT_MAX }),
+          html: Type.Optional(Type.String({ maxLength: NOTIF_OVERRIDE_BODY_MAX })),
+          text: Type.Optional(Type.String({ maxLength: NOTIF_OVERRIDE_BODY_MAX })),
+        })),
+      )),
+    },
     { default: {} },
-  ),
+  )),
   /** in-app inbox channel (send with channel: 'inbox' | 'both') */
   inboxEnabled: Type.Boolean({ default: false }),
+  /** §11b.5 broadcast campaigns channel. Optional bag (= 1 leaf): absent means
+   * disabled; per-campaign quiet_hours / freq_cap overrides live on the
+   * notifications.campaigns ROW (tenant data), not here. Folded into the
+   * canonical schema 2026-07-18 (M21/#4 — Value.Clean previously STRIPPED the
+   * worker-local extension, so campaigns 403'd via the real config path). */
+  broadcast: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    /** tenant-default per-recipient quiet window (defer-not-drop); a
+     * per-campaign quiet_hours wins over it. Mirrors the campaigns-row shape
+     * (workers/notifications-v1 CampaignBody.quiet_hours). start/end are
+     * pattern-pinned to what the worker's parseHhMm actually parses — a
+     * looser string ('10pm') would validate but FAIL OPEN at runtime
+     * (quiet window silently ignored). */
+    defaultQuietHours: Type.Optional(Type.Object({
+      tz: Type.String({ minLength: 1, maxLength: 64 }),
+      start: Type.String({ maxLength: 5, pattern: '^\\d{1,2}:\\d{2}$' }),
+      end: Type.String({ maxLength: 5, pattern: '^\\d{1,2}:\\d{2}$' }),
+    })),
+    /** default rolling per-user-per-day campaign-send cap across campaigns */
+    freqCapPerUserPerDay: Type.Integer({ default: 5, minimum: 0 }),
+  })),
 });
-// Leaves: enabled, fromEmail, fromName, replyTo, resendApiKeyRef, provider,
-// defaultLocale, retry.maxAttempts, retry.backoff,
+// Leaves: enabled, fromEmail, fromName, replyTo, resendApiKeyRef,
+// webhookSecretRef, provider, defaultLocale, retry (Optional bag = 1),
 // suppression.softBounceThreshold, rateLimit.perDay, rateLimit.perTenantSec,
-// templates.allowOverride, inboxEnabled → 14. Cap = 15.
+// templates (Optional bag = 1 — was templates.allowOverride, collapsed 2026-09-10
+// to fund the D4 `overrides` map at zero net cost), inboxEnabled,
+// broadcast (Optional bag = 1) → 15. Cap = 15 — AT the cap; the next flag must
+// collapse something. (`templates.overrides` is a Record MAP inside the ONE
+// optional templates leaf — DATA, not a flag — so catalog size never moves it.)
 
 export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
+/** The §11b.5 broadcast bag as persisted (present ⇒ leaf defaults applied). */
+export type BroadcastConfig = NonNullable<NotificationsConfig['broadcast']>;
 
 export const JobsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
@@ -160,10 +327,61 @@ const AppleRefsSchema = Type.Object({
   // Value.Clean stripping the field out of PUT /v1/config/auth.
   bundleIds: Type.Optional(Type.Array(Type.String(), { maxItems: 16 })),
 });
+// RB-2 — the generic OIDC / SSO bridge (roadmap §4.6.B, §1B.5; features/auth.md
+// §6.7). ONE tenant-supplied issuer, declared INSIDE the existing `providers`
+// bag so it spends NO leaf (an Optional object bag = ONE leaf; auth stays 11).
+// Declarative + opt-in: the block's PRESENCE enables the `oidc` provider (no
+// methods.* toggle — a `default:false` flag would re-materialize every published
+// manifest, breaking the D3 byte-identical fold). The worker discovers the
+// endpoints + JWKS from `{issuer}/.well-known/openid-configuration` and verifies
+// iss (byte-equal) / aud (= clientId) / nonce / exp / iat strictly, fail-closed.
+// `clientId` is NOT a secret (it rides every authorize URL); `clientSecretRef`
+// is a tenant_secrets POINTER (feature 'auth'), never the value. A SAML IdP
+// plugs in through a broker (Okta / Entra / Auth0 / WorkOS) that speaks OIDC —
+// there is deliberately NO native SAML.
+const OidcProviderSchema = Type.Object({
+  // https URL, no query/fragment (the OIDC issuer identifier). Compared
+  // BYTE-EQUAL to the discovery document's `issuer` and the id_token `iss`.
+  issuer: Type.String({ minLength: 12, maxLength: 512, pattern: '^https://[^\\s?#]+$' }),
+  clientId: Type.String({ minLength: 1, maxLength: 512 }),
+  clientSecretRef: Type.String({ minLength: 1, maxLength: 200 }),
+  // authorize-request scopes; `openid` is always added by the worker. Default
+  // (absent) = openid email profile.
+  scopes: Type.Optional(Type.Array(
+    Type.String({ minLength: 1, maxLength: 64, pattern: '^[\\x21-\\x7e]+$' }), { maxItems: 16 },
+  )),
+  // claim NAMES to read (absent = the standard `email` / `name`; `roles` has
+  // no default — no claim named ⇒ no role claims are minted).
+  claims: Type.Optional(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 })),
+  })),
+  // 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
+  // marks the email verified (the tenant declared the issuer authoritative).
+  allowedDomains: Type.Optional(Type.Array(
+    Type.String({ minLength: 3, maxLength: 253, pattern: '^[a-z0-9][a-z0-9.-]*\\.[a-z]{2,}$' }),
+    { maxItems: 32 },
+  )),
+  // default true: an identity whose VERIFIED email matches an existing user is
+  // linked to it (the shipped §6.4 rule). false: link only by the stable
+  // (issuer, sub) anchor; a matching email that is not yet linked → 409.
+  autoLink: Type.Optional(Type.Boolean()),
+});
 
 export const AuthConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
-  methods: Type.Object(
+  // D3 (auth wave 2026-09-10): the six method toggles collapsed into ONE
+  // Optional bag (6 leaves → 1, countLeaves counts an Optional object as ONE) —
+  // the notifications `retry`/`broadcast` precedent. It KEEPS `default: {}`,
+  // which Value.Default still materializes, so every persisted manifest carries
+  // methods.{emailPassword,magicLink,google,github,apple,facebook} with the
+  // SAME keys and defaults as before — byte-identical folds for existing
+  // tenants (index.test.ts "D3 fold bytes"). Only the TS type is now optional;
+  // the worker's gate() normalizes an absent bag to the defaults so every
+  // reader (config.methods.<flag>) is unchanged.
+  methods: Type.Optional(Type.Object(
     {
       emailPassword: Type.Boolean({ default: true }),
       magicLink: Type.Boolean({ default: true }),
@@ -173,7 +391,7 @@ export const AuthConfigSchema = Type.Object({
       facebook: Type.Boolean({ default: false }),
     },
     { default: {} },
-  ),
+  )),
   // Per-provider BYO credential refs. ONE optional bag (= ONE leaf per the cap
   // rule) keyed by provider, so the four provider blocks (and any future one)
   // never inflate the flag count — the prior shape spent a leaf per top-level
@@ -191,6 +409,8 @@ export const AuthConfigSchema = Type.Object({
     github: Type.Optional(OAuthRefsSchema),
     apple: Type.Optional(AppleRefsSchema),
     facebook: Type.Optional(OAuthRefsSchema),
+    // RB-2: the generic OIDC / SSO issuer (presence = enabled; see above)
+    oidc: Type.Optional(OidcProviderSchema),
   })),
   // session/password are OPTIONAL bags (= ONE leaf each per the cap rule) since
   // the OTP/anonymous/orgClaims wave — the `{ default: {} }` keeps the inner
@@ -201,6 +421,12 @@ export const AuthConfigSchema = Type.Object({
     {
       ttlMinutes: Type.Integer({ default: 60, minimum: 5, maximum: 1440 }),
       refreshTtlDays: Type.Integer({ default: 30, minimum: 1, maximum: 365 }),
+      // A1 (auth wave 2026-09-10): concurrent-session cap per user with
+      // TAKE-OVER — a new sign-in revokes the OLDEST sessions past the cap
+      // (revoked_reason 'device_cap', edge cache written) and reports them as
+      // `took_over: [session_id…]`. Optional WITHOUT a default so existing
+      // manifests fold byte-identically; absent/0 = unlimited (today).
+      maxConcurrent: Type.Optional(Type.Integer({ minimum: 0, maximum: 100 })),
     },
     { default: {} },
   )),
@@ -231,6 +457,16 @@ export const AuthConfigSchema = Type.Object({
     codeTtlMinutes: Type.Integer({ default: 10, minimum: 1, maximum: 60 }),
     maxAttempts: Type.Integer({ default: 5, minimum: 3, maximum: 10 }),
     resendCooldownSec: Type.Integer({ default: 60, minimum: 0, maximum: 600 }),
+    // F4-29 (auth wave 2026-09-10): test recipients — an OTP / step-up / email-
+    // claim request whose address matches an entry sends NO mail and returns
+    // the code as `test_code` (audit auth.otp.test_issued). Entries: an exact
+    // email, a `*@domain` glob, or a +E.164 number (accepted for the SMS
+    // channel; inert for email identifiers). ≤20; Optional (no default) so
+    // existing manifests fold byte-identically. Store-review / CI accounts
+    // only — never a real user's address.
+    testRecipients: Type.Optional(Type.Array(
+      Type.String({ minLength: 3, maxLength: 320 }), { maxItems: 20 },
+    )),
   })),
   // Anonymous (guest) sign-in (roadmap Tier-0). OPTIONAL bag = 1 leaf.
   anonymous: Type.Optional(Type.Object({
@@ -250,15 +486,49 @@ export const AuthConfigSchema = Type.Object({
   // its leaf was spent on the methods.{apple,facebook} toggles the shipped
   // §6.4 sign-in flow actually gates on. Re-adding it requires headroom or a
   // collapse elsewhere.
+  //
+  // Account-security controls (auth wave 2026-09-10, P0-3; features/auth.md
+  // §4b). ONE optional bag = 1 leaf; NO `default: {}` so an absent bag stays
+  // absent (existing manifests fold byte-identically) and every control is
+  // opt-in:
+  //   • lockout — present ⇒ per-(tenant, identifier) failure lockout on password
+  //     sign-in + OTP verify (429 account_locked + Retry-After); a bounded
+  //     counter row in auth.lockouts (migration 0088) survives restarts.
+  //   • breachedPasswords — HIBP k-anonymity range check (first 5 SHA-1 hex
+  //     chars leave the worker, never the password) at sign-up / reset-confirm;
+  //     fail-OPEN on network error → 422 password_breached.
+  //   • captchaSecretRef — a tenant_secrets ref (feature 'auth') holding the
+  //     Turnstile secret; when set, sign-up / OTP request / magic-link request
+  //     require `captcha_token` (403 captcha_failed otherwise).
+  //   • allowedRedirectOrigins — when non-empty, EVERY caller-supplied
+  //     redirect/return URL (magic link, password reset, email verification,
+  //     OAuth start) must match one origin exactly → 422 redirect_not_allowed.
+  security: Type.Optional(Type.Object({
+    lockout: Type.Optional(Type.Object({
+      maxFailures: Type.Integer({ default: 10, minimum: 3, maximum: 100 }),
+      windowMinutes: Type.Integer({ default: 15, minimum: 1, maximum: 1440 }),
+      lockMinutes: Type.Integer({ default: 15, minimum: 1, maximum: 1440 }),
+    })),
+    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: '^https://[^/?#\\s]+$' }),
+      { maxItems: 32 },
+    )),
+  })),
 });
-// Leaves: enabled(1) + methods(6) + providers(1, optional bag holding the four
-// google/github/apple/facebook credential blocks) + session(1, optional bag)
-// + password(1, optional bag) + emailVerification(1) + magicLink(1) + otp(1,
-// optional bag) + anonymous(1, optional bag) + orgClaims(1, optional bag) = 15.
-// Cap = 15 — at the cap; the next flag must collapse something.
-// providers is an optional bag → adding social providers (apple/facebook, §6) never
-// grows the flag count; the prior 15-flag version spent a leaf per top-level
-// google/github block.
+/** The security bag as persisted (present ⇒ leaf defaults applied). */
+export type AuthSecurityConfig = NonNullable<Static<typeof AuthConfigSchema>['security']>;
+/** The RB-2 generic OIDC / SSO issuer block (`providers.oidc`). */
+export type AuthOidcConfig = Static<typeof OidcProviderSchema>;
+// Leaves (auth wave 2026-09-10, D3): enabled(1) + methods(1, optional bag —
+// was 6) + providers(1, optional bag holding the four google/github/apple/
+// facebook credential blocks + the RB-2 `oidc` issuer block) + session(1, optional bag) + password(1,
+// optional bag) + emailVerification(1) + magicLink(1) + otp(1, optional bag)
+// + anonymous(1, optional bag) + orgClaims(1, optional bag) + security(1,
+// optional bag) = 11. Cap = 15 — 4 leaves of headroom. Knobs added inside an
+// existing bag (session.maxConcurrent, otp.testRecipients, the security
+// sub-bags) never move the count.
 
 export type AuthConfig = Static<typeof AuthConfigSchema>;
 
@@ -282,13 +552,16 @@ export type RateLimitsConfig = Static<typeof RateLimitsConfigSchema>;
 
 export const FilesConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
-  bucketRef: Type.String({ default: 'vxil-files' }),
+  // (F8-54) `bucketRef` was DELETED: the object-storage bucket is a platform
+  // binding on files-v1, never tenant-selectable, and no code ever read the
+  // leaf — declaring it invited "point files at my own bucket", which vxil does
+  // not offer. A persisted manifest that still carries it folds (Value.Clean).
   uploadUrlTtl: Type.Integer({ default: 900, minimum: 60, maximum: 86400 }),
   downloadUrlTtl: Type.Integer({ default: 900, minimum: 60, maximum: 86400 }),
   quotas: Type.Object(
     {
       // maximum caps are a defense-in-depth ceiling on tenant-editable storage —
-      // R2 is cheap but Neon-resident metadata + abuse aren't (pricing re-audit
+      // object storage is cheap but the SQL-database-resident metadata + abuse aren't (pricing re-audit
       // 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
       // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
       // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
@@ -299,13 +572,10 @@ export const FilesConfigSchema = Type.Object({
     { default: {} },
   ),
   allowedContentTypes: Type.Array(Type.String(), { default: ['*'], maxItems: 100 }),
-  contentScan: Type.Object(
-    {
-      enabled: Type.Boolean({ default: false }), // V1.5
-      quarantineOnFail: Type.Boolean({ default: true }),
-    },
-    { default: {} },
-  ),
+  // (F8-54) the `contentScan` bag ({enabled, quarantineOnFail}) was DELETED:
+  // there is no malware/content scanner in files-v1 (it was a "V1.5" placeholder
+  // neither leaf was ever read), so the knob promised quarantine that never
+  // happened. Re-declare it in the same change as a real scanner, not before.
   sharedLinks: Type.Object(
     {
       enabled: Type.Boolean({ default: true }),
@@ -338,7 +608,8 @@ export const FilesConfigSchema = Type.Object({
     boundingBoxes: Type.Boolean({ default: false }),
   })),
 });
-// Leaves: 12 + ttl(1, optional bag) + extractText(1, optional bag) = 14. Cap = 15.
+// Leaves: 9 + ttl(1, optional bag) + extractText(1, optional bag) = 11. Cap = 15.
+// (was 14 — F8-54 deleted the inert bucketRef leaf and the inert contentScan bag.)
 
 export type FilesConfig = Static<typeof FilesConfigSchema>;
 
@@ -458,7 +729,7 @@ export const CmsConfigSchema = Type.Object({
     }),
   )),
   // Realtime CDC bridge (cms-rel E): cms writes auto-publish a change event to
-  // a realtime channel — config-only rewiring of postgres_changes-style subs.
+  // a realtime channel — config-only rewiring of database-change-event-style subs.
   // Fire-and-forget via waitUntil; at-most-once (guaranteed delivery stays
   // webhooks-out / functions cms-hook). ONE Type.Record leaf.
   cdc: Type.Optional(Type.Record(
@@ -491,10 +762,10 @@ export const McpConfigSchema = Type.Object({
     { default: 'all' },
   ),
   allowToolList: Type.Optional(Type.Array(Type.String(), { maxItems: 200 })),
-  scopedKey: Type.Object(
-    { perAgentKeys: Type.Boolean({ default: false }) }, // V1.5
-    { default: {} },
-  ),
+  // (F8-54) the `scopedKey.perAgentKeys` leaf was DELETED: it was documented as
+  // a "dashboard-UI hint only" that no dashboard ever read, and key minting is a
+  // control-plane concern independent of MCP exposure — per-agent keys already
+  // work for every tenant, gated by nothing here.
   rateLimits: Type.Object(
     { toolCallsPerMin: Type.Integer({ default: 60, minimum: 1, maximum: 6000 }) },
     { default: {} },
@@ -544,10 +815,10 @@ export const McpConfigSchema = Type.Object({
     }),
   )),
 });
-// Leaves: 9 by countLeaves (enabled, exposureLevel, allowToolList,
-// scopedKey.perAgentKeys, rateLimits.toolCallsPerMin, branding.serverName,
-// branding.serverInstructions = 7, + customTools + prompts as ONE Type.Record
-// leaf each). Cap = 15.
+// Leaves: 8 by countLeaves (enabled, exposureLevel, allowToolList,
+// rateLimits.toolCallsPerMin, branding.serverName, branding.serverInstructions
+// = 6, + customTools + prompts as ONE Type.Record leaf each). Cap = 15.
+// (was 9 — F8-54 deleted the inert scopedKey.perAgentKeys leaf.)
 
 export type McpConfig = Static<typeof McpConfigSchema>;
 
@@ -632,12 +903,10 @@ export const ActivityFeedConfigSchema = Type.Object({
     { default: {} },
   ),
 
-  aggregation: Type.Object(
-    {
-      maxGroupActivities: Type.Integer({ default: 15, minimum: 1, maximum: 100 }), // newest-N kept per group
-    },
-    { default: {} },
-  ),
+  // (F8-54) the `aggregation.maxGroupActivities` leaf was DELETED: nothing kept
+  // or returned a per-group activity LIST — an aggregated read returns the group
+  // rollup (activity_count/actor_count/last_actor), so there was never an N to
+  // bound and no code read the leaf. Re-declare it with a group-detail route.
 
   realtime: Type.Object(
     {
@@ -657,18 +926,17 @@ export const ActivityFeedConfigSchema = Type.Object({
     { default: {} },
   ),
 
-  rateLimit: Type.Object(
-    {
-      addPerSec: Type.Integer({ default: 100, minimum: 1, maximum: 100_000 }), // per-tenant activity-write burst
-    },
-    { default: {} },
-  ),
+  // (F8-54) the `rateLimit.addPerSec` leaf was DELETED: activity-feed-v1 has no
+  // rate-limiter binding and never read it, so the declared per-tenant write
+  // burst was enforced by nothing (the edge front-door limiter and the
+  // per-tenant request meter are the real bounds). Re-declare it together with
+  // the binding that enforces it.
 });
 // Leaves: enabled(1), feedGroups(1, the Record bag → ONE leaf), fanout.{celebrityThreshold,
 //   maxFanoutPerJob, maxConcurrentTasks, pendingCeiling}(+4=6), follow.{copyLimit,
-//   maxFollowing}(+2=8), aggregation.maxGroupActivities(9), realtime.enabled(10),
-//   crossChannel.{enabled, digestCadence}(+2=12), rateLimit.addPerSec(13).
-// countLeaves → 13. Cap = 15. (feedGroups is Type.Record → patternProperties, ONE leaf.)
+//   maxFollowing}(+2=8), realtime.enabled(9), crossChannel.{enabled, digestCadence}(+2=11).
+// countLeaves → 11. Cap = 15. (feedGroups is Type.Record → patternProperties, ONE leaf.)
+// (was 13 — F8-54 deleted the inert aggregation and rateLimit bags.)
 
 export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
 
@@ -681,13 +949,13 @@ export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
 // synthesis / relevance tuning (the tenant's moat). An OPTIONAL leaf = ONE flag.
 export const VectorSearchConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
-  // 'auto' resolves to pgvector until Lakebase is GA'd for the tier (#147).
+  // 'auto' resolves to the default managed vector backend for the tier (#147).
   backend: Type.Union(
     [Type.Literal('auto'), Type.Literal('lakebase'), Type.Literal('pgvector')],
     { default: 'auto' },
   ),
   // 'byov'/'mock' need NO provider key (zero-config default); openai/cohere read a
-  // BYO key from public.tenant_secrets via apiKeyRef (envelope-encrypted).
+  // BYO key from tenant secrets via apiKeyRef (encrypted at rest).
   embed: Type.Object(
     {
       provider: Type.Union(
@@ -941,6 +1209,13 @@ export const PaymentsConfigSchema = Type.Object({
     // of the platform PROVIDER_WEBHOOK_SECRET — closes the multi-tenant RC
     // webhook-forgery vector (mirrors stripe/paddle webhookSecretRef).
     webhookSecretRef: Type.Optional(Type.String()),
+    // Environment integrity (money-path wave F1-4/D5). RevenueCat posts SANDBOX
+    // and PRODUCTION events to the SAME webhook with the same auth header, so a
+    // sandbox purchase would otherwise fold into production entitlements. A
+    // sandbox event is persisted as outcome 'rejected_environment' (200, never
+    // folded) unless the tenant opts in here. Stripe/Paddle/PayPal separate
+    // environments by signing secret / API base, so only RC carries this knob.
+    acceptSandbox: Type.Boolean({ default: false }),
   })),
   paypal: Type.Optional(Type.Object({
     clientIdRef: Type.String(),
@@ -953,10 +1228,10 @@ export const PaymentsConfigSchema = Type.Object({
   // https-only. Absent ⇒ the worker's WEB_BASE_URL env (vxil's site), never a
   // hardcoded host (audit 2026-07-10: the old fallback pointed at a dead apex).
   returnUrl: Type.Optional(Type.String({ pattern: '^https://', maxLength: 512 })),
-  prices: Type.Object(
-    { catalogRef: Type.String({ default: 'default' }) }, // tenant-supplied price catalog ref
-    { default: {} },
-  ),
+  // NB (F8-54, 2026-09-11): the former `prices.catalogRef` leaf was DELETED —
+  // it named nothing (prices resolve from ledger.priceMap; no code path ever
+  // read it). A persisted manifest that still carries `prices` folds:
+  // validateFeatureConfig's Value.Clean strips the stray key.
   defaults: Type.Object(
     {
       currency: Type.String({ default: 'usd' }),
@@ -990,22 +1265,44 @@ export const PaymentsConfigSchema = Type.Object({
     // fold (refoldEntitlements WHERE tier IS NOT NULL) reflects the subscription.
     priceMap: Type.Optional(Type.Record(Type.String(), Type.String())),
     autoRefundOnJobFailure: Type.Boolean({ default: true }), // consume(jobId) reverses on DLQ/timeout
+    // Grace window (money-path wave F1-7): a `past_due` subscription stays
+    // entitled for this many days AFTER its current_period_end (the dunning
+    // window the provider is retrying inside). 0 = today's behaviour (a past_due
+    // row is never entitled). ONE predicate in the fold — NOT a dunning ladder:
+    // no retries, no emails. Lives inside the ledger bag (no new top-level leaf).
+    grace: Type.Optional(Type.Object({
+      pastDueDays: Type.Integer({ default: 0, minimum: 0, maximum: 90 }),
+    })),
+    // Opt-in period-end enforcement (money-path operations wave, decision D2
+    // option a). ABSENT (the default) = today's behaviour: a subscription whose
+    // current_period_end passed with no provider event stays entitled forever
+    // (the provider is the only clock). PRESENT = the hourly reconcile sweep
+    // flips an `active`/`trialing` row whose current_period_end + slackHours
+    // has passed with no renewal to status 'lapsed' (+ refold, +
+    // payments.subscription.lapsed); a later provider renewal event revives it
+    // (the two-clocks revive rule). Never a manual row without `until`. Lives
+    // inside the ledger bag (no new top-level leaf).
+    enforcePeriodEnd: Type.Optional(Type.Object({
+      slackHours: Type.Integer({ default: 72, minimum: 0, maximum: 720 }),
+    })),
   })),
-  webhooks: Type.Object(
-    { forwardToTenantUrl: Type.Optional(Type.String({ format: 'uri' })) },
-    { default: {} },
-  ),
+  // NB (money-path wave F3-19): the former `webhooks.forwardToTenantUrl` leaf
+  // was DELETED — it had zero readers (never forwarded anything). Outbound
+  // delivery of payments state changes rides the audit_event → webhooks-out
+  // spine: subscribe to the `payments.` event prefix (payments.md §7b).
 });
 // Leaves: enabled(1), provider(2), stripe?(3), paddle?(4), revenuecat?(5),
-//   paypal?(6), prices.catalogRef(7), defaults.{currency,trialDays}(+2=9),
-//   ledger?(10), webhooks.forwardToTenantUrl(11). countLeaves → 11. Cap = 15.
-//   (productMap / tierMap / priceMap are Type.Record MAPS inside the ONE optional
-//   ledger leaf — DATA, not flags — so catalog size never moves the count.)
+//   paypal?(6), returnUrl(7), defaults.{currency,trialDays}(+2=9), ledger?(10).
+//   countLeaves → 10. Cap = 15. (prices.catalogRef was deleted 2026-09-11.)
+//   (productMap / tierMap / priceMap / grace / enforcePeriodEnd are inside the
+//   ONE optional ledger leaf — DATA + two nested optional bags — so catalog size
+//   never moves the count; revenuecat.acceptSandbox is inside the ONE optional
+//   revenuecat leaf.)
 
 export type PaymentsConfig = Static<typeof PaymentsConfigSchema>;
 
 // functions feature (vxil-functions-design §4.c). Tenant-deployed backend edge
-// functions on Workers-for-Platforms. The FUNCTION owns its identity (bundle via
+// functions on the managed serverless runtime. The FUNCTION owns its identity (bundle via
 // scriptRef, scopes, secrets, egress, limits, runtime) + a SET of trigger
 // bindings; every other surface (e.g. cms.hooks) REFERENCES a function BY NAME and
 // never re-embeds deploy config. The per-function bag is ONE Type.Record leaf
@@ -1014,13 +1311,17 @@ export type PaymentsConfig = Static<typeof PaymentsConfigSchema>;
 // opt-in (enabled defaults to false), egress-guarded.
 export const FunctionsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: false }),
-  // isolate = WfP Worker (Lane 2, default); container = CF Containers (Lane 3, design-only).
-  runtime: Type.Union([Type.Literal('isolate'), Type.Literal('container')], { default: 'isolate' }),
+  // (F8-54) `runtime` ('isolate' | 'container') was DELETED: the container lane
+  // is design-only, nothing read the leaf, and accepting 'container' silently
+  // ran the isolate anyway. It comes back with the lane, not before.
   defaultLimits: Type.Object(
     {
+      // cpuMs is the ONLY per-dispatch limit the managed runtime accepts and the
+      // only one anything reads (functions-v1 meter.ts + the dispatch cap).
+      // (F8-54) `timeoutMs` and `memoryMb` were DELETED: memory is fixed by the
+      // runtime and not tenant-selectable, and no wall-clock abort was ever
+      // applied — a declared 10s default that nothing enforced.
       cpuMs: Type.Integer({ default: 50, minimum: 5, maximum: 300_000 }),
-      timeoutMs: Type.Integer({ default: 10_000, minimum: 50, maximum: 300_000 }),
-      memoryMb: Type.Integer({ default: 128, minimum: 64, maximum: 1024 }),
     },
     { default: {} },
   ),
@@ -1096,11 +1397,12 @@ export const FunctionsConfigSchema = Type.Object({
     ),
   ),
 });
-// Leaves: enabled(1), runtime(2), defaultLimits.{cpuMs,timeoutMs,memoryMb}(+3=5),
-//   metering.enabled(6), functions(7, the Type.Record bag → ONE leaf;
-//   bindings[]/scriptRef/scopes/secrets/egressAllow/limits/enabled/signature
-//   are DATA inside the MAP value and never move the count, like cms.hooks).
-//   countLeaves → 7. Cap = 15.
+// Leaves: enabled(1), defaultLimits.cpuMs(2), metering.enabled(3),
+//   functions(4, the Type.Record bag → ONE leaf; bindings[]/scriptRef/scopes/
+//   secrets/egressAllow/limits/enabled/signature are DATA inside the MAP value
+//   and never move the count, like cms.hooks). countLeaves → 4. Cap = 15.
+//   (was 7 — F8-54 deleted the inert runtime, defaultLimits.timeoutMs and
+//   defaultLimits.memoryMb leaves.)
 export type FunctionsConfig = Static<typeof FunctionsConfigSchema>;
 
 // copilot feature (docs/copilot-agents-sku-design.md §4). Re-declared to match
@@ -1185,20 +1487,17 @@ export const CopilotConfigSchema = Type.Object({
     { default: {} },
   ),
 
-  // ── escalation: human hand-off (composes notifications/comments) ──────────
-  escalation: Type.Optional(Type.Object({
-    enabled: Type.Boolean({ default: false }),
-    handler: Type.Union(
-      [Type.Literal('comments'), Type.Literal('notifications')],
-      { default: 'comments' },
-    ),
-    notifyTemplate: Type.Optional(Type.String({ maxLength: 128 })),
-  })),
+  // (F8-54) the `escalation` bag ({enabled, handler, notifyTemplate}) was
+  // DELETED: the human hand-off it declared was never built — copilot-v1 read
+  // none of the three leaves, so a tenant who turned it on got silence. The
+  // shipped hand-off path is a tenant function on the conversation events.
 
   // ── limits: DELEGATE token/credit accounting to ai-v1 ─────────────────────
   limits: Type.Object({
     consumeCredits: Type.Boolean({ default: false }),
-    tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = inherit ai
+    // (F8-54) `tokensPerUserPerDay` was DELETED here: token accounting is
+    // delegated to ai-v1 (this bag's own doctrine) and only `ai`'s
+    // limits.tokensPerUserPerDay is enforced — the copilot twin read nothing.
   }, { default: {} }),
 
   // ── widget / embed (the Stage-3 public chat surface) ──────────────────────
@@ -1209,10 +1508,10 @@ export const CopilotConfigSchema = Type.Object({
     theme: Type.Optional(Type.String({ maxLength: 32 })),
   }, { default: {} }),
 });
-// Leaves: enabled(1), agents(2 — Type.Record MAP, ONE leaf), escalation?(3 —
-//   optional object, ONE leaf), limits.{consumeCredits,tokensPerUserPerDay}
-//   (+2=5), widget.{enabled,requireAuth,allowedOrigins,theme}(+4=9).
-//   countLeaves → 9. Cap = 15.
+// Leaves: enabled(1), agents(2 — Type.Record MAP, ONE leaf),
+//   limits.consumeCredits(3), widget.{enabled,requireAuth,allowedOrigins,theme}
+//   (+4=7). countLeaves → 7. Cap = 15.
+//   (was 9 — F8-54 deleted the inert escalation bag and limits.tokensPerUserPerDay.)
 
 export type CopilotConfig = Static<typeof CopilotConfigSchema>;
 
@@ -1244,6 +1543,36 @@ export const CONFIG_FLAG_CAP = 15;
  * Per features/auth.md §4: an OPTIONAL object (e.g. a provider credential
  * block) counts as ONE flag — the tenant's decision is "configure it or
  * not", not each inner ref. */
+/** The auth lifecycle events an `authHook` binding may name (F4-30) — the
+ * closed union `packages/config` types as AuthHookEvent; the control-plane
+ * reconciler maps each to its `auth.<event>` audit-event prefix. */
+export const AUTH_HOOK_EVENTS = ['user.created', 'session.created', 'session.revoked', 'signin.failure'] as const;
+export type AuthHookEvent = (typeof AUTH_HOOK_EVENTS)[number];
+
+/** F4-29 test-recipient entry grammar (shared by the validator and auth-v1's
+ * matcher): an exact email, a `*@domain` glob, or a +E.164 phone number. */
+export const TEST_RECIPIENT_EMAIL_RE = /^[^\s@*]+@[^\s@]+\.[^\s@]+$/;
+export const TEST_RECIPIENT_GLOB_RE = /^\*@[^\s@*]+\.[^\s@*]+$/;
+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);
+}
+/** True iff `identifier` (an email today) matches one configured entry:
+ * exact (case-insensitive) or the `*@domain` glob. +E.164 entries never match
+ * an email. */
+export function matchesTestRecipient(identifier: string, entries: readonly string[] | undefined): boolean {
+  if (!entries || entries.length === 0) return false;
+  const id = identifier.trim().toLowerCase();
+  const at = id.lastIndexOf('@');
+  const domain = at >= 0 ? id.slice(at + 1) : null;
+  return entries.some((raw) => {
+    const e = raw.trim().toLowerCase();
+    if (TEST_RECIPIENT_GLOB_RE.test(e)) return domain !== null && domain === e.slice(2);
+    if (TEST_RECIPIENT_E164_RE.test(e)) return id === e;
+    return id === e;
+  });
+}
+
 export function countLeaves(schema: TSchema): number {
   const t = schema as unknown as {
     type?: string;
@@ -1369,20 +1698,36 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
   // Cross-field rule: notifications only needs a Resend key for the real
   // provider. The `mock` provider (and inbox-only setups) stay zero-config.
   if (feature === 'notifications') {
-    const v = withDefaults as { provider?: string; resendApiKeyRef?: string };
+    const v = withDefaults as {
+      provider?: string;
+      resendApiKeyRef?: string;
+      templates?: {
+        allowOverride?: boolean;
+        overrides?: Record<string, Record<string, { subject?: string; html?: string; text?: string }>>;
+      };
+    };
     if (v.provider === 'resend' && !v.resendApiKeyRef) {
       return {
         ok: false,
         errors: ["/resendApiKeyRef: required when provider is 'resend' (omit it for provider 'mock')"],
       };
     }
+    const overrideErrs = validateNotificationOverrides(v.templates);
+    if (overrideErrs.length) return { ok: false, errors: overrideErrs.slice(0, 10) };
   }
   // Cross-field rule: a REAL payments provider needs its credential block; the
   // 'mock' provider (the deterministic default) stays zero-config so the whole
   // ledger path is testable without real keys (features/payments.md §0/§6).
   if (feature === 'payments') {
-    const v = withDefaults as { provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown };
-    const needsBlock: Record<string, keyof typeof v> = {
+    const v = withDefaults as {
+      provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown;
+      ledger?: {
+        productMap?: Record<string, { creditType?: string }>;
+        tierMap?: Record<string, { rank?: number; grants?: Array<{ creditType?: string }> }>;
+        priceMap?: Record<string, string>;
+      };
+    };
+    const needsBlock: Record<string, 'stripe' | 'paddle' | 'revenuecat'> = {
       stripe: 'stripe', paddle: 'paddle', revenuecat: 'revenuecat',
     };
     const key = v.provider ? needsBlock[v.provider] : undefined;
@@ -1392,6 +1737,56 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         errors: [`/${String(key)}: required when provider is '${v.provider}' (omit it for provider 'mock')`],
       };
     }
+    // A reserved (vxil-COGS) credit_type must NEVER appear in a ledger grant map:
+    // the webhook/subscription reducers would otherwise credit `fn_cpu_ms` to a
+    // user, running vxil-billed functions for free (audit F2). Rejected at write
+    // time so the tenant gets a clear `vxil push` error, not a silent runtime skip.
+    const ledgerErrs: string[] = [];
+    for (const [productId, rule] of Object.entries(v.ledger?.productMap ?? {})) {
+      if (rule.creditType && isReservedCreditType(rule.creditType)) {
+        ledgerErrs.push(
+          `/ledger/productMap/${productId}/creditType: '${rule.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`,
+        );
+      }
+    }
+    for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
+      (rule.grants ?? []).forEach((g, i) => {
+        if (g.creditType && isReservedCreditType(g.creditType)) {
+          ledgerErrs.push(
+            `/ledger/tierMap/${tier}/grants/${i}/creditType: '${g.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`,
+          );
+        }
+      });
+    }
+    // Money-path wave F1-3 (D3): an UNMAPPED price silently revoked a paying
+    // customer (priceMap miss → tier NULL → refold excluded the row). The
+    // reducer now stamps such an event outcome 'error' (reprocessable), and
+    // this lint catches the config half at `vxil push` time: every priceMap
+    // value must be a tierMap key, and explicitly-declared tier ranks must be
+    // unique (two tiers at the same rank make the multi-sub fold's winner
+    // order-dependent). Omitted ranks (default 0) are NOT checked — rejecting
+    // rank-less legacy configs on push would break existing tenants.
+    const tierKeys = new Set(Object.keys(v.ledger?.tierMap ?? {}));
+    for (const [priceRef, tier] of Object.entries(v.ledger?.priceMap ?? {})) {
+      if (!tierKeys.has(tier)) {
+        ledgerErrs.push(
+          `/ledger/priceMap/${priceRef}: '${tier}' is not a tierMap key (a webhook for this price would fold to an unknown tier)`,
+        );
+      }
+    }
+    const rankOwner = new Map<number, string>();
+    for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
+      if (typeof rule.rank !== 'number') continue;
+      const prior = rankOwner.get(rule.rank);
+      if (prior !== undefined) {
+        ledgerErrs.push(
+          `/ledger/tierMap/${tier}/rank: rank ${rule.rank} is already used by tier '${prior}' (tier ranks must be unique)`,
+        );
+      } else {
+        rankOwner.set(rule.rank, tier);
+      }
+    }
+    if (ledgerErrs.length) return { ok: false, errors: ledgerErrs.slice(0, 10) };
   }
   // Cross-field rule: CMS lifecycle hooks. Each hook's expression is parsed and
   // AST-validated against the closed sandbox allow-list HERE, at config-write
@@ -1475,6 +1870,16 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
       if (urlErr) return { ok: false, errors: [`/providers/compat/openaiBaseUrl: ${urlErr}`] };
     }
   }
+  // Cross-field rule: auth otp.testRecipients (F4-29) — every entry must be an
+  // email, an `*@domain` glob, or a +E.164 number; anything else would never
+  // match and silently do nothing.
+  if (feature === 'auth') {
+    const v = withDefaults as { otp?: { testRecipients?: string[] } };
+    const bad = (v.otp?.testRecipients ?? []).filter((e) => !isTestRecipientPattern(e));
+    if (bad.length) {
+      return { ok: false, errors: bad.slice(0, 10).map((e) => `/otp/testRecipients: '${e}' is not an email, an *@domain glob, or a +E.164 number`) };
+    }
+  }
   // Cross-field rule: functions. Reject privilege-escalating scopes and malformed
   // bindings at config-write time (the deploy pipeline additionally asserts the
   // scriptRef sha is uploaded + clamps scopes via DENY_FUNCTION_SCOPES). Bindings
@@ -1503,10 +1908,10 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         if (b.kind === 'cmsHook' && !b.collection) {
           errs.push(`/functions/${name}/bindings/${i}: a 'cmsHook' binding needs a collection`);
         }
-        // authHook: 'user.created' is the only event today — reject typos at
-        // write time so a binding never silently subscribes to nothing.
-        if (b.kind === 'authHook' && b.event !== undefined && b.event !== 'user.created') {
-          errs.push(`/functions/${name}/bindings/${i}: an 'authHook' binding's event must be 'user.created' (or omitted)`);
+        // authHook: a CLOSED event union (F4-30) — reject typos at write time
+        // so a binding never silently subscribes to nothing.
+        if (b.kind === 'authHook' && b.event !== undefined && !(AUTH_HOOK_EVENTS as readonly string[]).includes(b.event)) {
+          errs.push(`/functions/${name}/bindings/${i}: an 'authHook' binding's event must be one of ${AUTH_HOOK_EVENTS.join(' | ')} (or omitted = user.created)`);
         }
       });
       // Manifest-bloat guard: the signature is opaque DATA carried inside the
@@ -1528,7 +1933,6 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         actions?: { mode?: string; allow?: Record<string, unknown> };
         guardrails?: { allowGuest?: boolean; guestToolAllow?: string[] };
       }>;
-      escalation?: { handler?: string; notifyTemplate?: string };
       widget?: { requireAuth?: boolean };
     };
     const errs: string[] = [];
@@ -1563,10 +1967,154 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     if (v.widget?.requireAuth === false && !anyGuestAgent) {
       errs.push('/widget/requireAuth: false requires at least one agent with guardrails.allowGuest: true');
     }
-    if (v.escalation?.handler === 'notifications' && !v.escalation.notifyTemplate) {
-      errs.push("/escalation/notifyTemplate: required when handler is 'notifications'");
-    }
     if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
   }
   return { ok: true, errors: [], value: withDefaults };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PLANNER GROUNDING (roadmap §4.6.E; docs/ai-planner-design.md §2).
+// FEATURE_KEYS is the literal feature list the planner catalog is projected
+// from; the planner-catalog CI gate asserts set-equality with
+// Object.keys(FEATURE_SCHEMAS), so adding a feature without extending this
+// list (and FEATURE_HINTS below — a tsc error via the Record key-closure)
+// turns the gate red. Coverage is derived-and-gated; intent (whenToUse) is
+// human-authored but gated-for-presence.
+// ─────────────────────────────────────────────────────────────────────────────
+export const FEATURE_KEYS = [
+  'notifications', 'jobs', 'auth', 'rate-limits', 'files', 'webhooks',
+  'comments', 'cms', 'mcp', 'realtime', 'presence', 'orgs', 'activity-feed',
+  'vector-search', 'ai', 'rag', 'payments', 'functions', 'copilot',
+] as const;
+export type FeatureKey = (typeof FEATURE_KEYS)[number];
+
+/** The hand-authored "when to use" intent a machine schema cannot convey.
+ *  REQUIRED for every feature (Record key-closure): a feature added to
+ *  FEATURE_KEYS without a hint is a compile error naming the missing key. */
+export interface PlannerHint {
+  /** One or two sentences: when an app needs this feature. */
+  whenToUse: string;
+  /** Soft priors — words/needs that suggest the feature (NOT a matcher). */
+  signals: string[];
+  /** When NOT to pick it (disambiguation vs neighbors). */
+  notFor: string;
+  /** Features that must be enabled alongside (runtime substrate deps). */
+  dependsOn: FeatureKey[];
+}
+
+export const FEATURE_HINTS: Record<FeatureKey, PlannerHint> = {
+  notifications: {
+    whenToUse: 'Sending email (transactional or broadcast) or in-app inbox messages to end-users: welcomes, receipts, reminders, alerts, digests.',
+    signals: ['email', 'notify', 'alert', 'reminder', 'welcome', 'receipt', 'digest', 'inbox'],
+    notFor: 'Live in-page updates (realtime) or activity timelines (activity-feed).',
+    dependsOn: [],
+  },
+  jobs: {
+    whenToUse: 'Background work: scheduled/cron tasks, delayed sends, retries, queues, long-running or periodic processing, durable multi-step waits.',
+    signals: ['schedule', 'cron', 'daily', 'background', 'queue', 'later', 'recurring', 'batch'],
+    notFor: 'Simple request-response logic that completes inline.',
+    dependsOn: [],
+  },
+  auth: {
+    whenToUse: 'End-users sign in/up to the app: passwords, magic links, OTP, social login, sessions. Almost every app with per-user data wants it.',
+    signals: ['sign in', 'login', 'account', 'register', 'user', 'password', 'profile', 'member', 'seller', 'buyer'],
+    notFor: 'Pure-public read-only content with no user state.',
+    dependsOn: [],
+  },
+  'rate-limits': {
+    whenToUse: 'Throttling abuse-prone or costly operations: public forms, expensive endpoints, per-user quotas.',
+    signals: ['rate limit', 'throttle', 'abuse', 'quota', 'spam'],
+    notFor: 'General correctness — the platform already meters requests globally.',
+    dependsOn: [],
+  },
+  files: {
+    whenToUse: 'End-users upload or download files/images/documents: avatars, attachments, photos, PDFs, media libraries.',
+    signals: ['upload', 'image', 'photo', 'file', 'attachment', 'document', 'avatar', 'media'],
+    notFor: 'Structured records (cms) or text content authored in-app.',
+    dependsOn: [],
+  },
+  webhooks: {
+    whenToUse: 'Receiving events FROM external services (Stripe/GitHub/etc. callbacks) or fanning tenant events out TO external URLs.',
+    signals: ['webhook', 'callback', 'external event', 'integration', 'sync with'],
+    notFor: 'In-app eventing between vxil features (the audit bus covers that).',
+    dependsOn: ['jobs'],
+  },
+  comments: {
+    whenToUse: 'Threaded discussion, reviews, replies, or reactions attached to any topic/record; also direct messages between users.',
+    signals: ['comment', 'review', 'discussion', 'reply', 'thread', 'DM', 'message'],
+    notFor: 'A social following timeline (activity-feed) or live chat transport (realtime).',
+    dependsOn: [],
+  },
+  cms: {
+    whenToUse: 'The data spine: typed record collections with fields, relations, owner-scoping, draft/publish, and optional keyless public reads. Most apps are, underneath, cms collections.',
+    signals: ['store', 'list', 'catalog', 'posts', 'products', 'records', 'items', 'content', 'blog', 'tasks', 'listings'],
+    notFor: 'End-user identity (auth) or file bytes (files).',
+    dependsOn: [],
+  },
+  mcp: {
+    whenToUse: 'Exposing the tenant backend as typed tools an AI agent drives (Claude/Cursor etc.).',
+    signals: ['agent', 'MCP', 'AI tools', 'tool-calling'],
+    notFor: 'In-app AI text generation (ai) or chat over documents (rag).',
+    dependsOn: [],
+  },
+  realtime: {
+    whenToUse: 'Live in-page updates over channels: chat rooms, live boards, collaborative views, instant refresh when data changes.',
+    signals: ['live', 'realtime', 'chat', 'instantly', 'websocket', 'multiplayer'],
+    notFor: 'Email/inbox notifications (notifications) or historical timelines (activity-feed).',
+    dependsOn: [],
+  },
+  presence: {
+    whenToUse: 'Showing who is online/typing/active on a channel right now.',
+    signals: ['online', 'who is here', 'typing', 'active users', 'presence'],
+    notFor: 'Message delivery itself (realtime carries the messages).',
+    dependsOn: ['realtime'],
+  },
+  orgs: {
+    whenToUse: 'End-users grouped into teams/workspaces with roles and per-resource permissions (multi-member accounts, RBAC).',
+    signals: ['team', 'workspace', 'organization', 'role', 'invite member', 'permission'],
+    notFor: 'Simple per-user ownership (cms ownerField covers that without orgs).',
+    dependsOn: ['auth'],
+  },
+  'activity-feed': {
+    whenToUse: 'Social timelines: follow/unfollow, personal feeds, notification feeds of who-did-what.',
+    signals: ['feed', 'timeline', 'follow', 'social', 'activity', 'news feed'],
+    notFor: 'Live transport (realtime) or email (notifications).',
+    dependsOn: [],
+  },
+  'vector-search': {
+    whenToUse: 'Semantic/similarity search over content: find-similar, meaning-based search boxes.',
+    signals: ['search', 'semantic', 'similar', 'find by meaning'],
+    notFor: 'Exact filters/sorts over records (the cms query DSL covers those).',
+    dependsOn: [],
+  },
+  ai: {
+    whenToUse: 'Calling LLMs from the app: generate/summarize/classify text, prompt templates, streaming completions (BYO provider key).',
+    signals: ['generate', 'summarize', 'AI', 'GPT', 'classify', 'rewrite', 'draft'],
+    notFor: 'Answers grounded in the tenant’s own documents (rag) or an embedded agent (copilot).',
+    dependsOn: [],
+  },
+  rag: {
+    whenToUse: 'Question-answering grounded in the tenant’s own content with citations: “ask your docs/notes/knowledge base”.',
+    signals: ['ask questions', 'chatbot over', 'knowledge base', 'Q&A', 'answers from documents'],
+    notFor: 'Free-form generation with no grounding (ai).',
+    dependsOn: ['vector-search', 'ai', 'files'],
+  },
+  payments: {
+    whenToUse: 'A payments integration: the tenant connects their OWN Stripe/Paddle/PayPal/RevenueCat account for checkout sessions, subscriptions, entitlements, and usage credits. Funds never touch vxil.',
+    signals: ['pay', 'subscription', 'checkout', 'billing', 'sale', 'order', 'price', 'monetize', 'credits'],
+    notFor: 'Anything implying vxil processes money — it is an integration with the tenant’s own provider.',
+    dependsOn: [],
+  },
+  functions: {
+    whenToUse: 'ONLY for truly-unique server logic no feature or cms rule can express: bespoke sagas, custom integrations over the egress guard, computed endpoints. Prefer features/cms first; functions are the escape hatch.',
+    signals: ['custom logic', 'custom backend', 'integration with', 'workflow', 'saga'],
+    notFor: 'Anything a shipped feature or a cms lifecycle hook already covers.',
+    dependsOn: [],
+  },
+  copilot: {
+    whenToUse: 'An embeddable in-app AI assistant that retrieves tenant content and proposes/confirms actions against the tenant’s own API.',
+    signals: ['assistant', 'copilot', 'in-app AI helper', 'agent widget'],
+    notFor: 'Plain text generation (ai) or doc Q&A without actions (rag).',
+    dependsOn: ['ai', 'vector-search', 'rag', 'mcp'],
+  },
+};