@vxil/feature-configs 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -656,6 +656,7 @@ export declare const PaymentsConfigSchema: import("@sinclair/typebox").TObject<{
         secretApiKeyRef: import("@sinclair/typebox").TString;
         webhookSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         acceptSandbox: import("@sinclair/typebox").TBoolean;
+        sandboxUsers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>>;
     paypal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         clientIdRef: import("@sinclair/typebox").TString;
@@ -685,6 +686,7 @@ export declare const PaymentsConfigSchema: import("@sinclair/typebox").TObject<{
                 creditType: import("@sinclair/typebox").TString;
                 amount: import("@sinclair/typebox").TInteger;
                 period: import("@sinclair/typebox").TString;
+                mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"add">, import("@sinclair/typebox").TLiteral<"reset">]>>;
             }>>>;
         }>>;
         priceMap: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
@@ -718,11 +720,17 @@ export declare const FunctionsConfigSchema: import("@sinclair/typebox").TObject<
             retry: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
                 maxAttempts: import("@sinclair/typebox").TInteger;
             }>>;
+            overlap: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"allow">, import("@sinclair/typebox").TLiteral<"skip">]>>;
         }>>>;
         scriptRef: import("@sinclair/typebox").TString;
         scopes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         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>>;
+        runtime: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            compatibilityDate: import("@sinclair/typebox").TString;
+            compatibilityFlags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+            cpuMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        }>>;
         limits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
             cpuMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
             timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
@@ -790,6 +798,19 @@ export declare const CONFIG_FLAG_CAP = 15;
  * reconciler maps each to its `auth.<event>` audit-event prefix. */
 export declare const AUTH_HOOK_EVENTS: readonly ["user.created", "session.created", "session.revoked", "signin.failure"];
 export type AuthHookEvent = (typeof AUTH_HOOK_EVENTS)[number];
