@vxil/feature-configs 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,58 @@
+# @vxil/feature-configs
+
+The typed config schemas for every Vxil feature — the shapes a `vxil.config.ts`
+is built on, published so your editor and your CI can read the same contract the
+platform validates against.
+
+```bash
+npm i -D @vxil/feature-configs
+```
+
+Most people never import this directly: writing
+[`defineConfig`](https://www.npmjs.com/package/@vxil/config) gives you these
+types automatically. Reach for it when you want to validate a manifest yourself,
+generate config, or type a helper.
+
+## What's in it
+
+- **One schema per feature**, all 19 of them — `NotificationsConfigSchema`,
+  `AuthConfigSchema`, `CmsConfigSchema`, `PaymentsConfigSchema`,
+  `FunctionsConfigSchema`, … — plus the matching `Static<>` types
+  (`NotificationsConfig`, `AuthConfig`, …).
+- **`FEATURE_KEYS`** — the canonical feature list, and **`FEATURE_SCHEMAS`** —
+  the key → schema map.
+- **`validateFeatureConfig(feature, raw)`** — the exact validation the control
+  plane runs, returning `{ ok, errors }` with JSON-pointer-style messages. Use it
+  in a pre-commit hook or a test to fail on a bad config before you push it.
+- **`hooks`** (`@vxil/feature-configs/hooks`) — the CMS lifecycle-hook expression
+  grammar: the same closed, sandboxed parser/validator the server uses, so a
+  malformed `validate` / `derive` expression is caught in your editor.
+
+```ts
+import { validateFeatureConfig, FEATURE_KEYS } from '@vxil/feature-configs';
+
+const result = validateFeatureConfig('notifications', {
+  enabled: true,
+  fromEmail: 'noreply@acme.com',
+});
+if (!result.ok) throw new Error(result.errors.join('\n'));
+```
+
+## Why the schemas are small on purpose
+
+Every feature's config is capped at a fixed number of top-level leaves. A knob
+earns its slot by having a reader; one that nothing reads gets deleted rather
+than left to rot as a promise the product does not keep. That is why the schemas
+here are the whole truth about what a feature can be configured to do — and why
+a version bump may *remove* a knob that was never wired. Removals are listed in
+the feature reference at [vxil.com](https://vxil.com).
+
+## Related
+
+- [`@vxil/config`](https://www.npmjs.com/package/@vxil/config) — `defineConfig()`.
+- [`@vxil/cli`](https://www.npmjs.com/package/@vxil/cli) — the `vxil` command (`plan` / `push` / `gen`).
+- [`@vxil/sdk`](https://www.npmjs.com/package/@vxil/sdk) — the typed runtime client.
+
+Docs: [vxil.com](https://vxil.com) · Dashboard: [vxil.com/dashboard](https://vxil.com/dashboard)
+
+MIT © techmaker.io

package/dist/hooks.d.ts

@@ -10,7 +10,7 @@ export declare const HOOK_LIMITS: {
     readonly maxReadHooksPerCollection: 10;
 };
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (docs/end-user-principals-design.md §5.6) — read-only and
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
  *  populated ONLY on the READ path (runReadHooks); on the write path and in
  *  server-caller mode it is null, exactly like `before` on a create. It carries
  *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`

package/dist/hooks.js

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

package/dist/index.d.ts

@@ -6,6 +6,12 @@ export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
  *  of which is restricted to internal platform machinery). */
 export declare function isReservedCreditType(creditType: string): boolean;
 export declare const NOTIFICATION_TEMPLATE_PLACEHOLDERS: Readonly<Record<string, readonly string[]>>;
+/** Placeholders that are SLOTS in the BODY parts only — the renderer splits
+ * `html`/`text` on them (templates.ts `CTA_SLOT`) but the subject goes through
+ * the plain interpolator, where the same token is just a data key that does not
+ * exist and renders EMPTY. Rejected in `subject` for exactly the reason the
+ * whole allow-list exists: a silent empty render in a live email. */
+export declare const NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS: Readonly<Record<string, readonly string[]>>;
 /** Per-override caps (D4). Bodies are emails, not documents. */
 export declare const NOTIF_OVERRIDE_SUBJECT_MAX = 500;
 export declare const NOTIF_OVERRIDE_BODY_MAX = 20000;
@@ -54,7 +60,7 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
     templates: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         allowOverride: import("@sinclair/typebox").TBoolean;
         overrides: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
-            subject: import("@sinclair/typebox").TString;
+            subject: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             html: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             text: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         }>>>>;
@@ -203,9 +209,11 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
     emailVerification: import("@sinclair/typebox").TObject<{
         required: import("@sinclair/typebox").TBoolean;
     }>;
-    magicLink: import("@sinclair/typebox").TObject<{
+    magicLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         tokenTtlMinutes: import("@sinclair/typebox").TInteger;
-    }>;
+        resendCooldownSec: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    }>>;
+    registryAdopt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     otp: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
         codeTtlMinutes: import("@sinclair/typebox").TInteger;
@@ -275,6 +283,11 @@ export declare const WebhooksConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     maxSubscriptions: import("@sinclair/typebox").TInteger;
     maxSources: import("@sinclair/typebox").TInteger;
+    alerts: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        enabled: import("@sinclair/typebox").TBoolean;
+        minLevel: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"warn">, import("@sinclair/typebox").TLiteral<"error">]>;
+        digestMinutes: import("@sinclair/typebox").TInteger;
+    }>>;
 }>;
 export type WebhooksConfig = Static<typeof WebhooksConfigSchema>;
 export declare const CommentsConfigSchema: import("@sinclair/typebox").TObject<{
@@ -554,6 +567,7 @@ export declare const PaymentsConfigSchema: import("@sinclair/typebox").TObject<{
         enforcePeriodEnd: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
             slackHours: import("@sinclair/typebox").TInteger;
         }>>;
+        unmappedProduct: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"error">, import("@sinclair/typebox").TLiteral<"ignore">]>>;
     }>>;
 }>;
 export type PaymentsConfig = Static<typeof PaymentsConfigSchema>;
@@ -579,9 +593,8 @@ export declare const FunctionsConfigSchema: import("@sinclair/typebox").TObject<
         secrets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         egressAllow: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         limits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            cpuMs: import("@sinclair/typebox").TInteger;
-            timeoutMs: import("@sinclair/typebox").TInteger;
-            memoryMb: import("@sinclair/typebox").TInteger;
+            cpuMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+            timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
         }>>;
         enabled: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
         signature: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{

package/dist/index.js

@@ -44,7 +44,19 @@ 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'],
+    // `cta` (G-78) is a SLOT, not a data key: an override that writes `{{cta}}`
+    // chooses where the escaped CTA anchor built from cta_label + cta_url lands.
+    // Absent from the built-in bodies (which append it), so the worker parity
+    // suite pins it explicitly — see templates.test.ts.
+    transactional: ['subject', 'paragraph', 'cta_label', 'cta_url', 'cta'],
+};
+/** Placeholders that are SLOTS in the BODY parts only — the renderer splits
+ * `html`/`text` on them (templates.ts `CTA_SLOT`) but the subject goes through
+ * the plain interpolator, where the same token is just a data key that does not
+ * exist and renders EMPTY. Rejected in `subject` for exactly the reason the
+ * whole allow-list exists: a silent empty render in a live email. */
+export const NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS = {
+    transactional: ['cta'],
 };
 /** Per-override caps (D4). Bodies are emails, not documents. */
 export const NOTIF_OVERRIDE_SUBJECT_MAX = 500;
@@ -96,14 +108,31 @@ export function validateNotificationOverrides(templates) {
                 continue;
             }
             const variant = byLocale[locale];
+            if (typeof variant !== 'object' || variant === null) {
+                errs.push(`/templates/overrides/${templateId}/${locale}: must be an object with at least one of subject, html, text`);
+                continue;
+            }
+            // G-78 — every part is OPTIONAL (a body-only translation inherits the
+            // built-in subject), but an ALL-EMPTY variant is the new "inert config"
+            // and fails LOUD rather than silently rendering the built-in.
+            const nonEmpty = ['subject', 'html', 'text']
+                .filter((p) => typeof variant[p] === 'string' && variant[p] !== '');
+            if (nonEmpty.length === 0) {
+                errs.push(`/templates/overrides/${templateId}/${locale}: set at least one of subject, html, text`);
+                continue;
+            }
+            // body-only SLOTS are not subject placeholders (see the map's doc comment)
+            const slots = NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS[templateId] ?? [];
+            const subjectAllowed = allowed.filter((k) => !slots.includes(k));
             for (const part of ['subject', 'html', 'text']) {
                 const body = variant[part];
                 if (typeof body !== 'string')
                     continue;
+                const ok = part === 'subject' ? subjectAllowed : allowed;
                 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(', ')})`);
+                    if (!ok.includes(key)) {
+                        errs.push(`/templates/overrides/${templateId}/${locale}/${part}: unknown placeholder '{{${key}}}' (allowed: ${ok.join(', ')})`);
                     }
                 }
             }
@@ -161,15 +190,23 @@ export const NotificationsConfigSchema = 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,
+        // 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 }),
+        overrides: Type.Optional(Type.Record(Type.String(), 
+        // G-78: `subject` is OPTIONAL like html/text — a PARTIAL override
+        // inherits each omitted part from the built-in, so a body-only
+        // translation no longer forces you to restate the subject (and a
+        // subject-only 'ar' override no longer pairs an Arabic subject with the
+        // English built-in body). A strict widening: every config valid before
+        // this change is still valid. validateNotificationOverrides rejects the
+        // one shape this opens up — a variant with NO non-empty part.
+        Type.Record(Type.String(), Type.Object({
+            subject: Type.Optional(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 })),
         })))),
@@ -368,7 +405,35 @@ export const AuthConfigSchema = Type.Object({
     // verify-email token flow it would bound was never built). Same precedent as
     // the removed `redirects` block below. Its leaf funds the OTP wave.
     emailVerification: Type.Object({ required: Type.Boolean({ default: false }) }, { default: {} }),
-    magicLink: Type.Object({ tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }) }, { default: {} }),
+    // P1-16 (2026-09-18): magicLink is now an OPTIONAL bag (= ONE leaf however
+    // many knobs it holds — the methods/session/password precedent) so the
+    // request cooldown could land without spending a second leaf. It KEEPS
+    // `default: {}`, so Value.Default still materializes
+    // `magicLink.tokenTtlMinutes` exactly as before — every persisted manifest
+    // folds byte-identically.
+    magicLink: Type.Optional(Type.Object({
+        tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }),
+        // P1-16: the per-(tenant, identifier) magic-link REQUEST cooldown — the
+        // `otp.resendCooldownSec` twin, same bounds so the two knobs read the
+        // same. A second request for the same address inside the window is a 429
+        // `magic_link_rate_limited` with a Retry-After header. Type.Optional with
+        // NO default (the `otp.testRecipients` precedent below) so existing
+        // manifests fold byte-identically; the 60s fallback is applied by the
+        // auth feature at read time. 0 disables the cooldown.
+        resendCooldownSec: Type.Optional(Type.Integer({ minimum: 0, maximum: 600 })),
+    }, { default: {} })),
+    // P1-5 identity continuity (2026-09-18) — OPT-IN registry adoption. When
+    // true, a sign-in by a method that PROVES control of the address — magic
+    // link, email OTP, or OAuth with a provider-verified address — reuses the id
+    // of the one matching pre-registered end-user (POST /v1/users) that has no
+    // account yet, instead of minting a fresh `user_<ulid>` and leaving the
+    // tenant with two records for one person. Password SIGN-UP never adopts: it
+    // proves nothing about the address (auth.md §8.1 PROVEN_ADOPT_METHODS).
+    // OFF by default, and Type.Optional with NO default: adoption means whoever
+    // proves control of a pre-registered address becomes that record — a change
+    // of security semantics for a tenant that bulk-imports contacts, whose
+    // addresses vxil never verified.
+    registryAdopt: Type.Optional(Type.Boolean()),
     // Email OTP sign-in (roadmap Tier-0) + the knobs step-up re-auth shares.
     // OPTIONAL bag = 1 leaf; absent ⇒ disabled (the worker gates on
     // otp?.enabled === true).
