@vxil/config 0.8.0 → 0.8.2

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export interface FieldDef {
     relationTo?: string;
     computed?: boolean;
     compute?: unknown;
-    /** Claims-table-enforced value uniqueness across live items (cms.md §9.3):
+    /** Claims-table-enforced value uniqueness across live items (guide ch. 4):
      *  a duplicate write is a clean 409 unique_violation. Scalar types only
      *  (string/int/float/datetime/relation/file). Carried on collection/field
      *  CREATE by `vxil push` and server apply; since 2026-07-17 `vxil push` also
@@ -22,12 +22,12 @@ export interface FieldDef {
      *  field re-add — packages/cli/src/cms.ts FIELD_ATTRS); attributes push
      *  cannot reconcile surface as a visible plan warning, never a silent no-op. */
     unique?: boolean;
-    /** Per-relation-field delete behavior (cms.md §11): bounded, atomic fan-out
-     *  when the referenced item is deleted — or `restrict` (§11.1), which REFUSES
+    /** Per-relation-field delete behavior (guide ch. 4): bounded, atomic fan-out
+     *  when the referenced item is deleted — or `restrict`, which REFUSES
      *  the delete with 409 `referenced` while a live reference exists. Same
      *  carriage + reconcile behavior as `unique`. */
     onDelete?: 'cascade' | 'set_null' | 'restrict';
-    /** FIELD-LEVEL READ SECURITY (cms.md §18): the end-user ORG ROLE slugs allowed
+    /** FIELD-LEVEL READ SECURITY (guide ch. 4): the end-user ORG ROLE slugs allowed
      *  to READ this field. Omitted/`[]` = ungated (every caller sees it — today's
      *  behavior). A non-empty list is FAIL-SAFE: in VERIFIED end-user mode the
      *  field is OMITTED from every read (get / list / query / `$expand` at any
@@ -40,7 +40,7 @@ export interface FieldDef {
      *  `orgs` role alphabet). The gate
      *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
     readRoles?: string[];
-    /** EQUALITY INDEX for an UNSLOTTED field (cms.md §3 "Indexed equality"):
+    /** EQUALITY INDEX for an UNSLOTTED field (guide ch. 4 "Indexed equality"):
      *  `=` / `$eq` / `$in` filters on it are index-served instead of a bounded
      *  scan — results are identical either way. At most 4 per collection (the
      *  equality-key budget, separate from the 8 index slots); not together with
@@ -56,7 +56,7 @@ export declare const CMS_INDEXED_FIELD_BUDGET = 4;
  *  the server makes (422), so a config fails at `defineConfig` / `collection()`
  *  instead of mid-push. Throws on the first violation. */
 export declare function assertIndexedFields(name: string, def: CollectionDef): void;
-/** One config-declared per-record ACTION button (cms.md §17): exactly ONE
+/** One config-declared per-record ACTION button (guide ch. 4): exactly ONE
  *  human-initiated step — pressing it invokes the deployed tenant function `fn`
  *  with `{ collection, item_id, action, actor, item }` and returns its result.
  *  No conditions, no chaining, no scheduling. `key` matches
@@ -71,7 +71,7 @@ export interface CmsActionDef {
  *  `FieldDef` itself so it can never drift from the authoring type: it is every
  *  key of `FieldDef` except `type` (which is required, not an optional carried
  *  attribute). This is the compile-time source of truth for the config-carriage
- *  completeness ratchet (audit 2026-07-15e #2, roadmap §4.5 P3): the CLI carriage
+ *  completeness ratchet: the CLI carriage
  *  table (`packages/cli/src/cms.ts` FIELD_ATTRS) and the server one
  *  (`workers/control-plane/src/handlers/apply.ts` FIELD_ATTR_DELTA) each pin
  *  `keyof` coverage against a set that equals this — so a 9th attribute added to
@@ -98,7 +98,7 @@ export interface CollectionDef {
      *  server-caller mode. Not a hard-isolation predicate; a single declarative
      *  flag the typed worker consults. Omit for shared/reference collections. */
     ownerField?: string;
-    /** Public delivery (roadmap §4.4): when true, this collection's PUBLISHED items
+    /** Public delivery (guide ch. 4): when true, this collection's PUBLISHED items
      *  are servable through the keyless, edge-cached GET /v1/cms/public/:tenantId/
      *  :collection lane (no API key). Owner-UNSCOPED (public content, not per-user);
      *  the owner_field is stripped from every served row. Default false. Carried by
@@ -106,22 +106,22 @@ export interface CollectionDef {
      *  with a regression test on each — an attribute read by no enforcing path ships
      *  inert (the validation.unique / owner_field precedent). */
     public?: boolean;
-    /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]`, stored on
+    /** Per-record action buttons (guide ch. 4): `[{ key, label, fn }]`, stored on
      *  the collection (model data, not a config leaf). The dashboard renders one
      *  button per action on each record row; `POST /v1/cms/items/:coll/:id/actions/
      *  :key` invokes `fn` once. Carried by BOTH push paths (create + reconcile on
      *  existing collections — config is the source of truth; `[]`/absent clears). */
     actions?: CmsActionDef[];
 }
-/** The auth lifecycle events an `authHook` binding may subscribe to (F4-30,
- * auth wave 2026-09-10) — a CLOSED union; ONE event per binding, one audit
+/** The auth lifecycle events an `authHook` binding may subscribe to
+ * (2026-09-10) — a CLOSED union; ONE event per binding, one audit
  * event → one function invocation, no branching inside vxil:
  *   user.created    — auth.user.created  { user_id, method, is_anonymous }
  *   session.created — auth.session.created { user_id, session_id }
  *   session.revoked — auth.session.revoked { user_id, session_id, reason }
  *   signin.failure  — auth.signin.failure { email_hash | user_id, reason } */
 export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoked' | 'signin.failure';
-/** The opt-in re-delivery of a platform-delivered trigger (F33, 2026-09-25).
+/** The opt-in re-delivery of a platform-delivered trigger (guide ch. 8).
  *  DEFAULT OFF: the platform acknowledges every delivery with a 200 whatever
  *  the handler returned — an application error is observed (`functions.run.failed`),
  *  never re-delivered. With `retry` set on a `queue` / `webhook` / `cmsHook` /
@@ -141,7 +141,7 @@ export interface FunctionTriggerRetry {
     /** 1–5 attempts in all (1 = a failed attempt dead-letters at once, no re-delivery) */
     maxAttempts: number;
 }
-/** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
+/** A function trigger (guide ch. 8). cmsHook fires on a CMS write;
  * authHook fires on ONE auth lifecycle event (default `user.created` — the
  * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger = {
@@ -243,7 +243,7 @@ export interface FunctionDef {
         timeoutMs?: number;
     };
     enabled?: boolean;
-    /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
+    /** optional typed contract surfaced by `vxil gen` (Level 1; guide ch. 8). */
     signature?: {
         input?: unknown;
         output?: unknown;
@@ -278,8 +278,7 @@ export declare const RELEASED_API_VERSIONS: readonly ApiVersion[];
 /** 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
+ *  partially-written nested bag, including the guide's own skeleton. 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]>;
@@ -318,7 +317,7 @@ export interface VxilConfig {
     };
     /** (b) CMS SCHEMA-AS-CODE — collections + fields. `push` reconciles them
      *  additively against GET /v1/cms/collections (no destructive drops without
-     *  --allow-destructive). Lane-A hooks stay in features.cms.hooks (config). */
+     *  --allow-destructive). Validation hooks stay in features.cms.hooks (config). */
     cms?: {
         collections?: Record<string, CollectionDef>;
     };
@@ -334,7 +333,7 @@ export interface VxilConfig {
  *  from JS callers with no compile gate, or a stale generated value) fails fast
  *  here rather than 404-ing every request against a nonexistent major. */
 export declare function defineConfig(c: VxilConfig): VxilConfig;
-/** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
+/** Authoring helper for split-out cms/<name>.ts collection modules (guide ch. 5).
  *  `field('title', 'string', { required: true, indexSlot: 's1' })`. */
 export declare function field(type: FieldType, opts?: Omit<FieldDef, 'type'>): FieldDef;
 /** Authoring helper for a collection module: `export default collection({...})`. */

package/dist/index.js

@@ -37,7 +37,7 @@ export function defineConfig(c) {
         assertIndexedFields(name, def);
     return c;
 }
-/** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
+/** Authoring helper for split-out cms/<name>.ts collection modules (guide ch. 5).
  *  `field('title', 'string', { required: true, indexSlot: 's1' })`. */
 export function field(type, opts = {}) {
     return { type, ...opts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/config",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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",
@@ -19,10 +19,11 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.ts"
   ],
   "dependencies": {
-    "@vxil/feature-configs": "0.7.0"
+    "@vxil/feature-configs": "0.7.1"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -4,8 +4,8 @@
 // so `vxil push` can compile it to a JSON manifest. Type-checking happens in the
 // tenant's editor (real autocomplete from the @vxil/feature-configs Static<>
 // types); the control plane never executes this file. This keeps config-as-code
-// §7.3-consistent — config is DATA; the only tenant CODE that crosses into vxil
-// is (a) the Lane-A hook expressions (a closed sandbox) and (b) the functions/
+// consistent — config is DATA; the only tenant CODE that crosses into vxil
+// is (a) the hook expressions (a closed sandbox) and (b) the functions/
 // sources (the opt-in, plan-limited, egress-guarded crossing). Everything here is
 // declarative. See https://vxil.com/docs/guide/05-typed-sdk-and-cli.
 import type {
@@ -33,7 +33,7 @@ export interface FieldDef {
   relationTo?: string;
   computed?: boolean;
   compute?: unknown;
-  /** Claims-table-enforced value uniqueness across live items (cms.md §9.3):
+  /** Claims-table-enforced value uniqueness across live items (guide ch. 4):
    *  a duplicate write is a clean 409 unique_violation. Scalar types only
    *  (string/int/float/datetime/relation/file). Carried on collection/field
    *  CREATE by `vxil push` and server apply; since 2026-07-17 `vxil push` also
@@ -41,12 +41,12 @@ export interface FieldDef {
    *  field re-add — packages/cli/src/cms.ts FIELD_ATTRS); attributes push
    *  cannot reconcile surface as a visible plan warning, never a silent no-op. */
   unique?: boolean;
-  /** Per-relation-field delete behavior (cms.md §11): bounded, atomic fan-out
-   *  when the referenced item is deleted — or `restrict` (§11.1), which REFUSES
+  /** Per-relation-field delete behavior (guide ch. 4): bounded, atomic fan-out
+   *  when the referenced item is deleted — or `restrict`, which REFUSES
    *  the delete with 409 `referenced` while a live reference exists. Same
    *  carriage + reconcile behavior as `unique`. */
   onDelete?: 'cascade' | 'set_null' | 'restrict';
-  /** FIELD-LEVEL READ SECURITY (cms.md §18): the end-user ORG ROLE slugs allowed
+  /** FIELD-LEVEL READ SECURITY (guide ch. 4): the end-user ORG ROLE slugs allowed
    *  to READ this field. Omitted/`[]` = ungated (every caller sees it — today's
    *  behavior). A non-empty list is FAIL-SAFE: in VERIFIED end-user mode the
    *  field is OMITTED from every read (get / list / query / `$expand` at any
@@ -59,7 +59,7 @@ export interface FieldDef {
    *  `orgs` role alphabet). The gate
    *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
   readRoles?: string[];
-  /** EQUALITY INDEX for an UNSLOTTED field (cms.md §3 "Indexed equality"):
+  /** EQUALITY INDEX for an UNSLOTTED field (guide ch. 4 "Indexed equality"):
    *  `=` / `$eq` / `$in` filters on it are index-served instead of a bounded
    *  scan — results are identical either way. At most 4 per collection (the
    *  equality-key budget, separate from the 8 index slots); not together with
@@ -93,7 +93,7 @@ export function assertIndexedFields(name: string, def: CollectionDef): void {
   }
 }
 
-/** One config-declared per-record ACTION button (cms.md §17): exactly ONE
+/** One config-declared per-record ACTION button (guide ch. 4): exactly ONE
  *  human-initiated step — pressing it invokes the deployed tenant function `fn`
  *  with `{ collection, item_id, action, actor, item }` and returns its result.
  *  No conditions, no chaining, no scheduling. `key` matches
@@ -109,7 +109,7 @@ export interface CmsActionDef {
  *  `FieldDef` itself so it can never drift from the authoring type: it is every
  *  key of `FieldDef` except `type` (which is required, not an optional carried
  *  attribute). This is the compile-time source of truth for the config-carriage
- *  completeness ratchet (audit 2026-07-15e #2, roadmap §4.5 P3): the CLI carriage
+ *  completeness ratchet: the CLI carriage
  *  table (`packages/cli/src/cms.ts` FIELD_ATTRS) and the server one
  *  (`workers/control-plane/src/handlers/apply.ts` FIELD_ATTR_DELTA) each pin
  *  `keyof` coverage against a set that equals this — so a 9th attribute added to
@@ -137,7 +137,7 @@ export interface CollectionDef {
    *  server-caller mode. Not a hard-isolation predicate; a single declarative
    *  flag the typed worker consults. Omit for shared/reference collections. */
   ownerField?: string;
-  /** Public delivery (roadmap §4.4): when true, this collection's PUBLISHED items
+  /** Public delivery (guide ch. 4): when true, this collection's PUBLISHED items
    *  are servable through the keyless, edge-cached GET /v1/cms/public/:tenantId/
    *  :collection lane (no API key). Owner-UNSCOPED (public content, not per-user);
    *  the owner_field is stripped from every served row. Default false. Carried by
@@ -145,7 +145,7 @@ export interface CollectionDef {
    *  with a regression test on each — an attribute read by no enforcing path ships
    *  inert (the validation.unique / owner_field precedent). */
   public?: boolean;
-  /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]`, stored on
+  /** Per-record action buttons (guide ch. 4): `[{ key, label, fn }]`, stored on
    *  the collection (model data, not a config leaf). The dashboard renders one
    *  button per action on each record row; `POST /v1/cms/items/:coll/:id/actions/
    *  :key` invokes `fn` once. Carried by BOTH push paths (create + reconcile on
@@ -153,8 +153,8 @@ export interface CollectionDef {
   actions?: CmsActionDef[];
 }
 
-/** The auth lifecycle events an `authHook` binding may subscribe to (F4-30,
- * auth wave 2026-09-10) — a CLOSED union; ONE event per binding, one audit
+/** The auth lifecycle events an `authHook` binding may subscribe to
+ * (2026-09-10) — a CLOSED union; ONE event per binding, one audit
  * event → one function invocation, no branching inside vxil:
  *   user.created    — auth.user.created  { user_id, method, is_anonymous }
  *   session.created — auth.session.created { user_id, session_id }
@@ -162,7 +162,7 @@ export interface CollectionDef {
  *   signin.failure  — auth.signin.failure { email_hash | user_id, reason } */
 export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoked' | 'signin.failure';
 
