@vxil/feature-configs 0.4.1 → 0.5.0

package/dist/apiState.d.ts

@@ -0,0 +1,181 @@
+import type { DeclaredRlPolicy, DeclaredWebhookSubscription } from './index.js';
+/** The target_url path markers of the platform's function-delivery lanes
+ *  (control-plane fnCmsHooks.ts FN_CMSHOOK_PATH / FN_AUTHHOOK_PATH /
+ *  FN_WEBHOOK_TRIGGER_PATH — mirrored here because this package is
+ *  typebox-only). A subscription on one of them is derived from the functions
+ *  manifest by the deploy reconciler: never declarable, never "undeclared". */
+export declare const FN_TRIGGER_TARGET_MARKERS: readonly ["/v1/internal/fn/cms-hook/", "/v1/internal/fn/auth-hook/", "/v1/internal/fn/trigger/"];
+export declare function isFnTriggerSubscriptionUrl(targetUrl: string): boolean;
+export type ApiStateDatum = 'policies' | 'subscriptions' | 'templates';
+/** feature → the declared-API-state datum its config block may carry. */
+export declare const API_STATE_DATUMS: ReadonlyArray<{
+    feature: string;
+    datum: ApiStateDatum;
+}>;
+export declare function apiStateDatumOf(feature: string): ApiStateDatum | null;
+/** The declared list a validated manifest carries for its feature's datum, or
+ *  null when the feature has no datum / the block is absent. An absent block
+ *  means "not managed by config" (nothing converges, nothing is reported) —
+ *  distinct from an EMPTY array, which declares "there should be none". */
+export declare function declaredApiState(feature: string, manifest: Record<string, unknown> | null | undefined): {
+    datum: ApiStateDatum;
+    declared: unknown[];
+} | null;
+/** ONE row of GET /v1/rate-limits/policies (rate-limits-v1 core.ts Policy). */
+export interface LiveRlPolicy {
+    policy_id: string;
+    name: string;
+    key_template: string;
+    limit: number;
+    window_seconds: number;
+    behavior: string;
+    /** absent on a policy stored before the token-bucket pass → 'sliding_window' */
+    algorithm?: string;
+}
+/** The PUT /v1/rate-limits/policies/:id body the converge sends (core.ts
+ *  UpdateBody minus `name`, which is the key). */
+export interface RlPolicyPatch {
+    limit?: number;
+    window_seconds?: number;
+    behavior?: 'block' | 'shape';
+    algorithm?: 'sliding_window' | 'token_bucket';
+}
+export declare const RL_DEFAULT_BEHAVIOR: "block";
+export declare const RL_DEFAULT_ALGORITHM: "sliding_window";
+export interface RlPolicyPlan {
+    create: DeclaredRlPolicy[];
+    update: Array<{
+        policy_id: string;
+        name: string;
+        patch: RlPolicyPatch;
+        changed: string[];
+    }>;
+    /** `key_template` differs — the update route cannot change it, so the only
+     *  fix is delete+recreate (a NEW policy_id): destructive-shaped. */
+    recreate: Array<{
+        policy_id: string;
+        name: string;
+        declared: DeclaredRlPolicy;
+    }>;
+    unchanged: string[];
+    /** live rows the config does not declare (left in place by default) */
+    undeclared: Array<{
+        policy_id: string;
+        name: string;
+    }>;
+    /** a declared name matched by MORE THAN ONE live row — names are not a
+     *  unique key on the route, so the converge cannot pick; nothing is touched */
+    ambiguous: Array<{
+        name: string;
+        count: number;
+    }>;
+}
+export declare function planRlPolicies(declared: readonly DeclaredRlPolicy[], live: readonly LiveRlPolicy[]): RlPolicyPlan;
+/** ONE row of GET /v1/webhooks/subscriptions (state 'deleted' never listed). */
+export interface LiveWebhookSubscription {
+    sub_id: string;
+    target_url: string;
+    event_prefixes: string[];
+    state?: string;
+}
+export interface WebhookSubscriptionPlan {
+    create: DeclaredWebhookSubscription[];
+    /** the prefix SET differs — there is no update route, so delete+recreate (a
+     *  NEW sub_id, and the watermark restarts at "now"): destructive-shaped. */
+    recreate: Array<{
+        sub_id: string;
+        target_url: string;
+        declared: DeclaredWebhookSubscription;
+    }>;
+    unchanged: string[];
+    /** live rows the config does not declare, EXCLUDING the function-delivery
+     *  lanes (those derive from the functions manifest) — left in place by default */
+    undeclared: Array<{
+        sub_id: string;
+        target_url: string;
+    }>;
+}
+export declare function planWebhookSubscriptions(declared: readonly DeclaredWebhookSubscription[], live: readonly LiveWebhookSubscription[]): WebhookSubscriptionPlan;
+/** ONE row of GET /v1/ai/templates. `content_sha256` is the canonical hash of
+ *  the LATEST version's {system,user,schema} (@vxil/runtime
+ *  aiTemplateContentSha256), stamped by ai-v1 since 2026-09-23; absent on an
+ *  older server. */
+export interface LiveAiTemplate {
+    name: string;
+    latest_version: number;
+    content_sha256?: string;
+}
+/** A declared template with its content hash pre-computed by the caller (the
+ *  hash is async WebCrypto; this planner stays pure/sync). */
+export interface HashedDeclaredAiTemplate {
+    template: string;
+    content_sha256: string;
+}
+export interface AiTemplatePlan {
+    create: string[];
+    /** content differs → POST a new version (monotonic per name) */
+    update: string[];
+    unchanged: string[];
+    /** stored names the config does not declare — there is NO delete route for
+     *  templates, so these are only ever reported, never removed */
+    undeclared: string[];
+    /** live rows with no `content_sha256` (an older server): the content cannot
+     *  be compared, so each is re-put as `update` and named here */
+    unknownContent: string[];
+}
+export declare function planAiTemplates(declared: readonly HashedDeclaredAiTemplate[], live: readonly LiveAiTemplate[]): AiTemplatePlan;
+export interface ApiStateSummary {
+    datum: ApiStateDatum;
+    created: string[];
+    updated: string[];
+    /** destructive-shaped changes APPLIED under allow-destructive (delete+recreate) */
+    recreated: string[];
+    unchanged: string[];
+    /** live rows the config does not declare — left in place (or, under
+     *  allow-destructive, listed in `deleted` instead) */
+    undeclared: string[];
+    /** undeclared rows DELETED under allow-destructive */
+    deleted: string[];
+    /** destructive-shaped changes NOT applied (need allow-destructive) */
+    pending_destructive: string[];
+    /** declared keys the converge could not resolve (duplicate live rows) */
+    ambiguous: string[];
+    /** rows a route refused (a 4xx) — the converge continues past them */
+    failed: Array<{
+        key: string;
+        error: string;
+    }>;
+}
+export declare function emptyApiStateSummary(datum: ApiStateDatum): ApiStateSummary;
+/** The `api_state` object a config-write response carries (`PUT /v1/config/
+ *  :feature` and its dashboard twin, dry-run included — control-plane
+ *  handlers/apiState.ts apiStateResponseField) and the shape `vxil push` READS
+ *  back instead of converging a second time (review 2026-09-23, finding 1: the
+ *  server's converge is the one that ran with the key's scopes; a client-side
+ *  repeat re-listed a KV-backed datum ~100 ms later and could double-create).
+ *  `ok:false` + `deferred:true` = the feature worker has not seen the config
+ *  yet (the client may converge after its own wait); `ok:false` otherwise =
+ *  a DEFINITE, named refusal (nothing to retry); `note` = converged nothing on
+ *  purpose (a disabled feature). */
+export interface ApiStateResponseField extends ApiStateSummary {
+    ok: boolean;
+    dry_run?: boolean;
+    deferred?: boolean;
+    error?: string;
+    note?: string;
+}
+/** The note every executor reports for a DISABLED feature whose block still
+ *  declares rows: the declaration is kept in the manifest and nothing is
+ *  converged (a parked feature is not a propagation window — review finding 2). */
+export declare const API_STATE_DISABLED_NOTE = "feature disabled \u2014 declaration kept, not converged";
+/** `GET /v1/rate-limits/policies` is a 100-row HARD cap with no cursor. A list
+ *  AT the cap is not a complete live set, so planning creates against it would
+ *  re-POST every declared name the cap hid (review finding 5). Both executors
+ *  refuse with this message instead. */
+export declare function rlPolicyListCapError(liveCount: number): string | null;
+export declare const RL_POLICY_LIST_CAP = 100;
+/** `+2 created · ~1 updated · =3 unchanged · 1 undeclared (left in place)` —
+ *  the one-line summary `vxil push` prints and the apply journal notes. */
+export declare function formatApiStateSummary(s: ApiStateSummary): string;
+/** The multi-line detail under the summary: one line per named row. */
+export declare function formatApiStateDetail(s: ApiStateSummary): string[];