@@ -452,7 +517,7 @@ export const FilesConfigSchema = Type.Object({
         // object storage is cheap but the SQL-database-resident metadata + abuse aren't (pricing re-audit
         // 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
         // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
-        // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
+        // tenant tier threaded to files-v1 (plan tiers).
         maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
         maxTotalBytes: Type.Integer({ default: 10 * 1024 * 1024 * 1024, minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 }),
         maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
@@ -495,6 +560,27 @@ export const WebhooksConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
     maxSubscriptions: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
     maxSources: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
+    // FAILURE-ALERT DIGEST (P0-2). Outbound subscriptions are the real-time
+    // channel; this is the "nobody is consuming them yet" fallback — a periodic
+    // e-mail summary of the tenant's FAILURE-class audit events (the level:
+    // 'failure' rows of the generated event catalog). Read by
+    // workers/control-plane/src/alertDigest.ts on the minute cron.
+    //
+    // RECIPIENTS ARE DELIBERATELY NOT CONFIGURABLE, and this deviation is
+    // journaled here the way RateLimitsConfigSchema journals its own: an
+    // arbitrary `to` would turn vxil's own sending identity into a relay for
+    // tenant-authored content and open a PII egress path out of the audit trail.
+    // The digest goes to the OWNER-role dashboard accounts of the project (cap
+    // 3), who already receive platform mail (invites, magic links, resets), so no
+    // new consent surface is created. An arbitrary recipient is a separate
+    // decision with its own abuse review.
+    //
+    // An Optional object bag counts as ONE leaf (the countLeaves rule).
+    alerts: Type.Optional(Type.Object({
+        enabled: Type.Boolean({ default: false }),
+        minLevel: Type.Union([Type.Literal('warn'), Type.Literal('error')], { default: 'error' }),
+        digestMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 1440 }),
+    })),
 });
 // comments feature (wishlist): threaded discussion on tenant-defined topics.
 export const CommentsConfigSchema = Type.Object({
@@ -536,7 +622,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`
@@ -813,7 +899,7 @@ export const AiConfigSchema = Type.Object({
     cache: Type.Object({ ttlSeconds: Type.Integer({ default: 0, minimum: 0 }) }, { default: {} }), // 0 = off
     limits: Type.Object({
         tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = unlimited
-        consumeCredits: Type.Boolean({ default: false }), // reserve→settle (STUB until payments)
+        consumeCredits: Type.Boolean({ default: false }), // LIVE: reserve→settle against the payments credit ledger (a job-routed generation reserves pre-generation and 402s insufficient_credits)
     }, { default: {} }),
     streaming: Type.Object({
         enabled: Type.Boolean({ default: true }),
@@ -902,10 +988,16 @@ export const PaymentsConfigSchema = Type.Object({
         projectId: Type.String(),
         publicSdkKey: Type.String(),
         secretApiKeyRef: Type.String(),
-        // Optional per-tenant webhook secret ref (public.tenant_secrets). When set,
-        // inbound RevenueCat webhooks are verified with THIS tenant's secret instead
-        // of the platform PROVIDER_WEBHOOK_SECRET — closes the multi-tenant RC
-        // webhook-forgery vector (mirrors stripe/paddle webhookSecretRef).
+        // Per-tenant webhook secret ref (public.tenant_secrets). Inbound RevenueCat
+        // webhooks are verified against THIS ref and nothing else: there is no
+        // platform-wide PROVIDER_WEBHOOK_SECRET fallback for a real payment provider
+        // (that fallback WAS the multi-tenant RC webhook-forgery vector; it is now
+        // frozen out by tests/ci/src/provider-webhook-secret-fallback.test.ts, which
+        // permits `secrets.webhookSecret` only in makeProvider's mock/default arm).
+        // Optional at the SCHEMA level only — leaving it unset does not disable
+        // verification, it fails CLOSED: every delivery is 401 bad_signature with a
+        // `sig_failed` row that can never be reprocessed. 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
@@ -980,6 +1072,29 @@ export const PaymentsConfigSchema = Type.Object({
         enforcePeriodEnd: Type.Optional(Type.Object({
             slackHours: Type.Integer({ default: 72, minimum: 0, maximum: 720 }),
         })),
+        // (2026-09 P2) What to do with a one-off purchase whose `product_id` is NOT
+        // in productMap. 'error' (the DEFAULT and today's behaviour) stamps the
+        // delivery outcome `error`, emits payments.webhook_event.failed and lands a
+        // `stranded_webhook` reconcile finding. 'ignore' stamps it `ignored`, with
+        // no failure event and no stranded finding.
+        //
+        // WHY IT EXISTS: the trigger is `event.productId && !grantRule`, and Paddle
+        // carries items[0].price.product_id on EVERY transaction.completed —
+        // INCLUDING subscription-renewal transactions, whose money folds through the
+        // subscription.* events instead. A Paddle tenant that drives everything
+        // through tierMap/priceMap therefore got one `error` row + one failure event
+        // + one stranded finding PER RENEWAL, forever. 'ignore' is the one-line
+        // answer. The charge row is still recorded either way — only the ledger
+        // grant is declined — and an `ignored` row stays REPROCESSABLE, so mapping
+        // the product later and re-running the delivery folds it.
+        //
+        // NO SCHEMA DEFAULT ON PURPOSE: the config-write pipeline runs
+        // Value.Default, which MATERIALIZES an Optional-with-default into every
+        // persisted manifest — that would rewrite every payments manifest carrying a
+        // `ledger` bag and make `vxil push --dry-run` / `vxil diff` report drift for
+        // every payments tenant. The READER owns the default
+        // (`config.ledger?.unmappedProduct ?? 'error'`), which is the one definition.
+        unmappedProduct: Type.Optional(Type.Union([Type.Literal('error'), Type.Literal('ignore')])),
     })),
     // NB (money-path wave F3-19): the former `webhooks.forwardToTenantUrl` leaf
     // was DELETED — it had zero readers (never forwarded anything). Outbound
@@ -1044,14 +1159,49 @@ 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
+        // Per-function resource declarations. BOTH members are OPTIONAL (the bag
+        // used to REQUIRE all three, a latent 422 the moment anything sent it —
+        // nothing ever did, because the CLI never carried it) and BOTH are
+        // UNBOUNDED here on purpose: `deployFunction` validates the WHOLE merged
+        // manifest, `Value.Clean` strips unknown keys but never clamps
+        // out-of-range ones, so a min/max here would let ONE legacy entry 422
+        // every future deploy for that tenant. The bounds (cpuMs 5..300000,
+        // timeoutMs 1000..120000) are enforced at the ONE write path,
+        // `normalizeLimits` in the deploy handler, which also sanitizes pre-existing
+        // entries on merge.
+        //   cpuMs     — TIGHTENS the per-dispatch isolate CPU cap (never widens
+        //               FN_MAX_CPU_MS) and RAISES (never lowers) the metering
+        //               reserve, whose floor stays defaultLimits.cpuMs. THE
+        //               CONSEQUENCE, stated because the knob's name hides it:
+        //               the reserve is the payments HOLD, and the pro-rated
+        //               settle clamps the measured wall-ms into [floor, reserve]
+        //               — it can never commit more than it holds — so raising
+        //               the reserve raises the settle CEILING. An invoke whose
+        //               wall time exceeds defaultLimits.cpuMs (50) then settles
+        //               at its measured wall-ms instead of being capped at 50:
+        //               on a METERED tenant, declaring cpuMs raises the bill for
+        //               long-running functions (cpuMs: 1000 turns an 800 ms
+        //               invoke from 50 into 800). It does NOT move anyone's
+        //               availability — the ACCOUNT-global daily capacity budget
+        //               counts the platform's own estimate, never this value
+        //               (functions-v1 capacity.ts `capacityReserveCpuMs`).
+        //   timeoutMs — the wall budget for ONE outbound fetch, delivered to the
+        //               egress guard as an outbound parameter. NOT an invocation
+        //               budget: the INVOCATION is bounded by the platform's own
+        //               FN_MAX_INVOKE_MS deadline (default >= 5 min), which a
+        //               bigger per-fetch budget widens with you (audit FN-3).
+        // (F8-54's standing "strip the twins" note is DISCHARGED here: `memoryMb`
+        // is deleted — memory is fixed by the managed runtime and is not a
+        // per-dispatch option; the WfP dispatch bag takes { cpuMs, subRequests }.
+        // Value.Clean strips it from an old config, so such a config still loads
+        // and `vxil plan --explain` marks the key DROPPED.)
         limits: Type.Optional(Type.Object({
-            cpuMs: Type.Integer(),
-            timeoutMs: Type.Integer(),
-            memoryMb: Type.Integer(),
+            cpuMs: Type.Optional(Type.Integer()),
+            timeoutMs: Type.Optional(Type.Integer()),
         })),
         enabled: Type.Optional(Type.Boolean()),
         // Level-1 typed I/O (cli-sdk design §4.5): the declared input/output
@@ -1064,7 +1214,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,
@@ -1511,7 +1661,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
@@ -1557,7 +1707,7 @@ export function validateFeatureConfig(feature, raw) {
     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.3.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.4.0",
+  "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": {

package/src/hooks.ts

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

package/src/index.test.ts

@@ -11,6 +11,7 @@ import {
   setKnownMcpTools,
   validateFeatureConfig,
   NOTIF_OVERRIDE_MAX_BYTES, NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE,
+  NOTIFICATION_TEMPLATE_PLACEHOLDERS,
   validateNotificationOverrides,
 } from './index.js';
 // The LIVE mcp catalog (zero-import pure data) — the same relative-import
@@ -42,14 +43,16 @@ describe('15-flag cap analyzer (architecture §6)', () => {
     }
   });
 
-  it('auth schema is 11 leaves after D3 (methods collapsed to ONE optional bag; was 15 at the cap)', () => {
+  it('auth schema is 12 leaves (D3 collapse = 11, + the P1-5 registryAdopt opt-in)', () => {
     // enabled(1) + methods(1, optional bag — was 6) + providers(1) + session(1)
-    // + password(1) + emailVerification(1) + magicLink(1) + otp(1) + anonymous(1)
-    // + orgClaims(1) + security(1, optional bag — P0-3) = 11. The auth wave
+    // + password(1) + emailVerification(1) + magicLink(1, optional bag since
+    // P1-16) + otp(1) + anonymous(1) + orgClaims(1) + security(1, optional bag —
+    // P0-3) + registryAdopt(1, P1-5) = 12, 3 under the cap. The auth wave
     // (2026-09-10, D3) funded itself by the methods collapse — the notifications
-    // retry/broadcast precedent; session.maxConcurrent / otp.testRecipients ride
-    // inside existing bags and never move the count.
-    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(11);
+    // retry/broadcast precedent; session.maxConcurrent / otp.testRecipients /
+    // magicLink.resendCooldownSec ride inside existing bags and never move the
+    // count.
+    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(12);
     expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
   });
 
@@ -412,8 +415,8 @@ describe('validateFeatureConfig', () => {
     const min = validateFeatureConfig('auth', { providers: { oidc: { issuer: 'https://login.acme.example', clientId: 'a', clientSecretRef: 'secret:s' } } });
     expect(min.ok).toBe(true);
     expect((min.value as { providers: { oidc: Record<string, unknown> } }).providers.oidc).toEqual({ issuer: 'https://login.acme.example', clientId: 'a', clientSecretRef: 'secret:s' });
-    // still 11 leaves — the block lives INSIDE the providers bag
-    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(11);
+    // still 12 leaves — the block lives INSIDE the providers bag
+    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(12);
     // issuer must be https with no query/fragment; domains lowercase dotted
     for (const issuer of ['http://login.acme.example', 'https://login.acme.example/?x=1', 'https://a#b', 'login.acme.example']) {
       expect(validateFeatureConfig('auth', { providers: { oidc: { issuer, clientId: 'a', clientSecretRef: 'secret:s' } } }).ok, issuer).toBe(false);
@@ -423,6 +426,40 @@ describe('validateFeatureConfig', () => {
     expect(validateFeatureConfig('auth', { providers: { oidc: { issuer: 'https://login.acme.example', clientId: 'a' } } }).ok).toBe(false);
   });
 
+  it('P1-16: the magicLink Optional bag folds byte-identically and bounds resendCooldownSec', () => {
+    // The bag became Type.Optional (so the new knob costs NO leaf) but KEPT
+    // `default: {}`, and resendCooldownSec is Optional with NO default — so a
+    // manifest that never mentions the cooldown folds to exactly the bytes it
+    // folded to before the change. This is the assertion that keeps every
+    // PUBLISHED manifest unchanged (and the reason the worker, not the schema,
+    // supplies the 60s fallback).
+    expect(JSON.stringify((validateFeatureConfig('auth', {}).value as { magicLink: unknown }).magicLink))
+      .toBe('{"tokenTtlMinutes":15}');
+    expect(JSON.stringify((validateFeatureConfig('auth', { magicLink: { tokenTtlMinutes: 30 } }).value as { magicLink: unknown }).magicLink))
+      .toBe('{"tokenTtlMinutes":30}');
+    // set explicitly ⇒ persisted verbatim
+    const set = validateFeatureConfig('auth', { magicLink: { tokenTtlMinutes: 15, resendCooldownSec: 0 } });
+    expect(set.ok, set.errors.join()).toBe(true);
+    expect((set.value as { magicLink: Record<string, number> }).magicLink)
+      .toEqual({ tokenTtlMinutes: 15, resendCooldownSec: 0 });
+    // bounds mirror otp.resendCooldownSec exactly (0..600)
+    expect(validateFeatureConfig('auth', { magicLink: { resendCooldownSec: 600 } }).ok).toBe(true);
+    expect(validateFeatureConfig('auth', { magicLink: { resendCooldownSec: 601 } }).ok).toBe(false);
+    expect(validateFeatureConfig('auth', { magicLink: { resendCooldownSec: -1 } }).ok).toBe(false);
+  });
+
+  it('P1-5: registryAdopt is an OPT-IN boolean with no default (absent stays absent)', () => {
+    const bare = validateFeatureConfig('auth', {});
+    expect(bare.ok).toBe(true);
+    expect(bare.value).not.toHaveProperty('registryAdopt');
+    for (const v of [true, false]) {
+      const r = validateFeatureConfig('auth', { registryAdopt: v });
+      expect(r.ok, r.errors.join()).toBe(true);
+      expect((r.value as { registryAdopt: boolean }).registryAdopt).toBe(v);
+    }
+    expect(validateFeatureConfig('auth', { registryAdopt: 'yes' }).ok).toBe(false);
+  });
+
   it('auth: otp knob bounds are enforced (maxAttempts 3..10)', () => {
     expect(validateFeatureConfig('auth', { otp: { enabled: true, maxAttempts: 2 } }).ok).toBe(false);
     expect(validateFeatureConfig('auth', { otp: { enabled: true, maxAttempts: 11 } }).ok).toBe(false);
@@ -932,6 +969,42 @@ describe('payments: reserved credit_type rejected in ledger grant maps (F2)', ()
   });
 });
 
+// ── payments: ledger.unmappedProduct (2026-09 P2) ────────────────────────────
+// The policy for a one-off purchase whose product_id is not in productMap.
+// It lives INSIDE the one optional `ledger` bag, so the leaf budget is unmoved,
+// and it carries NO schema default so no persisted manifest is rewritten.
+describe('payments: ledger.unmappedProduct policy', () => {
+  it("accepts 'error' and 'ignore', rejects anything else", () => {
+    for (const v of ['error', 'ignore']) {
+      const r = validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {}, unmappedProduct: v } });
+      expect(r.ok, r.ok ? '' : r.errors.join()).toBe(true);
+    }
+    const bad = validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {}, unmappedProduct: 'skip' } });
+    expect(bad.ok).toBe(false);
+  });
+
+  it('LOAD-BEARING: it has NO schema default, so Value.Default never materializes it into a manifest', () => {
+    // A default would be written into every payments manifest carrying a
+    // `ledger` bag on the next PUT, making `vxil push --dry-run` / `vxil diff`
+    // report drift for every payments tenant. The READER owns the default.
+    const before = { ledger: { productMap: {}, tierMap: {} } };
+    const r = validateFeatureConfig('payments', before);
+    expect(r.ok, r.ok ? '' : r.errors.join()).toBe(true);
+    expect((r.value as { ledger?: Record<string, unknown> }).ledger).not.toHaveProperty('unmappedProduct');
+  });
+
+  it("an explicit 'ignore' round-trips through the write pipeline verbatim", () => {
+    const r = validateFeatureConfig('payments', { ledger: { productMap: {}, tierMap: {}, unmappedProduct: 'ignore' } });
+    expect(r.ok).toBe(true);
+    expect((r.value as { ledger?: { unmappedProduct?: string } }).ledger?.unmappedProduct).toBe('ignore');
+  });
+
+  it('the policy sits inside the ONE optional ledger leaf — the leaf budget is unchanged', () => {
+    expect(countLeaves(PaymentsConfigSchema)).toBe(10);
+    expect(countLeaves(PaymentsConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+});
+
 // ── payments: money-path wave (F1-3 config lint, F1-4 acceptSandbox, F1-7 grace,
 //    F3-19 forwardToTenantUrl deleted) ─────────────────────────────────────────
 describe('payments: priceMap ⊆ tierMap + unique ranks (F1-3 / D3 config lint)', () => {
@@ -1139,6 +1212,70 @@ describe('notifications: templates.overrides (D4 per-locale overrides)', () => {
     expect(huge.errors.join()).toContain(`${NOTIF_OVERRIDE_MAX_BYTES}-byte cap`);
   });
 
+  // ── G-78: every part is Optional; an ALL-EMPTY variant is the only new refusal
+  it('accepts a BODY-ONLY override (subject inherited from the built-in)', () => {
+    const v = validateFeatureConfig('notifications', {
+      ...base,
+      templates: {
+        allowOverride: true,
+        overrides: { transactional: { ar: { html: '<div dir="rtl">{{paragraph}}</div>' } } },
+      },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+  });
+
+  it('accepts a TEXT-ONLY override', () => {
+    const v = validateFeatureConfig('notifications', {
+      ...base,
+      templates: {
+        allowOverride: true,
+        overrides: { transactional: { fr: { text: 'FR {{paragraph}}' } } },
+      },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+  });
+
+  it('REJECTS a variant with no non-empty part (the new inert shape)', () => {
+    // `{}` and all-empty bodies reach the cross-field rule (html/text carry no
+    // minLength); an empty `subject` is still refused earlier by the schema's own
+    // minLength. Either way the write fails LOUD — never a silently inert override.
+    for (const variant of [{}, { html: '' }, { html: '', text: '' }]) {
+      const v = validateFeatureConfig('notifications', {
+        ...base,
+        templates: { allowOverride: true, overrides: { transactional: { ar: variant } } },
+      });
+      expect(v.ok, JSON.stringify(variant)).toBe(false);
+      if (!v.ok) {
+        expect(v.errors.join('\n'), JSON.stringify(variant))
+          .toContain('set at least one of subject, html, text');
+      }
+    }
+    const emptySubject = validateFeatureConfig('notifications', {
+      ...base,
+      templates: { allowOverride: true, overrides: { transactional: { ar: { subject: '' } } } },
+    });
+    expect(emptySubject.ok).toBe(false);
+  });
+
+  it('the pure validator refuses a non-object variant without throwing (total)', () => {
+    expect(validateNotificationOverrides({
+      allowOverride: true,
+      overrides: { welcome: { 'fr-FR': null } },
+    } as never).join('\n')).toContain('at least one of subject, html, text');
+  });
+
+  it('`cta` is an allowed transactional placeholder (the {{cta}} slot)', () => {
+    expect(NOTIFICATION_TEMPLATE_PLACEHOLDERS['transactional']).toContain('cta');
+    const v = validateFeatureConfig('notifications', {
+      ...base,
+      templates: {
+        allowOverride: true,
+        overrides: { transactional: { ar: { html: '<p>{{paragraph}}</p>{{cta}}' } } },
+      },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+  });
+
   it('the pure validator is [] for an absent/empty bag', () => {
     expect(validateNotificationOverrides(undefined)).toEqual([]);
     expect(validateNotificationOverrides({ allowOverride: true })).toEqual([]);
@@ -1247,6 +1384,37 @@ describe('F8-54: the deleted inert leaves stay deleted, and old manifests still
     expect(dl['memoryMb']).toBeUndefined();
   });
 
+  // D.18 — the PER-FUNCTION bag (inside the Type.Record value), not defaultLimits.
+  // It used to REQUIRE all three members whenever present, a latent 422 the moment
+  // anything sent one; nothing ever did, because the CLI never carried it.
+  it('functions: the per-function limits bag accepts each member ALONE', () => {
+    const base = { scriptRef: 'fn-t-hello-abc123def456' };
+    for (const limits of [{}, { cpuMs: 200 }, { timeoutMs: 60_000 }, { cpuMs: 200, timeoutMs: 60_000 }]) {
+      const r = validateFeatureConfig('functions', {
+        enabled: true, functions: { hello: { ...base, limits } },
+      });
+      expect(r.ok, JSON.stringify(limits)).toBe(true);
+    }
+  });
+
+  it('functions: a per-function memoryMb is STRIPPED, not rejected (the published F8-54 contract)', () => {
+    // docs/guide/changelog.md publishes strip-and-ignore for removed config keys:
+    // an already-saved manifest still loads and `vxil plan --explain` marks the
+    // key DROPPED. The DEPLOY BODY is the surface that 422s it (normalizeLimits).
+    const r = validateFeatureConfig('functions', {
+      enabled: true,
+      functions: { hello: { scriptRef: 'fn-t-hello-abc123def456', limits: { cpuMs: 200, memoryMb: 512 } } },
+    });
+    expect(r.ok).toBe(true);
+    const fns = (r.value as { functions: Record<string, { limits: Record<string, unknown> }> }).functions;
+    expect(fns.hello!.limits).toEqual({ cpuMs: 200 });
+    expect(fns.hello!.limits['memoryMb']).toBeUndefined();
+  });
+
+  it('functions: the per-function bag is DATA — re-typing it never moves the leaf count', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['functions']!)).toBe(4);
+  });
+
   it('every surviving schema still fits the cap (the deletions only freed budget)', () => {
     for (const [feature, schema] of Object.entries(FEATURE_SCHEMAS)) {
       expect(countLeaves(schema), `${feature} exceeds the flag cap`).toBeLessThanOrEqual(CONFIG_FLAG_CAP);

package/src/index.ts

@@ -49,7 +49,20 @@ export const NOTIFICATION_TEMPLATE_PLACEHOLDERS: Readonly<Record<string, readonl
   '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'],
+  // `cta` (G-78) is a SLOT, not a data key: an override that writes `{{cta}}`
+  // chooses where the escaped CTA anchor built from cta_label + cta_url lands.
+  // Absent from the built-in bodies (which append it), so the worker parity
+  // suite pins it explicitly — see templates.test.ts.
+  transactional: ['subject', 'paragraph', 'cta_label', 'cta_url', 'cta'],
+};
+
+/** Placeholders that are SLOTS in the BODY parts only — the renderer splits
+ * `html`/`text` on them (templates.ts `CTA_SLOT`) but the subject goes through
+ * the plain interpolator, where the same token is just a data key that does not
+ * exist and renders EMPTY. Rejected in `subject` for exactly the reason the
+ * whole allow-list exists: a silent empty render in a live email. */
+export const NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS: Readonly<Record<string, readonly string[]>> = {
+  transactional: ['cta'],
 };
 
 /** Per-override caps (D4). Bodies are emails, not documents. */
@@ -108,13 +121,30 @@ export function validateNotificationOverrides(
         continue;
       }
       const variant = byLocale![locale]!;
+      if (typeof variant !== 'object' || variant === null) {
+        errs.push(`/templates/overrides/${templateId}/${locale}: must be an object with at least one of subject, html, text`);
+        continue;
+      }
+      // G-78 — every part is OPTIONAL (a body-only translation inherits the
+      // built-in subject), but an ALL-EMPTY variant is the new "inert config"
+      // and fails LOUD rather than silently rendering the built-in.
+      const nonEmpty = (['subject', 'html', 'text'] as const)
+        .filter((p) => typeof variant[p] === 'string' && variant[p] !== '');
+      if (nonEmpty.length === 0) {
+        errs.push(`/templates/overrides/${templateId}/${locale}: set at least one of subject, html, text`);
+        continue;
+      }
+      // body-only SLOTS are not subject placeholders (see the map's doc comment)
+      const slots = NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS[templateId] ?? [];
+      const subjectAllowed = allowed.filter((k) => !slots.includes(k));
       for (const part of ['subject', 'html', 'text'] as const) {
         const body = variant[part];
         if (typeof body !== 'string') continue;
+        const ok = part === 'subject' ? subjectAllowed : allowed;
         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(', ')})`);
+          if (!ok.includes(key)) {
+            errs.push(`/templates/overrides/${templateId}/${locale}/${part}: unknown placeholder '{{${key}}}' (allowed: ${ok.join(', ')})`);
           }
         }
       }
