@vxil/feature-configs 0.2.0 → 0.3.1

package/src/hooks.ts

@@ -1,4 +1,4 @@
-// CMS lifecycle hooks — the SAFE expression engine (docs/cms-lifecycle-hooks-rung2-design.md, Lane A).
+// CMS lifecycle hooks — the SAFE expression engine (https://vxil.com/docs/guide/07-validation-and-hooks).
 //
 // A "code-based" lifecycle hook is a small EXPRESSION the tenant authors. Three kinds:
 //   - validate: the expression must evaluate truthy or the write is REJECTED (422)
@@ -17,8 +17,8 @@
 // CROSS-ROW AGGREGATION STAYS OUT — BY DESIGN. Read hooks are a pure function
 // of ONE row (+ `now`): there are no new root variables, no array/aggregate
 // functions, no access to sibling rows or other collections. Counts/sums/
-// group-bys across rows are the §5 identity-fork anti-item (docs/features/
-// cms.md §6.7) and must never enter this engine.
+// group-bys across rows are the identity-fork anti-item (function territory:
+// vxil.com/docs/guide/07-validation-and-hooks) and must never enter this engine.
 //
 // SAFETY (the "not malicious" guarantee) is structural, not heuristic:
 //   * No JS is executed. `eval`/`Function`/the host runtime are never touched. The