package/dist/apiState.js

@@ -0,0 +1,219 @@
+/** The target_url path markers of the platform's function-delivery lanes
+ *  (control-plane fnCmsHooks.ts FN_CMSHOOK_PATH / FN_AUTHHOOK_PATH /
+ *  FN_WEBHOOK_TRIGGER_PATH — mirrored here because this package is
+ *  typebox-only). A subscription on one of them is derived from the functions
+ *  manifest by the deploy reconciler: never declarable, never "undeclared". */
+export const FN_TRIGGER_TARGET_MARKERS = [
+    '/v1/internal/fn/cms-hook/',
+    '/v1/internal/fn/auth-hook/',
+    '/v1/internal/fn/trigger/',
+];
+export function isFnTriggerSubscriptionUrl(targetUrl) {
+    return FN_TRIGGER_TARGET_MARKERS.some((m) => targetUrl.includes(m));
+}
+/** feature → the declared-API-state datum its config block may carry. */
+export const API_STATE_DATUMS = [
+    { feature: 'rate-limits', datum: 'policies' },
+    { feature: 'webhooks', datum: 'subscriptions' },
+    { feature: 'ai', datum: 'templates' },
+];
+export function apiStateDatumOf(feature) {
+    return API_STATE_DATUMS.find((d) => d.feature === feature)?.datum ?? null;
+}
+/** The declared list a validated manifest carries for its feature's datum, or
+ *  null when the feature has no datum / the block is absent. An absent block
+ *  means "not managed by config" (nothing converges, nothing is reported) —
+ *  distinct from an EMPTY array, which declares "there should be none". */
+export function declaredApiState(feature, manifest) {
+    const datum = apiStateDatumOf(feature);
+    if (!datum || !manifest)
+        return null;
+    const list = manifest[datum];
+    if (!Array.isArray(list))
+        return null;
+    return { datum, declared: list };
+}
+export const RL_DEFAULT_BEHAVIOR = 'block';
+export const RL_DEFAULT_ALGORITHM = 'sliding_window';
+export function planRlPolicies(declared, live) {
+    const plan = { create: [], update: [], recreate: [], unchanged: [], undeclared: [], ambiguous: [] };
+    const byName = new Map();
+    for (const row of live)
+        byName.set(row.name, [...(byName.get(row.name) ?? []), row]);
+    const declaredNames = new Set(declared.map((d) => d.name));
+    for (const d of declared) {
+        const rows = byName.get(d.name) ?? [];
+        if (rows.length === 0) {
+            plan.create.push(d);
+            continue;
+        }
+        if (rows.length > 1) {
+            plan.ambiguous.push({ name: d.name, count: rows.length });
+            continue;
+        }
+        const l = rows[0];
+        if (l.key_template !== d.key_template) {
+            plan.recreate.push({ policy_id: l.policy_id, name: d.name, declared: d });
+            continue;
+        }
+        const patch = {};
+        const changed = [];
+        if (d.limit !== undefined && d.limit !== l.limit) {
+            patch.limit = d.limit;
+            changed.push('limit');
+        }
+        if (d.window_seconds !== undefined && d.window_seconds !== l.window_seconds) {
+            patch.window_seconds = d.window_seconds;
+            changed.push('window_seconds');
+        }
+        const wantBehavior = d.behavior ?? RL_DEFAULT_BEHAVIOR;
+        if (wantBehavior !== l.behavior) {
+            patch.behavior = wantBehavior;
+            changed.push('behavior');
+        }
+        const wantAlgorithm = d.algorithm ?? RL_DEFAULT_ALGORITHM;
+        if (wantAlgorithm !== (l.algorithm ?? RL_DEFAULT_ALGORITHM)) {
+            patch.algorithm = wantAlgorithm;
+            changed.push('algorithm');
+        }
+        if (changed.length)
+            plan.update.push({ policy_id: l.policy_id, name: d.name, patch, changed });
+        else
+            plan.unchanged.push(d.name);
+    }
+    for (const row of live) {
+        if (!declaredNames.has(row.name))
+            plan.undeclared.push({ policy_id: row.policy_id, name: row.name });
+    }
+    return plan;
+}
+function sameStringSet(a, b) {
+    const A = new Set(a);
+    const B = new Set(b);
+    return A.size === B.size && [...A].every((x) => B.has(x));
+}
+export function planWebhookSubscriptions(declared, live) {
+    const plan = { create: [], recreate: [], unchanged: [], undeclared: [] };
+    const declaredUrls = new Set(declared.map((d) => d.target_url));
+    const matched = new Set();
+    for (const d of declared) {
+        const want = d.event_prefixes ?? [];
+        const rows = live.filter((l) => l.target_url === d.target_url);
+        if (rows.length === 0) {
+            plan.create.push(d);
+            continue;
+        }
+        // Prefer an EXACT prefix-set match among duplicates (a hand-made row equal
+        // to the declaration is adopted as-is — no churn); else the first row is
+        // the one recreated and the rest fall through as undeclared duplicates.
+        const exact = rows.find((l) => sameStringSet(l.event_prefixes ?? [], want));
+        const chosen = exact ?? rows[0];
+        matched.add(chosen.sub_id);
+        if (exact)
+            plan.unchanged.push(d.target_url);
+        else
+            plan.recreate.push({ sub_id: chosen.sub_id, target_url: d.target_url, declared: d });
+    }
+    for (const l of live) {
+        if (matched.has(l.sub_id))
+            continue;
+        if (isFnTriggerSubscriptionUrl(l.target_url))
+            continue; // manifest-derived, never ours
+        if (declaredUrls.has(l.target_url)) {
+            // a duplicate live row for a declared url — surplus, not the adopted one
+            plan.undeclared.push({ sub_id: l.sub_id, target_url: l.target_url });
+            continue;
+        }
+        plan.undeclared.push({ sub_id: l.sub_id, target_url: l.target_url });
+    }
+    return plan;
+}
+export function planAiTemplates(declared, live) {
+    const plan = { create: [], update: [], unchanged: [], undeclared: [], unknownContent: [] };
+    const byName = new Map(live.map((l) => [l.name, l]));
+    const declaredNames = new Set(declared.map((d) => d.template));
+    for (const d of declared) {
+        const l = byName.get(d.template);
+        if (!l) {
+            plan.create.push(d.template);
+            continue;
+        }
+        if (l.content_sha256 === undefined) {
+            plan.unknownContent.push(d.template);
+            plan.update.push(d.template);
+            continue;
+        }
+        if (l.content_sha256 === d.content_sha256)
+            plan.unchanged.push(d.template);
+        else
+            plan.update.push(d.template);
+    }
+    for (const l of live)
+        if (!declaredNames.has(l.name))
+            plan.undeclared.push(l.name);
+    return plan;
+}
+export function emptyApiStateSummary(datum) {
+    return {
+        datum, created: [], updated: [], recreated: [], unchanged: [], undeclared: [],
+        deleted: [], pending_destructive: [], ambiguous: [], failed: [],
+    };
+}
+/** The note every executor reports for a DISABLED feature whose block still
+ *  declares rows: the declaration is kept in the manifest and nothing is
+ *  converged (a parked feature is not a propagation window — review finding 2). */
+export const API_STATE_DISABLED_NOTE = 'feature disabled — declaration kept, not converged';
+/** `GET /v1/rate-limits/policies` is a 100-row HARD cap with no cursor. A list
+ *  AT the cap is not a complete live set, so planning creates against it would
+ *  re-POST every declared name the cap hid (review finding 5). Both executors
+ *  refuse with this message instead. */
+export function rlPolicyListCapError(liveCount) {
+    if (liveCount < RL_POLICY_LIST_CAP)
+        return null;
+    return `the policy list is at its ${RL_POLICY_LIST_CAP}-row hard cap (no cursor) — the live set may be incomplete; delete undeclared policies before converging`;
+}
+export const RL_POLICY_LIST_CAP = 100;
+/** `+2 created · ~1 updated · =3 unchanged · 1 undeclared (left in place)` —
+ *  the one-line summary `vxil push` prints and the apply journal notes. */
+export function formatApiStateSummary(s) {
+    const parts = [];
+    if (s.created.length)
+        parts.push(`+${s.created.length} created`);
+    if (s.updated.length)
+        parts.push(`~${s.updated.length} updated`);
+    if (s.recreated.length)
+        parts.push(`↻${s.recreated.length} recreated`);
+    parts.push(`=${s.unchanged.length} unchanged`);
+    if (s.deleted.length)
+        parts.push(`-${s.deleted.length} deleted`);
+    if (s.undeclared.length)
+        parts.push(`${s.undeclared.length} undeclared (left in place)`);
+    if (s.pending_destructive.length)
+        parts.push(`${s.pending_destructive.length} destructive-shaped NOT applied (--allow-destructive)`);
+    if (s.ambiguous.length)
+        parts.push(`${s.ambiguous.length} ambiguous (duplicate live rows — not touched)`);
+    if (s.failed.length)
+        parts.push(`${s.failed.length} failed`);
+    return parts.join(' · ');
+}
+/** The multi-line detail under the summary: one line per named row. */
+export function formatApiStateDetail(s) {
+    const lines = [];
+    for (const k of s.created)
+        lines.push(`  + ${k}`);
+    for (const k of s.updated)
+        lines.push(`  ~ ${k}`);
+    for (const k of s.recreated)
+        lines.push(`  ↻ ${k} (recreated — new id)`);
+    for (const k of s.deleted)
+        lines.push(`  - ${k} (deleted: undeclared, --allow-destructive)`);
+    for (const k of s.undeclared)
+        lines.push(`  · ${k} — live but not declared (left in place; --allow-destructive deletes it)`);
+    for (const k of s.pending_destructive)
+        lines.push(`  ! ${k} — needs delete+recreate (new id); re-run with --allow-destructive`);
+    for (const k of s.ambiguous)
+        lines.push(`  ! ${k} — more than one live row carries this name; delete the extras first`);
+    for (const f of s.failed)
+        lines.push(`  ✗ ${f.key} — ${f.error}`);
+    return lines;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { type Static, type TSchema } from '@sinclair/typebox';
 export * from './hooks.js';
 export * from './readmodels.js';
+export * from './apiState.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */
@@ -37,6 +38,12 @@ export declare function validateNotificationOverrides(templates: {
         text?: string;
     }>>;
 } | undefined): string[];