@@ -183,7 +213,7 @@ export const NotificationsConfigSchema = 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,
+      // 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.
@@ -192,8 +222,15 @@ export const NotificationsConfigSchema = Type.Object({
       // LOUD, never silently inert) overrides present with allowOverride:false.
       overrides: Type.Optional(Type.Record(
         Type.String(),
+        // G-78: `subject` is OPTIONAL like html/text — a PARTIAL override
+        // inherits each omitted part from the built-in, so a body-only
+        // translation no longer forces you to restate the subject (and a
+        // subject-only 'ar' override no longer pairs an Arabic subject with the
+        // English built-in body). A strict widening: every config valid before
+        // this change is still valid. validateNotificationOverrides rejects the
+        // one shape this opens up — a variant with NO non-empty part.
         Type.Record(Type.String(), Type.Object({
-          subject: Type.String({ minLength: 1, maxLength: NOTIF_OVERRIDE_SUBJECT_MAX }),
+          subject: Type.Optional(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 })),
         })),
@@ -445,10 +482,38 @@ export const AuthConfigSchema = Type.Object({
     { required: Type.Boolean({ default: false }) },
     { default: {} },
   ),
-  magicLink: Type.Object(
-    { tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }) },
+  // P1-16 (2026-09-18): magicLink is now an OPTIONAL bag (= ONE leaf however
+  // many knobs it holds — the methods/session/password precedent) so the
+  // request cooldown could land without spending a second leaf. It KEEPS
+  // `default: {}`, so Value.Default still materializes
+  // `magicLink.tokenTtlMinutes` exactly as before — every persisted manifest
+  // folds byte-identically.
+  magicLink: Type.Optional(Type.Object(
+    {
+      tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }),
+      // P1-16: the per-(tenant, identifier) magic-link REQUEST cooldown — the
+      // `otp.resendCooldownSec` twin, same bounds so the two knobs read the
+      // same. A second request for the same address inside the window is a 429
+      // `magic_link_rate_limited` with a Retry-After header. Type.Optional with
+      // NO default (the `otp.testRecipients` precedent below) so existing
+      // manifests fold byte-identically; the 60s fallback is applied by the
+      // auth feature at read time. 0 disables the cooldown.
+      resendCooldownSec: Type.Optional(Type.Integer({ minimum: 0, maximum: 600 })),
+    },
     { default: {} },
-  ),
+  )),
+  // P1-5 identity continuity (2026-09-18) — OPT-IN registry adoption. When
+  // true, a sign-in by a method that PROVES control of the address — magic
+  // link, email OTP, or OAuth with a provider-verified address — reuses the id
+  // of the one matching pre-registered end-user (POST /v1/users) that has no
+  // account yet, instead of minting a fresh `user_<ulid>` and leaving the
+  // tenant with two records for one person. Password SIGN-UP never adopts: it
+  // proves nothing about the address (auth.md §8.1 PROVEN_ADOPT_METHODS).
+  // OFF by default, and Type.Optional with NO default: adoption means whoever
+  // proves control of a pre-registered address becomes that record — a change
+  // of security semantics for a tenant that bulk-imports contacts, whose
+  // addresses vxil never verified.
+  registryAdopt: Type.Optional(Type.Boolean()),
   // Email OTP sign-in (roadmap Tier-0) + the knobs step-up re-auth shares.
   // OPTIONAL bag = 1 leaf; absent ⇒ disabled (the worker gates on
   // otp?.enabled === true).
