@vxil/feature-configs 0.2.0 → 0.3.1

package/dist/index.js

@@ -33,6 +33,84 @@ export const RESERVED_CREDIT_TYPES = new Set(['fn_cpu_ms']);
 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' }),
@@ -73,7 +151,29 @@ export const NotificationsConfigSchema = 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
@@ -168,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
@@ -195,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
@@ -204,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 }),
@@ -223,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({
@@ -242,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 }),
@@ -252,7 +441,10 @@ 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({
@@ -260,16 +452,16 @@ 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 }),
     }, { 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 }),
@@ -344,7 +536,7 @@ export const CmsConfigSchema = Type.Object({
         maxExpandFields: Type.Integer({ default: 5, minimum: 1, maximum: 25 }),
         maxComputedFieldsPerCollection: Type.Integer({ default: 10, minimum: 1, maximum: 50 }),
     }, { 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`
@@ -407,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' }),
@@ -499,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: {} }),
@@ -509,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
@@ -710,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(),
@@ -722,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 }),
@@ -754,8 +960,31 @@ 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 the managed serverless runtime. The FUNCTION owns its identity (bundle via
@@ -767,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
@@ -811,9 +1044,9 @@ export const FunctionsConfigSchema = Type.Object({
             collection: Type.Optional(Type.String()), // cmsHook: the CMS collection slug
             event: Type.Optional(Type.String()), // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
         }), { 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({
             cpuMs: Type.Integer(),
@@ -831,7 +1064,7 @@ export const FunctionsConfigSchema = Type.Object({
         })),
     }))),
 });
-// 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,
@@ -895,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({
@@ -940,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) {
@@ -1053,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
@@ -1086,6 +1352,32 @@ export function validateFeatureConfig(feature, raw) {
                 }
             });
         }
+        // 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) };
     }
@@ -1170,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
@@ -1194,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
@@ -1209,7 +1511,7 @@ export function validateFeatureConfig(feature, raw) {
         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
@@ -1249,16 +1551,13 @@ 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).
+// 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

package/dist/readmodels.js

@@ -1,4 +1,4 @@
-// cms-rel B5/E config-write gates (docs/cms-relational-depth-options.md §3/§4)
+// cms-rel B5/E config-write gates (read models + transactions — https://vxil.com/docs/guide/04-data-with-cms)
 // — the hooks.ts sibling: PURE structural validation of the `readModels` and
 // `cdc` bags at config-write time (the anti-malice-gate pattern). The grammar
 // (fn/rank allow-lists, arity caps, window bounds, dotted-term shape) is

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.2.0",
-  "description": "TypeBox config schemas for every vxil feature — the typed manifests vxil.config.ts is built on. INTERNAL workspace package: bundled into the published `vxil` package (via @vxil/config), not published separately.",
+  "version": "0.3.1",
+  "description": "The per-feature configuration schemas and validators behind vxil.config.ts (published for @vxil/cli and @vxil/config).",
   "license": "MIT",
   "homepage": "https://vxil.com",
   "repository": {