+/** AWS region grammar for `notifications.ses.region` (`us-east-1`,
+ * `eu-central-1`, `ap-southeast-2`, `us-gov-west-1`, …): two-letter partition,
+ * one or more lowercase words, a single digit. Pinned as a pattern rather than
+ * a list so a newly launched SES region needs no vxil release; a typo still
+ * fails at `vxil push` (TypeBox), never as a DNS error on the first send. */
+export declare const SES_REGION_PATTERN = "^[a-z]{2}(-[a-z]+)+-\\d$";
 export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     fromEmail: import("@sinclair/typebox").TString;
@@ -44,7 +51,12 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
     replyTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     resendApiKeyRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     webhookSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-    provider: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"resend">, import("@sinclair/typebox").TLiteral<"mock">]>;
+    provider: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"resend">, import("@sinclair/typebox").TLiteral<"ses">, import("@sinclair/typebox").TLiteral<"mock">]>;
+    ses: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        region: import("@sinclair/typebox").TString;
+        accessKeyIdRef: import("@sinclair/typebox").TString;
+        secretAccessKeyRef: import("@sinclair/typebox").TString;
+    }>>;
     defaultLocale: import("@sinclair/typebox").TString;
     retry: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         maxAttempts: import("@sinclair/typebox").TInteger;