@@ -524,11 +589,12 @@ export type AuthOidcConfig = Static<typeof OidcProviderSchema>;
 // Leaves (auth wave 2026-09-10, D3): enabled(1) + methods(1, optional bag —
 // was 6) + providers(1, optional bag holding the four google/github/apple/
 // facebook credential blocks + the RB-2 `oidc` issuer block) + session(1, optional bag) + password(1,
-// optional bag) + emailVerification(1) + magicLink(1) + otp(1, optional bag)
+// optional bag) + emailVerification(1) + magicLink(1, optional bag) + otp(1, optional bag)
 // + anonymous(1, optional bag) + orgClaims(1, optional bag) + security(1,
-// optional bag) = 11. Cap = 15 — 4 leaves of headroom. Knobs added inside an
-// existing bag (session.maxConcurrent, otp.testRecipients, the security
-// sub-bags) never move the count.
+// optional bag) + registryAdopt(1, P1-5) = 12. Cap = 15 — 3 leaves of
+// headroom. Knobs added inside an existing bag (session.maxConcurrent,
+// otp.testRecipients, magicLink.resendCooldownSec, the security sub-bags)
+// never move the count.
 
 export type AuthConfig = Static<typeof AuthConfigSchema>;
 
@@ -564,7 +630,7 @@ export const FilesConfigSchema = Type.Object({
       // object storage is cheap but the SQL-database-resident metadata + abuse aren't (pricing re-audit
       // 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
       // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
-      // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
+      // tenant tier threaded to files-v1 (plan tiers).
       maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
       maxTotalBytes: Type.Integer({ default: 10 * 1024 * 1024 * 1024, minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 }),
       maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
@@ -620,8 +686,29 @@ export const WebhooksConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
   maxSubscriptions: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
   maxSources: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
+  // FAILURE-ALERT DIGEST (P0-2). Outbound subscriptions are the real-time
+  // channel; this is the "nobody is consuming them yet" fallback — a periodic
+  // e-mail summary of the tenant's FAILURE-class audit events (the level:
+  // 'failure' rows of the generated event catalog). Read by
+  // workers/control-plane/src/alertDigest.ts on the minute cron.
+  //
+  // RECIPIENTS ARE DELIBERATELY NOT CONFIGURABLE, and this deviation is
+  // journaled here the way RateLimitsConfigSchema journals its own: an
+  // arbitrary `to` would turn vxil's own sending identity into a relay for
+  // tenant-authored content and open a PII egress path out of the audit trail.
+  // The digest goes to the OWNER-role dashboard accounts of the project (cap
+  // 3), who already receive platform mail (invites, magic links, resets), so no
+  // new consent surface is created. An arbitrary recipient is a separate
+  // decision with its own abuse review.
+  //
+  // An Optional object bag counts as ONE leaf (the countLeaves rule).
+  alerts: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    minLevel: Type.Union([Type.Literal('warn'), Type.Literal('error')], { default: 'error' }),
+    digestMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 1440 }),
+  })),
 });