+/** The events a `cmsHook` function binding may name — the closed union
+ * `packages/config` types on the `cmsHook` trigger, and the keys of the
+ * functions-v1 receiver's CMS_HOOK_EVENTS_FOR (beforeCreate → created,
+ * beforeUpdate → updated, beforeWrite → both). Omitted = beforeWrite. Anything
+ * else is refused at config write (E-CMSHOOK, 2026-10-01): an unknown name used
+ * to fall back to beforeWrite at delivery, so a typo like 'afterCreate' or
+ * 'beforeDelete' silently subscribed the function to creates AND updates.
+ * tests/ci/src/fn-binding-contracts.test.ts pins every copy to this list. */
+export declare const CMS_HOOK_EVENTS: readonly ["beforeCreate", "beforeUpdate", "beforeWrite"];
+export type CmsHookEvent = (typeof CMS_HOOK_EVENTS)[number];
+/** The ONE refusal text for an unknown cmsHook binding event (the config
+ * validator and the deploy route's early 422 both use it). */
+export declare function cmsHookEventError(event: unknown): string | null;
 /** 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 declare const TEST_RECIPIENT_EMAIL_RE: RegExp;

package/dist/index.js

@@ -1116,8 +1116,9 @@ export const AiConfigSchema = Type.Object({
     // stamps on the latest version, and POSTs a new version ONLY when the content
     // differs — so a push is idempotent and versions stay monotonic per name.
     // Item shape mirrors ai-v1 core.ts TemplateBody exactly (`template` is the
-    // name). Stored templates the config does not declare are reported (there is
-    // no delete route — they are never removed). Bounded to 50 entries: the
+    // name). Stored templates the config does not declare are reported and left
+    // in place — RETIRED (soft: hidden from list + render, history kept) only
+    // under --allow-destructive (cvskit F67, 2026-10-01). Bounded to 50 entries: the
     // manifest rides the 1 MiB config body cap. An Optional ARRAY is ONE leaf.
     templates: Type.Optional(Type.Array(DeclaredAiTemplateSchema, { maxItems: AI_MAX_DECLARED_TEMPLATES })),
 });
@@ -1220,6 +1221,17 @@ export const PaymentsConfigSchema = Type.Object({
         // 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 }),
+        // (2026-10-01 §4.13 A18) Store-review purchases on a PRODUCTION tenant:
+        // the reviewer accounts' RevenueCat `app_user_id`s (≤ 20). A SANDBOX event
+        // whose subject (and, for a TRANSFER, every source user) is listed here
+        // folds — recorded `environment: 'sandbox'` on the delivery, the
+        // subscription and the charge, so it stays out of revenue — while every
+        // other sandbox event is still `rejected_environment`. The narrow,
+        // production-safe alternative to `acceptSandbox` (which folds EVERY
+        // TestFlight purchase and is refused by the CLI's production promotion
+        // gate). No default on purpose (Value.Default would materialize it into
+        // every RC manifest); absent = an empty list.
+        sandboxUsers: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 20 })),
     })),
     paypal: Type.Optional(Type.Object({
         clientIdRef: Type.String(),
@@ -1250,9 +1262,12 @@ export const PaymentsConfigSchema = Type.Object({
         //   { tier, durationDays }          (2026-09-25 F35+) a TIME-BOXED
         //     ENTITLEMENT: the buyer gets `tier` (a tierMap key — cross-checked
         //     below) for `durationDays`, as a charge-linked manual-style row that
-        //     STACKS on the user's live purchases of the same tier and is ENDED by
-        //     that charge's full refund / chargeback. No defaults in either shape,
-        //     so an existing manifest is byte-identical after Value.Default.
+        //     STACKS behind the user's live same-tier manual rows that have an end
+        //     (earlier passes AND comp grants since 2026-09-25 F38 — never a row
+        //     linked to the same charge, an open-ended grant or a provider
+        //     subscription) and is ENDED by that charge's full refund / chargeback.
+        //     No defaults in either shape, so an existing manifest is
+        //     byte-identical after Value.Default.
         productMap: Type.Record(Type.String(), Type.Union([
             Type.Object({
                 creditType: Type.String({ minLength: 1 }),
@@ -1273,6 +1288,14 @@ export const PaymentsConfigSchema = Type.Object({
                 creditType: Type.String({ minLength: 1 }),
                 amount: Type.Integer({ minimum: 1 }), // #128
                 period: Type.String(),
+                // (2026-10-01 §4.13 W9) 'add' (the reader's default, today's
+                // behaviour) ADDS `amount` each period; 'reset' makes the period's
+                // grant REPLACE what is left: the unspent available balance of
+                // `creditType` is written off as one `expire` ledger row and `amount`
+                // granted, so the user starts every period with exactly `amount`
+                // (credits held by an in-flight job stay held). No schema default (it
+                // would materialize into every manifest carrying grants).
+                mode: Type.Optional(Type.Union([Type.Literal('add'), Type.Literal('reset')])),
             }))),
         })),
         // provider price/plan id → tier. A real subscription webhook carries the
@@ -1396,11 +1419,30 @@ export const FunctionsConfigSchema = Type.Object({
             retry: Type.Optional(Type.Object({
                 maxAttempts: Type.Integer({ minimum: 1, maximum: FN_RETRY_MAX_ATTEMPTS }),
             })),
+            // W7 (2026-10-01): cron only — 'skip' = a due tick fires nothing
+            // while the previous tick's run is still open (queued / running /
+            // retrying / waiting / delayed). Absent = 'allow' (every tick runs).
+            overlap: Type.Optional(Type.Union([Type.Literal('allow'), Type.Literal('skip')])),
         }), { maxItems: 8 })),
         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())), // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
+        // R1 (2026-10-01): the runtime settings this function's script was
+        // UPLOADED with — server-SET by the deploy pipeline (never authored),
+        // read back by the rollback re-upload so a restored script runs under
+        // the settings it was deployed and tested with, not today's. Absent =
+        // the legacy settings (@vxil/types FUNCTIONS_RUNTIME_LEGACY). Unbounded
+        // strings on purpose (the deploy writes them from the one constant).
+        // cpuMs (F2, 2026-10-01): the per-invoke CPU limit the script was
+        // uploaded with (limits.cpu_ms = min(declared limits.cpuMs, the tier's
+        // cpuMsPerInvoke, FN_MAX_CPU_MS)) — server-set; the nightly plan pass
+        // rewrites it after a tier change. Absent = the platform default.
+        runtime: Type.Optional(Type.Object({
+            compatibilityDate: Type.String(),
+            compatibilityFlags: Type.Optional(Type.Array(Type.String())),
+            cpuMs: Type.Optional(Type.Number()),
+        })),
         // 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
@@ -1565,6 +1607,24 @@ export const CONFIG_FLAG_CAP = 15;
  * 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'];
+/** The events a `cmsHook` function binding may name — the closed union
+ * `packages/config` types on the `cmsHook` trigger, and the keys of the
+ * functions-v1 receiver's CMS_HOOK_EVENTS_FOR (beforeCreate → created,
+ * beforeUpdate → updated, beforeWrite → both). Omitted = beforeWrite. Anything
+ * else is refused at config write (E-CMSHOOK, 2026-10-01): an unknown name used
+ * to fall back to beforeWrite at delivery, so a typo like 'afterCreate' or
+ * 'beforeDelete' silently subscribed the function to creates AND updates.
+ * tests/ci/src/fn-binding-contracts.test.ts pins every copy to this list. */
+export const CMS_HOOK_EVENTS = ['beforeCreate', 'beforeUpdate', 'beforeWrite'];
+/** The ONE refusal text for an unknown cmsHook binding event (the config
+ * validator and the deploy route's early 422 both use it). */
+export function cmsHookEventError(event) {
+    if (event === undefined)
+        return null;
+    if (typeof event === 'string' && CMS_HOOK_EVENTS.includes(event))
+        return null;
+    return `a 'cmsHook' binding's event must be one of ${CMS_HOOK_EVENTS.join(' | ')} (or omitted = beforeWrite), not ${JSON.stringify(event)}`;
+}
 /** 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@]+$/;
@@ -1840,8 +1900,39 @@ export function validateFeatureConfig(feature, raw) {
                 if (g.creditType && isReservedCreditType(g.creditType)) {
                     ledgerErrs.push(`/ledger/tierMap/${tier}/grants/${i}/creditType: '${g.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`);
                 }
+                // (W9) 'reset' replaces the balance EACH PERIOD — a one-time grant has
+                // no period to reset, and a second grant of the same credit type in the
+                // same tier would be wiped (or wipe it) depending on array order.
+                if (g.mode === 'reset') {
+                    if (g.period === 'once') {
+                        ledgerErrs.push(`/ledger/tierMap/${tier}/grants/${i}/mode: 'reset' needs a recurring period (monthly or annual), not 'once'`);
+                    }
+                    const twin = (rule.grants ?? []).findIndex((o, j) => j !== i && o.creditType === g.creditType);
+                    if (twin >= 0) {
+                        ledgerErrs.push(`/ledger/tierMap/${tier}/grants/${i}/mode: a 'reset' grant must be the only grant of '${g.creditType}' in the tier (grants/${twin} also grants it)`);
+                    }
+                }
+            });
+        }
+        // (2026-10-01 review) A 'reset' grant writes off the WHOLE available balance
+        // of its credit type each period — purchased credits of that type included.
+        // A credit pack of a reset type would lose paid value at the next renewal,
+        // so it is refused here: keep packs on their own type and spend in order
+        // (`credit_types: ['plan', 'topup']`).
+        const resetBy = new Map();
+        for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
+            (rule.grants ?? []).forEach((g, i) => {
+                if (g.mode === 'reset' && g.creditType && !resetBy.has(g.creditType)) {
+                    resetBy.set(g.creditType, `/ledger/tierMap/${tier}/grants/${i}`);
+                }
             });
         }
+        for (const [productId, rule] of Object.entries(v.ledger?.productMap ?? {})) {
+            const by = rule.creditType ? resetBy.get(rule.creditType) : undefined;
+            if (by) {
+                ledgerErrs.push(`/ledger/productMap/${productId}/creditType: '${rule.creditType}' is reset each period by ${by} (mode 'reset' writes off purchased credits of that type) — sell packs on their own credit type and spend with credit_types`);
+            }
+        }
         // 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
@@ -2013,6 +2104,9 @@ export function validateFeatureConfig(feature, raw) {
                 if (b.kind === 'cron' && !b.schedule) {
                     errs.push(`/functions/${name}/bindings/${i}: a 'cron' binding needs a schedule`);
                 }
+                if (b.overlap !== undefined && b.kind !== 'cron') {
+                    errs.push(`/functions/${name}/bindings/${i}: 'overlap' applies to cron bindings only (not '${b.kind}')`);
+                }
                 // F33: retry is an opt-in for the platform-delivered event lanes only —
                 // an http invoke returns its real status to its caller, and a cron
                 // tick's retry would overlap the next tick.
@@ -2022,6 +2116,11 @@ export function validateFeatureConfig(feature, raw) {
                 if (b.kind === 'cmsHook' && !b.collection) {
                     errs.push(`/functions/${name}/bindings/${i}: a 'cmsHook' binding needs a collection`);
                 }
+                // E-CMSHOOK: the CLOSED cmsHook event union — an unknown name is a 422
+                // at write time, never a silent created+updated subscription.
+                const cmsEventErr = b.kind === 'cmsHook' ? cmsHookEventError(b.event) : null;
+                if (cmsEventErr)
+                    errs.push(`/functions/${name}/bindings/${i}: ${cmsEventErr}`);
                 // 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)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.6.0",
+  "version": "0.7.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",

package/src/index.ts

@@ -1405,8 +1405,9 @@ export const AiConfigSchema = Type.Object({
   // stamps on the latest version, and POSTs a new version ONLY when the content
   // differs — so a push is idempotent and versions stay monotonic per name.
   // Item shape mirrors ai-v1 core.ts TemplateBody exactly (`template` is the
-  // name). Stored templates the config does not declare are reported (there is
-  // no delete route — they are never removed). Bounded to 50 entries: the
+  // name). Stored templates the config does not declare are reported and left
+  // in place — RETIRED (soft: hidden from list + render, history kept) only
+  // under --allow-destructive (cvskit F67, 2026-10-01). Bounded to 50 entries: the
   // manifest rides the 1 MiB config body cap. An Optional ARRAY is ONE leaf.
   templates: Type.Optional(Type.Array(DeclaredAiTemplateSchema, { maxItems: AI_MAX_DECLARED_TEMPLATES })),
 });
@@ -1537,6 +1538,17 @@ export const PaymentsConfigSchema = Type.Object({
     // 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 }),
+    // (2026-10-01 §4.13 A18) Store-review purchases on a PRODUCTION tenant:
+    // the reviewer accounts' RevenueCat `app_user_id`s (≤ 20). A SANDBOX event
+    // whose subject (and, for a TRANSFER, every source user) is listed here
+    // folds — recorded `environment: 'sandbox'` on the delivery, the
+    // subscription and the charge, so it stays out of revenue — while every
+    // other sandbox event is still `rejected_environment`. The narrow,
+    // production-safe alternative to `acceptSandbox` (which folds EVERY
+    // TestFlight purchase and is refused by the CLI's production promotion
+    // gate). No default on purpose (Value.Default would materialize it into
+    // every RC manifest); absent = an empty list.
+    sandboxUsers: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 20 })),
   })),
   paypal: Type.Optional(Type.Object({
     clientIdRef: Type.String(),
@@ -1570,9 +1582,12 @@ export const PaymentsConfigSchema = Type.Object({
     //   { tier, durationDays }          (2026-09-25 F35+) a TIME-BOXED
     //     ENTITLEMENT: the buyer gets `tier` (a tierMap key — cross-checked
     //     below) for `durationDays`, as a charge-linked manual-style row that
-    //     STACKS on the user's live purchases of the same tier and is ENDED by
-    //     that charge's full refund / chargeback. No defaults in either shape,
-    //     so an existing manifest is byte-identical after Value.Default.
+    //     STACKS behind the user's live same-tier manual rows that have an end
+    //     (earlier passes AND comp grants since 2026-09-25 F38 — never a row
+    //     linked to the same charge, an open-ended grant or a provider
+    //     subscription) and is ENDED by that charge's full refund / chargeback.
+    //     No defaults in either shape, so an existing manifest is
+    //     byte-identical after Value.Default.
     productMap: Type.Record(Type.String(), Type.Union([
       Type.Object({
         creditType: Type.String({ minLength: 1 }),
@@ -1593,6 +1608,14 @@ export const PaymentsConfigSchema = Type.Object({
         creditType: Type.String({ minLength: 1 }),
         amount: Type.Integer({ minimum: 1 }),               // #128
         period: Type.String(),
+        // (2026-10-01 §4.13 W9) 'add' (the reader's default, today's
+        // behaviour) ADDS `amount` each period; 'reset' makes the period's
+        // grant REPLACE what is left: the unspent available balance of
+        // `creditType` is written off as one `expire` ledger row and `amount`
+        // granted, so the user starts every period with exactly `amount`
+        // (credits held by an in-flight job stay held). No schema default (it
+        // would materialize into every manifest carrying grants).
+        mode: Type.Optional(Type.Union([Type.Literal('add'), Type.Literal('reset')])),
       }))),
     })),
     // provider price/plan id → tier. A real subscription webhook carries the
@@ -1737,6 +1760,10 @@ export const FunctionsConfigSchema = Type.Object({
               retry: Type.Optional(Type.Object({
                 maxAttempts: Type.Integer({ minimum: 1, maximum: FN_RETRY_MAX_ATTEMPTS }),
               })),
+              // W7 (2026-10-01): cron only — 'skip' = a due tick fires nothing
+              // while the previous tick's run is still open (queued / running /
+              // retrying / waiting / delayed). Absent = 'allow' (every tick runs).
+              overlap: Type.Optional(Type.Union([Type.Literal('allow'), Type.Literal('skip')])),
             }),
             { maxItems: 8 },
           ),
@@ -1745,6 +1772,23 @@ export const FunctionsConfigSchema = Type.Object({
         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())), // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
+        // R1 (2026-10-01): the runtime settings this function's script was
+        // UPLOADED with — server-SET by the deploy pipeline (never authored),
+        // read back by the rollback re-upload so a restored script runs under
+        // the settings it was deployed and tested with, not today's. Absent =
+        // the legacy settings (@vxil/types FUNCTIONS_RUNTIME_LEGACY). Unbounded
+        // strings on purpose (the deploy writes them from the one constant).
+        // cpuMs (F2, 2026-10-01): the per-invoke CPU limit the script was
+        // uploaded with (limits.cpu_ms = min(declared limits.cpuMs, the tier's
+        // cpuMsPerInvoke, FN_MAX_CPU_MS)) — server-set; the nightly plan pass
+        // rewrites it after a tier change. Absent = the platform default.
+        runtime: Type.Optional(
+          Type.Object({
+            compatibilityDate: Type.String(),
+            compatibilityFlags: Type.Optional(Type.Array(Type.String())),
+            cpuMs: Type.Optional(Type.Number()),
+          }),
+        ),
         // 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
@@ -1952,6 +1996,25 @@ export const CONFIG_FLAG_CAP = 15;
 export const AUTH_HOOK_EVENTS = ['user.created', 'session.created', 'session.revoked', 'signin.failure'] as const;
 export type AuthHookEvent = (typeof AUTH_HOOK_EVENTS)[number];
 
+/** The events a `cmsHook` function binding may name — the closed union
+ * `packages/config` types on the `cmsHook` trigger, and the keys of the
+ * functions-v1 receiver's CMS_HOOK_EVENTS_FOR (beforeCreate → created,
+ * beforeUpdate → updated, beforeWrite → both). Omitted = beforeWrite. Anything
+ * else is refused at config write (E-CMSHOOK, 2026-10-01): an unknown name used
+ * to fall back to beforeWrite at delivery, so a typo like 'afterCreate' or
+ * 'beforeDelete' silently subscribed the function to creates AND updates.
+ * tests/ci/src/fn-binding-contracts.test.ts pins every copy to this list. */
+export const CMS_HOOK_EVENTS = ['beforeCreate', 'beforeUpdate', 'beforeWrite'] as const;
+export type CmsHookEvent = (typeof CMS_HOOK_EVENTS)[number];
+
+/** The ONE refusal text for an unknown cmsHook binding event (the config
+ * validator and the deploy route's early 422 both use it). */
+export function cmsHookEventError(event: unknown): string | null {
+  if (event === undefined) return null;
+  if (typeof event === 'string' && (CMS_HOOK_EVENTS as readonly string[]).includes(event)) return null;
+  return `a 'cmsHook' binding's event must be one of ${CMS_HOOK_EVENTS.join(' | ')} (or omitted = beforeWrite), not ${JSON.stringify(event)}`;
+}
+
 /** 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@]+$/;
@@ -2220,7 +2283,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
       provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown;
       ledger?: {
         productMap?: Record<string, { creditType?: string; tier?: string }>;
-        tierMap?: Record<string, { rank?: number; grants?: Array<{ creditType?: string }> }>;
+        tierMap?: Record<string, { rank?: number; grants?: Array<{ creditType?: string; period?: string; mode?: string }> }>;
         priceMap?: Record<string, string>;
       };
     };
@@ -2260,8 +2323,43 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
             `/ledger/tierMap/${tier}/grants/${i}/creditType: '${g.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`,
           );
         }
+        // (W9) 'reset' replaces the balance EACH PERIOD — a one-time grant has
+        // no period to reset, and a second grant of the same credit type in the
+        // same tier would be wiped (or wipe it) depending on array order.
+        if (g.mode === 'reset') {
+          if (g.period === 'once') {
+            ledgerErrs.push(`/ledger/tierMap/${tier}/grants/${i}/mode: 'reset' needs a recurring period (monthly or annual), not 'once'`);
+          }
+          const twin = (rule.grants ?? []).findIndex((o, j) => j !== i && o.creditType === g.creditType);
+          if (twin >= 0) {
+            ledgerErrs.push(
+              `/ledger/tierMap/${tier}/grants/${i}/mode: a 'reset' grant must be the only grant of '${g.creditType}' in the tier (grants/${twin} also grants it)`,
+            );
+          }
+        }
       });
     }
+    // (2026-10-01 review) A 'reset' grant writes off the WHOLE available balance
+    // of its credit type each period — purchased credits of that type included.
+    // A credit pack of a reset type would lose paid value at the next renewal,
+    // so it is refused here: keep packs on their own type and spend in order
+    // (`credit_types: ['plan', 'topup']`).
+    const resetBy = new Map<string, string>();
+    for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
+      (rule.grants ?? []).forEach((g, i) => {
+        if (g.mode === 'reset' && g.creditType && !resetBy.has(g.creditType)) {
+          resetBy.set(g.creditType, `/ledger/tierMap/${tier}/grants/${i}`);
+        }
+      });
+    }
+    for (const [productId, rule] of Object.entries(v.ledger?.productMap ?? {})) {
+      const by = rule.creditType ? resetBy.get(rule.creditType) : undefined;
+      if (by) {
+        ledgerErrs.push(
+          `/ledger/productMap/${productId}/creditType: '${rule.creditType}' is reset each period by ${by} (mode 'reset' writes off purchased credits of that type) — sell packs on their own credit type and spend with credit_types`,
+        );
+      }
+    }
     // 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
@@ -2430,7 +2528,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         string,
         {
           scriptRef?: string; scopes?: string[]; signature?: unknown;
-          bindings?: Array<{ kind: string; schedule?: string; collection?: string; event?: string; retry?: { maxAttempts?: number } }>;
+          bindings?: Array<{ kind: string; schedule?: string; collection?: string; event?: string; retry?: { maxAttempts?: number }; overlap?: string }>;
         }
       >;
     };
@@ -2446,6 +2544,9 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         if (b.kind === 'cron' && !b.schedule) {
           errs.push(`/functions/${name}/bindings/${i}: a 'cron' binding needs a schedule`);
         }
+        if (b.overlap !== undefined && b.kind !== 'cron') {
+          errs.push(`/functions/${name}/bindings/${i}: 'overlap' applies to cron bindings only (not '${b.kind}')`);
+        }
         // F33: retry is an opt-in for the platform-delivered event lanes only —
         // an http invoke returns its real status to its caller, and a cron
         // tick's retry would overlap the next tick.
@@ -2455,6 +2556,10 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         if (b.kind === 'cmsHook' && !b.collection) {
           errs.push(`/functions/${name}/bindings/${i}: a 'cmsHook' binding needs a collection`);
         }
+        // E-CMSHOOK: the CLOSED cmsHook event union — an unknown name is a 422
+        // at write time, never a silent created+updated subscription.
+        const cmsEventErr = b.kind === 'cmsHook' ? cmsHookEventError(b.event) : null;
+        if (cmsEventErr) errs.push(`/functions/${name}/bindings/${i}: ${cmsEventErr}`);
         // authHook: a CLOSED event union (F4-30) — reject typos at write time
         // so a binding never silently subscribes to nothing.
         if (b.kind === 'authHook' && b.event !== undefined && !(AUTH_HOOK_EVENTS as readonly string[]).includes(b.event)) {