-/** The opt-in re-delivery of a platform-delivered trigger (F33, 2026-09-25).
+/** The opt-in re-delivery of a platform-delivered trigger (guide ch. 8).
  *  DEFAULT OFF: the platform acknowledges every delivery with a 200 whatever
  *  the handler returned — an application error is observed (`functions.run.failed`),
  *  never re-delivered. With `retry` set on a `queue` / `webhook` / `cmsHook` /
@@ -183,7 +183,7 @@ export interface FunctionTriggerRetry {
   maxAttempts: number;
 }
 
-/** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
+/** A function trigger (guide ch. 8). cmsHook fires on a CMS write;
  * authHook fires on ONE auth lifecycle event (default `user.created` — the
  * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger =
@@ -265,7 +265,7 @@ export interface FunctionDef {
     timeoutMs?: number;
   };
   enabled?: boolean;
-  /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
+  /** optional typed contract surfaced by `vxil gen` (Level 1; guide ch. 8). */
   signature?: { input?: unknown; output?: unknown };
 }
 
@@ -296,8 +296,7 @@ export const RELEASED_API_VERSIONS: readonly ApiVersion[] = ['v1'];
 /** 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
+ *  partially-written nested bag, including the guide's own skeleton. Arrays and primitives are kept
  *  as-is; only plain object bags recurse. */
 export type DeepPartial<T> = T extends readonly unknown[]
   ? T