@@ -63,7 +63,7 @@ export const HOOK_LIMITS = {
 
 // ── allow-lists ─────────────────────────────────────────────────────────────
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
  *  populated ONLY on the READ path (runReadHooks); on the write path and in
  *  server-caller mode it is null, exactly like `before` on a create. It carries
  *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`

package/src/index.test.ts

@@ -10,6 +10,8 @@ import {
   isReservedCreditType,
   setKnownMcpTools,
   validateFeatureConfig,
+  NOTIF_OVERRIDE_MAX_BYTES, NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE,
+  validateNotificationOverrides,
 } from './index.js';
 // The LIVE mcp catalog (zero-import pure data) — the same relative-import
 // convention as packages/cli/src/mcp.ts. Test-only: the publish build
@@ -40,19 +42,45 @@ describe('15-flag cap analyzer (architecture §6)', () => {
     }
   });
 
-  it('auth schema sits AT the cap (optional bags = 1 leaf each)', () => {
-    // enabled(1) + methods(6) + providers(1) + session(1) + password(1)
-    // + emailVerification(1) + magicLink(1) + otp(1) + anonymous(1)
-    // + orgClaims(1) = 15. The OTP/anonymous/orgClaims wave funded itself by
-    // collapsing session/password to optional bags and dropping the
-    // consumer-less emailVerification.tokenTtlHours (same precedent as the
-    // dropped `redirects` block). The cap check is `>`, so 15 passes.
-    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(15);
+  it('auth schema is 11 leaves after D3 (methods collapsed to ONE optional bag; was 15 at the cap)', () => {
+    // enabled(1) + methods(1, optional bag — was 6) + providers(1) + session(1)
+    // + password(1) + emailVerification(1) + magicLink(1) + otp(1) + anonymous(1)
+    // + orgClaims(1) + security(1, optional bag — P0-3) = 11. The auth wave
+    // (2026-09-10, D3) funded itself by the methods collapse — the notifications
+    // retry/broadcast precedent; session.maxConcurrent / otp.testRecipients ride
+    // inside existing bags and never move the count.
+    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(11);
     expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
   });
 
-  it('files schema is 14 leaves after the ttl/extractText optional bags', () => {
-    expect(countLeaves(FEATURE_SCHEMAS['files']!)).toBe(14);
+  it('D3 fold bytes: existing auth manifests fold BYTE-IDENTICALLY after the methods collapse', () => {
+    // The three inputs below were folded through the PRE-collapse schema
+    // (methods = a required Type.Object with { default: {} }) and the exact
+    // JSON captured; the collapse keeps `default: {}` on the now-Optional bag,
+    // so Value.Default still materializes every method flag in the same key
+    // order with the same defaults. Any drift here = a behavioural delta for a
+    // published tenant manifest (the worker reads config.methods.<flag>).
+    const CASES: Array<[unknown, string]> = [
+      [{},
+        '{"enabled":true,"methods":{"emailPassword":true,"magicLink":true,"google":false,"github":false,"apple":false,"facebook":false},"session":{"ttlMinutes":60,"refreshTtlDays":30},"password":{"minLength":8,"requireMixed":false},"emailVerification":{"required":false},"magicLink":{"tokenTtlMinutes":15}}'],
+      [{ methods: { google: true, github: true }, providers: { google: { clientIdRef: 'secret:g_id', clientSecretRef: 'secret:g_sec' } } },
+        '{"methods":{"google":true,"github":true,"emailPassword":true,"magicLink":true,"apple":false,"facebook":false},"providers":{"google":{"clientIdRef":"secret:g_id","clientSecretRef":"secret:g_sec"}},"enabled":true,"session":{"ttlMinutes":60,"refreshTtlDays":30},"password":{"minLength":8,"requireMixed":false},"emailVerification":{"required":false},"magicLink":{"tokenTtlMinutes":15}}'],
+      [{ enabled: true, methods: { emailPassword: false, magicLink: true, apple: true, facebook: false }, session: { ttlMinutes: 120 }, password: { minLength: 12, requireMixed: true }, emailVerification: { required: true }, magicLink: { tokenTtlMinutes: 30 }, otp: { enabled: true, maxAttempts: 7 }, anonymous: { enabled: true }, orgClaims: { enabled: true } },
+        '{"enabled":true,"methods":{"emailPassword":false,"magicLink":true,"apple":true,"facebook":false,"google":false,"github":false},"session":{"ttlMinutes":120,"refreshTtlDays":30},"password":{"minLength":12,"requireMixed":true},"emailVerification":{"required":true},"magicLink":{"tokenTtlMinutes":30},"otp":{"enabled":true,"maxAttempts":7,"codeTtlMinutes":10,"resendCooldownSec":60},"anonymous":{"enabled":true},"orgClaims":{"enabled":true}}'],
+    ];
+    for (const [input, expected] of CASES) {
+      const v = validateFeatureConfig('auth', input);
+      expect(v.ok, v.errors.join()).toBe(true);
+      expect(JSON.stringify(v.value)).toBe(expected);
+    }
+    // a manifest that omits methods entirely still folds to the full flag set
+    // (the worker never sees an absent bag on a published manifest)
+    const m = (validateFeatureConfig('auth', { enabled: true }).value as { methods: Record<string, boolean> }).methods;
+    expect(m).toEqual({ emailPassword: true, magicLink: true, google: false, github: false, apple: false, facebook: false });
+  });
+
+  it('files schema is 11 leaves (F8-54 removed bucketRef + the contentScan bag)', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['files']!)).toBe(11);
     expect(countLeaves(FEATURE_SCHEMAS['files']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
   });
 
@@ -372,6 +400,29 @@ describe('validateFeatureConfig', () => {
     expect(bare.value).not.toHaveProperty('orgClaims');
   });
 
+  it('auth: RB-2 providers.oidc round-trips, spends NO leaf, and rejects a bad issuer', () => {
+    const oidc = {
+      issuer: 'https://login.acme.example', clientId: 'acme', clientSecretRef: 'secret:oidc_client_secret',
+      scopes: ['openid', 'groups'], claims: { roles: 'groups' }, allowedDomains: ['acme.example'], autoLink: false,
+    };
+    const r = validateFeatureConfig('auth', { providers: { oidc } });
+    expect(r.ok, r.errors.join()).toBe(true);
+    expect((r.value as { providers: { oidc: unknown } }).providers.oidc).toEqual(oidc);
+    // the minimal block (presence = enabled) also round-trips, with NO defaults materialized
+    const min = validateFeatureConfig('auth', { providers: { oidc: { issuer: 'https://login.acme.example', clientId: 'a', clientSecretRef: 'secret:s' } } });
+    expect(min.ok).toBe(true);
+    expect((min.value as { providers: { oidc: Record<string, unknown> } }).providers.oidc).toEqual({ issuer: 'https://login.acme.example', clientId: 'a', clientSecretRef: 'secret:s' });
+    // still 11 leaves — the block lives INSIDE the providers bag
+    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(11);
+    // issuer must be https with no query/fragment; domains lowercase dotted
+    for (const issuer of ['http://login.acme.example', 'https://login.acme.example/?x=1', 'https://a#b', 'login.acme.example']) {
+      expect(validateFeatureConfig('auth', { providers: { oidc: { issuer, clientId: 'a', clientSecretRef: 'secret:s' } } }).ok, issuer).toBe(false);
+    }
+    expect(validateFeatureConfig('auth', { providers: { oidc: { ...oidc, allowedDomains: ['ACME.example'] } } }).ok).toBe(false);
+    // a missing required field fails the pipeline (the worker would 501 anyway)
+    expect(validateFeatureConfig('auth', { providers: { oidc: { issuer: 'https://login.acme.example', clientId: 'a' } } }).ok).toBe(false);
+  });
+
   it('auth: otp knob bounds are enforced (maxAttempts 3..10)', () => {
     expect(validateFeatureConfig('auth', { otp: { enabled: true, maxAttempts: 2 } }).ok).toBe(false);
     expect(validateFeatureConfig('auth', { otp: { enabled: true, maxAttempts: 11 } }).ok).toBe(false);
@@ -386,9 +437,13 @@ describe('validateFeatureConfig', () => {
     expect(okCfg.ok).toBe(true);
     const explicit = validateFeatureConfig('functions', fn([{ kind: 'authHook', event: 'user.created' }]));
     expect(explicit.ok).toBe(true);
+    // F4-30: the CLOSED event union — every member accepted, anything else rejected
+    for (const event of ['session.created', 'session.revoked', 'signin.failure']) {
+      expect(validateFeatureConfig('functions', fn([{ kind: 'authHook', event }])).ok, event).toBe(true);
+    }
     const bad = validateFeatureConfig('functions', fn([{ kind: 'authHook', event: 'user.deleted' }]));
     expect(bad.ok).toBe(false);
-    expect(bad.errors.join(' ')).toContain("must be 'user.created'");
+    expect(bad.errors.join(' ')).toContain('user.created | session.created | session.revoked | signin.failure');
   });
 
   it('functions: DENY_FUNCTION_SCOPES rejects cross-tenant/self-integrity scopes but ALLOWS business scopes', () => {
@@ -449,8 +504,8 @@ describe('validateFeatureConfig', () => {
 });
 
 describe('mcp config: custom tools + prompts (mcp.md §6.5/§11)', () => {
-  it('McpConfigSchema stays at 9 leaves (customTools/prompts are ONE Record leaf each)', () => {
-    expect(countLeaves(FEATURE_SCHEMAS['mcp']!)).toBe(9);
+  it('McpConfigSchema is 8 leaves (customTools/prompts are ONE Record leaf each; F8-54 removed scopedKey)', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['mcp']!)).toBe(8);
     expect(countLeaves(FEATURE_SCHEMAS['mcp']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
   });
 
@@ -563,8 +618,8 @@ describe('mcp config: custom tools + prompts (mcp.md §6.5/§11)', () => {
 });
 
 describe('copilot config (docs/copilot-agents-sku-design.md §4)', () => {
-  it('has exactly 9 leaves — under the cap (agents/allow/collections are DATA)', () => {
-    expect(countLeaves(CopilotConfigSchema)).toBe(9);
+  it('has exactly 7 leaves — under the cap (agents/allow/collections are DATA)', () => {
+    expect(countLeaves(CopilotConfigSchema)).toBe(7);
     expect(countLeaves(CopilotConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
   });
 
@@ -649,19 +704,27 @@ describe('copilot config (docs/copilot-agents-sku-design.md §4)', () => {
     expect(good.ok).toBe(true);
   });
 
-  it("escalation.handler 'notifications' requires notifyTemplate", () => {
-    const bad = validateFeatureConfig('copilot', {
-      agents: {},
-      escalation: { enabled: true, handler: 'notifications' },
-    });
-    expect(bad.ok).toBe(false);
-    expect(bad.errors.join(' ')).toContain('notifyTemplate');
+  it('the inert escalation bag + limits.tokensPerUserPerDay are GONE (F8-54)', () => {
+    const props = (CopilotConfigSchema as unknown as { properties: Record<string, unknown> }).properties;
+    expect(props['escalation']).toBeUndefined();
+    const limits = props['limits'] as { properties: Record<string, unknown> };
+    expect(limits.properties['tokensPerUserPerDay']).toBeUndefined();
+    expect(limits.properties['consumeCredits']).toBeDefined(); // the READ leaf stays
+  });
 
-    const good = validateFeatureConfig('copilot', {
+  it('a PERSISTED manifest carrying the deleted copilot keys still folds (F8-54)', () => {
+    // The pre-F8-54 shape a live tenant may still have in config_versions/KV.
+    const r = validateFeatureConfig('copilot', {
+      enabled: true,
       agents: {},
       escalation: { enabled: true, handler: 'notifications', notifyTemplate: 'escalation' },
+      limits: { consumeCredits: true, tokensPerUserPerDay: 5000 },
     });
-    expect(good.ok).toBe(true);
+    expect(r.ok).toBe(true); // Value.Clean strips the unknown keys — never a 422
+    const v = r.value as { escalation?: unknown; limits: Record<string, unknown> };
+    expect(v.escalation).toBeUndefined();
+    expect(v.limits['tokensPerUserPerDay']).toBeUndefined();
+    expect(v.limits['consumeCredits']).toBe(true); // the surviving leaf is untouched
   });
 });
 
@@ -691,8 +754,8 @@ describe('functions config — signature (Level-1 typed I/O)', () => {
     expect(r.errors.join(' ')).toContain('/functions/hello/signature');
   });
 
-  it('functions schema stays at 7 leaves (signature is DATA in the map)', () => {
-    expect(countLeaves(FEATURE_SCHEMAS['functions']!)).toBe(7);
+  it('functions schema is 4 leaves (signature is DATA in the map; F8-54 removed runtime + 2 defaultLimits)', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['functions']!)).toBe(4);
   });
 });
 
@@ -868,3 +931,325 @@ describe('payments: reserved credit_type rejected in ledger grant maps (F2)', ()
     expect(countLeaves(PaymentsConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
   });
 });
+
+// ── payments: money-path wave (F1-3 config lint, F1-4 acceptSandbox, F1-7 grace,
+//    F3-19 forwardToTenantUrl deleted) ─────────────────────────────────────────
+describe('payments: priceMap ⊆ tierMap + unique ranks (F1-3 / D3 config lint)', () => {
+  const base = {
+    tierMap: {
+      free: { entitlements: [], quotas: {}, rank: 0 },
+      pro: { entitlements: ['pro'], quotas: {}, rank: 10 },
+    },
+    productMap: {},
+  };
+
+  it('rejects a priceMap value that is not a tierMap key', () => {
+    const v = validateFeatureConfig('payments', {
+      ledger: { ...base, priceMap: { price_pro_monthly: 'pro', price_team: 'team' } },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.some((e) => e.includes('/ledger/priceMap/price_team') && e.includes("'team'"))).toBe(true);
+  });
+
+  it('accepts a priceMap whose every value is a tierMap key', () => {
+    const v = validateFeatureConfig('payments', {
+      ledger: { ...base, priceMap: { price_pro_monthly: 'pro', price_pro_yearly: 'pro' } },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+  });
+
+  it('rejects two tiers declaring the SAME rank (fold winner would be order-dependent)', () => {
+    const v = validateFeatureConfig('payments', {
+      ledger: {
+        productMap: {},
+        tierMap: {
+          pro: { entitlements: ['pro'], quotas: {}, rank: 10 },
+          team: { entitlements: ['team'], quotas: {}, rank: 10 },
+        },
+      },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.some((e) => e.includes('/ledger/tierMap/team/rank') && e.includes('already used'))).toBe(true);
+  });
+
+  it('does NOT reject rank-less tiers (legacy configs keep pushing)', () => {
+    const v = validateFeatureConfig('payments', {
+      ledger: {
+        productMap: {},
+        tierMap: {
+          pro: { entitlements: ['pro'], quotas: {} },
+          team: { entitlements: ['team'], quotas: {} },
+        },
+      },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+  });
+});
+
+describe('payments: environment + grace knobs live INSIDE existing bags (leaf budget)', () => {
+  it('revenuecat.acceptSandbox defaults to false inside the revenuecat bag', () => {
+    const v = validateFeatureConfig('payments', {
+      provider: 'revenuecat',
+      revenuecat: { projectId: 'p', publicSdkKey: 'k', secretApiKeyRef: 'secret:rc' },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+    const rc = (v.value as { revenuecat: { acceptSandbox: boolean } }).revenuecat;
+    expect(rc.acceptSandbox).toBe(false);
+  });
+
+  it('ledger.grace.pastDueDays defaults to 0 when the bag is present, is bounded 0..90', () => {
+    const ok = validateFeatureConfig('payments', {
+      ledger: { productMap: {}, tierMap: {}, grace: {} },
+    });
+    expect(ok.ok, ok.errors.join()).toBe(true);
+    expect((ok.value as { ledger: { grace: { pastDueDays: number } } }).ledger.grace.pastDueDays).toBe(0);
+    expect(validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {}, grace: { pastDueDays: 91 } } }).ok).toBe(false);
+    expect(validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {}, grace: { pastDueDays: -1 } } }).ok).toBe(false);
+  });
+
+  it('the inert webhooks.forwardToTenantUrl leaf is GONE (F3-19)', () => {
+    const props = (PaymentsConfigSchema as unknown as { properties: Record<string, unknown> }).properties;
+    expect(props['webhooks']).toBeUndefined();
+    expect(JSON.stringify(PaymentsConfigSchema)).not.toContain('forwardToTenantUrl');
+  });
+
+  it('PaymentsConfig sits at 10 leaves (was 11 — the deleted prices.catalogRef leaf is a net budget gain)', () => {
+    // enabled, provider, stripe?, paddle?, revenuecat?, paypal?, returnUrl,
+    // defaults.currency, defaults.trialDays, ledger? = 10. (grace and
+    // enforcePeriodEnd are bags INSIDE the one optional ledger leaf.)
+    expect(countLeaves(PaymentsConfigSchema)).toBe(10);
+    expect(countLeaves(PaymentsConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('the inert prices.catalogRef leaf is GONE (F8-54) and a persisted manifest carrying it still folds', () => {
+    const props = (PaymentsConfigSchema as unknown as { properties: Record<string, unknown> }).properties;
+    expect(props['prices']).toBeUndefined();
+    expect(JSON.stringify(PaymentsConfigSchema)).not.toContain('catalogRef');
+    // the shipped manifests all carry `prices: { catalogRef: 'default' }` — Value.Clean strips it
+    const v = validateFeatureConfig('payments', { provider: 'mock', prices: { catalogRef: 'default' }, ledger: { productMap: {}, tierMap: {} } });
+    expect(v.ok, v.errors.join()).toBe(true);
+    expect((v.value as Record<string, unknown>).prices).toBeUndefined();
+  });
+
+  it('ledger.enforcePeriodEnd (D2) is an optional bag inside ledger with a 72h default slack, bounded 0..720', () => {
+    const on = validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {}, enforcePeriodEnd: {} } });
+    expect(on.ok).toBe(true);
+    expect((on.value as { ledger: { enforcePeriodEnd: { slackHours: number } } }).ledger.enforcePeriodEnd.slackHours).toBe(72);
+    const off = validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {} } });
+    expect((off.value as { ledger: { enforcePeriodEnd?: unknown } }).ledger.enforcePeriodEnd).toBeUndefined();
+    expect(validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {}, enforcePeriodEnd: { slackHours: 721 } } }).ok).toBe(false);
+  });
+});
+
+// ── notifications D4: per-locale template overrides ─────────────────────────
+describe('notifications: templates.overrides (D4 per-locale overrides)', () => {
+  const base = { fromEmail: 'a@b.test', provider: 'mock' as const };
+  const good = {
+    welcome: {
+      'fr-FR': {
+        subject: 'Bienvenue sur {{app_name}} !',
+        html: '<p>Salut{{first_name_greeting}} — {{app_name}}</p>',
+      },
+    },
+  };
+
+  it('accepts a well-formed override under allowOverride: true', () => {
+    const v = validateFeatureConfig('notifications', {
+      ...base, templates: { allowOverride: true, overrides: good },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+  });
+
+  it('REJECTS overrides when allowOverride is false — never silently inert', () => {
+    const v = validateFeatureConfig('notifications', {
+      ...base, templates: { allowOverride: false, overrides: good },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.join()).toContain('allowOverride');
+  });
+
+  it('rejects an unknown template id', () => {
+    const v = validateFeatureConfig('notifications', {
+      ...base,
+      templates: { allowOverride: true, overrides: { invoice: { 'en-US': { subject: 'x' } } } },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.join()).toContain('unknown template id');
+  });
+
+  it('rejects an unknown placeholder — the typo that would render as an empty string', () => {
+    const v = validateFeatureConfig('notifications', {
+      ...base,
+      templates: {
+        allowOverride: true,
+        overrides: { welcome: { 'fr-FR': { subject: 'Salut {{app_nmae}}' } } },
+      },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.join()).toContain("unknown placeholder '{{app_nmae}}'");
+  });
+
+  it('checks placeholders in html and text too, not just the subject', () => {
+    for (const part of ['html', 'text'] as const) {
+      const v = validateFeatureConfig('notifications', {
+        ...base,
+        templates: {
+          allowOverride: true,
+          overrides: { welcome: { 'fr-FR': { subject: 'ok', [part]: '{{nope}}' } } },
+        },
+      });
+      expect(v.ok, part).toBe(false);
+      expect(v.errors.join()).toContain(`/${part}`);
+    }
+  });
+
+  it('rejects a malformed locale tag', () => {
+    const v = validateFeatureConfig('notifications', {
+      ...base,
+      templates: { allowOverride: true, overrides: { welcome: { fr_FR: { subject: 'x' } } } },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.join()).toContain('BCP-47');
+  });
+
+  it('enforces the per-template locale cap and the whole-map byte cap', () => {
+    const manyLocales: Record<string, { subject: string }> = {};
+    for (let i = 0; i < NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE + 1; i++) {
+      manyLocales[`en-x${i}`] = { subject: 'x' };
+    }
+    const capped = validateFeatureConfig('notifications', {
+      ...base, templates: { allowOverride: true, overrides: { welcome: manyLocales } },
+    });
+    expect(capped.ok).toBe(false);
+    expect(capped.errors.join()).toContain('per-template cap');
+
+    const huge = validateFeatureConfig('notifications', {
+      ...base,
+      templates: {
+        allowOverride: true,
+        overrides: {
+          welcome: {
+            'fr-FR': { subject: 'x', html: 'y'.repeat(19_000), text: 'z'.repeat(19_000) },
+            'de-DE': { subject: 'x', html: 'y'.repeat(19_000), text: 'z'.repeat(19_000) },
+          },
+        },
+      },
+    });
+    expect(huge.ok).toBe(false);
+    expect(huge.errors.join()).toContain(`${NOTIF_OVERRIDE_MAX_BYTES}-byte cap`);
+  });
+
+  it('the pure validator is [] for an absent/empty bag', () => {
+    expect(validateNotificationOverrides(undefined)).toEqual([]);
+    expect(validateNotificationOverrides({ allowOverride: true })).toEqual([]);
+    expect(validateNotificationOverrides({ allowOverride: false, overrides: {} })).toEqual([]);
+  });
+
+  it('a legacy manifest with NO templates bag still validates and still materializes it', () => {
+    const v = validateFeatureConfig('notifications', base);
+    expect(v.ok, v.errors.join()).toBe(true);
+    // `default: {}` survives the Optional collapse — persisted manifests unchanged
+    expect((v.value as { templates: { allowOverride: boolean } }).templates)
+      .toEqual({ allowOverride: false });
+  });
+
+  it('NotificationsConfig stays AT the 15-leaf cap (overrides is a Record inside the ONE templates bag)', () => {
+    expect(countLeaves(NotificationsConfigSchema)).toBe(15);
+    expect(countLeaves(NotificationsConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+});
+
+// ── F8-54: inert declared knobs — wire or delete ─────────────────────────────
+// Six knobs shipped DECLARED but with no enforcing reader (register §8 / §12.4
+// B8); the programmatic sweep (scripts/config-leaf-readers.ts + the
+// tests/ci/src/config-leaf-readers.test.ts gate) found more. These assert the
+// DELETED half: the leaf is gone from the schema, the cap count moved, and a
+// manifest a live tenant already persisted with the old key STILL FOLDS —
+// Value.Clean strips unknown keys, so a deletion can never 422 an existing
+// tenant's next publish.
+describe('F8-54: the deleted inert leaves stay deleted, and old manifests still fold', () => {
+  const props = (schema: unknown): Record<string, unknown> =>
+    (schema as { properties: Record<string, unknown> }).properties;
+
+  it('files: bucketRef + the contentScan bag are gone (11 leaves, was 14)', () => {
+    const p = props(FEATURE_SCHEMAS['files']!);
+    expect(p['bucketRef']).toBeUndefined();
+    expect(p['contentScan']).toBeUndefined();
+    expect(countLeaves(FEATURE_SCHEMAS['files']!)).toBe(11);
+  });
+
+  it('files: a persisted manifest with bucketRef + contentScan still folds', () => {
+    const r = validateFeatureConfig('files', {
+      enabled: true,
+      bucketRef: 'vxil-files',
+      contentScan: { enabled: true, quarantineOnFail: false },
+      uploadUrlTtl: 1800,
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as Record<string, unknown>;
+    expect(v['bucketRef']).toBeUndefined();
+    expect(v['contentScan']).toBeUndefined();
+    expect(v['uploadUrlTtl']).toBe(1800); // the live leaves ride through untouched
+  });
+
+  it('mcp: scopedKey is gone (8 leaves, was 9) and an old manifest folds', () => {
+    expect(props(FEATURE_SCHEMAS['mcp']!)['scopedKey']).toBeUndefined();
+    expect(countLeaves(FEATURE_SCHEMAS['mcp']!)).toBe(8);
+    const r = validateFeatureConfig('mcp', {
+      enabled: true, scopedKey: { perAgentKeys: true }, exposureLevel: 'read-only',
+    });
+    expect(r.ok).toBe(true);
+    expect((r.value as Record<string, unknown>)['scopedKey']).toBeUndefined();
+    expect((r.value as Record<string, unknown>)['exposureLevel']).toBe('read-only');
+  });
+
+  it('activity-feed: the aggregation + rateLimit bags are gone (11 leaves, was 13)', () => {
+    const p = props(FEATURE_SCHEMAS['activity-feed']!);
+    expect(p['aggregation']).toBeUndefined();
+    expect(p['rateLimit']).toBeUndefined();
+    expect(countLeaves(FEATURE_SCHEMAS['activity-feed']!)).toBe(11);
+    const r = validateFeatureConfig('activity-feed', {
+      enabled: true,
+      aggregation: { maxGroupActivities: 30 },
+      rateLimit: { addPerSec: 500 },
+      follow: { copyLimit: 42 },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as Record<string, unknown>;
+    expect(v['aggregation']).toBeUndefined();
+    expect(v['rateLimit']).toBeUndefined();
+    expect((v['follow'] as Record<string, unknown>)['copyLimit']).toBe(42);
+  });
+
+  it('functions: runtime + defaultLimits.{timeoutMs,memoryMb} are gone (4 leaves, was 7)', () => {
+    const p = props(FEATURE_SCHEMAS['functions']!);
+    expect(p['runtime']).toBeUndefined();
+    const dl = props(p['defaultLimits']);
+    expect(dl['timeoutMs']).toBeUndefined();
+    expect(dl['memoryMb']).toBeUndefined();
+    expect(dl['cpuMs']).toBeDefined(); // the ONE enforced limit stays
+    expect(countLeaves(FEATURE_SCHEMAS['functions']!)).toBe(4);
+  });
+
+  it('functions: a persisted manifest with runtime + the dead limits still folds', () => {
+    const r = validateFeatureConfig('functions', {
+      enabled: true,
+      runtime: 'container',
+      defaultLimits: { cpuMs: 120, timeoutMs: 30_000, memoryMb: 512 },
+      metering: { enabled: true },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as Record<string, unknown>;
+    expect(v['runtime']).toBeUndefined();
+    const dl = v['defaultLimits'] as Record<string, unknown>;
+    expect(dl['cpuMs']).toBe(120); // the enforced value survives
+    expect(dl['timeoutMs']).toBeUndefined();
+    expect(dl['memoryMb']).toBeUndefined();
+  });
+
+  it('every surviving schema still fits the cap (the deletions only freed budget)', () => {
+    for (const [feature, schema] of Object.entries(FEATURE_SCHEMAS)) {
+      expect(countLeaves(schema), `${feature} exceeds the flag cap`).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+    }
+  });
+});