@vxil/feature-configs 0.1.0

package/src/index.ts

@@ -0,0 +1,1572 @@
+// 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
+// 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';
+import { validateHooksConfig, type HookDef } from './hooks.js';
+import { validateCdcConfig, validateReadModelsConfig } from './readmodels.js';
+
+// Re-export the CMS lifecycle-hook engine so feature workers (cms-v1, runtime
+// eval) and the control plane (config-time validation) share one definition.
+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';
+
+// TypeBox validates `format:` only for registered formats — register the ones
+// our schemas use (pragmatic RFC-lite email check; providers do the real one).
+if (!FormatRegistry.Has('email')) {
+  FormatRegistry.Set('email', (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v));
+}
+
+export const NotificationsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  fromEmail: Type.String({ format: 'email' }),
+  fromName: Type.String({ default: 'Notifications' }),
+  replyTo: Type.Optional(Type.String({ format: 'email' })),
+  // Optional at the schema level: the `mock` provider (and inbox-only setups)
+  // 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()),
+  // 'mock' exists for staging/e2e (deterministic provider); 'resend' is MVP.
+  provider: Type.Union([Type.Literal('resend'), Type.Literal('mock')], {
+    default: 'resend',
+  }),
+  defaultLocale: Type.String({ default: 'en-US' }),
+  // nested objects carry `default: {}` so Value.Default can materialize them
+  // and then recurse into the leaf defaults
+  retry: Type.Object(
+    {
+      maxAttempts: Type.Integer({ default: 5, minimum: 1, maximum: 20 }),
+      backoff: Type.Union([Type.Literal('exponential'), Type.Literal('linear')], {
+        default: 'exponential',
+      }),
+    },
+    { default: {} },
+  ),
+  suppression: Type.Object(
+    { softBounceThreshold: Type.Integer({ default: 3 }) },
+    { default: {} },
+  ),
+  rateLimit: Type.Object(
+    {
+      perDay: Type.Integer({ default: 100000 }),
+      perTenantSec: Type.Integer({ default: 50 }),
+    },
+    { default: {} },
+  ),
+  templates: Type.Object(
+    { allowOverride: Type.Boolean({ default: false }) },
+    { default: {} },
+  ),
+  /** in-app inbox channel (send with channel: 'inbox' | 'both') */
+  inboxEnabled: Type.Boolean({ default: false }),
+});
+// Leaves: enabled, fromEmail, fromName, replyTo, resendApiKeyRef, provider,
+// defaultLocale, retry.maxAttempts, retry.backoff,
+// suppression.softBounceThreshold, rateLimit.perDay, rateLimit.perTenantSec,
+// templates.allowOverride, inboxEnabled → 14. Cap = 15.
+
+export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
+
+export const JobsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  retry: Type.Object(
+    { defaultMaxAttempts: Type.Integer({ default: 5, minimum: 1, maximum: 20 }) },
+    { default: {} },
+  ),
+  retention: Type.Object(
+    {
+      successfulRunDays: Type.Integer({ default: 7, minimum: 1, maximum: 90 }),
+      failedRunDays: Type.Integer({ default: 30, minimum: 1, maximum: 365 }),
+    },
+    { default: {} },
+  ),
+  /** Per-tenant daily dead-letter quota (0 = unlimited). Once the tenant has
+   * dead-lettered this many runs today, a further failing run skips its
+   * remaining retry budget and dead-letters immediately (audited as
+   * `job.dead_letter_quota_exceeded`) — bounds the retry/DLQ churn one
+   * pathological target (e.g. an always-throwing function) can generate. */
+  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).
+  generation: Type.Object(
+    {
+      /** per-tenant in-flight generation cap (separate budget from queue jobs) */
+      maxConcurrent: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
+      /** default expiry/timeout when the descriptor omits one */
+      defaultTimeoutMs: Type.Integer({ default: 300_000, minimum: 1_000, maximum: 3_600_000 }),
+      /** hard ceiling a tenant-supplied timeout is clamped to */
+      maxTimeoutMs: Type.Integer({ default: 3_600_000, minimum: 1_000, maximum: 3_600_000 }),
+      /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
+      pollMaxAttempts: Type.Integer({ default: 60, minimum: 1, maximum: 1_000 }),
+      /** 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 }),
+      /** 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 }),
+    },
+    { default: {} },
+  ),
+});
+// Leaves: 13 (6 + dlqDailyQuota + the 6 generation leaves). Cap = 15.
+
+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
+// (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).
+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).
+  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).
+  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
+  // 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
+  // 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 })),
+});
+
+export const AuthConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  methods: Type.Object(
+    {
+      emailPassword: Type.Boolean({ default: true }),
+      magicLink: Type.Boolean({ default: true }),
+      google: Type.Boolean({ default: false }),
+      github: Type.Boolean({ default: false }),
+      apple: Type.Boolean({ default: false }),
+      facebook: Type.Boolean({ default: false }),
+    },
+    { default: {} },
+  ),
+  // Per-provider BYO credential refs. ONE optional bag (= ONE leaf per the cap
+  // rule) keyed by provider, so the four provider blocks (and any future one)
+  // never inflate the flag count — the prior shape spent a leaf per top-level
+  // 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):
+  //   • google/github/facebook → { clientIdRef, clientSecretRef, audRefs? }
+  //   • apple                  → { servicesId, teamId, keyId, p8KeyRef }
+  // All *Ref fields are tenant_secrets POINTERS, never raw secrets (§6.5). 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
+  // (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({
+    google: Type.Optional(OAuthRefsSchema),
+    github: Type.Optional(OAuthRefsSchema),
+    apple: Type.Optional(AppleRefsSchema),
+    facebook: Type.Optional(OAuthRefsSchema),
+  })),
+  // session/password are OPTIONAL bags (= ONE leaf each per the cap rule) since
+  // the OTP/anonymous/orgClaims wave — 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.
+  session: Type.Optional(Type.Object(
+    {
+      ttlMinutes: Type.Integer({ default: 60, minimum: 5, maximum: 1440 }),
+      refreshTtlDays: Type.Integer({ default: 30, minimum: 1, maximum: 365 }),
+    },
+    { default: {} },
+  )),
+  password: Type.Optional(Type.Object(
+    {
+      minLength: Type.Integer({ default: 8, minimum: 6, maximum: 128 }),
+      requireMixed: Type.Boolean({ default: false }),
+    },
+    { default: {} },
+  )),
+  // Deviation (journaled): 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.
+  emailVerification: Type.Object(
+    { required: Type.Boolean({ default: false }) },
+    { default: {} },
+  ),
+  magicLink: Type.Object(
+    { tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }) },
+    { default: {} },
+  ),
+  // Email OTP sign-in (roadmap Tier-0) + the knobs step-up re-auth shares.
+  // OPTIONAL bag = 1 leaf; absent ⇒ disabled (the worker gates on
+  // otp?.enabled === true).
+  otp: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    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 }),
+  })),
+  // Anonymous (guest) sign-in (roadmap Tier-0). 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):
+  // 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).
+  // OPTIONAL bag = 1 leaf. Lives in AUTH config (not orgs) because auth-v1's
+  // CONFIG_KV is the auth namespace and cannot see orgs config.
+  orgClaims: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+  })),
+  // Deviation (journaled): the doc's §4 `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
+  // collapse elsewhere.
+});
+// Leaves: enabled(1) + methods(6) + providers(1, optional bag holding the four
+// google/github/apple/facebook credential blocks) + session(1, optional bag)
+// + password(1, optional bag) + emailVerification(1) + magicLink(1) + otp(1,
+// optional bag) + anonymous(1, optional bag) + orgClaims(1, optional bag) = 15.
+// Cap = 15 — at the cap; the next flag must collapse something.
+// providers is an optional bag → adding social providers (apple/facebook, §6) never
+// grows the flag count; the prior 15-flag version spent a leaf per top-level
+// google/github block.
+
+export type AuthConfig = Static<typeof AuthConfigSchema>;
+
+export const RateLimitsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  defaults: Type.Object(
+    {
+      perTenantSec: Type.Integer({ default: 100, minimum: 1, maximum: 10000 }),
+      burstSize: Type.Integer({ default: 200, minimum: 1, maximum: 20000 }),
+    },
+    { default: {} },
+  ),
+});
+// Leaves: 3. Cap = 15. Deviation (journaled): the doc's `policies` array is
+// managed via the dedicated REST surface (§1 contract) in the feature's own
+// KV, not duplicated into the config artifact — one writer per datum. The
+// per-identifier overrides live the same way (an `ovr:` KV sibling per policy,
+// cap 50 = a code constant, not a config leaf).
+
+export type RateLimitsConfig = Static<typeof RateLimitsConfigSchema>;
+
+export const FilesConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  bucketRef: Type.String({ default: 'vxil-files' }),
+  uploadUrlTtl: Type.Integer({ default: 900, minimum: 60, maximum: 86400 }),
+  downloadUrlTtl: Type.Integer({ default: 900, minimum: 60, maximum: 86400 }),
+  quotas: Type.Object(
+    {
+      // maximum caps are a defense-in-depth ceiling on tenant-editable storage —
+      // R2 is cheap but Neon-resident metadata + abuse aren't (pricing re-audit
+      // 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
+      // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
+      // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
+      maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
+      maxTotalBytes: Type.Integer({ default: 10 * 1024 * 1024 * 1024, minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 }),
+      maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
+    },
+    { default: {} },
+  ),
+  allowedContentTypes: Type.Array(Type.String(), { default: ['*'], maxItems: 100 }),
+  contentScan: Type.Object(
+    {
+      enabled: Type.Boolean({ default: false }), // V1.5
+      quarantineOnFail: Type.Boolean({ default: true }),
+    },
+    { default: {} },
+  ),
+  sharedLinks: Type.Object(
+    {
+      enabled: Type.Boolean({ default: true }),
+      maxTtl: Type.Integer({ default: 7 * 24 * 3600 }),
+    },
+    { default: {} },
+  ),
+  // Wave-2 extensions (features/files.md §1.1 OCR + §1.2 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
+  // declaring them here is what stops Value.Clean silently stripping them
+  // out of PUT /v1/config/files.
+  ttl: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    // per-bucket default; omitted = never expire by default
+    defaultExpiresInSeconds: Type.Optional(Type.Integer({ minimum: 60 })),
+    sweepCron: Type.String({ default: '0 * * * *' }), // jobs-v1 TTL sweep schedule
+  })),
+  extractText: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    provider: Type.Union(
+      [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).
+    keyRef: Type.Optional(Type.String()),
+    asyncOverJobs: Type.Boolean({ default: true }), // large/multi-page → jobs
+    boundingBoxes: Type.Boolean({ default: false }),
+  })),
+});
+// Leaves: 12 + ttl(1, optional bag) + extractText(1, optional bag) = 14. Cap = 15.
+
+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.
+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 }),
+});
+// Leaves: 3. Cap = 15.
+
+export type WebhooksConfig = Static<typeof WebhooksConfigSchema>;
+
+// comments feature (wishlist): threaded discussion on tenant-defined topics.
+export const CommentsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  maxBodyLength: Type.Integer({ default: 10_000, minimum: 1, maximum: 65_536 }),
+  reactionsEnabled: Type.Boolean({ default: true }),
+  /** Author edits allowed this long after posting; 0 disables editing. */
+  editWindowMinutes: Type.Integer({ default: 15, minimum: 0, maximum: 10_080 }),
+});
+// Leaves: 4. Cap = 15.
+
+export type CommentsConfig = Static<typeof CommentsConfigSchema>;
+
+// content feature (cms-feature-analysis.md §4.2): 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.
+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,
+  // a VERIFIED end-user key (owner-scope mode) is DENIED access to any
+  // collection that declares no owner_field — 404 on read, 403 on write —
+  // 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
+  // declare an ownerField is unaffected. ONE boolean leaf.
+  strictEndUserScope: Type.Boolean({ default: false }),
+  limits: Type.Object(
+    {
+      maxCollections: Type.Integer({ default: 25, minimum: 1, maximum: 200 }),
+      maxFieldsPerCollection: Type.Integer({ default: 50, minimum: 1, maximum: 200 }),
+      maxItemBytes: Type.Integer({ default: 256 * 1024, minimum: 1024, maximum: 1024 * 1024 }),
+      maxItemsPerCollection: Type.Integer({ default: 100_000, minimum: 1 }),
+    },
+    { default: {} },
+  ),
+  query: Type.Object(
+    {
+      maxPageSize: Type.Integer({ default: 100, minimum: 1, maximum: 500 }),
+      defaultPageSize: Type.Integer({ default: 25, minimum: 1, maximum: 500 }),
+    },
+    { default: {} },
+  ),
+  // cms ENRICHMENT (cms.md §6.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(
+    {
+      maxExpandDepth: Type.Integer({ default: 1, minimum: 1, maximum: 2 }),
+      maxExpandFields: Type.Integer({ default: 5, minimum: 1, maximum: 25 }),
+      maxComputedFieldsPerCollection: Type.Integer({ default: 10, minimum: 1, maximum: 50 }),
+    },
+    { default: {} },
+  ),
+  // Code-based lifecycle hooks (docs/cms-lifecycle-hooks-rung2-design.md, Lane A):
+  // a tenant-authored SAFE expression. Write events (beforeCreate/beforeUpdate/
+  // beforeWrite) run in-transaction — `validate` rejects the write, `derive`
+  // computes a persisted field. Read events shape the RESPONSE only: `validate`
+  // on beforeRead drops the row (visibility filter); `derive`/`redact` on
+  // afterRead set/delete a field on the output copy (never persisted). The
+  // expression language is a closed, sandboxed, deterministic interpreter (see
+  // hooks.ts); each hook is AST-validated + kind/event-matrix-checked at config
+  // time (validateFeatureConfig below). Type.Record bag → counts as ONE leaf.
+  hooks: Type.Optional(
+    Type.Record(
+      Type.String(),
+      Type.Object({
+        collection: Type.String(),
+        event: Type.Union([
+          Type.Literal('beforeCreate'),
+          Type.Literal('beforeUpdate'),
+          Type.Literal('beforeWrite'),
+          Type.Literal('beforeRead'),
+          Type.Literal('afterRead'),
+        ]),
+        kind: Type.Union([Type.Literal('validate'), Type.Literal('derive'), Type.Literal('redact')]),
+        expr: Type.String({ maxLength: 2000 }),
+        field: Type.Optional(Type.String({ maxLength: 64 })),
+        message: Type.Optional(Type.String({ maxLength: 200 })),
+        enabled: Type.Optional(Type.Boolean()),
+      }),
+    ),
+  ),
+  // Declarative relational read-models (cms-relational-depth §3 B2/B3/B5).
+  // 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
+  // at config-write (validateReadModelsConfig — the hooks anti-malice-gate
+  // pattern); collection/slot existence at runtime. ONE Type.Record leaf.
+  readModels: Type.Optional(Type.Record(
+    Type.String({ maxLength: 64 }),
+    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 functions `signature` idiom); shape checked by the cross-field rule.
+      spec: Type.Unknown(),
+      materialize: Type.Optional(Type.Object({
+        cron: Type.String({ maxLength: 100 }),
+        to: Type.String({ maxLength: 64 }),
+      })),
+      enabled: Type.Optional(Type.Boolean()),
+    }),
+  )),
+  // Realtime CDC bridge (cms-rel E): cms writes auto-publish a change event to
+  // a realtime channel — config-only rewiring of postgres_changes-style subs.
+  // Fire-and-forget via waitUntil; at-most-once (guaranteed delivery stays
+  // webhooks-out / functions cms-hook). ONE Type.Record leaf.
+  cdc: Type.Optional(Type.Record(
+    Type.String({ maxLength: 64 }),
+    Type.Object({
+      collection: Type.String({ maxLength: 64 }),
+      channel: Type.String({ maxLength: 128 }),
+      events: Type.Optional(Type.Array(Type.Union([
+        Type.Literal('created'), Type.Literal('updated'),
+        Type.Literal('deleted'), Type.Literal('published'),
+      ]), { maxItems: 4 })),
+      payload: Type.Optional(Type.Union([Type.Literal('ids'), Type.Literal('full')])),
+      enabled: Type.Optional(Type.Boolean()),
+    }),
+  )),
+});
+// Leaves: 15 — enabled, draftPublish, strictEndUserScope, limits(4), query(2),
+// relations.{maxExpandDepth,maxExpandFields,maxComputedFieldsPerCollection}(3),
+// hooks + readModels + cdc (Type.Record bags = ONE leaf each). Cap = 15 (AT the
+// cap now — any future cms knob must ride inside an existing bag).
+
+export type CmsConfig = Static<typeof CmsConfigSchema>;
+
+// mcp feature (mcp.md §5): 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 }),
+  exposureLevel: Type.Union(
+    [Type.Literal('all'), Type.Literal('read-only'), Type.Literal('custom')],
+    { default: 'all' },
+  ),
+  allowToolList: Type.Optional(Type.Array(Type.String(), { maxItems: 200 })),
+  scopedKey: Type.Object(
+    { perAgentKeys: Type.Boolean({ default: false }) }, // V1.5
+    { default: {} },
+  ),
+  rateLimits: Type.Object(
+    { toolCallsPerMin: Type.Integer({ default: 60, minimum: 1, maximum: 6000 }) },
+    { default: {} },
+  ),
+  branding: Type.Object(
+    {
+      serverName: Type.String({ default: 'Vxil' }),
+      serverInstructions: Type.Optional(Type.String({ maxLength: 4000 })),
+    },
+    { default: {} },
+  ),
+
+  // Tenant-authored CUSTOM tools (mcp.md §6.5): 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
+  // is NEVER forwarded). ONE Type.Record leaf (the cms.hooks precedent).
+  // Cross-field rules (count/name/url/schema-size) live in
+  // validateFeatureConfig below.
+  customTools: Type.Optional(Type.Record(
+    Type.String({ maxLength: 64 }),
+    Type.Object({
+      description: Type.String({ maxLength: 500 }),
+      url: Type.String({ maxLength: 2000 }),
+      // free-form JSON-Schema (agent-facing) — Type.Unknown so Value.Clean
+      // does not hollow it out (the functions signature input/output idiom);
+      // shape (plain object) + size (≤8KB) are cross-field rules below.
+      inputSchema: Type.Optional(Type.Unknown()),
+      timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, maximum: 20_000 })),
+    }),
+  )),
+
+  // Config-declared MCP PROMPTS (mcp.md §11 closure): 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.
+  prompts: Type.Optional(Type.Record(
+    Type.String({ maxLength: 64 }),
+    Type.Object({
+      description: Type.Optional(Type.String({ maxLength: 500 })),
+      template: Type.String({ maxLength: 4000 }),
+      arguments: Type.Optional(Type.Array(Type.Object({
+        name: Type.String({ maxLength: 64 }),
+        description: Type.Optional(Type.String({ maxLength: 200 })),
+        required: Type.Optional(Type.Boolean()),
+      }), { maxItems: 10 })),
+    }),
+  )),
+});
+// Leaves: 9 by countLeaves (enabled, exposureLevel, allowToolList,
+// scopedKey.perAgentKeys, rateLimits.toolCallsPerMin, branding.serverName,
+// branding.serverInstructions = 7, + customTools + prompts as ONE Type.Record
+// leaf each). Cap = 15.
+
+export type McpConfig = Static<typeof McpConfigSchema>;
+
+// realtime feature (promoted wishlist): DO-backed pub/sub channels.
+export const RealtimeConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  maxConnectionsPerChannel: Type.Integer({ default: 100, minimum: 1, maximum: 10_000 }),
+});
+// Leaves: 2. Cap = 15.
+
+export type RealtimeConfig = Static<typeof RealtimeConfigSchema>;
+
+// presence feature (promoted wishlist): join/leave/typing on top of realtime.
+export const PresenceConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+});
+// Leaves: 1. Cap = 15.
+
+export type PresenceConfig = Static<typeof PresenceConfigSchema>;
+
+// orgs + RBAC feature (promoted wishlist): workspaces, invitations, role checks.
+export const OrgsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  maxOrgsPerTenant: Type.Integer({ default: 100, minimum: 1, maximum: 10_000 }),
+  maxMembersPerOrg: Type.Integer({ default: 1000, minimum: 1, maximum: 100_000 }),
+  invitationTtlHours: Type.Integer({ default: 168, minimum: 1, maximum: 720 }),
+});
+// Leaves: 4. Cap = 15.
+
+export type OrgsConfig = Static<typeof OrgsConfigSchema>;
+
+// activity-feed feature (features/activity-feed.md §3): 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
+// tenant's moat). feedGroups is a Type.Record (name → group def) → ONE leaf
+// (the bag), so adding feed groups / aggregation rules never grows the cap.
+export const ActivityFeedConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+
+  // FEED-GROUP definitions: name → group def. Each group declares its type +
+  // (for aggregated/notification) its aggregation rule + ranking. Counts as ONE
+  // leaf (the Record bag), per the cap rule.
+  feedGroups: Type.Record(
+    Type.String(),
+    Type.Object({
+      type: Type.Union([
+        Type.Literal('flat'),
+        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
+    }),
+    {
+      default: {
+        user: { type: 'flat' },
+        timeline: { type: 'flat', ranking: 'chronological' },
+        notification: {
+          type: 'notification',
+          aggregation: '{{ verb }}:{{ object }}:{{ time|date }}',
+        },
+      },
+    },
+  ),
+
+  fanout: 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)
+      pendingCeiling: Type.Integer({ default: 50_000, minimum: 1 }), // pending-fan-out-depth back-pressure ceiling
+    },
+    { default: {} },
+  ),
+
+  follow: Type.Object(
+    {
+      copyLimit: Type.Integer({ default: 100, minimum: 0, maximum: 1000 }), // backfill budget on follow
+      maxFollowing: Type.Integer({ default: 10_000, minimum: 0 }), // per-feed following cap
+    },
+    { default: {} },
+  ),
+
+  aggregation: Type.Object(
+    {
+      maxGroupActivities: Type.Integer({ default: 15, minimum: 1, maximum: 100 }), // newest-N kept per group
+    },
+    { default: {} },
+  ),
+
+  realtime: Type.Object(
+    {
+      enabled: Type.Boolean({ default: true }), // live new-activity + count push over the realtime ChannelDO
+    },
+    { default: {} },
+  ),
+
+  crossChannel: Type.Object(
+    {
+      enabled: Type.Boolean({ default: false }), // master gate for the notifications push/email trigger (§10)
+      digestCadence: Type.Union(
+        [Type.Literal('off'), Type.Literal('hourly'), Type.Literal('daily')],
+        { default: 'off' },
+      ), // digest roll-up window (feed owns the roll-up, rides notifications' live single-send)
+    },
+    { default: {} },
+  ),
+
+  rateLimit: Type.Object(
+    {
+      addPerSec: Type.Integer({ default: 100, minimum: 1, maximum: 100_000 }), // per-tenant activity-write burst
+    },
+    { default: {} },
+  ),
+});
+// Leaves: enabled(1), feedGroups(1, the Record bag → ONE leaf), fanout.{celebrityThreshold,
+//   maxFanoutPerJob, maxConcurrentTasks, pendingCeiling}(+4=6), follow.{copyLimit,
+//   maxFollowing}(+2=8), aggregation.maxGroupActivities(9), realtime.enabled(10),
+//   crossChannel.{enabled, digestCadence}(+2=12), rateLimit.addPerSec(13).
+// countLeaves → 13. Cap = 15. (feedGroups is Type.Record → patternProperties, ONE leaf.)
+
+export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
+
+// vector-search feature (features/vector-search.md §4). Re-declared here to match the
+// schema the worker EXPORTS from workers/vector-search-v1/src/config.ts — the
+// control plane validates writes against this shared copy (the same
+// one-definition / two-consumers note as the other features above; this package owns
+// the registry, the worker owns its in-process schema). Flags govern the BACKEND,
+// the embedder, chunking, the hybrid-fusion knobs, and limits — NEVER prompts /
+// 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 pgvector until Lakebase is GA'd for the tier (#147).
+  backend: Type.Union(
+    [Type.Literal('auto'), Type.Literal('lakebase'), Type.Literal('pgvector')],
+    { default: 'auto' },
+  ),
+  // 'byov'/'mock' need NO provider key (zero-config default); openai/cohere read a
+  // BYO key from public.tenant_secrets via apiKeyRef (envelope-encrypted).
+  embed: Type.Object(
+    {
+      provider: Type.Union(
+        [
+          Type.Literal('byov'),
+          Type.Literal('mock'),
+          Type.Literal('openai'),
+          Type.Literal('cohere'),
+        ],
+        { default: 'mock' },
+      ),
+      model: Type.Optional(Type.String()), // e.g. 'text-embedding-3-small'
+      apiKeyRef: Type.Optional(Type.String()), // 'secret:<name>'; omit for byov/mock
+      dimensions: Type.Integer({ default: 1536, minimum: 2, maximum: 4096 }),
+    },
+    { default: {} },
+  ),
+  chunking: Type.Object(
+    {
+      maxTokens: Type.Integer({ default: 512, minimum: 16, maximum: 4096 }),
+      overlap: Type.Integer({ default: 64, minimum: 0, maximum: 1024 }),
+    },
+    { default: {} },
+  ),
+  hybrid: Type.Object(
+    {
+      defaultMode: Type.Union(
+        [Type.Literal('hybrid'), Type.Literal('vector'), Type.Literal('keyword')],
+        { default: 'hybrid' },
+      ),
+      rrfK: Type.Integer({ default: 60, minimum: 1, maximum: 1000 }),
+    },
+    { default: {} },
+  ),
+  limits: Type.Object(
+    {
+      maxDocsPerCollection: Type.Integer({ default: 100_000, minimum: 1 }),
+      maxChunksPerDoc: Type.Integer({ default: 1000, minimum: 1, maximum: 10_000 }),
+    },
+    { default: {} },
+  ),
+  // BYO rerank pass over the RRF-fused candidates before the top-k slice.
+  // Config-declared provider (key never per-request); a request opts OUT with
+  // rerank:false. Fail-OPEN on provider errors (reranked:false). ONE leaf.
+  rerank: Type.Optional(
+    Type.Object({
+      provider: Type.Union(
+        [Type.Literal('mock'), Type.Literal('cohere'), Type.Literal('voyage')],
+      ),
+      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
+    }),
+  ),
+  // Config-driven auto-embedding sync from cms collections: the control plane
+  // reconciles one `vs-sync:` jobs schedule per entry on every config commit;
+  // the cron ticks the worker's internal receiver (backfill keyset →
+  // updated_at watermark over the public cms REST). ARRAY = ONE leaf.
+  sync: Type.Optional(
+    Type.Array(
+      Type.Object({
+        source: Type.Literal('cms'),
+        cmsCollection: Type.String({ minLength: 1, maxLength: 128 }),
+        collection: Type.String({ minLength: 1, maxLength: 128 }),
+        fields: Type.Array(Type.String(), { minItems: 1, maxItems: 16 }),
+        template: Type.Optional(Type.String({ maxLength: 4000 })),
+        metadataFields: Type.Optional(Type.Array(Type.String(), { maxItems: 16 })),
+        statusFilter: Type.Optional(
+          Type.Union([Type.Literal('published'), Type.Literal('all')]),
+        ),
+        cron: Type.Optional(Type.String({ pattern: '^\\S+ \\S+ \\S+ \\S+ \\S+$' })),
+      }),
+      { maxItems: 8 },
+    ),
+  ),
+});
+// Leaves: enabled(1), backend(2), embed.{provider,model,apiKeyRef,dimensions}(+4=6),
+//   chunking.{maxTokens,overlap}(+2=8), hybrid.{defaultMode,rrfK}(+2=10),
+//   limits.{maxDocsPerCollection,maxChunksPerDoc}(+2=12), rerank (optional
+//   object, +1=13), sync (array, +1=14). countLeaves → 14. Cap = 15 — one leaf
+//   of headroom; fold limits.* into one optional object (−1) if more is needed.
+
+export type VectorSearchConfig = Static<typeof VectorSearchConfigSchema>;
+
+// ai feature (features/ai.md §4). 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.
+export const AiConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  // 'azure' uses the OpenAI adapter shape (azure-openai compatible; pair it with
+  // providers.compat.openaiBaseUrl). 'openrouter' is the openai-compatible
+  // meta-provider (BYO key under providers.compat.openrouterKeyRef).
+  defaultProvider: Type.Union(
+    [Type.Literal('mock'), Type.Literal('openai'), Type.Literal('anthropic'),
+     Type.Literal('gemini'), Type.Literal('azure'), Type.Literal('openrouter')],
+    { default: 'mock' },
+  ),
+  // BYO keyRefs → public.tenant_secrets (envelope-encrypted). 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
+  // tenant writes a bare `{}` — the control plane is the defaulting authority and
+  // persists the materialized manifest the worker then reads verbatim.
+  providers: Type.Object({
+    openaiKeyRef: Type.Optional(Type.String()),
+    anthropicKeyRef: Type.Optional(Type.String()),
+    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.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
+    // assertPublicHttpsUrl in ai-v1) — the jobs target_url double-guard idiom.
+    compat: Type.Optional(Type.Object({
+      openrouterKeyRef: Type.Optional(Type.String()),
+      openaiBaseUrl: Type.Optional(Type.String({ maxLength: 512 })),
+    })),
+  }, { default: {} }),
+  defaults: Type.Object({
+    model: Type.String({ default: 'mock-1' }),
+    maxTokens: Type.Integer({ default: 1024, minimum: 1, maximum: 200_000 }),
+    temperature: Type.Number({ default: 0.7, minimum: 0, maximum: 2 }),
+  }, { default: {} }),
+  cache: Type.Object({ ttlSeconds: Type.Integer({ default: 0, minimum: 0 }) }, { default: {} }), // 0 = off
+  limits: Type.Object({
+    tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = unlimited
+    consumeCredits: Type.Boolean({ default: false }),              // reserve→settle (STUB until payments)
+  }, { default: {} }),
+  streaming: 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
+  }, { default: {} }),
+});
+// Leaves: enabled(1), defaultProvider(2), providers.{openai,anthropic,gemini}KeyRef(+3=5),
+//   providers.compat(+1=6 — Optional object → ONE leaf),
+//   defaults.{model,maxTokens,temperature}(+3=9), cache.ttlSeconds(10),
+//   limits.{tokensPerUserPerDay,consumeCredits}(+2=12),
+//   streaming.{enabled,replayBufferFrames,flushMs}(+3=15). countLeaves → 15. Cap = 15.
+//   ZERO headroom: any future ai knob must ride inside compat (free) or another
+//   optional object.
+
+export type AiConfig = Static<typeof AiConfigSchema>;
+
+// rag feature (features/rag.md §2). 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).
+export const RagConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  // default vector-search collection when the request omits `collection`.
+  defaultCollection: Type.Optional(Type.String()),
+  retrieval: Type.Object(
+    {
+      topK: Type.Integer({ default: 8, minimum: 1, maximum: 100 }),
+      mode: Type.Union(
+        [Type.Literal('hybrid'), Type.Literal('vector'), Type.Literal('keyword')],
+        { default: 'hybrid' },
+      ),
+      // drop retrieved chunks below this score BEFORE budgeting (0 = keep all).
+      minScore: Type.Number({ default: 0 }),
+      // forward rerank:true to vector-search's post-RRF BYO rerank pass (it owns
+      // the provider + key); inert until that pass exists/is configured there.
+      rerank: Type.Boolean({ default: false }),
+    },
+    { default: {} },
+  ),
+  // declarative per-metadata-field relevance boosts applied in rag AFTER
+  // retrieval, BEFORE minScore/budget/grounding (rag.md §2f). ONE Type.Record
+  // leaf (the activity-feed feedGroups precedent).
+  boosts: Type.Record(Type.String(), Type.Union([
+    Type.Object({
+      kind: Type.Literal('recency'),
+      halfLifeDays: Type.Number({ default: 30, minimum: 0.01, maximum: 3650 }),
+      weight: Type.Number({ default: 0.3, minimum: 0, maximum: 1 }),
+    }),
+    Type.Object({
+      kind: Type.Literal('value'),
+      weights: Type.Record(Type.String(), Type.Number({ minimum: 0, maximum: 100 })),
+    }),
+  ]), { default: {} }),
+  context: Type.Object(
+    {
+      // bounded context budget — enforced via the §2c 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).
+      tokenizer: Type.Union([Type.Literal('provider'), Type.Literal('heuristic')], {
+        default: 'provider',
+      }),
+    },
+    { default: {} },
+  ),
+  // an ai.templates ref (tenant-authored) used when the request omits `template`.
+  defaultTemplate: Type.Optional(Type.String()),
+  citations: Type.Boolean({ default: true }),
+  streaming: Type.Boolean({ default: true }),
+});
+// Leaves: enabled(1), defaultCollection(2),
+//   retrieval.{topK,mode,minScore,rerank}(+4=6), boosts(7 — Type.Record = ONE leaf),
+//   context.{maxTokens,strategy,tokenizer}(+3=10), defaultTemplate(11),
+//   citations(12), streaming(13). countLeaves → 13. Cap = 15.
+
+export type RagConfig = Static<typeof RagConfigSchema>;
+
+// payments feature (features/payments.md §5). 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
+// optional stripe/paddle/revenuecat credential blocks, each ONE leaf) and (B)
+// the credits & entitlements LEDGER. The `ledger` block is OPTIONAL → ONE leaf,
+// and its interior productMap/tierMap are Type.Record MAPS (data, not flags) —
+// so adding products/tiers never grows the cap. The mock provider is the
+// zero-config default (no provider block needed); a tenant picks ONE real
+// provider so only one optional credential sub-object is ever active.
+export const PaymentsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+  // 'mock' is the deterministic default (instant sub/credit, synthetic webhook
+  // events) so the ENTIRE ledger path is testable WITHOUT real provider keys.
+  provider: Type.Union(
+    [Type.Literal('mock'), Type.Literal('stripe'), Type.Literal('paddle'),
+     Type.Literal('revenuecat'), Type.Literal('paypal')],
+    { default: 'mock' },
+  ),
+  // BYO-key credential blocks → public.tenant_secrets (envelope-encrypted).
+  // Each OPTIONAL object counts as ONE leaf (the tenant's decision is
+  // "configure it or not", not each inner ref — features/auth.md §4).
+  stripe: Type.Optional(Type.Object({
+    secretKeyRef: Type.String(),
+    webhookSecretRef: Type.String(),
+    taxEnabled: Type.Boolean({ default: false }),
+  })),
+  paddle: Type.Optional(Type.Object({
+    apiKeyRef: Type.String(),
+    webhookSecretRef: Type.String(),
+    sandbox: Type.Boolean({ default: false }),
+  })),
+  revenuecat: Type.Optional(Type.Object({
+    projectId: Type.String(),
+    publicSdkKey: Type.String(),
+    secretApiKeyRef: Type.String(),
+    // Optional per-tenant webhook secret ref (public.tenant_secrets). When set,
+    // inbound RevenueCat webhooks are verified with THIS tenant's secret instead
+    // of the platform PROVIDER_WEBHOOK_SECRET — closes the multi-tenant RC
+    // webhook-forgery vector (mirrors stripe/paddle webhookSecretRef).
+    webhookSecretRef: Type.Optional(Type.String()),
+  })),
+  paypal: Type.Optional(Type.Object({
+    clientIdRef: Type.String(),
+    secretRef: Type.String(),
+    webhookId: Type.String(),          // the registered webhook's id (PayPal verifies by id, not a static secret)
+    sandbox: Type.Boolean({ default: false }),
+  })),
+  // 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).
+  returnUrl: Type.Optional(Type.String({ pattern: '^https://', maxLength: 512 })),
+  prices: Type.Object(
+    { catalogRef: Type.String({ default: 'default' }) }, // tenant-supplied price catalog ref
+    { default: {} },
+  ),
+  defaults: Type.Object(
+    {
+      currency: Type.String({ default: 'usd' }),
+      trialDays: Type.Integer({ default: 0, minimum: 0, maximum: 365 }),
+    },
+    { default: {} },
+  ),
+  // The credits & entitlements ledger config. OPTIONAL → ONE leaf at the
+  // 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')]),
+    })),
+    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)
+      grants: Type.Optional(Type.Array(Type.Object({
+        creditType: Type.String({ minLength: 1 }),
+        amount: Type.Integer({ minimum: 1 }),               // #128
+        period: Type.String(),
+      }))),
+    })),
+    // provider price/plan id → tier. A real subscription webhook carries the
+    // provider's price/plan id (Stripe price_…, Paddle pri_…, PayPal plan id),
+    // NOT a tier; this map lets the webhook reducer resolve it so the entitlement
+    // 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
+  })),
+  webhooks: Type.Object(
+    { forwardToTenantUrl: Type.Optional(Type.String({ format: 'uri' })) },
+    { default: {} },
+  ),
+});
+// Leaves: enabled(1), provider(2), stripe?(3), paddle?(4), revenuecat?(5),
+//   paypal?(6), prices.catalogRef(7), defaults.{currency,trialDays}(+2=9),
+//   ledger?(10), webhooks.forwardToTenantUrl(11). countLeaves → 11. Cap = 15.
+//   (productMap / tierMap / priceMap are Type.Record MAPS inside the ONE optional
+//   ledger leaf — DATA, not flags — so catalog size never moves the count.)
+
+export type PaymentsConfig = Static<typeof PaymentsConfigSchema>;
+
+// functions feature (vxil-functions-design §4.c). Tenant-deployed backend edge
+// functions on Workers-for-Platforms. 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,
+// opt-in (enabled defaults to false), egress-guarded.
+export const FunctionsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: false }),
+  // isolate = WfP Worker (Lane 2, default); container = CF Containers (Lane 3, design-only).
+  runtime: Type.Union([Type.Literal('isolate'), Type.Literal('container')], { default: 'isolate' }),
+  defaultLimits: Type.Object(
+    {
+      cpuMs: Type.Integer({ default: 50, minimum: 5, maximum: 300_000 }),
+      timeoutMs: Type.Integer({ default: 10_000, minimum: 50, maximum: 300_000 }),
+      memoryMb: Type.Integer({ default: 128, minimum: 64, maximum: 1024 }),
+    },
+    { default: {} },
+  ),
+  // Reserve→settle CPU-ms metering into the payments credit ledger (the
+  // recover-by-price tier, live-prep "functions metering"). When enabled the
+  // dispatcher RESERVES fn.limits.cpuMs (?? defaultLimits.cpuMs) `fn_cpu_ms`
+  // credits per invoke (provisional consume, job_id `fn:<request_id>`) and
+  // settles/reverses via the payments job-reversal after dispatch. Written by
+  // the deploy pipeline (`metering` in the deploy body), like everything else
+  // in this deploy-managed manifest.
+  metering: Type.Object(
+    { enabled: Type.Boolean({ default: false }) },
+    { default: {} },
+  ),
+  // ONE Type.Record leaf — the per-function object is DATA, not flags.
+  functions: Type.Optional(
+    Type.Record(
+      Type.String(),
+      Type.Object({
+        // http/cron/queue/webhook bindings live here; a `cmsHook` binding also
+        // lives here (it carries collection+event) so the control-plane can
+        // auto-wire the webhook_subscription that fires it — the cms.hooks
+        // {kind:function, ref} authoring surface still references the function
+        // by name for the Lane-A path. An `authHook` binding is the post-signup
+        // sibling: the control-plane auto-wires ONE webhook_subscription on the
+        // `auth.user.created` audit event (event defaults to 'user.created' —
+        // the only value today). Per-function fields are OPTIONAL because
+        // Value.Default does not recurse into Type.Record VALUES (same pattern
+        // as cms.hooks' HookDef). scriptRef is the only required field; the
+        // worker applies `?? []` / `?? true` at read time. The deploy pipeline
+        // always writes the full materialized entry.
+        bindings: Type.Optional(
+          Type.Array(
+            Type.Object({
+              kind: Type.Union([
+                Type.Literal('http'),
+                Type.Literal('queue'),
+                Type.Literal('cron'),
+                Type.Literal('webhook'),
+                Type.Literal('cmsHook'),
+                Type.Literal('authHook'),
+              ]),
+              path: Type.Optional(Type.String()), // http: custom path; default /v1/fn/<name>
+              schedule: Type.Optional(Type.String()), // cron: 5-field expression
+              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'
+            }),
+            { maxItems: 8 },
+          ),
+        ),
+        scriptRef: Type.String(), // content-hashed WfP script name: fn-<tenant>-<name>-<sha>
+        scopes: Type.Optional(Type.Array(Type.String())), // clamped via DENY_FUNCTION_SCOPES at deploy (admin/*/features:write/functions:write/secrets:write)
+        secrets: Type.Optional(Type.Array(Type.String())), // tenant_secrets refs (KEK_FUNCTIONS)
+        egressAllow: Type.Optional(Type.Array(Type.String())), // Outbound Worker allowlist hosts
+        limits: Type.Optional(
+          Type.Object({
+            cpuMs: Type.Integer(),
+            timeoutMs: Type.Integer(),
+            memoryMb: Type.Integer(),
+          }),
+        ),
+        enabled: Type.Optional(Type.Boolean()),
+        // Level-1 typed I/O (cli-sdk design §4.5): 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.
+        signature: Type.Optional(Type.Object({
+          input: Type.Optional(Type.Unknown()),
+          output: Type.Optional(Type.Unknown()),
+        })),
+      }),
+    ),
+  ),
+});
+// Leaves: enabled(1), runtime(2), defaultLimits.{cpuMs,timeoutMs,memoryMb}(+3=5),
+//   metering.enabled(6), functions(7, 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 → 7. Cap = 15.
+export type FunctionsConfig = Static<typeof FunctionsConfigSchema>;
+
+// copilot feature (docs/copilot-agents-sku-design.md §4). Re-declared to match
+// workers/copilot-v1/src/config.ts's exported CopilotConfigSchema (one shape,
+// two consumers — keep the two definitions byte-identical). A thin COMPOSITION
+// layer over ai + vector-search + rag + mcp: it owns the AGENT layer (persona,
+// knowledge wiring, the action-catalog gate, guardrails, the embed surface) and
+// never re-declares embedder/chunking/synthesis knobs (those belong to
+// vector-search / ai / rag). The `agents` Record is the one open-ended
+// structure — keyed by agentId, ONE leaf (cms.hooks / payments.ledger
+// precedent); inside each agent, `actions.allow` is a second nested Record
+// (toolKey → gate) — also data, not flags. Cross-feature resolutions
+// (collection existence, directiveRef → ai.templates) are deliberately NOT
+// validated here: they need control-plane round-trips, and the runtime already
+// fails soft with the capability-surface envelope.
+export const CopilotConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: true }),
+
+  // Per-agent map (data, not flags) → ONE leaf. NOTE: Value.Default does NOT
+  // recurse into Type.Record VALUES (the cms.hooks / functions.functions
+  // precedent), so nested per-agent objects are OPTIONAL and the worker applies
+  // `?? default` at read time. default {} so the quickstart's minimal
+  // `{ enabled: true }` body materializes to a valid zero-agent manifest.
+  agents: Type.Record(
+    Type.String({ minLength: 1, maxLength: 64 }),      // agentId (slug)
+    Type.Object({
+      // ── persona ──────────────────────────────────────────────────────────
+      name: Type.String({ minLength: 1, maxLength: 80 }),
+      // CONFIG-AS-CODE: a ref into the tenant's ai.templates (rendered by
+      // ai-v1, never authored as executable code).
+      directiveRef: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+      tone: Type.Optional(Type.String({ maxLength: 200 })),
+      greeting: Type.Optional(Type.String({ maxLength: 500 })),
+      locale: Type.Optional(Type.String({ maxLength: 16, default: 'en-US' })),
+
+      // ── knowledge: vector-search collection refs + retrieval policy ───────
+      // Pipeline knobs (topK/mmr/budget/tokenizer) stay in RagConfig.
+      // Interior fields are ALL Optional (Value.Default does not recurse into
+      // Type.Record VALUES — the functions.functions precedent); the `default`
+      // annotations document the read-time `?? default` the worker applies.
+      knowledge: Type.Optional(Type.Object({
+        collections: Type.Optional(Type.Array(Type.String({ maxLength: 128 }), { maxItems: 32, default: [] })),
+        useRag: Type.Optional(Type.Boolean({ default: true })),
+        ragTemplateRef: Type.Optional(Type.String({ maxLength: 128 })),
+        topKOverride: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+      })),
+
+      // ── citations + grounding ─────────────────────────────────────────────
+      citations: Type.Optional(Type.Boolean({ default: true })),
+      grounding: Type.Optional(Type.Union(
+        [Type.Literal('strict'), Type.Literal('blended')],
+        { default: 'strict' },
+      )),
+
+      // ── actions block: mcp toolKey → gate (the catalog IS the action set) ──
+      actions: Type.Optional(Type.Object({
+        mode: Type.Optional(Type.Union(
+          [Type.Literal('off'), Type.Literal('readonly'), Type.Literal('actions')],
+          { default: 'readonly' },
+        )),
+        allow: Type.Optional(Type.Record(
+          Type.String({ maxLength: 64 }),              // mcp toolKey
+          Type.Object({
+            enabled: Type.Optional(Type.Boolean({ default: true })),
+            requireConfirm: Type.Optional(Type.Boolean({ default: true })),
+            minScope: Type.Optional(Type.String({ maxLength: 64 })),
+          }),
+          { default: {} },
+        )),
+      })),
+
+      // ── guardrails ────────────────────────────────────────────────────────
+      guardrails: Type.Optional(Type.Object({
+        maxTurnsPerSession: Type.Optional(Type.Integer({ default: 40, minimum: 1, maximum: 500 })),
+        rateLimitPerUserPerDay: Type.Optional(Type.Integer({ default: 50, minimum: 0 })), // 0 = unlimited
+        maxInputChars: Type.Optional(Type.Integer({ default: 4000, minimum: 1, maximum: 32_000 })),
+        refusalMessage: Type.Optional(Type.String({ maxLength: 500 })),
+        allowGuest: Type.Optional(Type.Boolean({ default: false })),
+        guestToolAllow: Type.Optional(Type.Array(Type.String({ maxLength: 64 }), { maxItems: 16, default: [] })),
+      })),
+    }),
+    { default: {} },
+  ),
+
+  // ── escalation: human hand-off (composes notifications/comments) ──────────
+  escalation: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    handler: Type.Union(
+      [Type.Literal('comments'), Type.Literal('notifications')],
+      { default: 'comments' },
+    ),
+    notifyTemplate: Type.Optional(Type.String({ maxLength: 128 })),
+  })),
+
+  // ── limits: DELEGATE token/credit accounting to ai-v1 ─────────────────────
+  limits: Type.Object({
+    consumeCredits: Type.Boolean({ default: false }),
+    tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = inherit ai
+  }, { default: {} }),
+
+  // ── widget / embed (the Stage-3 public chat surface) ──────────────────────
+  widget: Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    requireAuth: Type.Boolean({ default: true }),
+    allowedOrigins: Type.Array(Type.String({ maxLength: 256 }), { maxItems: 32, default: [] }),
+    theme: Type.Optional(Type.String({ maxLength: 32 })),
+  }, { default: {} }),
+});
+// Leaves: enabled(1), agents(2 — Type.Record MAP, ONE leaf), escalation?(3 —
+//   optional object, ONE leaf), limits.{consumeCredits,tokensPerUserPerDay}
+//   (+2=5), widget.{enabled,requireAuth,allowedOrigins,theme}(+4=9).
+//   countLeaves → 9. Cap = 15.
+
+export type CopilotConfig = Static<typeof CopilotConfigSchema>;
+
+export const FEATURE_SCHEMAS: Record<string, TSchema> = {
+  notifications: NotificationsConfigSchema,
+  jobs: JobsConfigSchema,
+  auth: AuthConfigSchema,
+  'rate-limits': RateLimitsConfigSchema,
+  files: FilesConfigSchema,
+  webhooks: WebhooksConfigSchema,
+  comments: CommentsConfigSchema,
+  cms: CmsConfigSchema,
+  mcp: McpConfigSchema,
+  realtime: RealtimeConfigSchema,
+  presence: PresenceConfigSchema,
+  orgs: OrgsConfigSchema,
+  'activity-feed': ActivityFeedConfigSchema,
+  'vector-search': VectorSearchConfigSchema,
+  ai: AiConfigSchema,
+  rag: RagConfigSchema,
+  payments: PaymentsConfigSchema,
+  functions: FunctionsConfigSchema,
+  copilot: CopilotConfigSchema,
+};
+
+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
+ * block) counts as ONE flag — the tenant's decision is "configure it or
+ * not", not each inner ref. */
+export function countLeaves(schema: TSchema): number {
+  const t = schema as unknown as {
+    type?: string;
+    properties?: Record<string, TSchema>;
+  };
+  if (t.type === 'object' && t.properties) {
+    return Object.values(t.properties).reduce((n, child) => {
+      const c = child as unknown as { type?: string } & Record<symbol, unknown>;
+      const optionalObject = c.type === 'object' && c[OptionalKind] !== undefined;
+      return n + (optionalObject ? 1 : countLeaves(child));
+    }, 0);
+  }
+  return 1; // unions, primitives, arrays = one flag the tenant must learn
+}
+
+export interface ConfigValidation {
+  ok: boolean;
+  errors: string[];
+  /** value with TypeBox defaults applied (only when ok) */
+  value?: unknown;
+}
+
+// ── copilot ↔ mcp catalog bridge ─────────────────────────────────────────────
+// Copilot `actions.allow` keys / `guestToolAllow` entries are mcp catalog tool
+// names. The catalog lives in workers/mcp-v1/src/tools.ts (the zero-import pure
+// data module gen/trinity-drift read) — which this PUBLISHED package cannot
+// import: tsconfig.build.json compiles with rootDir=src, so a relative import
+// across the monorepo would break the npm build. Instead, consumers that HAVE
+// the catalog (the control-plane config write path, tests) register it once via
+// setKnownMcpTools(TOOLS.map(t => t.name)) — the setDocsBaseUrl-style seam.
+// Without a registered catalog, validateFeatureConfig skips ONLY the
+// name-existence rule (the pure subset/cross-field rules below still run);
+// at runtime the loop's manifest intersection makes an unknown key inert.
+let knownMcpTools: ReadonlySet<string> | null = null;
+export function setKnownMcpTools(names: readonly string[]): void {
+  knownMcpTools = new Set(names);
+}
+
+// ── mcp custom-tool / prompt caps + the pure public-https check ──────────────
+// (mcp.md §6.5) 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;
+const MCP_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+
+/** Pure mirror of @vxil/runtime assertPublicHttpsUrl (this package cannot
+ * depend on it — typebox-only). Returns an error string, or null when the URL
+ * is a plain https URL to a public-looking host. IPv6 literals are rejected
+ * outright at config time (stricter than runtime — declare a hostname). */
+function publicHttpsUrlError(url: string): string | null {
+  let u: URL;
+  try {
+    u = new URL(url);
+  } catch {
+    return 'not a valid URL';
+  }
+  if (u.protocol !== 'https:') return `only https:// is allowed (got ${u.protocol})`;
+  if (u.username !== '' || u.password !== '') return 'URLs with embedded credentials are rejected';
+  const host = u.hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '').replace(/\.$/, '');
+  if (host === '') return 'empty host';
+  if (
+    host === 'localhost' || host.endsWith('.localhost')
+    || host === 'metadata.google.internal'
+    || host.endsWith('.internal') || host.endsWith('.local')
+  ) {
+    return `host ${host} resolves to internal infrastructure`;
+  }
+  if (host.includes(':')) return 'IPv6 literals are not accepted — declare a hostname';
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (m) {
+    const o = m.slice(1).map(Number);
+    const [a, b] = o as [number, number, number, number];
+    if (
+      o.some((n) => n > 255)
+      || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)
+      || a === 127 || (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127)
+      || a === 0 || a >= 224
+    ) {
+      return `host ${host} is a private/reserved IP`;
+    }
+  }
+  return null;
+}
+
+/** Scopes a FUNCTION may NEVER carry (the deploy clamp + the config-write gate).
+ *  NARROWER than the appgen public-page deny-list — a function is authenticated,
+ *  per-function-scoped, tier-walled, egress-guarded tenant code, so the owner may
+ *  grant it business scopes (payments:write / notifications:send / users:*) that an
+ *  anonymous appgen page never gets. Only CROSS-TENANT escalation (admin/*) and
+ *  SELF-INTEGRITY rewrites stay forbidden: features:write (config rewrite outside
+ *  the versioned pipeline), functions:write (redeploy/modify the tenant's functions
+ *  at runtime — a persistence vector; function code ships via the CLI/dashboard,
+ *  not another function), and secrets:write (secret mutation). functions:invoke
+ *  stays ALLOWED (fn→fn composition). Source of truth for both the config-write
+ *  validation below and the control-plane deploy clamp. */
+export const DENY_FUNCTION_SCOPES = new Set(['admin', '*', 'features:write', 'functions:write', 'secrets:write']);
+
+export function validateFeatureConfig(feature: string, raw: unknown): ConfigValidation {
+  const schema = FEATURE_SCHEMAS[feature];
+  if (!schema) {
+    return { ok: false, errors: [`unknown feature '${feature}'`] };
+  }
+  if (countLeaves(schema) > CONFIG_FLAG_CAP) {
+    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):
+  // 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.
+  const withDefaults = Value.Clean(
+    schema,
+    Value.Default(schema, Value.Clone(raw)),
+  ) as unknown;
+  if (!Value.Check(schema, withDefaults)) {
+    const errors = [...Value.Errors(schema, withDefaults)].map(
+      (e) => `${e.path || '/'}: ${e.message}`,
+    );
+    return { ok: false, errors: errors.slice(0, 10) };
+  }
+  // Cross-field rule: notifications only needs a Resend key for the real
+  // provider. The `mock` provider (and inbox-only setups) stay zero-config.
+  if (feature === 'notifications') {
+    const v = withDefaults as { provider?: string; resendApiKeyRef?: string };
+    if (v.provider === 'resend' && !v.resendApiKeyRef) {
+      return {
+        ok: false,
+        errors: ["/resendApiKeyRef: required when provider is 'resend' (omit it for provider 'mock')"],
+      };
+    }
+  }
+  // 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).
+  if (feature === 'payments') {
+    const v = withDefaults as { provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown };
+    const needsBlock: Record<string, keyof typeof v> = {
+      stripe: 'stripe', paddle: 'paddle', revenuecat: 'revenuecat',
+    };
+    const key = v.provider ? needsBlock[v.provider] : undefined;
+    if (key && !v[key]) {
+      return {
+        ok: false,
+        errors: [`/${String(key)}: required when provider is '${v.provider}' (omit it for provider 'mock')`],
+      };
+    }
+  }
+  // Cross-field rule: CMS lifecycle hooks. Each hook's expression is parsed and
+  // AST-validated against the closed sandbox allow-list HERE, at config-write
+  // time — a malicious/oversized/ill-typed hook is rejected BEFORE it can be
+  // published to KV/runtime (the anti-malice gate). Field-existence is checked
+  // at runtime (the field list is per-collection DB data, not known here).
+  if (feature === 'cms') {
+    const v = withDefaults as {
+      hooks?: Record<string, HookDef>;
+      readModels?: Record<string, never>;
+      cdc?: Record<string, never>;
+    };
+    const hookErrors = validateHooksConfig(v.hooks);
+    if (hookErrors.length) return { ok: false, errors: hookErrors.slice(0, 10) };
+    // cms-rel B5/E: the read-model/cdc grammars are closed at config-write
+    // (readmodels.ts — the same anti-malice posture as the hooks gate).
+    const rmErrors = [
+      ...validateReadModelsConfig(v.readModels),
+      ...validateCdcConfig(v.cdc),
+    ];
+    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
+  // 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
+  // they can be published to config.
+  if (feature === 'mcp') {
+    const v = withDefaults as {
+      customTools?: Record<string, { url?: string; inputSchema?: unknown }>;
+      prompts?: Record<string, { template?: string; arguments?: Array<{ name?: string }> }>;
+    };
+    const errs: string[] = [];
+    const tools = Object.entries(v.customTools ?? {});
+    if (tools.length > MCP_MAX_CUSTOM_TOOLS) {
+      errs.push(`/customTools: at most ${MCP_MAX_CUSTOM_TOOLS} custom tools (got ${tools.length})`);
+    }
+    for (const [name, tool] of tools) {
+      if (!MCP_NAME_RE.test(name)) {
+        errs.push(`/customTools/${name}: name must match ${MCP_NAME_RE.source}`);
+      }
+      const urlErr = publicHttpsUrlError(tool.url ?? '');
+      if (urlErr) errs.push(`/customTools/${name}/url: ${urlErr}`);
+      if (tool.inputSchema !== undefined) {
+        if (typeof tool.inputSchema !== 'object' || tool.inputSchema === null
+          || Array.isArray(tool.inputSchema)) {
+          errs.push(`/customTools/${name}/inputSchema: must be a JSON-Schema object`);
+        } else if (JSON.stringify(tool.inputSchema).length > 8 * 1024) {
+          errs.push(`/customTools/${name}/inputSchema: serialized schema exceeds 8KB`);
+        }
+      }
+    }
+    const prompts = Object.entries(v.prompts ?? {});
+    if (prompts.length > MCP_MAX_PROMPTS) {
+      errs.push(`/prompts: at most ${MCP_MAX_PROMPTS} prompts (got ${prompts.length})`);
+    }
+    for (const [name, prompt] of prompts) {
+      if (!MCP_NAME_RE.test(name)) {
+        errs.push(`/prompts/${name}: name must match ${MCP_NAME_RE.source}`);
+      }
+      // Every {{placeholder}} must be a declared argument (declared-but-unused
+      // arguments are allowed — a template may evolve independently).
+      const declared = new Set((prompt.arguments ?? []).map((a) => a.name ?? ''));
+      for (const m of String(prompt.template ?? '').matchAll(/\{\{([a-z0-9_]+)\}\}/g)) {
+        if (!declared.has(m[1]!)) {
+          errs.push(`/prompts/${name}/template: placeholder {{${m[1]}}} is not a declared argument`);
+        }
+      }
+    }
+    if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
+  }
+  // Cross-field rule: ai. A tenant-supplied openai-compatible base URL is a
+  // platform egress target — reject non-https/private/internal hosts at config-
+  // write time (pure mirror of @vxil/runtime assertPublicHttpsUrl; ai-v1 re-runs
+  // the authoritative runtime guard at use time — the mcp customTools idiom).
+  if (feature === 'ai') {
+    const v = withDefaults as { providers?: { compat?: { openaiBaseUrl?: string } } };
+    const baseUrl = v.providers?.compat?.openaiBaseUrl;
+    if (baseUrl) {
+      const urlErr = publicHttpsUrlError(baseUrl);
+      if (urlErr) return { ok: false, errors: [`/providers/compat/openaiBaseUrl: ${urlErr}`] };
+    }
+  }
+  // Cross-field rule: functions. Reject privilege-escalating scopes and malformed
+  // bindings at config-write time (the deploy pipeline additionally asserts the
+  // scriptRef sha is uploaded + clamps scopes via DENY_FUNCTION_SCOPES). Bindings
+  // are http/cron/queue/webhook/cmsHook/authHook; a cmsHook binding carries
+  // collection+event, an authHook binding fires on auth.user.created (the
+  // control-plane auto-wires the webhook_subscription for both).
+  if (feature === 'functions') {
+    const v = withDefaults as {
+      functions?: Record<
+        string,
+        { scriptRef?: string; scopes?: string[]; bindings?: Array<{ kind: string; schedule?: string; collection?: string; event?: string }>; signature?: unknown }
+      >;
+    };
+    const errs: string[] = [];
+    for (const [name, fn] of Object.entries(v.functions ?? {})) {
+      if (!fn.scriptRef) errs.push(`/functions/${name}/scriptRef: required`);
+      for (const s of fn.scopes ?? []) {
+        if (DENY_FUNCTION_SCOPES.has(s)) {
+          errs.push(`/functions/${name}/scopes: '${s}' is never grantable to a function (deny-by-default) — cross-tenant/self-integrity scopes are forbidden; payments:write / notifications:send / users:* are allowed`);
+        }
+      }
+      (fn.bindings ?? []).forEach((b, i) => {
+        if (b.kind === 'cron' && !b.schedule) {
+          errs.push(`/functions/${name}/bindings/${i}: a 'cron' binding needs a schedule`);
+        }
+        if (b.kind === 'cmsHook' && !b.collection) {
+          errs.push(`/functions/${name}/bindings/${i}: a 'cmsHook' binding needs a collection`);
+        }
+        // authHook: 'user.created' is the only event today — reject typos at
+        // write time so a binding never silently subscribes to nothing.
+        if (b.kind === 'authHook' && b.event !== undefined && b.event !== 'user.created') {
+          errs.push(`/functions/${name}/bindings/${i}: an 'authHook' binding's event must be 'user.created' (or omitted)`);
+        }
+      });
+      // Manifest-bloat guard: the signature is opaque DATA carried inside the
+      // published manifest (and every config_versions row) — bound it.
+      if (fn.signature !== undefined && JSON.stringify(fn.signature).length > 8_192) {
+        errs.push(`/functions/${name}/signature: too large (max 8192 JSON chars)`);
+      }
+    }
+    if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
+  }
+  // Cross-field rules: copilot (docs/copilot-agents-sku-design.md §4). Pure
+  // rules only — cross-feature resolutions (collection existence, directiveRef
+  // → ai.templates) are deferred to runtime, which fails soft with the
+  // capability-surface envelope. Tool-NAME existence runs only when the mcp
+  // catalog has been registered (setKnownMcpTools above).
+  if (feature === 'copilot') {
+    const v = withDefaults as {
+      agents?: Record<string, {
+        actions?: { mode?: string; allow?: Record<string, unknown> };
+        guardrails?: { allowGuest?: boolean; guestToolAllow?: string[] };
+      }>;
+      escalation?: { handler?: string; notifyTemplate?: string };
+      widget?: { requireAuth?: boolean };
+    };
+    const errs: string[] = [];
+    let anyGuestAgent = false;
+    for (const [id, agent] of Object.entries(v.agents ?? {})) {
+      const allow = agent.actions?.allow ?? {};
+      const guestAllow = agent.guardrails?.guestToolAllow ?? [];
+      if (agent.guardrails?.allowGuest === true) anyGuestAgent = true;
+      if (knownMcpTools) {
+        for (const tool of Object.keys(allow)) {
+          if (!knownMcpTools.has(tool)) {
+            errs.push(`/agents/${id}/actions/allow/${tool}: not an mcp catalog tool name`);
+          }
+        }
+        for (const tool of guestAllow) {
+          if (!knownMcpTools.has(tool)) {
+            errs.push(`/agents/${id}/guardrails/guestToolAllow: '${tool}' is not an mcp catalog tool name`);
+          }
+        }
+      }
+      if (guestAllow.length > 0) {
+        if (agent.guardrails?.allowGuest !== true) {
+          errs.push(`/agents/${id}/guardrails/guestToolAllow: requires allowGuest: true`);
+        }
+        for (const tool of guestAllow) {
+          if (!(tool in allow)) {
+            errs.push(`/agents/${id}/guardrails/guestToolAllow: '${tool}' is not in actions.allow`);
+          }
+        }
+      }
+    }
+    if (v.widget?.requireAuth === false && !anyGuestAgent) {
+      errs.push('/widget/requireAuth: false requires at least one agent with guardrails.allowGuest: true');
+    }
+    if (v.escalation?.handler === 'notifications' && !v.escalation.notifyTemplate) {
+      errs.push("/escalation/notifyTemplate: required when handler is 'notifications'");
+    }
+    if (errs.length) return { ok: false, errors: errs.slice(0, 10) };
+  }
+  return { ok: true, errors: [], value: withDefaults };
+}