-// Leaves: 3. Cap = 15.
+// Leaves: 3 + alerts(1, optional bag) = 4. Cap = 15.
 
 export type WebhooksConfig = Static<typeof WebhooksConfigSchema>;
 
@@ -678,7 +765,7 @@ export const CmsConfigSchema = Type.Object({
     },
     { default: {} },
   ),
-  // Code-based lifecycle hooks (docs/cms-lifecycle-hooks-rung2-design.md, Lane A):
+  // Code-based lifecycle hooks (https://vxil.com/docs/guide/07-validation-and-hooks):
   // a tenant-authored SAFE expression. Write events (beforeCreate/beforeUpdate/
   // beforeWrite) run in-transaction — `validate` rejects the write, `derive`
   // computes a persisted field. Read events shape the RESPONSE only: `validate`
@@ -1086,7 +1173,7 @@ export const AiConfigSchema = Type.Object({
   cache: Type.Object({ ttlSeconds: Type.Integer({ default: 0, minimum: 0 }) }, { default: {} }), // 0 = off
   limits: Type.Object({
     tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = unlimited
-    consumeCredits: Type.Boolean({ default: false }),              // reserve→settle (STUB until payments)
+    consumeCredits: Type.Boolean({ default: false }),              // LIVE: reserve→settle against the payments credit ledger (a job-routed generation reserves pre-generation and 402s insufficient_credits)
   }, { default: {} }),
   streaming: Type.Object({
     enabled: Type.Boolean({ default: true }),
@@ -1204,10 +1291,16 @@ export const PaymentsConfigSchema = Type.Object({
     projectId: Type.String(),
     publicSdkKey: Type.String(),
     secretApiKeyRef: Type.String(),
-    // Optional per-tenant webhook secret ref (public.tenant_secrets). When set,
-    // inbound RevenueCat webhooks are verified with THIS tenant's secret instead
-    // of the platform PROVIDER_WEBHOOK_SECRET — closes the multi-tenant RC
-    // webhook-forgery vector (mirrors stripe/paddle webhookSecretRef).
+    // Per-tenant webhook secret ref (public.tenant_secrets). Inbound RevenueCat
+    // webhooks are verified against THIS ref and nothing else: there is no
+    // platform-wide PROVIDER_WEBHOOK_SECRET fallback for a real payment provider
+    // (that fallback WAS the multi-tenant RC webhook-forgery vector; it is now
+    // frozen out by tests/ci/src/provider-webhook-secret-fallback.test.ts, which
+    // permits `secrets.webhookSecret` only in makeProvider's mock/default arm).
+    // Optional at the SCHEMA level only — leaving it unset does not disable
+    // verification, it fails CLOSED: every delivery is 401 bad_signature with a
+    // `sig_failed` row that can never be reprocessed. 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
@@ -1285,6 +1378,29 @@ export const PaymentsConfigSchema = Type.Object({
     enforcePeriodEnd: Type.Optional(Type.Object({
       slackHours: Type.Integer({ default: 72, minimum: 0, maximum: 720 }),
     })),
+    // (2026-09 P2) What to do with a one-off purchase whose `product_id` is NOT
+    // in productMap. 'error' (the DEFAULT and today's behaviour) stamps the
+    // delivery outcome `error`, emits payments.webhook_event.failed and lands a
+    // `stranded_webhook` reconcile finding. 'ignore' stamps it `ignored`, with
+    // no failure event and no stranded finding.
+    //
+    // WHY IT EXISTS: the trigger is `event.productId && !grantRule`, and Paddle
+    // carries items[0].price.product_id on EVERY transaction.completed —
+    // INCLUDING subscription-renewal transactions, whose money folds through the
+    // subscription.* events instead. A Paddle tenant that drives everything
+    // through tierMap/priceMap therefore got one `error` row + one failure event
+    // + one stranded finding PER RENEWAL, forever. 'ignore' is the one-line
+    // answer. The charge row is still recorded either way — only the ledger
+    // grant is declined — and an `ignored` row stays REPROCESSABLE, so mapping
+    // the product later and re-running the delivery folds it.
+    //
+    // NO SCHEMA DEFAULT ON PURPOSE: the config-write pipeline runs
+    // Value.Default, which MATERIALIZES an Optional-with-default into every
+    // persisted manifest — that would rewrite every payments manifest carrying a
+    // `ledger` bag and make `vxil push --dry-run` / `vxil diff` report drift for
+    // every payments tenant. The READER owns the default
+    // (`config.ledger?.unmappedProduct ?? 'error'`), which is the one definition.
+    unmappedProduct: Type.Optional(Type.Union([Type.Literal('error'), Type.Literal('ignore')])),
   })),
   // NB (money-path wave F3-19): the former `webhooks.forwardToTenantUrl` leaf
   // was DELETED — it had zero readers (never forwarded anything). Outbound
@@ -1373,15 +1489,50 @@ export const FunctionsConfigSchema = Type.Object({
             { maxItems: 8 },
           ),
         ),
-        scriptRef: Type.String(), // content-hashed WfP script name: fn-<tenant>-<name>-<sha>
+        scriptRef: Type.String(), // content-hashed hosted-script name: fn-<tenant>-<name>-<sha>
         scopes: Type.Optional(Type.Array(Type.String())), // clamped via DENY_FUNCTION_SCOPES at deploy (admin/*/features:write/functions:write/secrets:write)
-        secrets: Type.Optional(Type.Array(Type.String())), // tenant_secrets refs (KEK_FUNCTIONS)
+        secrets: Type.Optional(Type.Array(Type.String())), // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
+        // Per-function resource declarations. BOTH members are OPTIONAL (the bag
+        // used to REQUIRE all three, a latent 422 the moment anything sent it —
+        // nothing ever did, because the CLI never carried it) and BOTH are
+        // UNBOUNDED here on purpose: `deployFunction` validates the WHOLE merged
+        // manifest, `Value.Clean` strips unknown keys but never clamps
+        // out-of-range ones, so a min/max here would let ONE legacy entry 422
+        // every future deploy for that tenant. The bounds (cpuMs 5..300000,
+        // timeoutMs 1000..120000) are enforced at the ONE write path,
+        // `normalizeLimits` in the deploy handler, which also sanitizes pre-existing
+        // entries on merge.
+        //   cpuMs     — TIGHTENS the per-dispatch isolate CPU cap (never widens
+        //               FN_MAX_CPU_MS) and RAISES (never lowers) the metering
+        //               reserve, whose floor stays defaultLimits.cpuMs. THE
+        //               CONSEQUENCE, stated because the knob's name hides it:
+        //               the reserve is the payments HOLD, and the pro-rated
+        //               settle clamps the measured wall-ms into [floor, reserve]
+        //               — it can never commit more than it holds — so raising
+        //               the reserve raises the settle CEILING. An invoke whose
+        //               wall time exceeds defaultLimits.cpuMs (50) then settles
+        //               at its measured wall-ms instead of being capped at 50:
+        //               on a METERED tenant, declaring cpuMs raises the bill for
+        //               long-running functions (cpuMs: 1000 turns an 800 ms
+        //               invoke from 50 into 800). It does NOT move anyone's
+        //               availability — the ACCOUNT-global daily capacity budget
+        //               counts the platform's own estimate, never this value
+        //               (functions-v1 capacity.ts `capacityReserveCpuMs`).
+        //   timeoutMs — the wall budget for ONE outbound fetch, delivered to the
+        //               egress guard as an outbound parameter. NOT an invocation
+        //               budget: the INVOCATION is bounded by the platform's own
+        //               FN_MAX_INVOKE_MS deadline (default >= 5 min), which a
+        //               bigger per-fetch budget widens with you (audit FN-3).
+        // (F8-54's standing "strip the twins" note is DISCHARGED here: `memoryMb`
+        // is deleted — memory is fixed by the managed runtime and is not a
+        // per-dispatch option; the WfP dispatch bag takes { cpuMs, subRequests }.
+        // Value.Clean strips it from an old config, so such a config still loads
+        // and `vxil plan --explain` marks the key DROPPED.)
         limits: Type.Optional(
           Type.Object({
-            cpuMs: Type.Integer(),
-            timeoutMs: Type.Integer(),
-            memoryMb: Type.Integer(),
+            cpuMs: Type.Optional(Type.Integer()),
+            timeoutMs: Type.Optional(Type.Integer()),
           }),
         ),
         enabled: Type.Optional(Type.Boolean()),
@@ -1405,7 +1556,7 @@ export const FunctionsConfigSchema = Type.Object({
 //   defaultLimits.memoryMb leaves.)
 export type FunctionsConfig = Static<typeof FunctionsConfigSchema>;
 
-// copilot feature (docs/copilot-agents-sku-design.md §4). Re-declared to match
+// copilot feature (https://vxil.com/docs/guide/11-copilot-agents). Re-declared to match
 // workers/copilot-v1/src/config.ts's exported CopilotConfigSchema (one shape,
 // two consumers — keep the two definitions byte-identical). A thin COMPOSITION
 // layer over ai + vector-search + rag + mcp: it owns the AGENT layer (persona,
@@ -1922,7 +2073,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     }
     if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
   }
-  // Cross-field rules: copilot (docs/copilot-agents-sku-design.md §4). Pure
+  // Cross-field rules: copilot (https://vxil.com/docs/guide/11-copilot-agents). Pure
   // rules only — cross-feature resolutions (collection existence, directiveRef
   // → ai.templates) are deferred to runtime, which fails soft with the
   // capability-surface envelope. Tool-NAME existence runs only when the mcp
@@ -1973,7 +2124,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// 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/src/readmodels.ts

@@ -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