@@ -53,10 +65,10 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
     suppression: import("@sinclair/typebox").TObject<{
         softBounceThreshold: import("@sinclair/typebox").TInteger;
     }>;
-    rateLimit: import("@sinclair/typebox").TObject<{
+    rateLimit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         perDay: import("@sinclair/typebox").TInteger;
         perTenantSec: import("@sinclair/typebox").TInteger;
-    }>;
+    }>>;
     templates: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         allowOverride: import("@sinclair/typebox").TBoolean;
         overrides: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
@@ -150,6 +162,17 @@ declare const OidcProviderSchema: import("@sinclair/typebox").TObject<{
     allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
+export declare const REDIRECT_ORIGIN_PATTERN = "^(https://[^/?#\\s]+|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$";
+/** THE scheme rule for a redirect/return URL: https anywhere, http on loopback
+ *  only. Takes the parsed URL (or any {protocol, hostname} pair) so the config
+ *  validator and the worker's runtime guard call the identical predicate. */
+export declare function redirectSchemeAllowed(u: {
+    protocol: string;
+    hostname: string;
+}): boolean;
+/** An allow-list ENTRY is a bare origin that parses and passes the scheme
+ *  rule. Used by validateFeatureConfig (auth) on top of the coarse pattern. */
+export declare function isAllowedRedirectOriginEntry(entry: string): boolean;
 export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     methods: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
@@ -243,12 +266,35 @@ export type AuthSecurityConfig = NonNullable<Static<typeof AuthConfigSchema>['se
 /** The RB-2 generic OIDC / SSO issuer block (`providers.oidc`). */
 export type AuthOidcConfig = Static<typeof OidcProviderSchema>;
 export type AuthConfig = Static<typeof AuthConfigSchema>;
+export declare const RL_POLICY_NAME_PATTERN = "^[a-zA-Z0-9_.:-]+$";
+/** GET /v1/rate-limits/policies lists at most 100 with no cursor (core.ts
+ *  listPolicies) — a declared set past that could never be reconciled. */
+export declare const RL_MAX_DECLARED_POLICIES = 100;
+/** rate-limits-v1 core.ts createPolicy: at most 8 distinct `{var}`s. */
+export declare const RL_KEY_TEMPLATE_MAX_VARS = 8;
+export declare const DeclaredRlPolicySchema: import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TString;
+    key_template: import("@sinclair/typebox").TString;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    window_seconds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    behavior: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"block">, import("@sinclair/typebox").TLiteral<"shape">]>>;
+    algorithm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"sliding_window">, import("@sinclair/typebox").TLiteral<"token_bucket">]>>;
+}>;
+export type DeclaredRlPolicy = Static<typeof DeclaredRlPolicySchema>;
 export declare const RateLimitsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     defaults: import("@sinclair/typebox").TObject<{
         perTenantSec: import("@sinclair/typebox").TInteger;
         burstSize: import("@sinclair/typebox").TInteger;
     }>;
