@vxil/cli 0.12.0 → 0.13.0

package/dist/config.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.

package/dist/config.js

@@ -1,4 +1,21 @@
 // ../config/src/index.ts
+var CMS_INDEXED_FIELD_BUDGET = 4;
+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}' \u2014 a slot already indexes equality; use one`);
+    }
+    if (f.computed) {
+      throw new Error(`vxil.config: cms.${name}.${fname} is computed \u2014 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 \u2014 at most ${CMS_INDEXED_FIELD_BUDGET} per collection`);
+  }
+}
 var RELEASED_API_VERSIONS = ["v1"];
 function defineConfig(c) {
   if (c.apiVersion !== void 0 && !RELEASED_API_VERSIONS.includes(c.apiVersion)) {
@@ -6,16 +23,20 @@ function defineConfig(c) {
       `vxil.config: apiVersion '${String(c.apiVersion)}' is not a released API major (released: ${RELEASED_API_VERSIONS.map((v) => `'${v}'`).join(", ")}). A new major ships as a new path with its own deprecation window \u2014 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;
 }
 function field(type, opts = {}) {
   return { type, ...opts };
 }
 function collection(def) {
+  assertIndexedFields(def.singular ?? "collection", def);
   return def;
 }
 export {
+  CMS_INDEXED_FIELD_BUDGET,
   RELEASED_API_VERSIONS,
+  assertIndexedFields,
   collection,
   defineConfig,
   field

package/dist/vxil.js

@@ -4461,9 +4461,9 @@ function lowerAllTriggerBindings(def, name) {
   return bindings;
 }
 var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
-var VXIL_CONFIG_PKG_VERSION = "0.7.0";
-var VXIL_SDK_PKG_VERSION = "0.12.0";
-var VXIL_CLI_PKG_VERSION = "0.12.0";
+var VXIL_CONFIG_PKG_VERSION = "0.8.0";
+var VXIL_SDK_PKG_VERSION = "0.13.0";
+var VXIL_CLI_PKG_VERSION = "0.13.0";
 function ensureScaffoldPackageJson(cwd, opts = {}) {
   const file = resolve(cwd, "package.json");
   const wanted = {
@@ -8150,6 +8150,14 @@ function formatLogLines(lines) {
 }
 
 // src/cms.ts
+function indexReadyOf(rf) {
+  return rf.index_ready === true;
+}
+var EQ_INDEX_INLINE_MAX_ROWS = 2e3;
+function indexArmNote(rows) {
+  if (rows === null) return "arms inline or through the re-index push runs (live row count unavailable)";
+  return rows <= EQ_INDEX_INLINE_MAX_ROWS ? `arms inline (${rows} rows)` : `needs reindex (${rows} rows; push runs it)`;
+}
 function normalizeActions(raw) {
   if (!Array.isArray(raw)) return [];
   return raw.filter((a) => !!a && typeof a === "object").map((a) => ({ key: String(a.key), label: String(a.label), fn: String(a.fn) }));
@@ -8169,7 +8177,10 @@ var FIELD_ATTRS = [
   // (the server stores NULL for "ungated" and normalizes `[]` to NULL), so an
   // omitted attribute diffs clean; CLEARING it WIDENS access and therefore rides
   // the same --allow-destructive gate as clearing unique/on_delete/owner_field.
-  { config: "readRoles", wire: "read_roles", remote: "read_roles", blank: null, alter: "tighten-only" }
+  { config: "readRoles", wire: "read_roles", remote: "read_roles", blank: null, alter: "tighten-only" },
+  // PERF-26b: the equality index of an unslotted field (≤4 per collection).
+  // Present-key on the server; arming on > 2,000 live rows runs the re-index.
+  { config: "indexed", wire: "indexed", remote: "indexed", blank: false, alter: "index" }
 ];
 function fieldToInput(name, def) {
   const out = { field: name, type: def.type };
@@ -8192,7 +8203,7 @@ function remoteFieldToConfig(rf) {
 function fieldAttrDelta(def, rf) {
   const d = def;
   const r = rf;
-  const out = { flags: [], clearing: [], inPlace: [], reindex: [], retarget: [], drift: [] };
+  const out = { flags: [], clearing: [], inPlace: [], reindex: [], retarget: [], index: [], drift: [] };
   for (const a of FIELD_ATTRS) {
     const wantBlank = stableStringify(a.blank);
     const want = stableStringify(d[a.config] ?? a.blank);
@@ -8209,6 +8220,7 @@ function fieldAttrDelta(def, rf) {
     }
     if (a.alter === "reindex") out.reindex.push(line);
     else if (a.alter === "destructive") out.retarget.push(line);
+    else if (a.alter === "index") out.index.push(line);
     else out.inPlace.push(line);
   }
   return out;
@@ -8254,6 +8266,7 @@ async function reindexCollection({ api, collection, field, onProgress }) {
   let updated = 0;
   let pages = 0;
   let skipped = 0;
+  let indexCertify;
   const page = async () => {
     const res = await api("POST", `/v1/cms/collections/${encodeURIComponent(collection)}/reindex`, {
       ...field ? { field } : {},
@@ -8267,6 +8280,7 @@ async function reindexCollection({ api, collection, field, onProgress }) {
     scanned += d.scanned ?? 0;
     updated += d.updated ?? 0;
     pages++;
+    if (d.index_certify) indexCertify = d.index_certify;
     return d;
   };
   for (; ; ) {
@@ -8283,7 +8297,7 @@ async function reindexCollection({ api, collection, field, onProgress }) {
     }
     cursor = d.next_cursor;
   }
-  return { scanned, updated, pages, skipped };
+  return { scanned, updated, pages, skipped, ...indexCertify ? { indexCertify } : {} };
 }
 async function planCmsSchema({ api, collections, apply, allowDestructive = false, onProgress }) {
   const read = await readRemote2(api);
@@ -8312,11 +8326,17 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
     const collChanges = [];
     const post = [];
     const slotMoved = [];
+    const indexArming = [];
+    const indexVacating = [];
+    let rowsMemo;
+    const rows = () => rowsMemo ??= liveRowCount(api, name);
     const remoteByName = new Map(rc.fields.map((f) => [f.field, f]));
     for (const [fn, fd] of declaredFields) {
       const existing = remoteByName.get(fn);
       if (!existing) {
-        collChanges.push({ collection: name, kind: "add-field", field: fn, detail: `${name}.${fn} (${fd.type})` });
+        const arm = fd.indexed === true ? `; indexed: ${indexArmNote(await rows())}` : "";
+        if (fd.indexed === true) indexArming.push(fn);
+        collChanges.push({ collection: name, kind: "add-field", field: fn, detail: `${name}.${fn} (${fd.type})${arm}` });
       } else if (existing.type !== fd.type) {
         if (allowDestructive && (fd.indexSlot ?? null) !== (existing.index_slot ?? null)) {
           if (existing.index_slot) {
@@ -8339,10 +8359,14 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
           detail: `${name}.${fn} type ${existing.type} \u2192 ${fd.type} (destructive alter)`
         });
       } else {
-        const { flags, clearing, inPlace, reindex, retarget, drift } = fieldAttrDelta(fd, existing);
+        const { flags, clearing, inPlace, reindex, retarget, index, drift } = fieldAttrDelta(fd, existing);
+        const armsIndex = fd.indexed === true && (index.length > 0 || !indexReadyOf(existing));
+        const indexNote = armsIndex ? ` \u2014 ${fn} indexed: ${indexArmNote(await rows())}` : "";
+        if (armsIndex) indexArming.push(fn);
+        if (index.length > 0 && fd.indexed !== true && existing.indexed === true) indexVacating.push(fn);
         const destructiveAttrs = [...clearing, ...reindex, ...retarget];
         if (destructiveAttrs.length) {
-          const all = [...destructiveAttrs, ...flags, ...inPlace];
+          const all = [...destructiveAttrs, ...flags, ...inPlace, ...index];
           if (allowDestructive) {
             if (reindex.length && existing.index_slot) {
               pre.push({
@@ -8359,7 +8383,7 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
               kind: "destructive",
               op: "alter-field",
               field: fn,
-              detail: `${name}.${fn} ${all.join(", ")}` + (clearing.length ? " \u2014 clearing a live invariant (unique claims / on_delete cascade / read_roles gate)" : "") + (reindex.length ? " \u2014 an index_slot move: stored rows keep the OLD projection until the re-index runs" : "") + (retarget.length ? " \u2014 a relation retarget: every stored id now names a different collection" : "") + " (full-config reconciliation)"
+              detail: `${name}.${fn} ${all.join(", ")}` + (clearing.length ? " \u2014 clearing a live invariant (unique claims / on_delete cascade / read_roles gate)" : "") + (reindex.length ? " \u2014 an index_slot move: stored rows keep the OLD projection until the re-index runs" : "") + (retarget.length ? " \u2014 a relation retarget: every stored id now names a different collection" : "") + indexNote + " (full-config reconciliation)"
             });
             if (reindex.length) slotMoved.push(fn);
           } else {
@@ -8370,12 +8394,12 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
               detail: `${name}.${fn} ${all.join(", ")}: this is DESTRUCTIVE-SHAPED \u2014 ` + (clearing.length ? "it CLEARS a live invariant (clearing unique DROPS the uniqueness claims \u2014 duplicates then accepted, unrecoverable; clearing on_delete stops cascades; clearing read_roles WIDENS the field to every end-user); " : "") + (reindex.length ? "an index_slot move leaves stored rows on the OLD projection until a re-index, so queries on the field return the WRONG rows; " : "") + (retarget.length ? "a relation retarget repoints every stored id at another collection; " : "") + "it is NOT applied (nor is any co-declared in-place change on this field). Re-run with --allow-destructive to apply."
             });
           }
-        } else if (flags.length || inPlace.length) {
+        } else if (flags.length || inPlace.length || index.length) {
           collChanges.push({
             collection: name,
             kind: "alter-flags",
             field: fn,
-            detail: `${name}.${fn} ${[...flags, ...inPlace].join(", ")} (non-destructive in-place alter)`
+            detail: `${name}.${fn} ${[...flags, ...inPlace, ...index].join(", ")} (non-destructive in-place alter)${indexNote}`
           });
         }
         if (drift.length) {
@@ -8439,12 +8463,25 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
         });
       }
     }
-    if (slotMoved.length) {
-      const n = await liveRowCount(api, name);
+    let armReindex = false;
+    let vacateReindex = false;
+    if (indexArming.length > 0 || indexVacating.length > 0) {
+      const n = await rows();
+      const large = n === null || n > EQ_INDEX_INLINE_MAX_ROWS;
+      armReindex = large && indexArming.length > 0;
+      vacateReindex = large && indexVacating.length > 0;
+    }
+    if (slotMoved.length || armReindex || vacateReindex) {
+      const n = await rows();
+      const why = [
+        ...slotMoved.length ? [`the index_slot move on ${slotMoved.join(", ")}`] : [],
+        ...armReindex ? [`arming the equality index on ${indexArming.join(", ")}`] : [],
+        ...vacateReindex ? [`clearing the equality index of ${indexVacating.join(", ")}`] : []
+      ];
       post.push({
         collection: name,
         kind: "reindex",
-        detail: `${name} re-index ${n === null ? "live rows" : `${n} live rows`} after the index_slot move on ${slotMoved.join(", ")}`
+        detail: `${name} re-index ${n === null ? "live rows" : `${n} live rows`} after ${why.join(" and ")}`
       });
     }
     changes.push(...pre, ...collChanges, ...post);
@@ -8534,6 +8571,8 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
         if (done.skipped > 0) {
           onProgress?.(`  \u26A0 ${done.skipped} row(s) of ${c.collection} were written while the re-index ran and were NOT re-projected \u2014 re-run \`vxil cms reindex ` + c.collection + "` when writes are quiet");
         }
+        const certifyWarning = indexCertifyWarning(c.collection, done.indexCertify);
+        if (certifyWarning) onProgress?.(certifyWarning);
         applied++;
       } else if (c.kind === "destructive") {
         applied += await applyDestructive(api, collections, c);
@@ -8608,6 +8647,10 @@ function formatCollectionDrop(collection, plan, declaredLocally) {
   }
   return lines.join("\n");
 }
