@vxil/feature-configs 0.6.0 → 0.7.1

package/src/index.ts

@@ -1,7 +1,7 @@
 // Per-feature TypeBox config schemas + the 15-leaf cap analyzer.
-// Location note (journaled deviation): the docs place each schema inside its
-// feature Worker; the control plane must validate writes against the same
-// schema (architecture §7.1 stage 2), so schemas live in this shared package
+// Location note: each schema belongs to its feature, but the config-write
+// path must validate writes against the same schema, so schemas live in this
+// shared package
 // and feature Workers import from here — one definition, two consumers.
 import { FormatRegistry, OptionalKind, Type, type Static, type TSchema } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
@@ -15,7 +15,7 @@ export * from './hooks.js';
 // Re-export the cms-rel read-model/cdc config gates (the pure-mirror split:
 // grammar validated here at config-write; field existence at runtime).
 export * from './readmodels.js';
-// Re-export the DECLARED API STATE planner (roadmap §4.11 P0-3): pure
+// Re-export the DECLARED API STATE planner: pure
 // declared-vs-live reconciliation, shared by the control-plane apply path and
 // the CLI (`vxil plan/diff/push`), so the two push paths can never diverge.
 export * from './apiState.js';
@@ -29,7 +29,7 @@ if (!FormatRegistry.Has('email')) {
   FormatRegistry.Set('email', (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v));
 }
 
-// ── RESERVED (vxil-COGS) CREDIT TYPES — single source of truth (audit F2) ─────
+// ── RESERVED (vxil-COGS) CREDIT TYPES — single source of truth ─────────────────
 // `fn_cpu_ms` funds vxil's OWN function-compute cost-of-goods (the
 // functions "recover-by-price" meter). It must NEVER be grantable or consumable
 // by a tenant's own `payments:write` key, NOR mapped-in via ledger config — a
@@ -40,7 +40,7 @@ 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
+/** 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. */
@@ -53,7 +53,7 @@ export function isReservedCreditType(creditType: string): boolean {
   return RESERVED_CREDIT_TYPES.has(creditType);
 }
 
-// ── notifications template catalog (D4 per-locale overrides) ─────────────────
+// ── notifications template catalog (per-locale overrides) ────────────────────
 // The SHIPPED template ids and the placeholders each body may interpolate. The
 // renderer itself lives in workers/notifications-v1/src/templates.ts (templates
 // are code, not rows); this table is the CONFIG-TIME half so a `vxil push` that
@@ -80,7 +80,7 @@ export const NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS: Readonly<Record<string, re
   transactional: ['cta'],
 };
 
-/** Per-override caps (D4). Bodies are emails, not documents. */
+/** Per-override caps. Bodies are emails, not documents. */
 export const NOTIF_OVERRIDE_SUBJECT_MAX = 500;
 export const NOTIF_OVERRIDE_BODY_MAX = 20_000;
 /** Whole-map caps: keeps one manifest (and the KV row every send reads) small. */
@@ -94,7 +94,7 @@ const NOTIF_PLACEHOLDER_RE = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
 const NOTIF_LOCALE_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$/;
 
 /**
- * D4 — validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
+ * Validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
  * bag is absent or clean. Every rule fails LOUD rather than shipping something
  * that silently renders wrong in a customer's inbox:
  *   • overrides present with `allowOverride:false` → rejected (never inert);
@@ -189,12 +189,12 @@ export const NotificationsConfigSchema = Type.Object({
   // need no email account, so the mock path is zero-config. A cross-field
   // check in validateFeatureConfig requires it only when provider === 'resend'.
   resendApiKeyRef: Type.Optional(Type.String()),
-  // Optional per-tenant Resend/Svix ENDPOINT secret ref (public.tenant_secrets,
-  // envelope-encrypted under KEK_NOTIFICATIONS — same store as resendApiKeyRef).
+  // Optional per-tenant Resend/Svix ENDPOINT secret ref (a pointer into the
+  // tenant's encrypted secret store — same store as resendApiKeyRef).
   // When set, inbound Resend webhooks are verified with THIS tenant's secret
   // instead of the platform-wide PROVIDER_WEBHOOK_SECRET, binding the signature
   // to the tenant so a signed event for tenant A can never validate at tenant
-  // B's webhook URL (audit H6 — mirrors payments revenuecat.webhookSecretRef).
+  // B's webhook URL (mirrors payments revenuecat.webhookSecretRef).
   webhookSecretRef: Type.Optional(Type.String()),
   // 'mock' exists for staging/e2e (deterministic provider); 'resend' is MVP;
   // 'ses' (2026-09-19) is the second real provider — Amazon SES v2, BYO IAM
@@ -206,7 +206,7 @@ export const NotificationsConfigSchema = Type.Object({
   // cap rule — funded by folding `rateLimit` into an Optional bag below);
   // NO `default: {}` so an absent bag stays absent (the auth `security`
   // precedent). Both refs are `secret:<name>` POINTERS into
-  // public.tenant_secrets (feature='notifications', KEK_NOTIFICATIONS) —
+  // the tenant's encrypted secret store (feature='notifications') —
   // exactly how resendApiKeyRef resolves; the region is plain config (not a
   // secret) and is pattern-pinned to the AWS region grammar so a typo fails
   // at `vxil push` instead of as a DNS error on the first send. Required
@@ -228,7 +228,7 @@ export const NotificationsConfigSchema = Type.Object({
   // nested objects carry `default: {}` so Value.Default can materialize them
   // and then recurse into the leaf defaults.
   // `retry` became an OPTIONAL bag (2 leaves → 1, countLeaves counts an
-  // Optional object as ONE) to fund `broadcast` below (M21/#4, 2026-07-18).
+  // Optional object as ONE) to fund `broadcast` below (2026-07-18).
   // It KEEPS `default: {}`, which Value.Default still materializes — so every
   // persisted manifest carries retry.{maxAttempts,backoff} exactly as before
   // (zero behavioral delta); only the TS type is now optional (workers read
@@ -246,7 +246,7 @@ export const NotificationsConfigSchema = Type.Object({
     { softBounceThreshold: Type.Integer({ default: 3 }) },
     { default: {} },
   ),
-  // `rateLimit` became an OPTIONAL bag (2 leaves → 1, the M21 `retry` trick)
+  // `rateLimit` became an OPTIONAL bag (2 leaves → 1, the `retry` trick)
   // on 2026-09-19 to fund the `ses` credential bag above. It KEEPS
   // `default: {}`, so Value.Default still materializes
   // rateLimit.{perDay,perTenantSec} into every persisted manifest exactly as
@@ -259,8 +259,8 @@ export const NotificationsConfigSchema = Type.Object({
     },
     { default: {} },
   )),
-  // `templates` became an OPTIONAL bag (1 leaf, the same M21 trick `retry`
-  // uses) to fund the D4 per-locale `overrides` map WITHOUT moving the count:
+  // `templates` became an OPTIONAL bag (1 leaf, the same trick `retry`
+  // uses) to fund the per-locale `overrides` map WITHOUT moving the count:
   // countLeaves scores an Optional object as ONE. `default: {}` is KEPT, so
   // Value.Default still materializes `templates.allowOverride` into every
   // persisted manifest exactly as before — zero behavioral delta; only the TS
@@ -268,7 +268,7 @@ export const NotificationsConfigSchema = Type.Object({
   templates: Type.Optional(Type.Object(
     {
       allowOverride: Type.Boolean({ default: false }),
-      // D4 (2026-09-10) — TENANT-AUTHORED PER-LOCALE OVERRIDES of the SHIPPED
+      // (2026-09-10) TENANT-AUTHORED PER-LOCALE OVERRIDES of the SHIPPED
       // template ids, as config DATA (a Record = 1 leaf, catalog size never
       // moves the count). Shape: { [templateId]: { [locale]: { subject?,
       // html?, text? } } }. Same escaped `{{placeholder}}` grammar as the
@@ -297,10 +297,10 @@ export const NotificationsConfigSchema = Type.Object({
   )),
   /** in-app inbox channel (send with channel: 'inbox' | 'both') */
   inboxEnabled: Type.Boolean({ default: false }),
