@vxil/feature-configs 0.2.0 → 0.3.1

package/src/index.ts

@@ -38,6 +38,91 @@ 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' }),
@@ -87,10 +172,35 @@ 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
@@ -118,8 +228,11 @@ export const NotificationsConfigSchema = Type.Object({
 // Leaves: enabled, fromEmail, fromName, replyTo, resendApiKeyRef,
 // webhookSecretRef, provider, defaultLocale, retry (Optional bag = 1),
 // suppression.softBounceThreshold, rateLimit.perDay, rateLimit.perTenantSec,
-// templates.allowOverride, inboxEnabled, broadcast (Optional bag = 1) → 15.
-// Cap = 15 — AT the cap; the next flag must collapse something.
+// 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). */
@@ -214,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 }),
@@ -227,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
@@ -245,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
@@ -255,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: {} },
   )),
@@ -285,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({
@@ -304,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>;
 
@@ -336,7 +552,10 @@ 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(
@@ -345,7 +564,7 @@ export const FilesConfigSchema = Type.Object({
       // 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).
+      // tenant tier threaded to files-v1 (plan tiers).
       maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
       maxTotalBytes: Type.Integer({ default: 10 * 1024 * 1024 * 1024, minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 }),
       maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
@@ -353,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 }),
@@ -392,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>;
 
@@ -461,7 +678,7 @@ export const CmsConfigSchema = Type.Object({
     },
     { default: {} },
   ),
-  // Code-based lifecycle hooks (docs/cms-lifecycle-hooks-rung2-design.md, Lane A):
+  // Code-based lifecycle hooks (https://vxil.com/docs/guide/07-validation-and-hooks):
   // a tenant-authored SAFE expression. Write events (beforeCreate/beforeUpdate/
   // beforeWrite) run in-transaction — `validate` rejects the write, `derive`
   // computes a persisted field. Read events shape the RESPONSE only: `validate`
@@ -545,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: {} },
@@ -598,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>;
 
@@ -686,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(
     {
@@ -711,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>;
 
@@ -995,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(),
@@ -1007,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' }),
@@ -1044,17 +1265,39 @@ 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>;
 
@@ -1068,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: {} },
   ),
@@ -1126,9 +1373,9 @@ export const FunctionsConfigSchema = Type.Object({
             { maxItems: 8 },
           ),
         ),
-        scriptRef: Type.String(), // content-hashed WfP script name: fn-<tenant>-<name>-<sha>
+        scriptRef: Type.String(), // content-hashed hosted-script name: fn-<tenant>-<name>-<sha>
         scopes: Type.Optional(Type.Array(Type.String())), // clamped via DENY_FUNCTION_SCOPES at deploy (admin/*/features:write/functions:write/secrets:write)
-        secrets: Type.Optional(Type.Array(Type.String())), // tenant_secrets refs (KEK_FUNCTIONS)
+        secrets: Type.Optional(Type.Array(Type.String())), // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
         limits: Type.Optional(
           Type.Object({
@@ -1150,14 +1397,15 @@ 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
+// copilot feature (https://vxil.com/docs/guide/11-copilot-agents). Re-declared to match
 // workers/copilot-v1/src/config.ts's exported CopilotConfigSchema (one shape,
 // two consumers — keep the two definitions byte-identical). A thin COMPOSITION
 // layer over ai + vector-search + rag + mcp: it owns the AGENT layer (persona,
@@ -1239,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) ──────────────────────
@@ -1263,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>;
 
@@ -1298,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;
@@ -1423,13 +1698,22 @@ 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
@@ -1439,7 +1723,8 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
       provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown;
       ledger?: {
         productMap?: Record<string, { creditType?: string }>;
-        tierMap?: Record<string, { grants?: Array<{ creditType?: string }> }>;
+        tierMap?: Record<string, { rank?: number; grants?: Array<{ creditType?: string }> }>;
+        priceMap?: Record<string, string>;
       };
     };
     const needsBlock: Record<string, 'stripe' | 'paddle' | 'revenuecat'> = {
@@ -1473,6 +1758,34 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         }
       });
     }
+    // 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
@@ -1557,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
@@ -1585,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
@@ -1599,7 +1922,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     }
     if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
   }
-  // Cross-field rules: copilot (docs/copilot-agents-sku-design.md §4). Pure
+  // Cross-field rules: copilot (https://vxil.com/docs/guide/11-copilot-agents). Pure
   // rules only — cross-feature resolutions (collection existence, directiveRef
   // → ai.templates) are deferred to runtime, which fails soft with the
   // capability-surface envelope. Tool-NAME existence runs only when the mcp
@@ -1610,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[] = [];
@@ -1645,16 +1967,13 @@ 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).
+// PLANNER GROUNDING (https://vxil.com/docs/guide/10-agents-and-mcp).
 // 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