@vxil/feature-configs 0.5.1 → 0.6.0

package/dist/apiState.d.ts

@@ -80,12 +80,14 @@ export interface LiveWebhookSubscription {
 }
 export interface WebhookSubscriptionPlan {
     create: DeclaredWebhookSubscription[];
-    /** the prefix SET differs — there is no update route, so delete+recreate (a
-     *  NEW sub_id, and the watermark restarts at "now"): destructive-shaped. */
-    recreate: Array<{
+    /** the prefix SET differs — `PATCH /v1/webhooks/subscriptions/:subId
+     *  { event_prefixes }` (2026-09-25) changes it in place: the sub_id and the
+     *  cursor are kept, so this is an ordinary update, not destructive-shaped
+     *  (before 2026-09-25 it was delete+recreate under --allow-destructive). */
+    update: Array<{
         sub_id: string;
         target_url: string;
-        declared: DeclaredWebhookSubscription;
+        event_prefixes: string[];
     }>;
     unchanged: string[];
     /** live rows the config does not declare, EXCLUDING the function-delivery

package/dist/apiState.js

@@ -93,7 +93,7 @@ function sameStringSet(a, b) {
     return A.size === B.size && [...A].every((x) => B.has(x));
 }
 export function planWebhookSubscriptions(declared, live) {
-    const plan = { create: [], recreate: [], unchanged: [], undeclared: [] };
+    const plan = { create: [], update: [], unchanged: [], undeclared: [] };
     const declaredUrls = new Set(declared.map((d) => d.target_url));
     const matched = new Set();
     for (const d of declared) {
@@ -105,14 +105,14 @@ export function planWebhookSubscriptions(declared, live) {
         }
         // Prefer an EXACT prefix-set match among duplicates (a hand-made row equal
         // to the declaration is adopted as-is — no churn); else the first row is
-        // the one recreated and the rest fall through as undeclared duplicates.
+        // the one updated in place and the rest fall through as undeclared duplicates.
         const exact = rows.find((l) => sameStringSet(l.event_prefixes ?? [], want));
         const chosen = exact ?? rows[0];
         matched.add(chosen.sub_id);
         if (exact)
             plan.unchanged.push(d.target_url);
         else
-            plan.recreate.push({ sub_id: chosen.sub_id, target_url: d.target_url, declared: d });
+            plan.update.push({ sub_id: chosen.sub_id, target_url: d.target_url, event_prefixes: [...want] });
     }
     for (const l of live) {
         if (matched.has(l.sub_id))

package/dist/index.d.ts

@@ -4,6 +4,12 @@ export * from './readmodels.js';
 export * from './apiState.js';
 export * from './canonicalJson.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
+/** F33 (2026-09-25): a function binding's `retry.maxAttempts` ceiling, and the
+ *  binding kinds that may carry `retry` — the platform-delivered event lanes
+ *  (an http invoke returns its own status; a cron tick's retry would overlap
+ *  the next tick). Read by the schema, the deploy clamp and the CLI. */
+export declare const FN_RETRY_MAX_ATTEMPTS = 5;
+export declare const FN_RETRY_BINDING_KINDS: ReadonlySet<string>;
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */
 export declare function isReservedCreditType(creditType: string): boolean;
@@ -39,6 +45,10 @@ export declare function validateNotificationOverrides(templates: {
         text?: string;
     }>>;
 } | undefined): string[];
+/** `notifications.ses.snsTopicArn` grammar: a plain SNS topic ARN (the
+ *  `aws-cn` / `aws-us-gov` partitions included). Mirrored by SNS_TOPIC_ARN_RE
+ *  in the notifications worker's snsIntake.ts. */
+export declare const SNS_TOPIC_ARN_PATTERN = "^arn:aws(-[a-z]+)?:sns:[a-z0-9-]+:\\d{12}:[A-Za-z0-9_-]{1,256}$";
 /** AWS region grammar for `notifications.ses.region` (`us-east-1`,
  * `eu-central-1`, `ap-southeast-2`, `us-gov-west-1`, …): two-letter partition,
  * one or more lowercase words, a single digit. Pinned as a pattern rather than
@@ -57,6 +67,7 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
         region: import("@sinclair/typebox").TString;
         accessKeyIdRef: import("@sinclair/typebox").TString;
         secretAccessKeyRef: import("@sinclair/typebox").TString;
+        snsTopicArn: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     defaultLocale: import("@sinclair/typebox").TString;
     retry: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
@@ -105,6 +116,49 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
 export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
 /** The §11b.5 broadcast bag as persisted (present ⇒ leaf defaults applied). */
 export type BroadcastConfig = NonNullable<NotificationsConfig['broadcast']>;
+/** Generation-lifecycle config defaults (jobs.md §11 / §5 ≤15-flag budget). */
+export declare const GENERATION_DEFAULTS: {
+    /** per-tenant in-flight generation cap (separate budget from queue jobs) */
+    readonly maxConcurrent: 20;
+    /** default expiry/timeout when the descriptor omits one — 5 min */
+    readonly defaultTimeoutMs: number;
+    /** hard ceiling a tenant-supplied timeout is clamped to — 1 h */
+    readonly maxTimeoutMs: number;
+    /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
+    readonly pollMaxAttempts: 60;
+    /** MANDATORY per-hold cap on a `reserve_credits.amount` (clamped, never rejected) */
+    readonly maxReserveCredits: 1000;
+    /** MANDATORY per-tenant ceiling on the sum of un-settled provisional holds */
+    readonly maxOutstandingReserveCredits: 100000;
+};
+/** The inclusive [min, max] each `generation` leaf is clamped to — by the
+ *  schema at config-write time and by jobs-v1 at read time. */
+export declare const GENERATION_BOUNDS: {
+    readonly maxConcurrent: {
+        readonly min: 1;
+        readonly max: 200;
+    };
+    readonly defaultTimeoutMs: {
+        readonly min: 1000;
+        readonly max: 3600000;
+    };
+    readonly maxTimeoutMs: {
+        readonly min: 1000;
+        readonly max: 3600000;
+    };
+    readonly pollMaxAttempts: {
+        readonly min: 1;
+        readonly max: 1000;
+    };
+    readonly maxReserveCredits: {
+        readonly min: 1;
+        readonly max: 1000000;
+    };
+    readonly maxOutstandingReserveCredits: {
+        readonly min: 1;
+        readonly max: 100000000;
+    };
+};
 export declare const JobsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     retry: import("@sinclair/typebox").TObject<{
@@ -615,11 +669,14 @@ export declare const PaymentsConfigSchema: import("@sinclair/typebox").TObject<{
         trialDays: import("@sinclair/typebox").TInteger;
     }>;
     ledger: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        productMap: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+        productMap: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
             creditType: import("@sinclair/typebox").TString;
             amount: import("@sinclair/typebox").TInteger;
             period: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"once">, import("@sinclair/typebox").TLiteral<"monthly">, import("@sinclair/typebox").TLiteral<"annual">]>;
-        }>>;
+        }>, import("@sinclair/typebox").TObject<{
+            tier: import("@sinclair/typebox").TString;
+            durationDays: import("@sinclair/typebox").TInteger;
+        }>]>>;
         tierMap: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
             entitlements: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
             quotas: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TInteger>;
