@vxil/config 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -118,10 +118,27 @@ export type FunctionTrigger = {
 } | {
     kind: 'queue';
     source: string;
-} | {
+}
+/** `webhook`: the function is woken by a webhook_subscription fan-out whose
+ *  target_url is `<edge>/v1/internal/fn/trigger/<name>?tenant=<id>`. That
+ *  subscription is AUTO-WIRED on deploy (2026-09-19): the platform reconciles
+ *  one per function declaring this binding, with `event_prefixes` = the
+ *  function's `source` values — a hand-made one equal in target + prefixes is
+ *  adopted. `source` is an event-name PREFIX (e.g. 'payments.') or a full event
+ *  name — lowercase dotted segments, ≤64 chars, validated at deploy — and is
+ *  also enforced at delivery: a non-matching event is ACK-200 skipped.
+ *  Declaring the binding is what opts the function into event delivery; a
+ *  receiver that declares only `cron` keeps the older cron+{} wake. */
+ | {
     kind: 'webhook';
     source: string;
-} | {
+}
+/** `cmsHook`: fires after a CMS write in `collection`. The platform filters
+ *  deliveries on the binding (2026-09-19): `beforeCreate` → created only,
+ *  `beforeUpdate` → updated only, `beforeWrite` → created|updated; a write to
+ *  another collection never wakes the function. Deleted/bulk events are not
+ *  delivered to a cmsHook binding. */
+ | {
     kind: 'cmsHook';
     collection: string;
     event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite';
@@ -142,10 +159,34 @@ export interface FunctionDef {
     secrets?: string[];
     /** Outbound host allowlist (deny-by-default egress guard). */
     egressAllow?: string[];
+    /** Per-function resource declarations. Both optional; both clamped server-side.
+     *  `memoryMb` was REMOVED (2026-09-18): memory is fixed by the managed runtime
+     *  and is not per-dispatch selectable. A config that still declares it pushes
+     *  fine — the key is stripped, and `vxil plan --explain` marks it DROPPED. */
     limits?: {
+        /** per-dispatch isolate CPU ceiling, ms (5..300000). Only ever TIGHTENS the
+         *  platform cap.
+         *
+         *  IT ALSO RAISES YOUR BILL on a metered tenant, and that is worth reading
+         *  twice: it raises (never lowers) the per-invoke credit reserve, whose floor
+         *  is the manifest default — and the reserve is the CEILING the pro-rated
+         *  settle clamps into, because the settle can never commit more than the hold
+         *  it releases from. So an invoke whose wall time exceeds `defaultLimits.cpuMs`
+         *  (50) settles at its MEASURED wall-ms instead of being capped at 50:
+         *  declaring `cpuMs: 1000` makes an 800 ms invoke cost 800 instead of 50.
+         *  Declaring only `timeoutMs` leaves metering byte-identical.
+         *
+         *  It does NOT affect anyone else's availability: the account-wide daily
+         *  capacity budget counts the platform's own per-invoke estimate, never this
+         *  value (workers/functions-v1/src/capacity.ts `capacityReserveCpuMs`). */
         cpuMs?: number;
+        /** wall budget for ONE outbound fetch this function makes, ms (1000..120000,
+         *  default 30000). Not a whole-invocation budget: three 25 s fetches still
+         *  take 75 s. The invocation is bounded separately by the platform's own
+         *  deadline (`FN_MAX_INVOKE_MS`, default ≥ 5 minutes), which raising this
+         *  value widens with you. The vxil API callback leg keeps the platform's
+         *  own 30 s bound. */
         timeoutMs?: number;
-        memoryMb?: number;
     };
     enabled?: boolean;
     /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
@@ -180,6 +221,15 @@ export type ApiVersion = 'v1';
  *  only by a real v2. */
 export declare const RELEASED_API_VERSIONS: readonly ApiVersion[];
 /** The whole vxil backend, declared in one typed, version-controlled file. */
+/** Recursive partial: a `vxil.config.ts` may write any SUBSET of a nested bag
+ *  (`auth: { otp: { enabled: true } }`) — the server applies the defaults for
+ *  the rest (Value.Default). A shallow `Partial` made `tsc` reject every
+ *  partially-written nested bag, including the guide's own skeleton
+ *  (found by the 2026-09-19 cvskit dry-run). Arrays and primitives are kept
+ *  as-is; only plain object bags recurse. */
+export type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 export interface VxilConfig {
     /** target environment label; resolved to a baseUrl by `vxil link` / `--env`. */
     env?: string;
@@ -192,25 +242,25 @@ export interface VxilConfig {
      *  same Value.Default/Clean pipeline the server uses. Keys match FEATURE_SCHEMAS
      *  exactly (note the hyphenated ids). */
     features?: {
-        notifications?: Partial<NotificationsConfig>;
-        jobs?: Partial<JobsConfig>;
-        auth?: Partial<AuthConfig>;
-        'rate-limits'?: Partial<RateLimitsConfig>;
-        files?: Partial<FilesConfig>;
-        webhooks?: Partial<WebhooksConfig>;
-        comments?: Partial<CommentsConfig>;
-        cms?: Partial<CmsConfig>;
-        mcp?: Partial<McpConfig>;
-        realtime?: Partial<RealtimeConfig>;
-        presence?: Partial<PresenceConfig>;
-        orgs?: Partial<OrgsConfig>;
-        'activity-feed'?: Partial<ActivityFeedConfig>;
-        'vector-search'?: Partial<VectorSearchConfig>;
-        ai?: Partial<AiConfig>;
-        rag?: Partial<RagConfig>;
-        payments?: Partial<PaymentsConfig>;
-        functions?: Partial<FunctionsConfig>;
-        copilot?: Partial<CopilotConfig>;
+        notifications?: DeepPartial<NotificationsConfig>;
+        jobs?: DeepPartial<JobsConfig>;
+        auth?: DeepPartial<AuthConfig>;
+        'rate-limits'?: DeepPartial<RateLimitsConfig>;
+        files?: DeepPartial<FilesConfig>;
+        webhooks?: DeepPartial<WebhooksConfig>;
+        comments?: DeepPartial<CommentsConfig>;
+        cms?: DeepPartial<CmsConfig>;
+        mcp?: DeepPartial<McpConfig>;
+        realtime?: DeepPartial<RealtimeConfig>;
+        presence?: DeepPartial<PresenceConfig>;
+        orgs?: DeepPartial<OrgsConfig>;
+        'activity-feed'?: DeepPartial<ActivityFeedConfig>;
+        'vector-search'?: DeepPartial<VectorSearchConfig>;
+        ai?: DeepPartial<AiConfig>;
+        rag?: DeepPartial<RagConfig>;
+        payments?: DeepPartial<PaymentsConfig>;
+        functions?: DeepPartial<FunctionsConfig>;
+        copilot?: DeepPartial<CopilotConfig>;
     };
     /** (b) CMS SCHEMA-AS-CODE — collections + fields. `push` reconciles them
      *  additively against GET /v1/cms/collections (no destructive drops without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/config",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Typed vxil.config.ts authoring for the vxil backend platform — defineConfig, feature and cms field definitions (published for @vxil/cli).",
   "license": "MIT",
   "homepage": "https://vxil.com",
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "@vxil/feature-configs": "0.3.1"
+    "@vxil/feature-configs": "0.4.1"
   },
   "publishConfig": {
     "access": "public"

package/src/deepPartial.test.ts

@@ -0,0 +1,24 @@
+// A `vxil.config.ts` may write any SUBSET of a nested feature bag; the server
+// defaults the rest. This file is COMPILED by the package typecheck, so a
+// regression to a shallow Partial fails `tsc`, not just a runtime assertion
+// (the 2026-09-19 cvskit dry-run found the guide's own skeleton red under tsc).
+import { describe, expect, it } from 'vitest';
+import type { DeepPartial, VxilConfig } from './index.js';
+
+const partial: VxilConfig = {
+  features: {
+    auth: { otp: { enabled: true }, anonymous: { enabled: true } },
+    files: { ttl: { enabled: true, defaultExpiresInSeconds: 2592000 } },
+    ai: { defaults: { model: 'x' } },
+    cms: { limits: { maxItemsPerCollection: 5 } },
+  },
+};
+
+describe('DeepPartial', () => {
+  it('accepts partially-written nested bags (compile-time) and leaves arrays alone', () => {
+    type T = DeepPartial<{ a: { b: number; c: string }; list: string[] }>;
+    const v: T = { a: { b: 1 }, list: ['x'] };
+    expect(v.a?.b).toBe(1);
+    expect(partial.features?.auth?.otp?.enabled).toBe(true);
+  });
+});

package/src/index.ts

@@ -137,7 +137,22 @@ export type FunctionTrigger =
   | { kind: 'http'; path?: string }
   | { kind: 'cron'; schedule: string }
   | { kind: 'queue'; source: string }
+  /** `webhook`: the function is woken by a webhook_subscription fan-out whose
+   *  target_url is `<edge>/v1/internal/fn/trigger/<name>?tenant=<id>`. That
+   *  subscription is AUTO-WIRED on deploy (2026-09-19): the platform reconciles
+   *  one per function declaring this binding, with `event_prefixes` = the
+   *  function's `source` values — a hand-made one equal in target + prefixes is
+   *  adopted. `source` is an event-name PREFIX (e.g. 'payments.') or a full event
+   *  name — lowercase dotted segments, ≤64 chars, validated at deploy — and is
+   *  also enforced at delivery: a non-matching event is ACK-200 skipped.
+   *  Declaring the binding is what opts the function into event delivery; a
+   *  receiver that declares only `cron` keeps the older cron+{} wake. */
   | { kind: 'webhook'; source: string }
+  /** `cmsHook`: fires after a CMS write in `collection`. The platform filters
+   *  deliveries on the binding (2026-09-19): `beforeCreate` → created only,
+   *  `beforeUpdate` → updated only, `beforeWrite` → created|updated; a write to
+   *  another collection never wakes the function. Deleted/bulk events are not
+   *  delivered to a cmsHook binding. */
   | { kind: 'cmsHook'; collection: string; event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite' }
   | { kind: 'authHook'; event?: AuthHookEvent };
 
@@ -154,7 +169,35 @@ export interface FunctionDef {
   secrets?: string[];
   /** Outbound host allowlist (deny-by-default egress guard). */
   egressAllow?: string[];
-  limits?: { cpuMs?: number; timeoutMs?: number; memoryMb?: number };
+  /** Per-function resource declarations. Both optional; both clamped server-side.
+   *  `memoryMb` was REMOVED (2026-09-18): memory is fixed by the managed runtime
+   *  and is not per-dispatch selectable. A config that still declares it pushes
+   *  fine — the key is stripped, and `vxil plan --explain` marks it DROPPED. */
+  limits?: {
+    /** per-dispatch isolate CPU ceiling, ms (5..300000). Only ever TIGHTENS the
+     *  platform cap.
+     *
+     *  IT ALSO RAISES YOUR BILL on a metered tenant, and that is worth reading
+     *  twice: it raises (never lowers) the per-invoke credit reserve, whose floor
+     *  is the manifest default — and the reserve is the CEILING the pro-rated
+     *  settle clamps into, because the settle can never commit more than the hold
+     *  it releases from. So an invoke whose wall time exceeds `defaultLimits.cpuMs`
+     *  (50) settles at its MEASURED wall-ms instead of being capped at 50:
+     *  declaring `cpuMs: 1000` makes an 800 ms invoke cost 800 instead of 50.
+     *  Declaring only `timeoutMs` leaves metering byte-identical.
+     *
+     *  It does NOT affect anyone else's availability: the account-wide daily
+     *  capacity budget counts the platform's own per-invoke estimate, never this
+     *  value (workers/functions-v1/src/capacity.ts `capacityReserveCpuMs`). */
+    cpuMs?: number;
+    /** wall budget for ONE outbound fetch this function makes, ms (1000..120000,
+     *  default 30000). Not a whole-invocation budget: three 25 s fetches still
+     *  take 75 s. The invocation is bounded separately by the platform's own
+     *  deadline (`FN_MAX_INVOKE_MS`, default ≥ 5 minutes), which raising this
+     *  value widens with you. The vxil API callback leg keeps the platform's
+     *  own 30 s bound. */
+    timeoutMs?: number;
+  };
   enabled?: boolean;
   /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
   signature?: { input?: unknown; output?: unknown };
@@ -184,6 +227,18 @@ export type ApiVersion = 'v1';
 export const RELEASED_API_VERSIONS: readonly ApiVersion[] = ['v1'];
 
 /** The whole vxil backend, declared in one typed, version-controlled file. */
+/** Recursive partial: a `vxil.config.ts` may write any SUBSET of a nested bag
+ *  (`auth: { otp: { enabled: true } }`) — the server applies the defaults for
+ *  the rest (Value.Default). A shallow `Partial` made `tsc` reject every
+ *  partially-written nested bag, including the guide's own skeleton
+ *  (found by the 2026-09-19 cvskit dry-run). Arrays and primitives are kept
+ *  as-is; only plain object bags recurse. */
+export type DeepPartial<T> = T extends readonly unknown[]
+  ? T
+  : T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T;
+
 export interface VxilConfig {
   /** target environment label; resolved to a baseUrl by `vxil link` / `--env`. */
   env?: string;
@@ -198,25 +253,25 @@ export interface VxilConfig {
    *  same Value.Default/Clean pipeline the server uses. Keys match FEATURE_SCHEMAS
    *  exactly (note the hyphenated ids). */
   features?: {
-    notifications?: Partial<NotificationsConfig>;
-    jobs?: Partial<JobsConfig>;
-    auth?: Partial<AuthConfig>;
-    'rate-limits'?: Partial<RateLimitsConfig>;
-    files?: Partial<FilesConfig>;
-    webhooks?: Partial<WebhooksConfig>;
-    comments?: Partial<CommentsConfig>;
-    cms?: Partial<CmsConfig>;
-    mcp?: Partial<McpConfig>;
-    realtime?: Partial<RealtimeConfig>;
-    presence?: Partial<PresenceConfig>;
-    orgs?: Partial<OrgsConfig>;
-    'activity-feed'?: Partial<ActivityFeedConfig>;
-    'vector-search'?: Partial<VectorSearchConfig>;
-    ai?: Partial<AiConfig>;
-    rag?: Partial<RagConfig>;
-    payments?: Partial<PaymentsConfig>;
-    functions?: Partial<FunctionsConfig>;
-    copilot?: Partial<CopilotConfig>;
+    notifications?: DeepPartial<NotificationsConfig>;
+    jobs?: DeepPartial<JobsConfig>;
+    auth?: DeepPartial<AuthConfig>;
+    'rate-limits'?: DeepPartial<RateLimitsConfig>;
+    files?: DeepPartial<FilesConfig>;
+    webhooks?: DeepPartial<WebhooksConfig>;
+    comments?: DeepPartial<CommentsConfig>;
+    cms?: DeepPartial<CmsConfig>;
+    mcp?: DeepPartial<McpConfig>;
+    realtime?: DeepPartial<RealtimeConfig>;
+    presence?: DeepPartial<PresenceConfig>;
+    orgs?: DeepPartial<OrgsConfig>;
+    'activity-feed'?: DeepPartial<ActivityFeedConfig>;
+    'vector-search'?: DeepPartial<VectorSearchConfig>;
+    ai?: DeepPartial<AiConfig>;
+    rag?: DeepPartial<RagConfig>;
+    payments?: DeepPartial<PaymentsConfig>;
+    functions?: DeepPartial<FunctionsConfig>;
+    copilot?: DeepPartial<CopilotConfig>;
   };
 
   /** (b) CMS SCHEMA-AS-CODE — collections + fields. `push` reconciles them