@vxil/feature-configs 0.1.1 → 0.3.0

package/dist/index.js

@@ -18,6 +18,99 @@ export * from './readmodels.js';
 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 = new Set(['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) {
+    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 = {
+    '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) {
+    const overrides = templates?.overrides;
+    if (!overrides || Object.keys(overrides).length === 0)
+        return [];
+    const errs = [];
+    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']) {
+                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' }),
@@ -27,27 +120,83 @@ 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')], {
             default: 'exponential',
         }),
-    }, { default: {} }),
+    }, { default: {} })),
     suppression: Type.Object({ softBounceThreshold: Type.Integer({ default: 3 }) }, { default: {} }),
     rateLimit: Type.Object({
         perDay: Type.Integer({ default: 100000 }),
         perTenantSec: Type.Integer({ default: 50 }),
     }, { default: {} }),
-    templates: Type.Object({ allowOverride: Type.Boolean({ default: false }) }, { default: {} }),
+    // `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 }),
+    })),
 });
 export const JobsConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
@@ -119,16 +268,62 @@ 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 }),
         google: Type.Boolean({ default: false }),
         github: Type.Boolean({ default: false }),
         apple: Type.Boolean({ default: false }),
         facebook: Type.Boolean({ default: false }),
-    }, { default: {} }),
+    }, { 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
@@ -146,6 +341,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
@@ -155,6 +352,12 @@ export const AuthConfigSchema = Type.Object({
     session: Type.Optional(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: {} })),
     password: Type.Optional(Type.Object({
         minLength: Type.Integer({ default: 8, minimum: 6, maximum: 128 }),
@@ -174,6 +377,14 @@ 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({
@@ -193,6 +404,33 @@ 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 })),
+    })),
 });
 export const RateLimitsConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
@@ -203,12 +441,15 @@ export const RateLimitsConfigSchema = Type.Object({
 });
 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).
@@ -217,10 +458,10 @@ export const FilesConfigSchema = Type.Object({
         maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
     }, { 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 }),
         maxTtl: Type.Integer({ default: 7 * 24 * 3600 }),
@@ -338,7 +579,7 @@ export const CmsConfigSchema = Type.Object({
         enabled: Type.Optional(Type.Boolean()),
     }))),
     // 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(Type.String({ maxLength: 64 }), Type.Object({
@@ -358,8 +599,10 @@ export const McpConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
     exposureLevel: Type.Union([Type.Literal('all'), Type.Literal('read-only'), Type.Literal('custom')], { 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: {} }),
     branding: Type.Object({
         serverName: Type.String({ default: 'Vxil' }),
@@ -450,9 +693,10 @@ export const ActivityFeedConfigSchema = Type.Object({
         copyLimit: Type.Integer({ default: 100, minimum: 0, maximum: 1000 }), // backfill budget on follow
         maxFollowing: Type.Integer({ default: 10_000, minimum: 0 }), // per-feed following cap
     }, { 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({
         enabled: Type.Boolean({ default: true }), // live new-activity + count push over the realtime ChannelDO
     }, { default: {} }),
@@ -460,9 +704,11 @@ export const ActivityFeedConfigSchema = Type.Object({
         enabled: Type.Boolean({ default: false }), // master gate for the notifications push/email trigger (§10)
         digestCadence: Type.Union([Type.Literal('off'), Type.Literal('hourly'), Type.Literal('daily')], { default: 'off' }), // digest roll-up window (feed owns the roll-up, rides notifications' live single-send)
     }, { 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.
 });
 // vector-search feature (features/vector-search.md §4). Re-declared here to match the
 // schema the worker EXPORTS from workers/vector-search-v1/src/config.ts — the
@@ -473,10 +719,10 @@ export const ActivityFeedConfigSchema = Type.Object({
 // 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([
             Type.Literal('byov'),
@@ -661,6 +907,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(),
@@ -673,8 +926,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' }),
         trialDays: Type.Integer({ default: 0, minimum: 0, maximum: 365 }),
@@ -705,11 +960,34 @@ 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).
 });
 // 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
@@ -718,12 +996,16 @@ export const PaymentsConfigSchema = Type.Object({
 // 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: {} }),
     // Reserve→settle CPU-ms metering into the payments credit ledger (the
     // recover-by-price tier, live-prep "functions metering"). When enabled the
@@ -846,16 +1128,16 @@ export const CopilotConfigSchema = Type.Object({
             guestToolAllow: Type.Optional(Type.Array(Type.String({ maxLength: 64 }), { maxItems: 16, default: [] })),
         })),
     }), { 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) ──────────────────────
     widget: Type.Object({
@@ -891,6 +1173,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'];
+/** 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) {
+    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, entries) {
+    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) {
     const t = schema;
     if (t.type === 'object' && t.properties) {
@@ -1004,6 +1316,9 @@ export function validateFeatureConfig(feature, raw) {
                 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
@@ -1020,6 +1335,51 @@ export function validateFeatureConfig(feature, raw) {
                 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 = [];
+        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();
+        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
@@ -1102,6 +1462,16 @@ export function validateFeatureConfig(feature, raw) {
                 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;
+        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
@@ -1126,10 +1496,10 @@ export function validateFeatureConfig(feature, raw) {
                 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.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
@@ -1181,11 +1551,138 @@ export function validateFeatureConfig(feature, raw) {
         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',
+];
+export const FEATURE_HINTS = {
+    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'],
+    },
+};