@@ -342,7 +341,7 @@ export interface VxilConfig {
 
   /** (b) CMS SCHEMA-AS-CODE — collections + fields. `push` reconciles them
    *  additively against GET /v1/cms/collections (no destructive drops without
-   *  --allow-destructive). Lane-A hooks stay in features.cms.hooks (config). */
+   *  --allow-destructive). Validation hooks stay in features.cms.hooks (config). */
   cms?: {
     collections?: Record<string, CollectionDef>;
   };
@@ -373,7 +372,7 @@ export function defineConfig(c: VxilConfig): VxilConfig {
   return c;
 }
 
-/** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
+/** Authoring helper for split-out cms/<name>.ts collection modules (guide ch. 5).
  *  `field('title', 'string', { required: true, indexSlot: 's1' })`. */
 export function field(
   type: FieldType,

package/src/deepPartial.test.ts

@@ -1,24 +0,0 @@
-// 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.test.ts

@@ -1,52 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  assertIndexedFields, CMS_INDEXED_FIELD_BUDGET, collection, defineConfig, field, RELEASED_API_VERSIONS,
-} from './index.js';
-
-describe('defineConfig', () => {
-  it('is an identity function (returns its argument verbatim)', () => {
-    const cfg = { features: { cms: {} } };
-    expect(defineConfig(cfg)).toBe(cfg);
-  });
-
-  it('accepts the released apiVersion', () => {
-    const cfg = defineConfig({ apiVersion: 'v1', features: {} });
-    expect(cfg.apiVersion).toBe('v1');
-    expect(RELEASED_API_VERSIONS).toEqual(['v1']);
-  });
-
-  it('accepts a config without apiVersion (optional; defaults to v1 at the CLI)', () => {
-    expect(() => defineConfig({ features: {} })).not.toThrow();
-  });
-
-  it('throws on an unreleased apiVersion (fail-fast, actionable message)', () => {
-    // A JS caller (no compile gate) or a stale generated value must be rejected
-    // at load, not silently 404 every request.
-    expect(() => defineConfig({ apiVersion: 'v2' as 'v1', features: {} }))
-      .toThrow(/apiVersion 'v2' is not a released API major/);
-    expect(() => defineConfig({ apiVersion: 'latest' as 'v1' }))
-      .toThrow(/docs\/guide\/12-going-to-production/);
-  });
-});
-
-describe('indexed fields (PERF-26b) — define-time checks', () => {
-  it('accepts up to four unslotted indexed fields', () => {
-    const c = collection({ fields: {
-      a: field('string', { indexed: true }), b: field('int', { indexed: true }),
-      c: field('bool', { indexed: true }), d: field('string', { indexed: true }),
-      e: field('string', { indexSlot: 's1' }),
-    } });
-    expect(Object.keys(c.fields)).toHaveLength(5);
-    expect(CMS_INDEXED_FIELD_BUDGET).toBe(4);
-  });
-
-  it('refuses a fifth, indexed + indexSlot, and a computed indexed field', () => {
-    expect(() => defineConfig({ cms: { collections: { posts: { fields: Object.fromEntries(
-      ['a', 'b', 'c', 'd', 'e'].map((k) => [k, field('string', { indexed: true })]),
-    ) } } } })).toThrow(/at most 4 per collection/);
-    expect(() => collection({ fields: { a: field('string', { indexed: true, indexSlot: 's1' }) } }))
-      .toThrow(/already indexes equality/);
-    expect(() => assertIndexedFields('posts', { fields: { a: field('string', { indexed: true, computed: true }) } }))
-      .toThrow(/computed/);
-  });
-});