+function indexCertifyWarning(collection, certify) {
+  if (certify !== "timeout" && certify !== "pending") return null;
+  return `  \u26A0 the index on ${collection} is NOT armed yet (` + (certify === "timeout" ? "its certification ran out of time" : "rows changed during the pass") + ") \u2014 filters stay correct but unaccelerated; re-run `vxil cms reindex " + collection + "`";
+}
 
 // src/apiCmd.ts
 var API_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
@@ -11733,7 +11776,7 @@ var TOOLS = [
   {
     name: "cms_list_collections",
     feature: "cms",
-    description: "List the tenant's content model: collections with their typed field definitions (the schema items are validated against). Each field row carries its attributes \u2014 required, validation, index_slot, relation_to, computed/compute, is_unique, on_delete, and read_roles (the end-user org roles allowed to READ that field; null = ungated). A field with read_roles is omitted from end-user reads without a matching role and is never served on the public lane, so a missing key in an item's data may be a read gate rather than an unset value.",
+    description: "List the tenant's content model: collections with their typed field definitions (the schema items are validated against). Each field row carries its attributes \u2014 required, validation, index_slot, relation_to, computed/compute, is_unique, on_delete, read_roles (the end-user org roles allowed to READ that field; null = ungated), and on an equality-indexed field indexed: true + index_ready (equality filters on it are index-served once ready; until then, and on unindexed unslotted fields, they are a bounded scan \u2014 same results). A field with read_roles is omitted from end-user reads without a matching role and is never served on the public lane, so a missing key in an item's data may be a read gate rather than an unset value.",
     inputSchema: { type: "object", properties: {} },
     method: "GET",
     path: "/v1/cms/collections"
@@ -11757,7 +11800,7 @@ var TOOLS = [
   {
     name: "cms_query_items",
     feature: "cms",
-    description: 'Query content items with the bounded DSL. filter is a JSON object (\u22648 terms): {"price":{"$gte":10},"status":"published"}; ops $eq $ne $gt $gte $lt $lte $in $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). Paging: pass the returned next_cursor back as cursor WITH THE SAME filter and sort (works for the default order and for any slot/timestamp sort; not for a dotted join sort). $expand inlines relation/file fields. count=true returns {count} instead of a page (filter only \u2014 no sort/limit/cursor/$expand).',
+    description: 'Query content items with the bounded DSL. filter is a JSON object (\u22648 terms): {"price":{"$gte":10},"status":"published"}; ops $eq $ne $gt $gte $lt $lte $in $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). Equality ($eq / bare value / $in) is index-served on slot-indexed and `indexed` fields; on other fields it is a bounded scan (same results). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). Paging: pass the returned next_cursor back as cursor WITH THE SAME filter and sort (works for the default order and for any slot/timestamp sort; not for a dotted join sort). $expand inlines relation/file fields. count=true returns {count} instead of a page (filter only \u2014 no sort/limit/cursor/$expand).',
     inputSchema: {
       type: "object",
       properties: {
@@ -22529,6 +22572,8 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
         if (done.skipped > 0) {
           console.log(`  \u26A0 ${done.skipped} row(s) were written while the re-index ran and were NOT re-projected \u2014 re-run \`vxil cms reindex ${collection}\` when writes are quiet`);
         }
+        const certifyWarning = indexCertifyWarning(collection, done.indexCertify);
+        if (certifyWarning) console.log(certifyWarning);
       } else {
         fail("usage: vxil cms status|pull|reindex <collection> [--field <field>]|drop <collection> [--yes]|bulk-rm <collection> --filter '<json>' [--dry-run] [--yes]");
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": false,
   "description": "The vxil CLI — init, quickstart, push, gen, secrets, keys, migrate, doctor, diff, functions, payments; installs the `vxil` command (npm i -g @vxil/cli).",
   "license": "MIT",
@@ -46,10 +46,10 @@
   },
   "devDependencies": {
     "miniflare": "^4.20260611.0",
-    "@vxil/config": "0.7.0",
+    "@vxil/config": "0.8.0",
     "@vxil/runtime": "0.0.1",
-    "@vxil/types": "0.0.1",
-    "@vxil/feature-configs": "0.7.0"
+    "@vxil/feature-configs": "0.7.0",
+    "@vxil/types": "0.0.1"
   },
   "scripts": {
     "build": "pnpm --filter @vxil/feature-configs run build && pnpm --filter @vxil/config run build && esbuild bin/vxil.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/vxil.js --banner:js='#!/usr/bin/env node' --external:esbuild --external:miniflare && esbuild src/config-entry.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/config.js && pnpm exec tsx scripts/build-config-dts.ts",