@@ -658,6 +715,9 @@ export declare const FunctionsConfigSchema: import("@sinclair/typebox").TObject<
             source: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             collection: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             event: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            retry: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                maxAttempts: import("@sinclair/typebox").TInteger;
+            }>>;
         }>>>;
         scriptRef: import("@sinclair/typebox").TString;
         scopes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;

package/dist/index.js

@@ -36,6 +36,12 @@ if (!FormatRegistry.Has('email')) {
 // config-write gate AND payments-v1 import) so the runtime choke point and the
 // config-write refusal share ONE list. payments-v1/core.ts re-exports these.
 export const RESERVED_CREDIT_TYPES = new Set(['fn_cpu_ms']);
+/** F33 (2026-09-25): a function binding's `retry.maxAttempts` ceiling, and the
+ *  binding kinds that may carry `retry` — the platform-delivered event lanes
+ *  (an http invoke returns its own status; a cron tick's retry would overlap
+ *  the next tick). Read by the schema, the deploy clamp and the CLI. */
+export const FN_RETRY_MAX_ATTEMPTS = 5;
+export const FN_RETRY_BINDING_KINDS = new Set(['queue', 'webhook', 'cmsHook', 'authHook']);
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */
 export function isReservedCreditType(creditType) {
@@ -148,6 +154,10 @@ export function validateNotificationOverrides(templates) {
     }
     return errs;
 }
+/** `notifications.ses.snsTopicArn` grammar: a plain SNS topic ARN (the
+ *  `aws-cn` / `aws-us-gov` partitions included). Mirrored by SNS_TOPIC_ARN_RE
+ *  in the notifications worker's snsIntake.ts. */
+export const SNS_TOPIC_ARN_PATTERN = '^arn:aws(-[a-z]+)?:sns:[a-z0-9-]+:\\d{12}:[A-Za-z0-9_-]{1,256}$';
 /** AWS region grammar for `notifications.ses.region` (`us-east-1`,
  * `eu-central-1`, `ap-southeast-2`, `us-gov-west-1`, …): two-letter partition,
  * one or more lowercase words, a single digit. Pinned as a pattern rather than
@@ -190,6 +200,13 @@ export const NotificationsConfigSchema = Type.Object({
         region: Type.String({ pattern: SES_REGION_PATTERN, maxLength: 32 }),
         accessKeyIdRef: Type.String({ minLength: 1 }),
         secretAccessKeyRef: Type.String({ minLength: 1 }),
+        // Bounce/complaint intake (2026-09-25): the SNS topic SES publishes its
+        // bounce/complaint events to; its HTTPS subscription posts to the worker's
+        // `/v1/notifications/webhooks/ses/<tenant>/<tag>` route, which accepts a
+        // message ONLY when its TopicArn equals this value (fail closed: unset ⇒
+        // the lane answers 404). Plain config, not a secret — the AWS signature is
+        // the proof. Inside the Optional bag ⇒ zero leaf cost.
+        snsTopicArn: Type.Optional(Type.String({ pattern: SNS_TOPIC_ARN_PATTERN, maxLength: 320 })),
     })),
     defaultLocale: Type.String({ default: 'en-US' }),
     // nested objects carry `default: {}` so Value.Default can materialize them
@@ -272,6 +289,41 @@ export const NotificationsConfigSchema = Type.Object({
         freqCapPerUserPerDay: Type.Integer({ default: 5, minimum: 0 }),
     })),
 });
+// ── jobs `generation` block: the ONE declaration of its defaults and bounds ──
+// (roadmap §4.10, 2026-09-25 — "dropping the jobs-v1 GENERATION_DEFAULTS
+// copy"). The JobsConfigSchema `generation` leaf reads these for its
+// `default` / `minimum` / `maximum`, and workers/jobs-v1/src/generation.ts
+// imports them (jobs-v1 already depends on @vxil/feature-configs; this package
+// has no @vxil/types dependency, so the shared value lives here — the
+// RESERVED_CREDIT_TYPES precedent). A future edit changes one object; the
+// feature-configs unit test pins schema ↔ constant, and the CI gate
+// tests/ci/src/generation-defaults-single-source.test.ts pins that no second
+// object-literal declaration of the constant reappears anywhere.
+/** Generation-lifecycle config defaults (jobs.md §11 / §5 ≤15-flag budget). */
+export const GENERATION_DEFAULTS = {
+    /** per-tenant in-flight generation cap (separate budget from queue jobs) */
+    maxConcurrent: 20,
+    /** default expiry/timeout when the descriptor omits one — 5 min */
+    defaultTimeoutMs: 5 * 60_000,
+    /** hard ceiling a tenant-supplied timeout is clamped to — 1 h */
+    maxTimeoutMs: 60 * 60_000,
+    /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
+    pollMaxAttempts: 60,
+    /** MANDATORY per-hold cap on a `reserve_credits.amount` (clamped, never rejected) */
+    maxReserveCredits: 1_000,
+    /** MANDATORY per-tenant ceiling on the sum of un-settled provisional holds */
+    maxOutstandingReserveCredits: 100_000,
+};
+/** The inclusive [min, max] each `generation` leaf is clamped to — by the
+ *  schema at config-write time and by jobs-v1 at read time. */
+export const GENERATION_BOUNDS = {
+    maxConcurrent: { min: 1, max: 200 },
+    defaultTimeoutMs: { min: 1_000, max: 3_600_000 },
+    maxTimeoutMs: { min: 1_000, max: 3_600_000 },
+    pollMaxAttempts: { min: 1, max: 1_000 },
+    maxReserveCredits: { min: 1, max: 1_000_000 },
+    maxOutstandingReserveCredits: { min: 1, max: 100_000_000 },
+};
 export const JobsConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
     retry: Type.Object({ defaultMaxAttempts: Type.Integer({ default: 5, minimum: 1, maximum: 20 }) }, { default: {} }),
@@ -287,31 +339,32 @@ export const JobsConfigSchema = Type.Object({
     dlqDailyQuota: Type.Integer({ default: 0, minimum: 0, maximum: 100_000 }),
     schedules: Type.Object({ maxPerTenant: Type.Integer({ default: 50, minimum: 1, maximum: 1000 }) }, { default: {} }),
     concurrency: Type.Object({ maxConcurrent: Type.Integer({ default: 10, minimum: 1, maximum: 100 }) }, { default: {} }),
-    // 2.F6 generation lifecycle knobs (jobs.md §11) — mirrors the worker-local
-    // GENERATION_DEFAULTS in workers/jobs-v1/src/generation.ts (its
-    // resolveGenerationConfig reads `loaded.generation` and clamps to these same
-    // bounds when a field is absent).
+    // 2.F6 generation lifecycle knobs (jobs.md §11). The defaults and bounds are
+    // declared ONCE, as GENERATION_DEFAULTS / GENERATION_BOUNDS below this schema
+    // (2026-09-25): jobs-v1's resolveGenerationConfig imports them and clamps a
+    // pre-fold manifest to the same numbers — a hand-mirrored copy used to live
+    // in workers/jobs-v1/src/generation.ts.
     generation: Type.Object({
         /** per-tenant in-flight generation cap (separate budget from queue jobs) */
-        maxConcurrent: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
+        maxConcurrent: Type.Integer({ default: GENERATION_DEFAULTS.maxConcurrent, minimum: GENERATION_BOUNDS.maxConcurrent.min, maximum: GENERATION_BOUNDS.maxConcurrent.max }),
         /** default expiry/timeout when the descriptor omits one */
-        defaultTimeoutMs: Type.Integer({ default: 300_000, minimum: 1_000, maximum: 3_600_000 }),
+        defaultTimeoutMs: Type.Integer({ default: GENERATION_DEFAULTS.defaultTimeoutMs, minimum: GENERATION_BOUNDS.defaultTimeoutMs.min, maximum: GENERATION_BOUNDS.defaultTimeoutMs.max }),
         /** hard ceiling a tenant-supplied timeout is clamped to */
-        maxTimeoutMs: Type.Integer({ default: 3_600_000, minimum: 1_000, maximum: 3_600_000 }),
+        maxTimeoutMs: Type.Integer({ default: GENERATION_DEFAULTS.maxTimeoutMs, minimum: GENERATION_BOUNDS.maxTimeoutMs.min, maximum: GENERATION_BOUNDS.maxTimeoutMs.max }),
         /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
-        pollMaxAttempts: Type.Integer({ default: 60, minimum: 1, maximum: 1_000 }),
+        pollMaxAttempts: Type.Integer({ default: GENERATION_DEFAULTS.pollMaxAttempts, minimum: GENERATION_BOUNDS.pollMaxAttempts.min, maximum: GENERATION_BOUNDS.pollMaxAttempts.max }),
         /** MANDATORY per-hold cap on a generation `reserve_credits.amount` (jobs.md
          * §11.8). Every requested amount is CLAMPED to this (never rejected) — a
          * conservative default so an untrusted deployed function that carries a
          * reserve block can never hold more than a bounded amount per run without
          * any tenant action. */
-        maxReserveCredits: Type.Integer({ default: 1_000, minimum: 1, maximum: 1_000_000 }),
+        maxReserveCredits: Type.Integer({ default: GENERATION_DEFAULTS.maxReserveCredits, minimum: GENERATION_BOUNDS.maxReserveCredits.min, maximum: GENERATION_BOUNDS.maxReserveCredits.max }),
         /** MANDATORY per-tenant ceiling on the SUM of un-settled provisional
          * reserve holds across all in-flight generation runs (jobs.md §11.8): a
          * reserve whose amount would push the tenant's outstanding-holds total over
          * this is rejected 429, so a runaway function cannot hold every user at
          * once. Defaulted so no tenant action is required to be safe. */
-        maxOutstandingReserveCredits: Type.Integer({ default: 100_000, minimum: 1, maximum: 100_000_000 }),
+        maxOutstandingReserveCredits: Type.Integer({ default: GENERATION_DEFAULTS.maxOutstandingReserveCredits, minimum: GENERATION_BOUNDS.maxOutstandingReserveCredits.min, maximum: GENERATION_BOUNDS.maxOutstandingReserveCredits.max }),
     }, { default: {} }),
 });
 // One social-provider's BYO credential block. The *Ref fields are POINTERS into
@@ -703,9 +756,9 @@ export const WebhooksConfigSchema = Type.Object({
     })),
     // DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23): the tenant's OUTBOUND
     // subscriptions as config. Keyed by `target_url` — the only stable identity a
