@vxil/config 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -40,7 +40,22 @@ 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"):
+     *  `=` / `$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
+     *  `indexSlot` (a slot already indexes equality) and not on a computed field
+     *  (both checked here at define time and again by the server). Carried by
+     *  BOTH push paths and alterable in place; on a collection over 2,000 live
+     *  items `vxil push` also runs the re-index that arms it. */
+    indexed?: boolean;
 }
+/** The per-collection budget of `indexed: true` fields (cms/0158: e1…e4). */
+export declare const CMS_INDEXED_FIELD_BUDGET = 4;
+/** Define-time checks of a collection's `indexed` fields — the same refusals
+ *  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
  *  human-initiated step — pressing it invokes the deployed tenant function `fn`
  *  with `{ collection, item_id, action, actor, item }` and returns its result.
@@ -132,9 +147,15 @@ export interface FunctionTriggerRetry {
 export type FunctionTrigger = {
     kind: 'http';
     path?: string;
-} | {
+}
+/** `overlap: 'skip'` (2026-10-01): a due tick fires nothing while the
+ *  previous tick's run is still open (queued / running / retrying / waiting /
+ *  delayed) — the slot is counted, never caught up. Default `'allow'`. Every
+ *  cron envelope carries `scheduled_for`, the slot it was due for. */
+ | {
     kind: 'cron';
     schedule: string;
+    overlap?: 'allow' | 'skip';
 } | {
     kind: 'queue';
     source: string;

package/dist/index.js

@@ -1,3 +1,25 @@
+/** The per-collection budget of `indexed: true` fields (cms/0158: e1…e4). */
+export const CMS_INDEXED_FIELD_BUDGET = 4;
+/** Define-time checks of a collection's `indexed` fields — the same refusals
+ *  the server makes (422), so a config fails at `defineConfig` / `collection()`
+ *  instead of mid-push. Throws on the first violation. */
+export function assertIndexedFields(name, def) {
+    let n = 0;
+    for (const [fname, f] of Object.entries(def.fields ?? {})) {
+        if (f.indexed !== true)
+            continue;
+        n += 1;
+        if (f.indexSlot) {
+            throw new Error(`vxil.config: cms.${name}.${fname} sets both indexed and indexSlot '${f.indexSlot}' — a slot already indexes equality; use one`);
+        }
+        if (f.computed) {
+            throw new Error(`vxil.config: cms.${name}.${fname} is computed — a computed field cannot be indexed (bind it to an indexSlot instead)`);
+        }
+    }
+    if (n > CMS_INDEXED_FIELD_BUDGET) {
+        throw new Error(`vxil.config: cms.${name} has ${n} indexed fields — at most ${CMS_INDEXED_FIELD_BUDGET} per collection`);
+    }
+}
 /** The released majors `defineConfig` validates `apiVersion` against. Widened
  *  only by a real v2. */
 export const RELEASED_API_VERSIONS = ['v1'];
@@ -11,6 +33,8 @@ export function defineConfig(c) {
             `(released: ${RELEASED_API_VERSIONS.map((v) => `'${v}'`).join(', ')}). ` +
             'A new major ships as a new path with its own deprecation window — see https://vxil.com/docs/guide/12-going-to-production.');
     }
+    for (const [name, def] of Object.entries(c.cms?.collections ?? {}))
+        assertIndexedFields(name, def);
     return c;
 }
 /** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
@@ -20,5 +44,6 @@ export function field(type, opts = {}) {
 }
 /** Authoring helper for a collection module: `export default collection({...})`. */
 export function collection(def) {
+    assertIndexedFields(def.singular ?? 'collection', def);
     return def;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/config",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "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.6.0"
+    "@vxil/feature-configs": "0.7.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest';
-import { defineConfig, RELEASED_API_VERSIONS } from './index.js';
+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)', () => {
@@ -26,3 +28,25 @@ describe('defineConfig', () => {
       .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/);
+  });
+});

package/src/index.ts

@@ -6,7 +6,7 @@
 // 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/
-// sources (the paid, opt-in, egress-guarded crossing). Everything here is
+// 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 {
   NotificationsConfig, JobsConfig, AuthConfig, RateLimitsConfig, FilesConfig,
@@ -59,6 +59,38 @@ 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"):
+   *  `=` / `$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
+   *  `indexSlot` (a slot already indexes equality) and not on a computed field
+   *  (both checked here at define time and again by the server). Carried by
+   *  BOTH push paths and alterable in place; on a collection over 2,000 live
+   *  items `vxil push` also runs the re-index that arms it. */
+  indexed?: boolean;
+}
+
+/** The per-collection budget of `indexed: true` fields (cms/0158: e1…e4). */
+export const CMS_INDEXED_FIELD_BUDGET = 4;
+
+/** Define-time checks of a collection's `indexed` fields — the same refusals
+ *  the server makes (422), so a config fails at `defineConfig` / `collection()`
+ *  instead of mid-push. Throws on the first violation. */
+export function assertIndexedFields(name: string, def: CollectionDef): void {
+  let n = 0;
+  for (const [fname, f] of Object.entries(def.fields ?? {})) {
+    if (f.indexed !== true) continue;
+    n += 1;
+    if (f.indexSlot) {
+      throw new Error(`vxil.config: cms.${name}.${fname} sets both indexed and indexSlot '${f.indexSlot}' — a slot already indexes equality; use one`);
+    }
+    if (f.computed) {
+      throw new Error(`vxil.config: cms.${name}.${fname} is computed — a computed field cannot be indexed (bind it to an indexSlot instead)`);
+    }
+  }
+  if (n > CMS_INDEXED_FIELD_BUDGET) {
+    throw new Error(`vxil.config: cms.${name} has ${n} indexed fields — at most ${CMS_INDEXED_FIELD_BUDGET} per collection`);
+  }
 }
 
 /** One config-declared per-record ACTION button (cms.md §17): exactly ONE
@@ -156,7 +188,11 @@ export interface FunctionTriggerRetry {
  * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger =
   | { kind: 'http'; path?: string }
-  | { kind: 'cron'; schedule: string }
+  /** `overlap: 'skip'` (2026-10-01): a due tick fires nothing while the
+   *  previous tick's run is still open (queued / running / retrying / waiting /
+   *  delayed) — the slot is counted, never caught up. Default `'allow'`. Every
+   *  cron envelope carries `scheduled_for`, the slot it was due for. */
+  | { kind: 'cron'; schedule: string; overlap?: 'allow' | 'skip' }
   | { kind: 'queue'; source: string; retry?: FunctionTriggerRetry }
   /** `webhook`: the function is woken by a webhook_subscription fan-out whose
    *  target_url is `<edge>/v1/internal/fn/trigger/<name>?tenant=<id>`. That
@@ -333,6 +369,7 @@ export function defineConfig(c: VxilConfig): VxilConfig {
         'A new major ships as a new path with its own deprecation window — see https://vxil.com/docs/guide/12-going-to-production.',
     );
   }
+  for (const [name, def] of Object.entries(c.cms?.collections ?? {})) assertIndexedFields(name, def);
   return c;
 }
 
@@ -347,5 +384,6 @@ export function field(
 
 /** Authoring helper for a collection module: `export default collection({...})`. */
 export function collection(def: CollectionDef): CollectionDef {
+  assertIndexedFields(def.singular ?? 'collection', def);
   return def;
 }