+    policies: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+        key_template: import("@sinclair/typebox").TString;
+        limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        window_seconds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        behavior: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"block">, import("@sinclair/typebox").TLiteral<"shape">]>>;
+        algorithm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"sliding_window">, import("@sinclair/typebox").TLiteral<"token_bucket">]>>;
+    }>>>;
 }>;
 export type RateLimitsConfig = Static<typeof RateLimitsConfigSchema>;
 export declare const FilesConfigSchema: import("@sinclair/typebox").TObject<{
@@ -279,6 +325,11 @@ export declare const FilesConfigSchema: import("@sinclair/typebox").TObject<{
     }>>;
 }>;
 export type FilesConfig = Static<typeof FilesConfigSchema>;
+export declare const DeclaredWebhookSubscriptionSchema: import("@sinclair/typebox").TObject<{
+    target_url: import("@sinclair/typebox").TString;
+    event_prefixes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+}>;
+export type DeclaredWebhookSubscription = Static<typeof DeclaredWebhookSubscriptionSchema>;
 export declare const WebhooksConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     maxSubscriptions: import("@sinclair/typebox").TInteger;
@@ -288,6 +339,10 @@ export declare const WebhooksConfigSchema: import("@sinclair/typebox").TObject<{
         minLevel: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"warn">, import("@sinclair/typebox").TLiteral<"error">]>;
         digestMinutes: import("@sinclair/typebox").TInteger;
     }>>;