-  /** §11b.5 broadcast campaigns channel. Optional bag (= 1 leaf): absent means
+  /** Broadcast campaigns channel. Optional bag (= 1 leaf): absent means
    * disabled; per-campaign quiet_hours / freq_cap overrides live on the
    * notifications.campaigns ROW (tenant data), not here. Folded into the
-   * canonical schema 2026-07-18 (M21/#4 — Value.Clean previously STRIPPED the
+   * canonical schema 2026-07-18 (Value.Clean previously STRIPPED the
    * worker-local extension, so campaigns 403'd via the real config path). */
   broadcast: Type.Optional(Type.Object({
     enabled: Type.Boolean({ default: false }),
@@ -324,28 +324,26 @@ export const NotificationsConfigSchema = Type.Object({
 // retry (Optional bag = 1), suppression.softBounceThreshold,
 // rateLimit (Optional bag = 1 — was rateLimit.{perDay,perTenantSec}, collapsed
 // 2026-09-19 to fund `ses` at zero net cost), templates (Optional bag = 1 — was
-// templates.allowOverride, collapsed 2026-09-10 to fund the D4 `overrides` map
+// templates.allowOverride, collapsed 2026-09-10 to fund the `overrides` map
 // at zero net cost), inboxEnabled, broadcast (Optional bag = 1) → 15. Cap = 15 —
 // AT the cap; the next flag must collapse something. (`templates.overrides` is
 // a Record MAP inside the ONE optional templates leaf — DATA, not a flag — so
 // catalog size never moves it.)
 
 export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
-/** The §11b.5 broadcast bag as persisted (present ⇒ leaf defaults applied). */
+/** The 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
+// (2026-09-25 — one copy of the generation defaults, not two). 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.
+// feature-configs unit test pins schema ↔ constant, and a CI gate pins that no
+// second object-literal declaration of the constant reappears anywhere.
 
-/** Generation-lifecycle config defaults (jobs.md §11 / §5 ≤15-flag budget). */
+/** Generation-lifecycle config defaults (guide ch. 6, jobs). */
 export const GENERATION_DEFAULTS = {
   /** per-tenant in-flight generation cap (separate budget from queue jobs) */
   maxConcurrent: 20,
@@ -399,7 +397,7 @@ export const JobsConfigSchema = Type.Object({
     { maxConcurrent: Type.Integer({ default: 10, minimum: 1, maximum: 100 }) },
     { default: {} },
   ),
-  // 2.F6 generation lifecycle knobs (jobs.md §11). The defaults and bounds are
+  // Generation lifecycle knobs (guide ch. 6, jobs). 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
@@ -414,14 +412,14 @@ export const JobsConfigSchema = Type.Object({
       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: 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
+      /** MANDATORY per-hold cap on a generation `reserve_credits.amount`
+       * (guide ch. 6, jobs). 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: 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 holds across all in-flight generation runs (guide ch. 6, jobs): 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. */
@@ -435,43 +433,42 @@ export const JobsConfigSchema = Type.Object({
 export type JobsConfig = Static<typeof JobsConfigSchema>;
 
 // One social-provider's BYO credential block. The *Ref fields are POINTERS into
-// public.tenant_secrets (envelope-encrypted) — never raw secrets (features/auth.md
-// §6.5). google/github/facebook share the clientId/secret shape; apple is distinct
+// the tenant's encrypted secret store — never raw secrets (guide ch. 6, auth).
+// google/github/facebook share the clientId/secret shape; apple is distinct
 // (Sign in with Apple has no static secret — it mints an ES256 client_secret from
-// the .p8, so it carries servicesId/teamId/keyId + a p8 keyRef, §6.4).
+// the .p8, so it carries servicesId/teamId/keyId + a p8 keyRef).
 const OAuthRefsSchema = Type.Object({
   // clientId/secret refs are OPTIONAL at the schema layer: a tenant may stage a
   // partial block, and the worker enforces presence at use (→ 501 if missing),
   // matching the worker's OAuthProviderRefs shape (core.ts). They stay POINTERS
-  // into tenant_secrets — never raw secrets (features/auth.md §6.5).
+  // into the tenant's secret store — never raw secrets (guide ch. 6, auth).
   clientIdRef: Type.Optional(Type.String()),
   clientSecretRef: Type.Optional(Type.String()),
   // extra native-aud allow-list entries (iOS/web client ids that differ from the
-  // primary clientIdRef) — also tenant_secrets refs (features/auth.md §6.4).
+  // primary clientIdRef) — also secret-store refs (guide ch. 6, auth).
   audRefs: Type.Optional(Type.Array(Type.String(), { maxItems: 16 })),
 });
 const AppleRefsSchema = Type.Object({
   servicesId: Type.String(), // the OAuth client_id / native aud (NOT a secret)
   teamId: Type.String(),
   keyId: Type.String(),
-  p8KeyRef: Type.String(), // tenant_secrets ref → envelope-encrypted .p8 PEM
+  p8KeyRef: Type.String(), // secret-store ref → the encrypted .p8 PEM
   // extra native-aud allow-list entries: genuine iOS ASAuthorization id_tokens
-  // carry the app BUNDLE ID as aud, not the Services ID (auth.md §6.4). Plain
+  // carry the app BUNDLE ID as aud, not the Services ID (guide ch. 6, auth). Plain
   // config values — bundle ids are not secrets. The worker already honors them
   // (oauthCore.ts nativeAudAllowList); declaring them here is what stops
   // Value.Clean stripping the field out of PUT /v1/config/auth.
   bundleIds: Type.Optional(Type.Array(Type.String(), { maxItems: 16 })),
 });
-// RB-2 — the generic OIDC / SSO bridge (roadmap §4.6.B, §1B.5; features/auth.md
-// §6.7). ONE tenant-supplied issuer, declared INSIDE the existing `providers`
+// The generic OIDC / SSO bridge (guide ch. 6, auth). ONE tenant-supplied issuer, declared INSIDE the existing `providers`
 // bag so it spends NO leaf (an Optional object bag = ONE leaf; auth stays 11).
 // Declarative + opt-in: the block's PRESENCE enables the `oidc` provider (no
 // methods.* toggle — a `default:false` flag would re-materialize every published
-// manifest, breaking the D3 byte-identical fold). The worker discovers the
+// manifest, breaking the byte-identical fold). The worker discovers the
 // endpoints + JWKS from `{issuer}/.well-known/openid-configuration` and verifies
 // iss (byte-equal) / aud (= clientId) / nonce / exp / iat strictly, fail-closed.
 // `clientId` is NOT a secret (it rides every authorize URL); `clientSecretRef`
-// is a tenant_secrets POINTER (feature 'auth'), never the value. A SAML IdP
+// is a secret-store POINTER (feature 'auth'), never the value. A SAML IdP
 // plugs in through a broker (Okta / Entra / Auth0 / WorkOS) that speaks OIDC —
 // there is deliberately NO native SAML.
 const OidcProviderSchema = Type.Object({
@@ -500,7 +497,7 @@ const OidcProviderSchema = Type.Object({
     { maxItems: 32 },
   )),
   // default true: an identity whose VERIFIED email matches an existing user is
-  // linked to it (the shipped §6.4 rule). false: link only by the stable
+  // linked to it (the shipped social sign-in rule). false: link only by the stable
   // (issuer, sub) anchor; a matching email that is not yet linked → 409.
   autoLink: Type.Optional(Type.Boolean()),
 });
@@ -510,7 +507,7 @@ const OidcProviderSchema = Type.Object({
 // on every caller-supplied `redirect_url` / `redirect_uri` (core.ts
 // `isAllowedRedirectUrl`) must agree on WHICH schemes a sign-in link may be
 // delivered to, or a tenant could allow-list an origin the worker then refuses
-// (or the reverse). The rule (cvskit gap 7, 2026-09-19): `https://` on any
+// (or the reverse). The rule (2026-09-19): `https://` on any
 // host, plus PLAIN `http://` ONLY on the two loopback names — `localhost` and
 // `127.0.0.1`, any port — so a local dev server can complete a magic link
 // without a staging origin. Any other `http://` (a LAN host, `*.local`, a
@@ -521,7 +518,7 @@ const OidcProviderSchema = Type.Object({
 // with THIS predicate, and auth-v1 calls it on the parsed URL — the parity test
 // in index.test.ts / redirectRule.test.ts holds the two together. The CLI's
 // production promotion gate still refuses any `http://` origin on a
-// production push (cli-sdk.md), so a loopback entry is a DEV-tenant affair.
+// production push, so a loopback entry is a DEV-tenant affair.
 export const REDIRECT_ORIGIN_PATTERN =
   '^(https://[^/?#\\s]+|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$';
 
@@ -547,13 +544,13 @@ export function isAllowedRedirectOriginEntry(entry: string): boolean {
 
 export const AuthConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
-  // D3 (auth wave 2026-09-10): the six method toggles collapsed into ONE
+  // (2026-09-10) the six method toggles collapsed into ONE
   // Optional bag (6 leaves → 1, countLeaves counts an Optional object as ONE) —
   // the notifications `retry`/`broadcast` precedent. It KEEPS `default: {}`,
   // which Value.Default still materializes, so every persisted manifest carries
   // methods.{emailPassword,magicLink,google,github,apple,facebook} with the
   // SAME keys and defaults as before — byte-identical folds for existing
-  // tenants (index.test.ts "D3 fold bytes"). Only the TS type is now optional;
+  // tenants (index.test.ts pins the fold bytes). Only the TS type is now optional;
   // the worker's gate() normalizes an absent bag to the defaults so every
   // reader (config.methods.<flag>) is unchanged.
   methods: Type.Optional(Type.Object(
@@ -571,12 +568,12 @@ export const AuthConfigSchema = Type.Object({
   // rule) keyed by provider, so the four provider blocks (and any future one)
   // never inflate the flag count — the prior shape spent a leaf per top-level
   // google/github block. This bag REPLACES those two top-level blocks (−2, +1
-  // for the bag) and EXTENDS the accepted providers to apple + facebook (§6):
+  // for the bag) and EXTENDS the accepted providers to apple + facebook:
   //   • google/github/facebook → { clientIdRef, clientSecretRef, audRefs? }
   //   • apple                  → { servicesId, teamId, keyId, p8KeyRef }
-  // All *Ref fields are tenant_secrets POINTERS, never raw secrets (§6.5). The
+  // All *Ref fields are secret-store POINTERS, never raw secrets. The
   // worker reads config.providers?.{google,github,apple,facebook} (oauthCore.ts).
-  // The §6.4 runtime sign-in flow for apple/facebook is SHIPPED in oauthCore.ts
+  // The runtime sign-in flow for apple/facebook is SHIPPED in oauthCore.ts
   // (id_token/access_token verification + ES256 Apple client_secret minting);
   // methods.{apple,facebook} above are the enable toggles it gates on.
   providers: Type.Optional(Type.Object({
@@ -584,11 +581,11 @@ export const AuthConfigSchema = Type.Object({
     github: Type.Optional(OAuthRefsSchema),
     apple: Type.Optional(AppleRefsSchema),
     facebook: Type.Optional(OAuthRefsSchema),
-    // RB-2: the generic OIDC / SSO issuer (presence = enabled; see above)
+    // the generic OIDC / SSO issuer (presence = enabled; see above)
     oidc: Type.Optional(OidcProviderSchema),
   })),
   // session/password are OPTIONAL bags (= ONE leaf each per the cap rule) since
-  // the OTP/anonymous/orgClaims wave — the `{ default: {} }` keeps the inner
+  // the OTP/anonymous/orgClaims release — the `{ default: {} }` keeps the inner
   // defaults materializing on publish, so the worker still reads fully-populated
   // manifests; its `config.session?.ttlMinutes ?? 60` fallbacks cover sparse
   // hand-built manifests only.
@@ -596,7 +593,7 @@ export const AuthConfigSchema = Type.Object({
     {
       ttlMinutes: Type.Integer({ default: 60, minimum: 5, maximum: 1440 }),
       refreshTtlDays: Type.Integer({ default: 30, minimum: 1, maximum: 365 }),
-      // A1 (auth wave 2026-09-10): concurrent-session cap per user with
+      // (2026-09-10) concurrent-session cap per user with
       // TAKE-OVER — a new sign-in revokes the OLDEST sessions past the cap
       // (revoked_reason 'device_cap', edge cache written) and reports them as
       // `took_over: [session_id…]`. Optional WITHOUT a default so existing
@@ -612,15 +609,15 @@ export const AuthConfigSchema = Type.Object({
     },
     { default: {} },
   )),
-  // Deviation (journaled): emailVerification.tokenTtlHours was DROPPED —
+  // Note: emailVerification.tokenTtlHours was DROPPED —
   // consumer-less (grep-verified: only this schema + dist mentioned it; the
   // verify-email token flow it would bound was never built). Same precedent as
-  // the removed `redirects` block below. Its leaf funds the OTP wave.
+  // the removed `redirects` block below. Its leaf funds the OTP sign-in bag.
   emailVerification: Type.Object(
     { required: Type.Boolean({ default: false }) },
     { default: {} },
   ),
-  // P1-16 (2026-09-18): magicLink is now an OPTIONAL bag (= ONE leaf however
+  // (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
@@ -629,7 +626,7 @@ export const AuthConfigSchema = Type.Object({
   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
+      // 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
@@ -640,19 +637,19 @@ export const AuthConfigSchema = Type.Object({
     },
     { default: {} },
   )),
-  // P1-5 identity continuity (2026-09-18) — OPT-IN registry adoption. When
+  // 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).
+  // proves nothing about the address (guide ch. 6, auth).
   // 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.
+  // Email OTP sign-in + the knobs step-up re-auth shares.
   // OPTIONAL bag = 1 leaf; absent ⇒ disabled (the worker gates on
   // otp?.enabled === true).
   otp: Type.Optional(Type.Object({
@@ -660,7 +657,7 @@ export const AuthConfigSchema = Type.Object({
     codeTtlMinutes: Type.Integer({ default: 10, minimum: 1, maximum: 60 }),
     maxAttempts: Type.Integer({ default: 5, minimum: 3, maximum: 10 }),
     resendCooldownSec: Type.Integer({ default: 60, minimum: 0, maximum: 600 }),
-    // F4-29 (auth wave 2026-09-10): test recipients — an OTP / step-up / email-
+    // (2026-09-10) test recipients — an OTP / step-up / email-
     // claim request whose address matches an entry sends NO mail and returns
     // the code as `test_code` (audit auth.otp.test_issued). Entries: an exact
     // email, a `*@domain` glob, or a +E.164 number (accepted for the SMS
@@ -671,11 +668,11 @@ export const AuthConfigSchema = Type.Object({
       Type.String({ minLength: 3, maxLength: 320 }), { maxItems: 20 },
     )),
   })),
-  // Anonymous (guest) sign-in (roadmap Tier-0). OPTIONAL bag = 1 leaf.
+  // Anonymous (guest) sign-in. OPTIONAL bag = 1 leaf.
   anonymous: Type.Optional(Type.Object({
     enabled: Type.Boolean({ default: false }),
   })),
-  // Org claims embedded in session JWTs at mint/refresh (roadmap Tier-1C):
+  // Org claims embedded in session JWTs at mint/refresh:
   // when enabled, auth-v1 fetches the user's active-org membership from orgs
   // over the EDGE and embeds { org_id, role, perms[] } as the `org` claim.
   // Fail-open: an orgs outage mints WITHOUT claims (sign-in never breaks).
@@ -684,23 +681,22 @@ export const AuthConfigSchema = Type.Object({
   orgClaims: Type.Optional(Type.Object({
     enabled: Type.Boolean({ default: false }),
   })),
-  // Deviation (journaled): the doc's §4 `redirects` block was DROPPED entirely —
+  // Note: the earlier `redirects` block was DROPPED entirely —
   // it had zero consumers (grep-verified: no worker reads config.redirects) and
   // its leaf was spent on the methods.{apple,facebook} toggles the shipped
-  // §6.4 sign-in flow actually gates on. Re-adding it requires headroom or a
+  // social sign-in flow actually gates on. Re-adding it requires headroom or a
   // collapse elsewhere.
   //
-  // Account-security controls (auth wave 2026-09-10, P0-3; features/auth.md
-  // §4b). ONE optional bag = 1 leaf; NO `default: {}` so an absent bag stays
+  // Account-security controls (2026-09-10; guide ch. 6, auth). ONE optional bag = 1 leaf; NO `default: {}` so an absent bag stays
   // absent (existing manifests fold byte-identically) and every control is
   // opt-in:
   //   • lockout — present ⇒ per-(tenant, identifier) failure lockout on password
   //     sign-in + OTP verify (429 account_locked + Retry-After); a bounded
-  //     counter row in auth.lockouts (migration 0088) survives restarts.
+  //     stored counter survives restarts.
   //   • breachedPasswords — HIBP k-anonymity range check (first 5 SHA-1 hex
   //     chars leave the worker, never the password) at sign-up / reset-confirm;
   //     fail-OPEN on network error → 422 password_breached.
-  //   • captchaSecretRef — a tenant_secrets ref (feature 'auth') holding the
+  //   • captchaSecretRef — a secret-store ref (feature 'auth') holding the
   //     Turnstile secret; when set, sign-up / OTP request / magic-link request
   //     require `captcha_token` (403 captcha_failed otherwise).
   //   • allowedRedirectOrigins — when non-empty, EVERY caller-supplied
@@ -725,24 +721,24 @@ export const AuthConfigSchema = Type.Object({
 });
 /** The security bag as persisted (present ⇒ leaf defaults applied). */
 export type AuthSecurityConfig = NonNullable<Static<typeof AuthConfigSchema>['security']>;
-/** The RB-2 generic OIDC / SSO issuer block (`providers.oidc`). */
+/** The generic OIDC / SSO issuer block (`providers.oidc`). */
 export type AuthOidcConfig = Static<typeof OidcProviderSchema>;
-// Leaves (auth wave 2026-09-10, D3): enabled(1) + methods(1, optional bag —
+// Leaves (2026-09-10): 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,
+// facebook credential blocks + the `oidc` issuer block) + session(1, optional bag) + password(1,
 // optional bag) + emailVerification(1) + magicLink(1, optional bag) + otp(1, optional bag)
 // + anonymous(1, optional bag) + orgClaims(1, optional bag) + security(1,
-// optional bag) + registryAdopt(1, P1-5) = 12. Cap = 15 — 3 leaves of
+// optional bag) + registryAdopt(1) = 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>;
 
-// ── DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23) ──────────────────────
+// ── DECLARED API STATE (2026-09-23) ──────────────────────────────────────────
 // A rate-limit policy is a ROW in the feature's own KV store, written by
 // POST/PUT/DELETE /v1/rate-limits/policies. It used to be API state OUTSIDE
-// vxil.config (a journaled deviation: "one writer per datum, and the writer is
+// vxil.config (by the old rule "one writer per datum, and the writer is
 // the route"), which made a second environment non-reproducible — every tenant
 // ended up with an `ensure-rate-limit-policies.ts` + a nightly assert. The
 // rule is unchanged — one writer per datum — but the writer is now THE
@@ -793,7 +789,7 @@ export type RateLimitsConfig = Static<typeof RateLimitsConfigSchema>;
 
 export const FilesConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
-  // (F8-54) `bucketRef` was DELETED: the object-storage bucket is a platform
+  // `bucketRef` was DELETED (2026-09-11): the object-storage bucket is a platform
   // binding on files-v1, never tenant-selectable, and no code ever read the
   // leaf — declaring it invited "point files at my own bucket", which vxil does
   // not offer. A persisted manifest that still carries it folds (Value.Clean).
@@ -802,8 +798,8 @@ export const FilesConfigSchema = Type.Object({
   quotas: Type.Object(
     {
       // maximum caps are a defense-in-depth ceiling on tenant-editable storage —
-      // 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
+      // object storage is cheap but the database-resident metadata + abuse aren't
+      // (pricing review 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 (plan tiers).
       maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
@@ -813,7 +809,7 @@ export const FilesConfigSchema = Type.Object({
     { default: {} },
   ),
   allowedContentTypes: Type.Array(Type.String(), { default: ['*'], maxItems: 100 }),
-  // (F8-54) the `contentScan` bag ({enabled, quarantineOnFail}) was DELETED:
+  // (2026-09-11) the `contentScan` bag ({enabled, quarantineOnFail}) was DELETED:
   // there is no malware/content scanner in files-v1 (it was a "V1.5" placeholder
   // neither leaf was ever read), so the knob promised quarantine that never
   // happened. Re-declare it in the same change as a real scanner, not before.
@@ -824,7 +820,7 @@ export const FilesConfigSchema = Type.Object({
     },
     { default: {} },
   ),
-  // Wave-2 extensions (features/files.md §1.1 OCR + §1.2 TTL) — the merge of
+  // Wave-2 extensions (guide ch. 6, files: OCR + TTL) — the merge of
   // workers/files-v1/src/ext.ts FilesExtensionsConfigSchema promised by its
   // 'wiring phase' comment. Each is an OPTIONAL bag (= ONE leaf per the cap
   // rule); files-v1 already reads both defensively (FilesConfigWithExt), so
@@ -842,21 +838,20 @@ export const FilesConfigSchema = Type.Object({
       [Type.Literal('gcv'), Type.Literal('textract'), Type.Literal('azure-di'), Type.Literal('mock')],
       { default: 'mock' },
     ),
-    // provider key is BYO + envelope-encrypted in public.tenant_secrets — NOT a
-    // config flag. keyRef names the tenant_secrets row (like ai's keyRefs).
+    // provider key is BYO + encrypted in the tenant's secret store — NOT a
+    // config flag. keyRef names the stored secret (like ai's keyRefs).
     keyRef: Type.Optional(Type.String()),
     asyncOverJobs: Type.Boolean({ default: true }), // large/multi-page → jobs
     boundingBoxes: Type.Boolean({ default: false }),
   })),
 });
 // Leaves: 9 + ttl(1, optional bag) + extractText(1, optional bag) = 11. Cap = 15.
-// (was 14 — F8-54 deleted the inert bucketRef leaf and the inert contentScan bag.)
+// (was 14 — 2026-09-11 deleted the inert bucketRef leaf and the inert contentScan bag.)
 
 export type FilesConfig = Static<typeof FilesConfigSchema>;
 
 // webhooks-out (wishlist feature): outbound event fan-out over the jobs delivery
-// engine. Subscriptions live in their own table (§1 contract — one writer
-// per datum); config is just the capability gate + a cap.
+// engine. Subscriptions live in their own store (one writer per datum); config is just the capability gate + a cap.
 export const DeclaredWebhookSubscriptionSchema = Type.Object({
   target_url: Type.String({ minLength: 9, maxLength: 2000 }),
   event_prefixes: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 100 }), { maxItems: 20 })),
@@ -867,14 +862,14 @@ 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
+  // FAILURE-ALERT DIGEST. 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
+  // RECIPIENTS ARE DELIBERATELY NOT CONFIGURABLE, and this decision is
+  // recorded here the way RateLimitsConfigSchema records 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
@@ -884,7 +879,7 @@ export const WebhooksConfigSchema = Type.Object({
   //
   // An Optional object bag counts as ONE leaf (the countLeaves rule).
   //
-  // `digestMinutes: 0` is IMMEDIATE (roadmap §4.11 P0-4c, 2026-09-23): the
+  // `digestMinutes: 0` is IMMEDIATE (2026-09-23): the
   // pass runs every minute for the tenant and mails the `error`-level failure
   // rows that landed since its last mail — at most one mail per minute, still
   // to the owner accounts. 1–4 are clamped up to 5 by the reader.
@@ -893,11 +888,11 @@ export const WebhooksConfigSchema = Type.Object({
     minLevel: Type.Union([Type.Literal('warn'), Type.Literal('error')], { default: 'error' }),
     digestMinutes: Type.Integer({ default: 15, minimum: 0, maximum: 1440 }),
   })),
-  // DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23): the tenant's OUTBOUND
+  // DECLARED API STATE (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). 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
+  // cursor (2026-09-25). `vxil push` / `POST /v1/apply` converge the live 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
@@ -922,16 +917,16 @@ export const CommentsConfigSchema = Type.Object({
 
 export type CommentsConfig = Static<typeof CommentsConfigSchema>;
 
-// content feature (cms-feature-analysis.md §4.2): flags govern LIMITS, never the
+// content feature (guide ch. 4): flags govern LIMITS, never the
 // content model — the model itself is data (cms.collections / cms.fields via
-// the REST surface). versioning/localization/publicRead land later waves.
+// the REST surface). versioning/localization/publicRead land later.
 export const CmsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
   draftPublish: Type.Boolean({ default: true }),
-  // cms end-user default-deny fail-safe (path-to-100 §3.2, Feature B). When ON,
+  // cms end-user default-deny fail-safe (guide ch. 4). When ON,
   // a VERIFIED end-user key (owner-scope mode) is DENIED access to any
   // collection that declares no owner_field — `403 server_only` on read AND
-  // write (finding 29, 2026-09-20; reads used to be a 404) — instead of the
+  // write (2026-09-20; reads used to be a 404) — instead of the
   // default tenant-wide-shared behavior. Server-caller mode is a
   // byte-for-byte no-op. Default OFF preserves today's shared semantics
   // (owner.int.test.ts's shared-collection invariant). A collection that DOES
@@ -953,7 +948,7 @@ export const CmsConfigSchema = Type.Object({
     },
     { default: {} },
   ),
-  // cms ENRICHMENT (cms.md §6.4): the read-time relation budget. The worker
+  // cms ENRICHMENT (guide ch. 4): the read-time relation budget. The worker
   // clamps via resolveRelationsConfig (enrich.ts) with the SAME defaults +
   // hard ceilings, so an out-of-range value can never widen the bound.
   relations: Type.Object(
@@ -993,7 +988,7 @@ export const CmsConfigSchema = Type.Object({
       }),
     ),
   ),
-  // Declarative relational read-models (cms-relational-depth §3 B2/B3/B5).
+  // Declarative relational read-models (guide ch. 4).
   // Each is a NAMED, closed-grammar aggregate/rank spec, optionally
   // materialized to a rollup collection on the EXISTING jobs cron (the
   // fn-cron:* reconciler idiom → cms-rollup:* schedules). Grammar is validated
@@ -1004,7 +999,7 @@ export const CmsConfigSchema = Type.Object({
     Type.Object({
       collection: Type.String({ maxLength: 64 }),
       kind: Type.Union([Type.Literal('aggregate'), Type.Literal('rank')]),
-      // the §3.1/§4.1 body minus limit — Type.Unknown so Value.Clean keeps it
+      // the aggregate/rank query body minus limit — Type.Unknown so Value.Clean keeps it
       // (the functions `signature` idiom); shape checked by the cross-field rule.
       spec: Type.Unknown(),
       materialize: Type.Optional(Type.Object({
@@ -1039,7 +1034,7 @@ export const CmsConfigSchema = Type.Object({
 
 export type CmsConfig = Static<typeof CmsConfigSchema>;
 
-// mcp feature (mcp.md §5): the aggregation surface's own knobs. Default-enabled —
+// mcp feature (guide ch. 10): the aggregation surface's own knobs. Default-enabled —
 // a tenant with no mcp config row still gets the aggregated tool list.
 export const McpConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
@@ -1048,7 +1043,7 @@ export const McpConfigSchema = Type.Object({
     { default: 'all' },
   ),
   allowToolList: Type.Optional(Type.Array(Type.String(), { maxItems: 200 })),
-  // (F8-54) the `scopedKey.perAgentKeys` leaf was DELETED: it was documented as
+  // (2026-09-11) the `scopedKey.perAgentKeys` leaf was DELETED: it was documented as
   // a "dashboard-UI hint only" that no dashboard ever read, and key minting is a
   // control-plane concern independent of MCP exposure — per-agent keys already
   // work for every tenant, gated by nothing here.
@@ -1064,7 +1059,7 @@ export const McpConfigSchema = Type.Object({
     { default: {} },
   ),
 
-  // Tenant-authored CUSTOM tools (mcp.md §6.5): name → tenant-owned https
+  // Tenant-authored CUSTOM tools (guide ch. 10): name → tenant-owned https
   // endpoint. mcp-v1 lists each as `custom_<name>` and POSTs the tool
   // arguments to `url`, HMAC-signed with the per-tenant key from
   // GET /v1/mcp/signing-secret (X-Vxil-Mcp-Signature; the caller's vxil bearer
@@ -1084,7 +1079,7 @@ export const McpConfigSchema = Type.Object({
     }),
   )),
 
-  // Config-declared MCP PROMPTS (mcp.md §11 closure): name → template with
+  // Config-declared MCP PROMPTS (guide ch. 10): name → template with
   // {{placeholder}} interpolation. Served verbatim by mcp-v1 prompts/list +
   // prompts/get. ONE Type.Record leaf; placeholder ↔ arguments consistency is
   // a cross-field rule below.
@@ -1104,7 +1099,7 @@ export const McpConfigSchema = Type.Object({
 // Leaves: 8 by countLeaves (enabled, exposureLevel, allowToolList,
 // rateLimits.toolCallsPerMin, branding.serverName, branding.serverInstructions
 // = 6, + customTools + prompts as ONE Type.Record leaf each). Cap = 15.
-// (was 9 — F8-54 deleted the inert scopedKey.perAgentKeys leaf.)
+// (was 9 — 2026-09-11 deleted the inert scopedKey.perAgentKeys leaf.)
 
 export type McpConfig = Static<typeof McpConfigSchema>;
 
@@ -1136,7 +1131,7 @@ export const OrgsConfigSchema = Type.Object({
 
 export type OrgsConfig = Static<typeof OrgsConfigSchema>;
 
-// activity-feed feature (features/activity-feed.md §3): a GetStream-class activity-
+// activity-feed feature (guide ch. 6, activity-feed): a GetStream-class activity-
 // streams engine + a Knock/Novu-class in-app notification FEED. Flags govern
 // the fan-out throttle, the follow/aggregation caps, and the cross-channel /
 // realtime gates — NEVER the verb vocabulary or the personalized ranker (the
@@ -1156,8 +1151,8 @@ export const ActivityFeedConfigSchema = Type.Object({
         Type.Literal('aggregated'),
         Type.Literal('notification'),
       ]),
-      aggregation: Type.Optional(Type.String()), // group-format rule (§7); required for aggregated/notification
-      ranking: Type.Optional(Type.String()), // 'chronological' | 'decay' (§8); flat-only; default chronological
+      aggregation: Type.Optional(Type.String()), // group-format rule; required for aggregated/notification
+      ranking: Type.Optional(Type.String()), // 'chronological' | 'decay'; flat-only; default chronological
     }),
     {
       default: {
@@ -1175,7 +1170,7 @@ export const ActivityFeedConfigSchema = Type.Object({
     {
       celebrityThreshold: Type.Integer({ default: 10_000, minimum: 0 }), // ≥ → pull (read-side); < → push (write-side)
       maxFanoutPerJob: Type.Integer({ default: 1000, minimum: 1, maximum: 10_000 }), // follower batch size per jobs task
-      maxConcurrentTasks: Type.Integer({ default: 20, minimum: 1, maximum: 1000 }), // per-tenant in-flight cap (LOCAL throttle §5)
+      maxConcurrentTasks: Type.Integer({ default: 20, minimum: 1, maximum: 1000 }), // per-tenant in-flight cap (local throttle)
       pendingCeiling: Type.Integer({ default: 50_000, minimum: 1 }), // pending-fan-out-depth back-pressure ceiling
     },
     { default: {} },
@@ -1189,7 +1184,7 @@ export const ActivityFeedConfigSchema = Type.Object({
     { default: {} },
   ),
 
-  // (F8-54) the `aggregation.maxGroupActivities` leaf was DELETED: nothing kept
+  // (2026-09-11) the `aggregation.maxGroupActivities` leaf was DELETED: nothing kept
   // or returned a per-group activity LIST — an aggregated read returns the group
   // rollup (activity_count/actor_count/last_actor), so there was never an N to
   // bound and no code read the leaf. Re-declare it with a group-detail route.
@@ -1203,7 +1198,7 @@ export const ActivityFeedConfigSchema = Type.Object({
 
   crossChannel: Type.Object(
     {
-      enabled: Type.Boolean({ default: false }), // master gate for the notifications push/email trigger (§10)
+      enabled: Type.Boolean({ default: false }), // master gate for the notifications push/email trigger
       digestCadence: Type.Union(
         [Type.Literal('off'), Type.Literal('hourly'), Type.Literal('daily')],
         { default: 'off' },
@@ -1212,7 +1207,7 @@ export const ActivityFeedConfigSchema = Type.Object({
     { default: {} },
   ),
 
-  // (F8-54) the `rateLimit.addPerSec` leaf was DELETED: activity-feed-v1 has no
+  // (2026-09-11) the `rateLimit.addPerSec` leaf was DELETED: activity-feed-v1 has no
   // rate-limiter binding and never read it, so the declared per-tenant write
   // burst was enforced by nothing (the edge front-door limiter and the
   // per-tenant request meter are the real bounds). Re-declare it together with
@@ -1222,11 +1217,11 @@ export const ActivityFeedConfigSchema = Type.Object({
 //   maxFanoutPerJob, maxConcurrentTasks, pendingCeiling}(+4=6), follow.{copyLimit,
 //   maxFollowing}(+2=8), realtime.enabled(9), crossChannel.{enabled, digestCadence}(+2=11).
 // countLeaves → 11. Cap = 15. (feedGroups is Type.Record → patternProperties, ONE leaf.)
-// (was 13 — F8-54 deleted the inert aggregation and rateLimit bags.)
+// (was 13 — 2026-09-11 deleted the inert aggregation and rateLimit bags.)
 
 export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
 
-// vector-search feature (features/vector-search.md §4). Re-declared here to match the
+// vector-search feature (guide ch. 6, vector-search). Re-declared here to match the
 // schema the worker EXPORTS from workers/vector-search-v1/src/config.ts — the
 // control plane validates writes against this shared copy (the same
 // one-definition / two-consumers note as the other features above; this package owns
@@ -1235,7 +1230,7 @@ export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
 // synthesis / relevance tuning (the tenant's moat). An OPTIONAL leaf = ONE flag.
 export const VectorSearchConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
-  // 'auto' resolves to the default managed vector backend for the tier (#147).
+  // 'auto' resolves to the default managed vector backend for the tier.
   backend: Type.Union(
     [Type.Literal('auto'), Type.Literal('lakebase'), Type.Literal('pgvector')],
     { default: 'auto' },
@@ -1293,7 +1288,7 @@ export const VectorSearchConfigSchema = Type.Object({
       ),
       model: Type.Optional(Type.String({ maxLength: 128 })), // cohere 'rerank-v3.5' / voyage 'rerank-2'
       topN: Type.Optional(Type.Integer({ default: 50, minimum: 1, maximum: 200 })),
-      apiKeyRef: Type.Optional(Type.String({ maxLength: 128 })), // 'secret:<name>' under KEK_VECTOR_SEARCH
+      apiKeyRef: Type.Optional(Type.String({ maxLength: 128 })), // 'secret:<name>' in the tenant's secret store
     }),
   ),
   // Config-driven auto-embedding sync from cms collections: the control plane
@@ -1326,12 +1321,12 @@ export const VectorSearchConfigSchema = Type.Object({
 
 export type VectorSearchConfig = Static<typeof VectorSearchConfigSchema>;
 
-// ai feature (features/ai.md §4). Re-declared to match workers/ai-v1/src/core.ts's
+// ai feature (guide ch. 6, ai). Re-declared to match workers/ai-v1/src/core.ts's
 // exported AiConfigSchema. vxil owns the call SCAFFOLDING (routing, streaming,
 // token accounting, caching, the reserve→settle budget); the tenant owns the
 // intelligence (prompt TEMPLATES are config-as-code, stored/rendered but never
 // authored). 'mock' is the deterministic default until a BYO key is provisioned;
-// the real providers route via tenant_secrets keyRefs.
+// the real providers route via secret-store keyRefs.
 export const AI_TEMPLATE_NAME_PATTERN = '^[a-zA-Z0-9_.\\-]+$';
 export const AI_MAX_DECLARED_TEMPLATES = 50;
 export const DeclaredAiTemplateSchema = Type.Object({
@@ -1352,7 +1347,7 @@ export const AiConfigSchema = Type.Object({
      Type.Literal('gemini'), Type.Literal('azure'), Type.Literal('openrouter')],
     { default: 'mock' },
   ),
-  // BYO keyRefs → public.tenant_secrets (envelope-encrypted). The block is NOT
+  // BYO keyRefs → the tenant's encrypted secret store. The block is NOT
   // optional (the worker declares it plain), so its three optional refs each count
   // as a leaf. The nested blocks carry `default: {}` (this package's convention)
   // so Value.Default materializes them + recurses into the leaf defaults when a
@@ -1364,7 +1359,7 @@ export const AiConfigSchema = Type.Object({
     geminiKeyRef: Type.Optional(Type.String()),
     // The openai-compatible extension surface — ONE optional object = ONE config
     // leaf (countLeaves collapses optional objects; 15-leaf cap discipline).
-    // compat.openrouterKeyRef: BYO OpenRouter key (tenant_secrets ref, KEK_AI).
+    // compat.openrouterKeyRef: BYO OpenRouter key (a secret-store ref).
     // compat.openaiBaseUrl: point the openai adapter at ANY openai-compatible
     // host (DeepSeek, vLLM, an Azure-compatible proxy). Public-https validated
     // at config WRITE (publicHttpsUrlError below) AND at USE (@vxil/runtime
@@ -1384,7 +1379,7 @@ export const AiConfigSchema = Type.Object({
     tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = unlimited
     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` became an OPTIONAL bag (3 leaves → 1, the M21 `retry` trick)
+  // `streaming` became an OPTIONAL bag (3 leaves → 1, the `retry` trick)
   // on 2026-09-23 to fund the declared `templates[]` below. It KEEPS
   // `default: {}`, so Value.Default still materializes
   // streaming.{enabled,replayBufferFrames,flushMs} into every persisted
@@ -1393,20 +1388,20 @@ export const AiConfigSchema = Type.Object({
   // here is optional.
   streaming: Type.Optional(Type.Object({
     enabled: Type.Boolean({ default: true }),
-    replayBufferFrames: Type.Integer({ default: 256, minimum: 1 }), // §2a ring-buffer depth
-    flushMs: Type.Integer({ default: 50, minimum: 0 }),             // §2a/#148 token→frame coalesce window
+    replayBufferFrames: Type.Integer({ default: 256, minimum: 1 }), // replay ring-buffer depth
+    flushMs: Type.Integer({ default: 50, minimum: 0 }),             // token→frame coalesce window
   }, { default: {} })),
-  // DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23): the tenant's stored
-  // prompt templates as config. vxil STORES + versions, never authors (ai.md
-  // §0) — declaring them here changes WHO writes the row (the repository, via
+  // DECLARED API STATE (2026-09-23): the tenant's stored
+  // prompt templates as config. vxil STORES + versions, never authors — declaring them here changes WHO writes the row (the repository, via
   // `vxil push`), not what vxil does with it. Converged by CONTENT: the
   // control-plane hashes each declared entry (@vxil/runtime
   // aiTemplateContentSha256) against the `content_sha256` GET /v1/ai/templates
   // 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 (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 })),
 });
@@ -1419,7 +1414,7 @@ export const AiConfigSchema = Type.Object({
 
 export type AiConfig = Static<typeof AiConfigSchema>;
 
-// rag feature (features/rag.md §2). Re-declared to match workers/rag-v1/src/config.ts's
+// rag feature (guide ch. 6, rag). Re-declared to match workers/rag-v1/src/config.ts's
 // exported RagConfigSchema. rag owns the PIPELINE knobs only — retrieval budget,
 // context budget + strategy + tokenizer, the citation/stream gates — NEVER the
 // prompt, the synthesis, or relevance tuning (the tenant's `ai` template owns those).
@@ -1443,7 +1438,7 @@ export const RagConfigSchema = Type.Object({
     { default: {} },
   ),
   // declarative per-metadata-field relevance boosts applied in rag AFTER
-  // retrieval, BEFORE minScore/budget/grounding (rag.md §2f). ONE Type.Record
+  // retrieval, BEFORE minScore/budget/grounding (guide ch. 6, rag). ONE Type.Record
   // leaf (the activity-feed feedGroups precedent).
   boosts: Type.Record(Type.String(), Type.Union([
     Type.Object({
@@ -1458,13 +1453,13 @@ export const RagConfigSchema = Type.Object({
   ]), { default: {} }),
   context: Type.Object(
     {
-      // bounded context budget — enforced via the §2c tokenizer, BEFORE the ai call.
+      // bounded context budget — enforced via the tokenizer, BEFORE the ai call.
       maxTokens: Type.Integer({ default: 4000, minimum: 1, maximum: 1_000_000 }),
       strategy: Type.Union([Type.Literal('topk'), Type.Literal('mmr')], {
         default: 'topk',
       }),
       // 'provider' = the resolved ai provider's tokenizer; 'heuristic' = portable
-      // ~chars/4 with a safety margin (§2c, #149).
+      // ~chars/4 with a safety margin.
       tokenizer: Type.Union([Type.Literal('provider'), Type.Literal('heuristic')], {
         default: 'provider',
       }),
@@ -1483,7 +1478,7 @@ export const RagConfigSchema = Type.Object({
 
 export type RagConfig = Static<typeof RagConfigSchema>;
 
-// payments feature (features/payments.md §5). Re-declared to match the schema the
+// payments feature (guide ch. 6, payments). Re-declared to match the schema the
 // worker EXPORTS from workers/payments-v1/src/core.ts — the control plane
 // validates writes against this shared copy (one-definition / two-consumers,
 // like the other features). Two co-equal pillars: (A) provider payments (the
@@ -1502,9 +1497,9 @@ export const PaymentsConfigSchema = Type.Object({
      Type.Literal('revenuecat'), Type.Literal('paypal')],
     { default: 'mock' },
   ),
-  // BYO-key credential blocks → public.tenant_secrets (envelope-encrypted).
+  // BYO-key credential blocks → the tenant's encrypted secret store.
   // Each OPTIONAL object counts as ONE leaf (the tenant's decision is
-  // "configure it or not", not each inner ref — features/auth.md §4).
+  // "configure it or not", not each inner ref — guide ch. 6, auth).
   stripe: Type.Optional(Type.Object({
     secretKeyRef: Type.String(),
     webhookSecretRef: Type.String(),
@@ -1519,24 +1514,34 @@ export const PaymentsConfigSchema = Type.Object({
     projectId: Type.String(),
     publicSdkKey: Type.String(),
     secretApiKeyRef: Type.String(),
-    // Per-tenant webhook secret ref (public.tenant_secrets). Inbound RevenueCat
+    // Per-tenant webhook secret ref (secret store). 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
+    // (that fallback WAS a cross-tenant webhook-forgery vector; a CI gate now
     // 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
+    // Environment integrity. RevenueCat posts SANDBOX
     // and PRODUCTION events to the SAME webhook with the same auth header, so a
     // sandbox purchase would otherwise fold into production entitlements. A
     // sandbox event is persisted as outcome 'rejected_environment' (200, never
     // folded) unless the tenant opts in here. Stripe/Paddle/PayPal separate
     // environments by signing secret / API base, so only RC carries this knob.
     acceptSandbox: Type.Boolean({ default: false }),
+    // (2026-10-01) 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(),
@@ -1547,9 +1552,9 @@ export const PaymentsConfigSchema = Type.Object({
   // Where a provider-hosted flow sends the payer back (Stripe billing-portal
   // return, PayPal approval return/cancel) — the TENANT's own app URL,
   // https-only. Absent ⇒ the worker's WEB_BASE_URL env (vxil's site), never a
-  // hardcoded host (audit 2026-07-10: the old fallback pointed at a dead apex).
+  // hardcoded host (2026-07-10: the old fallback pointed at a dead apex).
   returnUrl: Type.Optional(Type.String({ pattern: '^https://', maxLength: 512 })),
-  // NB (F8-54, 2026-09-11): the former `prices.catalogRef` leaf was DELETED —
+  // NB (2026-09-11): the former `prices.catalogRef` leaf was DELETED —
   // it named nothing (prices resolve from ledger.priceMap; no code path ever
   // read it). A persisted manifest that still carries `prices` folds:
   // validateFeatureConfig's Value.Clean strips the stray key.
@@ -1567,16 +1572,19 @@ export const PaymentsConfigSchema = Type.Object({
     // 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
+    //   { tier, durationDays }          (2026-09-25) 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 — 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 }),
-        amount: Type.Integer({ minimum: 1 }),                 // #128: a grant only ADDS
+        amount: Type.Integer({ minimum: 1 }),                 // a grant only ADDS
         period: Type.Union([Type.Literal('once'), Type.Literal('monthly'),
                             Type.Literal('annual')]),
       }),
@@ -1587,12 +1595,20 @@ export const PaymentsConfigSchema = Type.Object({
     ])),
     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
-      rank: Type.Optional(Type.Integer({ minimum: 0 })),   // precedence for the multi-sub fold (#125)
+      quotas: Type.Record(Type.String(), Type.Integer({ minimum: 0 })), // no negative quota
+      rank: Type.Optional(Type.Integer({ minimum: 0 })),   // precedence for the multi-sub fold
       grants: Type.Optional(Type.Array(Type.Object({
         creditType: Type.String({ minLength: 1 }),
-        amount: Type.Integer({ minimum: 1 }),               // #128
+        amount: Type.Integer({ minimum: 1 }),               // a grant only ADDS
         period: Type.String(),
+        // (2026-10-01) '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
@@ -1601,7 +1617,7 @@ export const PaymentsConfigSchema = Type.Object({
     // fold (refoldEntitlements WHERE tier IS NOT NULL) reflects the subscription.
     priceMap: Type.Optional(Type.Record(Type.String(), Type.String())),
     autoRefundOnJobFailure: Type.Boolean({ default: true }), // consume(jobId) reverses on DLQ/timeout
-    // Grace window (money-path wave F1-7): a `past_due` subscription stays
+    // Grace window: a `past_due` subscription stays
     // entitled for this many days AFTER its current_period_end (the dunning
     // window the provider is retrying inside). 0 = today's behaviour (a past_due
     // row is never entitled). ONE predicate in the fold — NOT a dunning ladder:
@@ -1609,8 +1625,7 @@ export const PaymentsConfigSchema = Type.Object({
     grace: Type.Optional(Type.Object({
       pastDueDays: Type.Integer({ default: 0, minimum: 0, maximum: 90 }),
     })),
-    // Opt-in period-end enforcement (money-path operations wave, decision D2
-    // option a). ABSENT (the default) = today's behaviour: a subscription whose
+    // Opt-in period-end enforcement. ABSENT (the default) = today's behaviour: a subscription whose
     // current_period_end passed with no provider event stays entitled forever
     // (the provider is the only clock). PRESENT = the nightly reconcile sweep
     // flips an `active`/`trialing` row whose current_period_end + slackHours
@@ -1645,10 +1660,10 @@ export const PaymentsConfigSchema = Type.Object({
     // (`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
+  // NB: the former `webhooks.forwardToTenantUrl` leaf
   // was DELETED — it had zero readers (never forwarded anything). Outbound
-  // delivery of payments state changes rides the audit_event → webhooks-out
-  // spine: subscribe to the `payments.` event prefix (payments.md §7b).
+  // delivery of payments state changes rides the audit stream → outbound
+  // webhooks: subscribe to the `payments.` event prefix (guide ch. 6, payments).
 });
 // Leaves: enabled(1), provider(2), stripe?(3), paddle?(4), revenuecat?(5),
 //   paypal?(6), returnUrl(7), defaults.{currency,trialDays}(+2=9), ledger?(10).
@@ -1660,24 +1675,24 @@ export const PaymentsConfigSchema = Type.Object({
 
 export type PaymentsConfig = Static<typeof PaymentsConfigSchema>;
 
-// functions feature (vxil-functions-design §4.c). Tenant-deployed backend edge
+// functions feature (guide ch. 8). Tenant-deployed backend edge
 // functions on the managed serverless runtime. The FUNCTION owns its identity (bundle via
 // scriptRef, scopes, secrets, egress, limits, runtime) + a SET of trigger
 // bindings; every other surface (e.g. cms.hooks) REFERENCES a function BY NAME and
 // never re-embeds deploy config. The per-function bag is ONE Type.Record leaf
 // (cms.hooks / payments.ledger precedent), so any number of deployed functions
-// never grows the flag cap. This is the §7.3 crossing — paid, tier-walled,
+// never grows the flag cap. Tenant code on the platform — paid, tier-walled,
 // opt-in (enabled defaults to false), egress-guarded.
 export const FunctionsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: false }),
-  // (F8-54) `runtime` ('isolate' | 'container') was DELETED: the container lane
-  // is design-only, nothing read the leaf, and accepting 'container' silently
+  // (2026-09-11) `runtime` ('isolate' | 'container') was DELETED: the container lane
+  // is not built, nothing read the leaf, and accepting 'container' silently
   // ran the isolate anyway. It comes back with the lane, not before.
   defaultLimits: Type.Object(
     {
       // cpuMs is the ONLY per-dispatch limit the managed runtime accepts and the
       // only one anything reads (functions-v1 meter.ts + the dispatch cap).
-      // (F8-54) `timeoutMs` and `memoryMb` were DELETED: memory is fixed by the
+      // (2026-09-11) `timeoutMs` and `memoryMb` were DELETED: memory is fixed by the
       // runtime and not tenant-selectable, and no wall-clock abort was ever
       // applied — a declared 10s default that nothing enforced.
       cpuMs: Type.Integer({ default: 50, minimum: 5, maximum: 300_000 }),
@@ -1728,7 +1743,7 @@ 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
+              // (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)
@@ -1737,6 +1752,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 +1764,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 (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
@@ -1775,10 +1811,9 @@ export const FunctionsConfigSchema = Type.Object({
         //               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 }.
+        //               bigger per-fetch budget widens with you.
+        // (`memoryMb` is deleted — memory is fixed by the managed runtime and is
+        // not a per-dispatch option; a dispatch 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(
@@ -1788,7 +1823,7 @@ export const FunctionsConfigSchema = Type.Object({
           }),
         ),
         enabled: Type.Optional(Type.Boolean()),
-        // Level-1 typed I/O (cli-sdk design §4.5): the declared input/output
+        // Level-1 typed I/O (guide ch. 8): the declared input/output
         // contract, persisted by the deploy body so ONLINE `vxil gen` emits the
         // same typed fn client as --offline. Opaque JSON-schema-ish payloads —
         // the CLI's lowerSig lowers them; the platform never interprets them.
@@ -1804,7 +1839,7 @@ export const FunctionsConfigSchema = Type.Object({
 //   functions(4, the Type.Record bag → ONE leaf; bindings[]/scriptRef/scopes/
 //   secrets/egressAllow/limits/enabled/signature are DATA inside the MAP value
 //   and never move the count, like cms.hooks). countLeaves → 4. Cap = 15.
-//   (was 7 — F8-54 deleted the inert runtime, defaultLimits.timeoutMs and
+//   (was 7 — 2026-09-11 deleted the inert runtime, defaultLimits.timeoutMs and
 //   defaultLimits.memoryMb leaves.)
 export type FunctionsConfig = Static<typeof FunctionsConfigSchema>;
 
@@ -1890,7 +1925,7 @@ export const CopilotConfigSchema = Type.Object({
     { default: {} },
   ),
 
-  // (F8-54) the `escalation` bag ({enabled, handler, notifyTemplate}) was
+  // (2026-09-11) the `escalation` bag ({enabled, handler, notifyTemplate}) was
   // DELETED: the human hand-off it declared was never built — copilot-v1 read
   // none of the three leaves, so a tenant who turned it on got silence. The
   // shipped hand-off path is a tenant function on the conversation events.
@@ -1898,7 +1933,7 @@ export const CopilotConfigSchema = Type.Object({
   // ── limits: DELEGATE token/credit accounting to ai-v1 ─────────────────────
   limits: Type.Object({
     consumeCredits: Type.Boolean({ default: false }),
-    // (F8-54) `tokensPerUserPerDay` was DELETED here: token accounting is
+    // (2026-09-11) `tokensPerUserPerDay` was DELETED here: token accounting is
     // delegated to ai-v1 (this bag's own doctrine) and only `ai`'s
     // limits.tokensPerUserPerDay is enforced — the copilot twin read nothing.
   }, { default: {} }),
@@ -1914,7 +1949,7 @@ export const CopilotConfigSchema = Type.Object({
 // Leaves: enabled(1), agents(2 — Type.Record MAP, ONE leaf),
 //   limits.consumeCredits(3), widget.{enabled,requireAuth,allowedOrigins,theme}
 //   (+4=7). countLeaves → 7. Cap = 15.
-//   (was 9 — F8-54 deleted the inert escalation bag and limits.tokensPerUserPerDay.)
+//   (was 9 — 2026-09-11 deleted the inert escalation bag and limits.tokensPerUserPerDay.)
 
 export type CopilotConfig = Static<typeof CopilotConfigSchema>;
 
@@ -1942,17 +1977,36 @@ export const FEATURE_SCHEMAS: Record<string, TSchema> = {
 
 export const CONFIG_FLAG_CAP = 15;
 
-/** Counts leaf flags in a TypeBox object schema (architecture §6).
- * Per features/auth.md §4: an OPTIONAL object (e.g. a provider credential
+/** Counts leaf flags in a TypeBox object schema.
+ * Per guide ch. 6, auth: an OPTIONAL object (e.g. a provider credential
  * block) counts as ONE flag — the tenant's decision is "configure it or
  * not", not each inner ref. */
-/** The auth lifecycle events an `authHook` binding may name (F4-30) — the
+/** The auth lifecycle events an `authHook` binding may name — the
  * closed union `packages/config` types as AuthHookEvent; the control-plane
  * reconciler maps each to its `auth.<event>` audit-event prefix. */
 export const AUTH_HOOK_EVENTS = ['user.created', 'session.created', 'session.revoked', 'signin.failure'] as const;
 export type AuthHookEvent = (typeof AUTH_HOOK_EVENTS)[number];
 
-/** F4-29 test-recipient entry grammar (shared by the validator and auth-v1's
+/** 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.
+ * A CI gate 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)}`;
+}
+
+/** The OTP test-recipient entry grammar (shared by the validator and auth-v1's
  * matcher): an exact email, a `*@domain` glob, or a +E.164 phone number. */
 export const TEST_RECIPIENT_EMAIL_RE = /^[^\s@*]+@[^\s@]+\.[^\s@]+$/;
 export const TEST_RECIPIENT_GLOB_RE = /^\*@[^\s@*]+\.[^\s@*]+$/;
@@ -2015,7 +2069,7 @@ export function setKnownMcpTools(names: readonly string[]): void {
 }
 
 // ── mcp custom-tool / prompt caps + the pure public-https check ──────────────
-// (mcp.md §6.5) Caps are deliberately tighter than the 200-tool listing cap:
+// (guide ch. 10) Caps are deliberately tighter than the 200-tool listing cap:
 // each custom tool is a platform-signed egress target, so the bag stays small.
 export const MCP_MAX_CUSTOM_TOOLS = 32;
 export const MCP_MAX_PROMPTS = 32;
@@ -2073,7 +2127,7 @@ function publicHttpsUrlError(url: string): string | null {
  *  validation below and the control-plane deploy clamp. */
 export const DENY_FUNCTION_SCOPES = new Set(['admin', '*', 'features:write', 'functions:write', 'secrets:write']);
 
-// ── declared API state — config-write validators (roadmap §4.11 P0-3) ────────
+// ── declared API state — config-write validators ────────────────────────────
 /** `{var}` names of a rate-limit key template (rate-limits-v1 core.ts
  *  templateVars parity). */
 export function rlTemplateVars(template: string): string[] {
@@ -2165,12 +2219,12 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     return { ok: false, errors: [`schema for '${feature}' exceeds the ${CONFIG_FLAG_CAP}-flag cap`] };
   }
   // Apply defaults to a clone, then STRIP any property the schema does not
-  // declare, then check. Value.Clean makes the validator TOTAL (audit #112):
+  // declare, then check. Value.Clean makes the validator TOTAL:
   // the schemas are open Type.Object()s, so without it Value.Check passes on —
   // and putConfig would persist — arbitrary unknown keys. Clean runs AFTER
   // Default so materialized nested defaults survive but stray top-level/nested
   // keys are dropped. This also removes the CLI dry-run idempotency drift
-  // (audit #118): plan/push diff the same cleaned manifest the server stores.
+  // too: plan/push diff the same cleaned manifest the server stores.
   const withDefaults = Value.Clean(
     schema,
     Value.Default(schema, Value.Clone(raw)),
@@ -2214,13 +2268,13 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
   }
   // Cross-field rule: a REAL payments provider needs its credential block; the
   // 'mock' provider (the deterministic default) stays zero-config so the whole
-  // ledger path is testable without real keys (features/payments.md §0/§6).
+  // ledger path is testable without real keys (guide ch. 6, payments).
   if (feature === 'payments') {
     const v = withDefaults as {
       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>;
       };
     };
@@ -2236,7 +2290,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     }
     // A reserved (vxil-COGS) credit_type must NEVER appear in a ledger grant map:
     // the webhook/subscription reducers would otherwise credit `fn_cpu_ms` to a
-    // user, running vxil-billed functions for free (audit F2). Rejected at write
+    // user, running vxil-billed functions for free. 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 ?? {}));
@@ -2246,7 +2300,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
           `/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
+      // (2026-09-25) 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)) {
@@ -2260,9 +2314,44 @@ 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)`,
+            );
+          }
+        }
       });
     }
-    // Money-path wave F1-3 (D3): an UNMAPPED price silently revoked a paying
+    // (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`,
+        );
+      }
+    }
+    // An UNMAPPED price silently revoked a paying
     // customer (priceMap miss → tier NULL → refold excluded the row). The
     // reducer now stamps such an event outcome 'error' (reprocessable), and
     // this lint catches the config half at `vxil push` time: every priceMap
@@ -2313,7 +2402,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     ];
     if (rmErrors.length) return { ok: false, errors: rmErrors.slice(0, 10) };
   }
-  // Cross-field rules: mcp custom tools + prompts (mcp.md §6.5/§11). The URL
+  // Cross-field rules: mcp custom tools + prompts (guide ch. 10). The URL
   // check here is a PURE mirror of @vxil/runtime assertPublicHttpsUrl (this
   // package is typebox-only) — the authoritative runtime guard re-runs in
   // mcp-v1 at call time; this gate rejects obviously-internal targets BEFORE
@@ -2379,7 +2468,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     const tplErrs = validateDeclaredAiTemplates(v.templates);
     if (tplErrs.length) return { ok: false, errors: tplErrs.slice(0, 10) };
   }
-  // Cross-field rules: declared API state (roadmap §4.11 P0-3). Each list is
+  // Cross-field rules: declared API state. Each list is
   // converged by NAME/URL, so a duplicate key is ambiguous and refused at push;
   // the per-item rules mirror the feature route's own validation so a declared
   // entry can never be one the converge would 422 on.
@@ -2393,7 +2482,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     const errs = validateDeclaredWebhookSubscriptions(v.subscriptions, v.maxSubscriptions);
     if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
   }
-  // Cross-field rule: auth otp.testRecipients (F4-29) — every entry must be an
+  // Cross-field rule: auth otp.testRecipients — every entry must be an
   // email, an `*@domain` glob, or a +E.164 number; anything else would never
   // match and silently do nothing.
   if (feature === 'auth') {
@@ -2430,7 +2519,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,7 +2535,10 @@ 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 —
+        if (b.overlap !== undefined && b.kind !== 'cron') {
+          errs.push(`/functions/${name}/bindings/${i}: 'overlap' applies to cron bindings only (not '${b.kind}')`);
+        }
+        // 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)) {
@@ -2455,7 +2547,11 @@ 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`);
         }
-        // authHook: a CLOSED event union (F4-30) — reject typos at write time
+        // 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 — 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)) {
           errs.push(`/functions/${name}/bindings/${i}: an 'authHook' binding's event must be one of ${AUTH_HOOK_EVENTS.join(' | ')} (or omitted = user.created)`);