-    // subscription has (there is no name column and no update route, so a changed
-    // prefix set is delete+recreate, exactly what the function-trigger reconciler
-    // does). `vxil push` / `POST /v1/apply` converge public.webhook_subscriptions
+    // subscription has (there is no name column). A changed prefix set is an
+    // in-place update — PATCH /v1/webhooks/subscriptions/:subId, same sub_id and
+    // cursor (2026-09-25). `vxil push` / `POST /v1/apply` converge public.webhook_subscriptions
     // onto this list (handlers/apiState.ts); undeclared live rows are LEFT and
     // reported (deleted only under --allow-destructive). Rows on the platform's
     // signed function-delivery lanes (/v1/internal/fn/…) are NEVER declared here
@@ -1191,12 +1244,27 @@ export const PaymentsConfigSchema = Type.Object({
     // analyzer's top level; productMap/tierMap are tenant-supplied Type.Record
     // MAPS (one typed leaf each), so catalog size never inflates the flag count.
     ledger: Type.Optional(Type.Object({
-        productMap: Type.Record(Type.String(), Type.Object({
-            creditType: Type.String({ minLength: 1 }),
-            amount: Type.Integer({ minimum: 1 }), // #128: a grant only ADDS
-            period: Type.Union([Type.Literal('once'), Type.Literal('monthly'),
-                Type.Literal('annual')]),
-        })),
+        // product_id → what the purchase GRANTS. ONE Type.Record leaf (the rag
+        // `boosts` Record-of-Union precedent) with two rule shapes:
+        //   { creditType, amount, period }  a credit grant (the original rule)
+        //   { 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.
+        productMap: Type.Record(Type.String(), Type.Union([
+            Type.Object({
+                creditType: Type.String({ minLength: 1 }),
+                amount: Type.Integer({ minimum: 1 }), // #128: a grant only ADDS
+                period: Type.Union([Type.Literal('once'), Type.Literal('monthly'),
+                    Type.Literal('annual')]),
+            }),
+            Type.Object({
+                tier: Type.String({ minLength: 1 }),
+                durationDays: Type.Integer({ minimum: 1, maximum: 3650 }),
+            }),
+        ])),
         tierMap: Type.Record(Type.String(), Type.Object({
             entitlements: Type.Array(Type.String()),
             quotas: Type.Record(Type.String(), Type.Integer({ minimum: 0 })), // #128: no negative quota
@@ -1319,6 +1387,15 @@ export const FunctionsConfigSchema = Type.Object({
             source: Type.Optional(Type.String()), // webhook/queue: source/queue id
             collection: Type.Optional(Type.String()), // cmsHook: the CMS collection slug
             event: Type.Optional(Type.String()), // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
+            // F33 (2026-09-25): the per-binding opt-in to re-delivery on
+            // queue / webhook / cmsHook / authHook (the cross-field rule
+            // rejects it on http / cron). Absent = the ACK-200 default. The
+            // receiver answers a failed attempt as an enveloped 503 (ladder)
+            // and the last one as a terminal 409 (dead + job.dead_lettered);
+            // effective attempts = min(maxAttempts, jobs.retry.defaultMaxAttempts).
+            retry: Type.Optional(Type.Object({
+                maxAttempts: Type.Integer({ minimum: 1, maximum: FN_RETRY_MAX_ATTEMPTS }),
+            })),
         }), { 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)
@@ -1746,10 +1823,17 @@ export function validateFeatureConfig(feature, raw) {
         // user, running vxil-billed functions for free (audit F2). Rejected at write
         // time so the tenant gets a clear `vxil push` error, not a silent runtime skip.
         const ledgerErrs = [];
+        const tierKeysForProducts = new Set(Object.keys(v.ledger?.tierMap ?? {}));
         for (const [productId, rule] of Object.entries(v.ledger?.productMap ?? {})) {
             if (rule.creditType && isReservedCreditType(rule.creditType)) {
                 ledgerErrs.push(`/ledger/productMap/${productId}/creditType: '${rule.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`);
             }
+            // (2026-09-25 F35+) an entitlement rule must name a declared tier — the
+            // write-time mirror of the runtime's unknown-tier refusal (a purchase for
+            // a tier nobody declared would land the delivery `error`).
+            if (rule.tier !== undefined && !tierKeysForProducts.has(rule.tier)) {
+                ledgerErrs.push(`/ledger/productMap/${productId}/tier: '${rule.tier}' is not a ledger.tierMap key`);
+            }
         }
         for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
             (rule.grants ?? []).forEach((g, i) => {
@@ -1929,6 +2013,12 @@ export function validateFeatureConfig(feature, raw) {
                 if (b.kind === 'cron' && !b.schedule) {
                     errs.push(`/functions/${name}/bindings/${i}: a 'cron' binding needs a schedule`);
                 }
+                // 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.
+                if (b.retry !== undefined && !FN_RETRY_BINDING_KINDS.has(b.kind)) {
+                    errs.push(`/functions/${name}/bindings/${i}: 'retry' applies to ${[...FN_RETRY_BINDING_KINDS].join(' | ')} bindings only (not '${b.kind}')`);
+                }
                 if (b.kind === 'cmsHook' && !b.collection) {
                     errs.push(`/functions/${name}/bindings/${i}: a 'cmsHook' binding needs a collection`);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.5.1",
+  "version": "0.6.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/apiState.ts

@@ -9,7 +9,7 @@
 // by `vxil push` and `POST /v1/apply`:
 //
 //   rate-limits.policies[]     — keyed by `name`      (POST/PUT/DELETE /v1/rate-limits/policies)
-//   webhooks.subscriptions[]   — keyed by `target_url` (POST/DELETE /v1/webhooks/subscriptions)
+//   webhooks.subscriptions[]   — keyed by `target_url` (POST/PATCH/DELETE /v1/webhooks/subscriptions)
 //   ai.templates[]             — keyed by `template`   (POST /v1/ai/templates, by content hash)
 //
 // ONE WRITER PER DATUM, AND THE WRITER IS THE REPOSITORY. The planner below is
@@ -27,9 +27,11 @@
 // LEFT IN PLACE and reported as `undeclared` — deleted only when the caller
 // passes allow-destructive — so adopting a block on an existing tenant is a
 // report, never a wipe. A change that can only be applied by delete+recreate
-// (a policy's `key_template`; a subscription's prefix set) is likewise
-// destructive-SHAPED: it changes the row's id, which a caller may have
-// cached, so it is reported and applied only under the same ack.
+// (a policy's `key_template`) is likewise destructive-SHAPED: it changes the
+// row's id, which a caller may have cached, so it is reported and applied
+// only under the same ack. A subscription's prefix set used to be one of
+// those; since 2026-09-25 the PATCH route changes it in place (same sub_id,
+// same cursor), so it is an ordinary `update`.
 //
 // Two shapes this file deliberately does NOT cover, with the reason:
 //   notifications.templates — templates are CODE with per-locale `overrides`
@@ -161,9 +163,11 @@ export interface LiveWebhookSubscription {
 
 export interface WebhookSubscriptionPlan {
   create: DeclaredWebhookSubscription[];
-  /** the prefix SET differs — there is no update route, so delete+recreate (a
-   *  NEW sub_id, and the watermark restarts at "now"): destructive-shaped. */
-  recreate: Array<{ sub_id: string; target_url: string; declared: DeclaredWebhookSubscription }>;
+  /** the prefix SET differs — `PATCH /v1/webhooks/subscriptions/:subId
+   *  { event_prefixes }` (2026-09-25) changes it in place: the sub_id and the
+   *  cursor are kept, so this is an ordinary update, not destructive-shaped
+   *  (before 2026-09-25 it was delete+recreate under --allow-destructive). */
+  update: Array<{ sub_id: string; target_url: string; event_prefixes: string[] }>;
   unchanged: string[];
   /** live rows the config does not declare, EXCLUDING the function-delivery
    *  lanes (those derive from the functions manifest) — left in place by default */
@@ -178,7 +182,7 @@ function sameStringSet(a: readonly string[], b: readonly string[]): boolean {
 export function planWebhookSubscriptions(
   declared: readonly DeclaredWebhookSubscription[], live: readonly LiveWebhookSubscription[],
 ): WebhookSubscriptionPlan {
-  const plan: WebhookSubscriptionPlan = { create: [], recreate: [], unchanged: [], undeclared: [] };
+  const plan: WebhookSubscriptionPlan = { create: [], update: [], unchanged: [], undeclared: [] };
   const declaredUrls = new Set(declared.map((d) => d.target_url));
   const matched = new Set<string>();
   for (const d of declared) {
@@ -187,12 +191,12 @@ export function planWebhookSubscriptions(
     if (rows.length === 0) { plan.create.push(d); continue; }
     // Prefer an EXACT prefix-set match among duplicates (a hand-made row equal
     // to the declaration is adopted as-is — no churn); else the first row is
-    // the one recreated and the rest fall through as undeclared duplicates.
+    // the one updated in place and the rest fall through as undeclared duplicates.
     const exact = rows.find((l) => sameStringSet(l.event_prefixes ?? [], want));
     const chosen = exact ?? rows[0]!;
     matched.add(chosen.sub_id);
     if (exact) plan.unchanged.push(d.target_url);
-    else plan.recreate.push({ sub_id: chosen.sub_id, target_url: d.target_url, declared: d });
+    else plan.update.push({ sub_id: chosen.sub_id, target_url: d.target_url, event_prefixes: [...want] });
   }
   for (const l of live) {
     if (matched.has(l.sub_id)) continue;

package/src/index.ts

@@ -40,6 +40,13 @@ if (!FormatRegistry.Has('email')) {
 // config-write refusal share ONE list. payments-v1/core.ts re-exports these.
 export const RESERVED_CREDIT_TYPES: ReadonlySet<string> = new Set<string>(['fn_cpu_ms']);
 
+/** F33 (2026-09-25): a function binding's `retry.maxAttempts` ceiling, and the
+ *  binding kinds that may carry `retry` — the platform-delivered event lanes
+ *  (an http invoke returns its own status; a cron tick's retry would overlap
+ *  the next tick). Read by the schema, the deploy clamp and the CLI. */
+export const FN_RETRY_MAX_ATTEMPTS = 5;
+export const FN_RETRY_BINDING_KINDS: ReadonlySet<string> = new Set(['queue', 'webhook', 'cmsHook', 'authHook']);
+
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */
 export function isReservedCreditType(creditType: string): boolean {
@@ -161,6 +168,11 @@ export function validateNotificationOverrides(
   return errs;
 }
 
+/** `notifications.ses.snsTopicArn` grammar: a plain SNS topic ARN (the
+ *  `aws-cn` / `aws-us-gov` partitions included). Mirrored by SNS_TOPIC_ARN_RE
+ *  in the notifications worker's snsIntake.ts. */
+export const SNS_TOPIC_ARN_PATTERN = '^arn:aws(-[a-z]+)?:sns:[a-z0-9-]+:\\d{12}:[A-Za-z0-9_-]{1,256}$';
+
 /** AWS region grammar for `notifications.ses.region` (`us-east-1`,
  * `eu-central-1`, `ap-southeast-2`, `us-gov-west-1`, …): two-letter partition,
  * one or more lowercase words, a single digit. Pinned as a pattern rather than
@@ -204,6 +216,13 @@ export const NotificationsConfigSchema = Type.Object({
     region: Type.String({ pattern: SES_REGION_PATTERN, maxLength: 32 }),
     accessKeyIdRef: Type.String({ minLength: 1 }),
     secretAccessKeyRef: Type.String({ minLength: 1 }),
+    // Bounce/complaint intake (2026-09-25): the SNS topic SES publishes its
+    // bounce/complaint events to; its HTTPS subscription posts to the worker's
+    // `/v1/notifications/webhooks/ses/<tenant>/<tag>` route, which accepts a
+    // message ONLY when its TopicArn equals this value (fail closed: unset ⇒
+    // the lane answers 404). Plain config, not a secret — the AWS signature is
+    // the proof. Inside the Optional bag ⇒ zero leaf cost.
+    snsTopicArn: Type.Optional(Type.String({ pattern: SNS_TOPIC_ARN_PATTERN, maxLength: 320 })),
   })),
   defaultLocale: Type.String({ default: 'en-US' }),
   // nested objects carry `default: {}` so Value.Default can materialize them
@@ -315,6 +334,44 @@ export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
 /** The §11b.5 broadcast bag as persisted (present ⇒ leaf defaults applied). */
 export type BroadcastConfig = NonNullable<NotificationsConfig['broadcast']>;
 
+// ── jobs `generation` block: the ONE declaration of its defaults and bounds ──
+// (roadmap §4.10, 2026-09-25 — "dropping the jobs-v1 GENERATION_DEFAULTS
+// copy"). The JobsConfigSchema `generation` leaf reads these for its
+// `default` / `minimum` / `maximum`, and workers/jobs-v1/src/generation.ts
+// imports them (jobs-v1 already depends on @vxil/feature-configs; this package
+// has no @vxil/types dependency, so the shared value lives here — the
+// RESERVED_CREDIT_TYPES precedent). A future edit changes one object; the
+// feature-configs unit test pins schema ↔ constant, and the CI gate
+// tests/ci/src/generation-defaults-single-source.test.ts pins that no second
+// object-literal declaration of the constant reappears anywhere.
+
+/** Generation-lifecycle config defaults (jobs.md §11 / §5 ≤15-flag budget). */
+export const GENERATION_DEFAULTS = {
+  /** per-tenant in-flight generation cap (separate budget from queue jobs) */
+  maxConcurrent: 20,
+  /** default expiry/timeout when the descriptor omits one — 5 min */
+  defaultTimeoutMs: 5 * 60_000,
+  /** hard ceiling a tenant-supplied timeout is clamped to — 1 h */
+  maxTimeoutMs: 60 * 60_000,
+  /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
+  pollMaxAttempts: 60,
+  /** MANDATORY per-hold cap on a `reserve_credits.amount` (clamped, never rejected) */
+  maxReserveCredits: 1_000,
+  /** MANDATORY per-tenant ceiling on the sum of un-settled provisional holds */
+  maxOutstandingReserveCredits: 100_000,
+} as const;
+
+/** The inclusive [min, max] each `generation` leaf is clamped to — by the
+ *  schema at config-write time and by jobs-v1 at read time. */
+export const GENERATION_BOUNDS = {
+  maxConcurrent: { min: 1, max: 200 },
+  defaultTimeoutMs: { min: 1_000, max: 3_600_000 },
+  maxTimeoutMs: { min: 1_000, max: 3_600_000 },
+  pollMaxAttempts: { min: 1, max: 1_000 },
+  maxReserveCredits: { min: 1, max: 1_000_000 },
+  maxOutstandingReserveCredits: { min: 1, max: 100_000_000 },
+} as const satisfies Record<keyof typeof GENERATION_DEFAULTS, { min: number; max: number }>;
+
 export const JobsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
   retry: Type.Object(
@@ -342,32 +399,33 @@ export const JobsConfigSchema = Type.Object({
     { maxConcurrent: Type.Integer({ default: 10, minimum: 1, maximum: 100 }) },
     { default: {} },
   ),
-  // 2.F6 generation lifecycle knobs (jobs.md §11) — mirrors the worker-local
-  // GENERATION_DEFAULTS in workers/jobs-v1/src/generation.ts (its
-  // resolveGenerationConfig reads `loaded.generation` and clamps to these same
-  // bounds when a field is absent).
+  // 2.F6 generation lifecycle knobs (jobs.md §11). The defaults and bounds are
+  // declared ONCE, as GENERATION_DEFAULTS / GENERATION_BOUNDS below this schema
+  // (2026-09-25): jobs-v1's resolveGenerationConfig imports them and clamps a
+  // pre-fold manifest to the same numbers — a hand-mirrored copy used to live
+  // in workers/jobs-v1/src/generation.ts.
   generation: Type.Object(
     {
       /** per-tenant in-flight generation cap (separate budget from queue jobs) */
-      maxConcurrent: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
+      maxConcurrent: Type.Integer({ default: GENERATION_DEFAULTS.maxConcurrent, minimum: GENERATION_BOUNDS.maxConcurrent.min, maximum: GENERATION_BOUNDS.maxConcurrent.max }),
       /** default expiry/timeout when the descriptor omits one */
-      defaultTimeoutMs: Type.Integer({ default: 300_000, minimum: 1_000, maximum: 3_600_000 }),
+      defaultTimeoutMs: Type.Integer({ default: GENERATION_DEFAULTS.defaultTimeoutMs, minimum: GENERATION_BOUNDS.defaultTimeoutMs.min, maximum: GENERATION_BOUNDS.defaultTimeoutMs.max }),
       /** hard ceiling a tenant-supplied timeout is clamped to */
-      maxTimeoutMs: Type.Integer({ default: 3_600_000, minimum: 1_000, maximum: 3_600_000 }),
+      maxTimeoutMs: Type.Integer({ default: GENERATION_DEFAULTS.maxTimeoutMs, minimum: GENERATION_BOUNDS.maxTimeoutMs.min, maximum: GENERATION_BOUNDS.maxTimeoutMs.max }),
       /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
-      pollMaxAttempts: Type.Integer({ default: 60, minimum: 1, maximum: 1_000 }),
+      pollMaxAttempts: Type.Integer({ default: GENERATION_DEFAULTS.pollMaxAttempts, minimum: GENERATION_BOUNDS.pollMaxAttempts.min, maximum: GENERATION_BOUNDS.pollMaxAttempts.max }),
       /** MANDATORY per-hold cap on a generation `reserve_credits.amount` (jobs.md
        * §11.8). Every requested amount is CLAMPED to this (never rejected) — a
        * conservative default so an untrusted deployed function that carries a
        * reserve block can never hold more than a bounded amount per run without
        * any tenant action. */
-      maxReserveCredits: Type.Integer({ default: 1_000, minimum: 1, maximum: 1_000_000 }),
+      maxReserveCredits: Type.Integer({ default: GENERATION_DEFAULTS.maxReserveCredits, minimum: GENERATION_BOUNDS.maxReserveCredits.min, maximum: GENERATION_BOUNDS.maxReserveCredits.max }),
       /** MANDATORY per-tenant ceiling on the SUM of un-settled provisional
        * reserve holds across all in-flight generation runs (jobs.md §11.8): a
        * reserve whose amount would push the tenant's outstanding-holds total over
        * this is rejected 429, so a runaway function cannot hold every user at
        * once. Defaulted so no tenant action is required to be safe. */
-      maxOutstandingReserveCredits: Type.Integer({ default: 100_000, minimum: 1, maximum: 100_000_000 }),
+      maxOutstandingReserveCredits: Type.Integer({ default: GENERATION_DEFAULTS.maxOutstandingReserveCredits, minimum: GENERATION_BOUNDS.maxOutstandingReserveCredits.min, maximum: GENERATION_BOUNDS.maxOutstandingReserveCredits.max }),
     },
     { default: {} },
   ),
@@ -837,9 +895,9 @@ export const WebhooksConfigSchema = Type.Object({
   })),
   // DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23): the tenant's OUTBOUND
   // subscriptions as config. Keyed by `target_url` — the only stable identity a
-  // subscription has (there is no name column and no update route, so a changed
-  // prefix set is delete+recreate, exactly what the function-trigger reconciler
-  // does). `vxil push` / `POST /v1/apply` converge public.webhook_subscriptions
+  // subscription has (there is no name column). A changed prefix set is an
+  // in-place update — PATCH /v1/webhooks/subscriptions/:subId, same sub_id and
+  // cursor (2026-09-25). `vxil push` / `POST /v1/apply` converge public.webhook_subscriptions
   // onto this list (handlers/apiState.ts); undeclared live rows are LEFT and
   // reported (deleted only under --allow-destructive). Rows on the platform's
   // signed function-delivery lanes (/v1/internal/fn/…) are NEVER declared here
@@ -1506,12 +1564,27 @@ export const PaymentsConfigSchema = Type.Object({
   // analyzer's top level; productMap/tierMap are tenant-supplied Type.Record
   // MAPS (one typed leaf each), so catalog size never inflates the flag count.
   ledger: Type.Optional(Type.Object({
-    productMap: Type.Record(Type.String(), Type.Object({   // product_id → grant rule
-      creditType: Type.String({ minLength: 1 }),
-      amount: Type.Integer({ minimum: 1 }),                 // #128: a grant only ADDS
-      period: Type.Union([Type.Literal('once'), Type.Literal('monthly'),
-                          Type.Literal('annual')]),
-    })),
+    // product_id → what the purchase GRANTS. ONE Type.Record leaf (the rag
+    // `boosts` Record-of-Union precedent) with two rule shapes:
+    //   { creditType, amount, period }  a credit grant (the original rule)
+    //   { 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.
+    productMap: Type.Record(Type.String(), Type.Union([
+      Type.Object({
+        creditType: Type.String({ minLength: 1 }),
+        amount: Type.Integer({ minimum: 1 }),                 // #128: a grant only ADDS
+        period: Type.Union([Type.Literal('once'), Type.Literal('monthly'),
+                            Type.Literal('annual')]),
+      }),
+      Type.Object({
+        tier: Type.String({ minLength: 1 }),
+        durationDays: Type.Integer({ minimum: 1, maximum: 3650 }),
+      }),
+    ])),
     tierMap: Type.Record(Type.String(), Type.Object({      // tier → entitlement/quota/grant
       entitlements: Type.Array(Type.String()),
       quotas: Type.Record(Type.String(), Type.Integer({ minimum: 0 })), // #128: no negative quota
@@ -1655,6 +1728,15 @@ export const FunctionsConfigSchema = Type.Object({
               source: Type.Optional(Type.String()), // webhook/queue: source/queue id
               collection: Type.Optional(Type.String()), // cmsHook: the CMS collection slug
               event: Type.Optional(Type.String()), // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
+              // F33 (2026-09-25): the per-binding opt-in to re-delivery on
+              // queue / webhook / cmsHook / authHook (the cross-field rule
+              // rejects it on http / cron). Absent = the ACK-200 default. The
+              // receiver answers a failed attempt as an enveloped 503 (ladder)
+              // and the last one as a terminal 409 (dead + job.dead_lettered);
+              // effective attempts = min(maxAttempts, jobs.retry.defaultMaxAttempts).
+              retry: Type.Optional(Type.Object({
+                maxAttempts: Type.Integer({ minimum: 1, maximum: FN_RETRY_MAX_ATTEMPTS }),
+              })),
             }),
             { maxItems: 8 },
           ),
@@ -2105,7 +2187,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     const v = withDefaults as {
       provider?: string;
       resendApiKeyRef?: string;
-      ses?: { region?: string; accessKeyIdRef?: string; secretAccessKeyRef?: string };
+      ses?: { region?: string; accessKeyIdRef?: string; secretAccessKeyRef?: string; snsTopicArn?: string };
       templates?: {
         allowOverride?: boolean;
         overrides?: Record<string, Record<string, { subject?: string; html?: string; text?: string }>>;
@@ -2137,7 +2219,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     const v = withDefaults as {
       provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown;
       ledger?: {
-        productMap?: Record<string, { creditType?: string }>;
+        productMap?: Record<string, { creditType?: string; tier?: string }>;
         tierMap?: Record<string, { rank?: number; grants?: Array<{ creditType?: string }> }>;
         priceMap?: Record<string, string>;
       };
@@ -2157,12 +2239,19 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     // user, running vxil-billed functions for free (audit F2). Rejected at write
     // time so the tenant gets a clear `vxil push` error, not a silent runtime skip.
     const ledgerErrs: string[] = [];
+    const tierKeysForProducts = new Set(Object.keys(v.ledger?.tierMap ?? {}));
     for (const [productId, rule] of Object.entries(v.ledger?.productMap ?? {})) {
       if (rule.creditType && isReservedCreditType(rule.creditType)) {
         ledgerErrs.push(
           `/ledger/productMap/${productId}/creditType: '${rule.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`,
         );
       }
+      // (2026-09-25 F35+) an entitlement rule must name a declared tier — the
+      // write-time mirror of the runtime's unknown-tier refusal (a purchase for
+      // a tier nobody declared would land the delivery `error`).
+      if (rule.tier !== undefined && !tierKeysForProducts.has(rule.tier)) {
+        ledgerErrs.push(`/ledger/productMap/${productId}/tier: '${rule.tier}' is not a ledger.tierMap key`);
+      }
     }
     for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
       (rule.grants ?? []).forEach((g, i) => {
@@ -2339,7 +2428,10 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     const v = withDefaults as {
       functions?: Record<
         string,
-        { scriptRef?: string; scopes?: string[]; bindings?: Array<{ kind: string; schedule?: string; collection?: string; event?: string }>; signature?: unknown }
+        {
+          scriptRef?: string; scopes?: string[]; signature?: unknown;
+          bindings?: Array<{ kind: string; schedule?: string; collection?: string; event?: string; retry?: { maxAttempts?: number } }>;
+        }
       >;
     };
     const errs: string[] = [];
@@ -2354,6 +2446,12 @@ 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`);
         }
+        // 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.
+        if (b.retry !== undefined && !FN_RETRY_BINDING_KINDS.has(b.kind)) {
+          errs.push(`/functions/${name}/bindings/${i}: 'retry' applies to ${[...FN_RETRY_BINDING_KINDS].join(' | ')} bindings only (not '${b.kind}')`);
+        }
         if (b.kind === 'cmsHook' && !b.collection) {
           errs.push(`/functions/${name}/bindings/${i}: a 'cmsHook' binding needs a collection`);
         }