+    subscriptions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        target_url: import("@sinclair/typebox").TString;
+        event_prefixes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    }>>>;
 }>;
 export type WebhooksConfig = Static<typeof WebhooksConfigSchema>;
 export declare const CommentsConfigSchema: import("@sinclair/typebox").TObject<{
@@ -454,6 +509,15 @@ export declare const VectorSearchConfigSchema: import("@sinclair/typebox").TObje
     }>>>;
 }>;
 export type VectorSearchConfig = Static<typeof VectorSearchConfigSchema>;
+export declare const AI_TEMPLATE_NAME_PATTERN = "^[a-zA-Z0-9_.\\-]+$";
+export declare const AI_MAX_DECLARED_TEMPLATES = 50;
+export declare const DeclaredAiTemplateSchema: import("@sinclair/typebox").TObject<{
+    template: import("@sinclair/typebox").TString;
+    user: import("@sinclair/typebox").TString;
+    system: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+}>;
+export type DeclaredAiTemplate = Static<typeof DeclaredAiTemplateSchema>;
 export declare const AiConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     defaultProvider: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"mock">, import("@sinclair/typebox").TLiteral<"openai">, import("@sinclair/typebox").TLiteral<"anthropic">, import("@sinclair/typebox").TLiteral<"gemini">, import("@sinclair/typebox").TLiteral<"azure">, import("@sinclair/typebox").TLiteral<"openrouter">]>;
@@ -478,11 +542,17 @@ export declare const AiConfigSchema: import("@sinclair/typebox").TObject<{
         tokensPerUserPerDay: import("@sinclair/typebox").TInteger;
         consumeCredits: import("@sinclair/typebox").TBoolean;
     }>;
-    streaming: import("@sinclair/typebox").TObject<{
+    streaming: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
         replayBufferFrames: import("@sinclair/typebox").TInteger;
         flushMs: import("@sinclair/typebox").TInteger;
-    }>;
+    }>>;
+    templates: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        template: import("@sinclair/typebox").TString;
+        user: import("@sinclair/typebox").TString;
+        system: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+    }>>>;
 }>;
 export type AiConfig = Static<typeof AiConfigSchema>;
 export declare const RagConfigSchema: import("@sinclair/typebox").TObject<{
@@ -691,6 +761,18 @@ export declare const MCP_MAX_PROMPTS = 32;
  *  stays ALLOWED (fn→fn composition). Source of truth for both the config-write
  *  validation below and the control-plane deploy clamp. */
 export declare const DENY_FUNCTION_SCOPES: Set<string>;
+/** `{var}` names of a rate-limit key template (rate-limits-v1 core.ts
+ *  templateVars parity). */
+export declare function rlTemplateVars(template: string): string[];
+export declare function validateDeclaredRlPolicies(policies: readonly DeclaredRlPolicy[] | undefined): string[];
+export declare function validateDeclaredWebhookSubscriptions(subscriptions: readonly DeclaredWebhookSubscription[] | undefined, maxSubscriptions: number | undefined): string[];
+/** The stored-template `schema` bounds — MIRRORED from @vxil/runtime
+ *  (AI_TEMPLATE_SCHEMA_MAX_BYTES / AI_TEMPLATE_SCHEMA_MAX_DEPTH; this package is
+ *  typebox-only). ai-v1 putTemplate refuses the same numbers at the route, so a
+ *  declared entry that passes here is never a 422 at converge. */
+export declare const AI_TEMPLATE_SCHEMA_MAX_BYTES = 32000;
+export declare const AI_TEMPLATE_SCHEMA_MAX_DEPTH = 64;
+export declare function validateDeclaredAiTemplates(templates: readonly DeclaredAiTemplate[] | undefined): string[];
 export declare function validateFeatureConfig(feature: string, raw: unknown): ConfigValidation;
 export declare const FEATURE_KEYS: readonly ["notifications", "jobs", "auth", "rate-limits", "files", "webhooks", "comments", "cms", "mcp", "realtime", "presence", "orgs", "activity-feed", "vector-search", "ai", "rag", "payments", "functions", "copilot"];
 export type FeatureKey = (typeof FEATURE_KEYS)[number];