@vxil/cli 0.11.1 → 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.11.1";
-var VXIL_CLI_PKG_VERSION = "0.11.1";
+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 = {
@@ -4748,6 +4748,7 @@ async function serverApply({ api, bundle, resume, allowDestructive, onPlan }) {
     `apply execute (resume with: vxil push --server --resume ${plan.apply_id})`
   );
 }
+var PUSH_READ_CONCURRENCY = 5;
 async function planOrPush({ api, features, apply, allowDestructive }) {
   const results = [];
   const destructiveQs = allowDestructive ? "&allow_destructive=true" : "";
@@ -4755,8 +4756,20 @@ async function planOrPush({ api, features, apply, allowDestructive }) {
     const v = r.body.data?.api_state;
     return v && typeof v === "object" && typeof v.ok === "boolean" ? v : void 0;
   };
-  for (const [feature, manifest] of Object.entries(features)) {
-    const dry = await api("PUT", `/v1/config/${feature}?dry_run=true${destructiveQs}`, manifest);
+  const entries = Object.entries(features);
+  const reads = await mapPool(entries, PUSH_READ_CONCURRENCY, async ([feature, manifest]) => {
+    try {
+      const dry = await api("PUT", `/v1/config/${feature}?dry_run=true${destructiveQs}`, manifest);
+      if (dry.status !== 200) return { dry };
+      return { dry, cur: await api("GET", `/v1/config/${feature}`) };
+    } catch (err) {
+      return { err };
+    }
+  });
+  for (const [i, [feature, manifest]] of entries.entries()) {
+    const read = reads[i];
+    if ("err" in read) throw read.err;
+    const dry = read.dry;
     if (dry.status !== 200) {
       const e = dry.body.error ?? {};
       throw new Error(
@@ -4765,7 +4778,7 @@ async function planOrPush({ api, features, apply, allowDestructive }) {
     }
     const effective = dry.body.data?.manifest;
     const apiStatePlan = apiStateOf(dry);
-    const cur = await api("GET", `/v1/config/${feature}`);
+    const cur = read.cur;
     const unavailable = readUnavailable(`GET /v1/config/${feature}`, cur);
     if (unavailable) {
       if (apply) {
@@ -7706,6 +7719,58 @@ function hookReconcileOf(data2) {
 function hookReconcileRemedy(fnName) {
   return fnName ? `re-run the reconcile with \`vxil functions deploy ${fnName} --force\` or \`vxil push --server\` (a plain re-push sends no deploy for an unchanged function, so it would not retry it)` : "re-run the reconcile with `vxil push --server` (a plain re-push sends no deploy, so it would not retry it)";
 }
+var WIRING_WARNING = /trigger subscription|cron schedule/i;
+function triggerWiringOf(data2) {
+  if (!data2) return null;
+  const counts = (v) => {
+    if (!v || typeof v !== "object" || Array.isArray(v)) return void 0;
+    const o = v;
+    const n = (x) => typeof x === "number" && Number.isFinite(x) ? x : 0;
+    const opt = (x) => typeof x === "number" && Number.isFinite(x) ? x : void 0;
+    const updated = opt(o.updated);
+    const unchanged = opt(o.unchanged);
+    return {
+      created: n(o.created),
+      ...updated !== void 0 ? { updated } : {},
+      ...unchanged !== void 0 ? { unchanged } : {},
+      deleted: n(o.deleted),
+      failed: n(o.failed)
+    };
+  };
+  const cms = counts(data2.cms_hook_subscriptions);
+  const webhook = counts(data2.webhook_subscriptions);
+  const cron = counts(data2.cron_schedules);
+  const total = counts(data2.hook_reconcile);
+  if (!total && !cms && !webhook && !cron) return null;
+  const warnings = Array.isArray(data2.warnings) ? data2.warnings.filter((w) => typeof w === "string" && WIRING_WARNING.test(w)) : [];
+  return {
+    total: total ?? { created: 0, deleted: 0, failed: (cms?.failed ?? 0) + (webhook?.failed ?? 0) + (cron?.failed ?? 0) },
+    ...cms ? { cms_hook_subscriptions: cms } : {},
+    ...webhook ? { webhook_subscriptions: webhook } : {},
+    ...cron ? { cron_schedules: cron } : {},
+    warnings
+  };
+}
+function formatTriggerWiring(r) {
+  const line = (c) => [
+    `${c.created} created`,
+    ...c.updated !== void 0 ? [`${c.updated} updated`] : [],
+    ...c.unchanged !== void 0 ? [`${c.unchanged} unchanged`] : [],
+    `${c.deleted} removed`,
+    `${c.failed} failed`
+  ].join(" \xB7 ");
+  const lanes = [
+    ["hook subscriptions (cms/auth)", r.cms_hook_subscriptions],
+    ["webhook-trigger subscriptions", r.webhook_subscriptions],
+    ["cron schedules", r.cron_schedules]
+  ];
+  const out = [r.total.failed > 0 ? `trigger wiring (reconciled by the server) \u2014 ${r.total.failed} FAILED:` : "trigger wiring (reconciled by the server):"];
+  const shown = lanes.filter(([, c]) => c);
+  if (shown.length) for (const [label, c] of shown) out.push(`  ${label.padEnd(30)}  ${line(c)}`);
+  else out.push(`  ${"all triggers".padEnd(30)}  ${line(r.total)}`);
+  for (const w of r.warnings) out.push(`  ! ${w}`);
+  return out;
+}
 function sourceSha12(source, runtime) {
   const suffix = runtime ? functionsRuntimeHashSuffix(runtime) : "";
   return createHash("sha256").update(source + suffix, "utf8").digest("hex").slice(0, 12);
@@ -8085,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) }));
@@ -8104,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 };
@@ -8127,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);
@@ -8144,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;
@@ -8189,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 } : {},
@@ -8202,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 (; ; ) {
@@ -8218,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);
@@ -8247,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) {
@@ -8274,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({
@@ -8294,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 {
@@ -8305,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) {
@@ -8374,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);
@@ -8469,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);
@@ -8543,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"];
@@ -11668,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"
@@ -11692,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: {
@@ -12302,7 +12410,7 @@ var TOOLS = [
   {
     name: "search_query",
     feature: "vector-search",
-    description: "Retrieve the top-k most relevant chunks from a vector-search collection. mode 'hybrid' (default) fuses semantic + keyword via RRF; 'vector' is pure semantic; 'keyword' is lexical. filter is a JSON object of equality constraints over chunk metadata. Returns scored results with document/chunk attribution.",
+    description: "Retrieve the top-k most relevant chunks from a vector-search collection. mode 'hybrid' (default) fuses semantic + keyword via RRF; 'vector' is pure semantic; 'keyword' is lexical. filter is a JSON object of equality constraints over chunk metadata. Returns ranked results with document/chunk attribution: score is the fused rank value (orders the hits, not a similarity); similarity is the cosine similarity to the query (-1..1, null in keyword mode) \u2014 threshold on similarity.",
     inputSchema: {
       type: "object",
       properties: {
@@ -12496,7 +12604,7 @@ var TOOLS = [
         filter: { type: "object", additionalProperties: true, description: "Metadata equality filter applied to retrieval." },
         rerank: { type: "boolean", description: "Forward rerank:true to vector-search's BYO rerank pass (inert until configured there)." },
         boosts: { type: "object", additionalProperties: true, description: "Per-metadata-field boost specs: { field: { kind:'recency', halfLifeDays?, weight? } | { kind:'value', weights:{\u2026} } }." },
-        min_score: { type: "number", description: "Drop hits below this EFFECTIVE (post-boost) score." }
+        min_score: { type: "number", description: "Drop hits below this EFFECTIVE (post-boost) score. score is a rank value (about 0.016-0.033 at the top), so a floor above ~0.033 drops every hit; judge relevance by each hit's similarity instead." }
       },
       required: ["query"]
     },
@@ -13933,7 +14041,7 @@ var VERB_USAGE = {
   mcp: "usage: vxil mcp install [--client cursor|claude|vscode] [--project] [--print] [--key <api_key>] [--scopes a,b] [--name <server>]",
   plan: "usage: vxil plan [--dev|--target <name>] [--explain] [--skip-functions]  \u2014 what `vxil push` would change: cms schema, feature config, declared API state, functions (a deployed function the config no longer declares shows as `-`); writes nothing",
   diff: "usage: vxil diff [--against <target>|--exit-code] [--explain] [--ignore <k,\u2026>] [--strict-secrets] [--strict-api-state] [--api-state] [--json]  \u2014 the CI gate: exit 0 no drift \xB7 1 drift \xB7 2 error",
-  push: "usage: vxil push [--dev|--target <name>|--prod] [--allow-destructive] [--strict] [--server [--resume <apply_id>]] [--no-gen] [--skip-functions] [--yes]  \u2014 apply the config; --allow-destructive also deletes deployed functions and stored AI templates the config no longer declares; --strict exits 1 when anything declared was refused, deferred or left unwired",
+  push: "usage: vxil push [--dev|--target <name>|--prod] [--allow-destructive] [--strict] [--server [--resume <apply_id>]] [--no-gen] [--skip-functions] [--yes]  \u2014 apply the config; --allow-destructive also deletes deployed functions and stored AI templates the config no longer declares; --strict exits 1 when anything declared was refused, deferred or left unwired; --server prints the trigger wiring the server reconciled (--json: one result document on stdout)",
   gen: "usage: vxil gen [--check] [--offline] [--out <f>] [--no-mcp] [--mcp-out <f>]  \u2014 generate vxil.types.ts (+ vxil.mcp.json); --offline keeps an existing API_VERSIONS block; --check compares instead of writing",
   types: "usage: vxil types  \u2014 alias of `vxil gen` (run `vxil gen --help`)",
   doctor: "usage: vxil doctor [--dev|--target <name>]  \u2014 preflight: the binding's tenant vs the key's tenant, secrets referenced-vs-stored, per-function hashes, keys (read-only)",
@@ -14022,6 +14130,32 @@ function pushExitCode(p, strict) {
   if (p.strict.length) lines.push(`${p.strict.length} warning(s) \u2014 \`vxil push --strict\` turns them into exit 1 for CI`);
   return { code: 0, lines };
 }
+function serverApplyJson(input) {
+  const { view, triggerWiring, problems, exitCode, error } = input;
+  return {
+    ok: exitCode === 0,
+    exit_code: exitCode,
+    apply_id: view.apply_id,
+    status: view.status,
+    steps: view.steps,
+    ...view.failed_step ? { failed_step: view.failed_step } : {},
+    trigger_wiring: triggerWiring ?? null,
+    problems: { hard: problems.hard, strict: problems.strict },
+    ...error ? { error } : {}
+  };
+}
+function serverApplyErrorJson(input) {
+  return {
+    ok: false,
+    exit_code: input.exitCode,
+    apply_id: null,
+    status: null,
+    steps: [],
+    trigger_wiring: null,
+    problems: { hard: [], strict: [] },
+    error: input.error
+  };
+}
 
 // src/paymentsCmd.ts
 var SIMULATE_SCENARIOS = [
@@ -19669,12 +19803,19 @@ function hasFlag(name) {
   return rest.includes(`--${name}`);
 }
 var jsonOut = rest.includes("--json");
+var jsonFailDoc = null;
 function ttlFlag(fallback) {
   const parsed = parseTtlFlag(flag("ttl"), fallback);
   if ("error" in parsed) fail(parsed.error);
   return parsed.hours;
 }
 function fail(msg, code = 1) {
+  if (jsonFailDoc) {
+    const doc = jsonFailDoc;
+    jsonFailDoc = null;
+    process.stdout.write(`${doc(msg, code)}
+`);
+  }
   console.error(`vxil: ${msg}`);
   process.exit(code);
 }
@@ -20566,22 +20707,79 @@ async function backendListsFunctions(api) {
   }
 }
 async function runServerApply(sel) {
+  armServerApplyJsonFail();
   const { api, target } = requireApi(sel, { write: "push --server" });
+  const say = (s) => {
+    if (jsonOut) console.error(s);
+    else console.log(s);
+  };
+  const strict = hasFlag("strict");
+  const finish = async (done2, problems2, code, error) => {
+    jsonFailDoc = null;
+    if (jsonOut) {
+      const doc = JSON.stringify(serverApplyJson({
+        view: done2,
+        triggerWiring: triggerWiringOf(done2),
+        problems: problems2,
+        exitCode: code,
+        ...error ? { error } : {}
+      }));
+      await new Promise((r) => {
+        process.stdout.write(`${doc}
+`, () => r());
+      });
+    }
+    if (error) fail(error, code);
+    process.exit(code);
+  };
+  const armWith = (done2, problems2) => {
+    if (!jsonOut) return;
+    jsonFailDoc = (error, exitCode) => JSON.stringify(serverApplyJson({
+      view: done2,
+      triggerWiring: triggerWiringOf(done2),
+      problems: problems2,
+      exitCode,
+      error
+    }));
+  };
+  const report = (done2, wiring) => {
+    say(formatApplySteps(done2.steps));
+    say(`
+apply ${done2.apply_id}: ${done2.status}`);
+    if (!wiring) return;
+    const w = triggerWiringOf(done2);
+    if (w) say(`
+${formatTriggerWiring(w).join("\n")}`);
+  };
+  const gen = async () => {
+    if (hasFlag("no-gen")) return;
+    if (!jsonOut) {
+      await runGen(sel);
+      return;
+    }
+    const log = console.log;
+    console.log = (...a) => {
+      console.error(...a);
+    };
+    try {
+      await runGen(sel);
+    } finally {
+      console.log = log;
+    }
+  };
   const resume = flag("resume");
   if (resume) {
     const done2 = await serverApply({ api, resume });
-    console.log(formatApplySteps(done2.steps));
-    console.log(`
-apply ${done2.apply_id}: ${done2.status}`);
-    if (done2.status === "running") console.log(`resume with: vxil push --server --resume ${done2.apply_id}`);
-    if (done2.status !== "succeeded" && done2.status !== "running") process.exit(1);
-    if (done2.status === "succeeded" && !hasFlag("no-gen")) await runGen(sel);
+    report(done2, true);
     const resumed = { hard: [], strict: [] };
+    armWith(done2, resumed);
+    if (done2.status === "running") say(`resume with: vxil push --server --resume ${done2.apply_id}`);
+    if (done2.status !== "succeeded" && done2.status !== "running") return finish(done2, resumed, 1);
+    if (done2.status === "succeeded") await gen();
     applyHookProblems(done2, resumed);
-    const exitResumed = pushExitCode(resumed, hasFlag("strict"));
+    const exitResumed = pushExitCode(resumed, strict);
     for (const line of exitResumed.lines) console.error(`vxil: ${line}`);
-    if (exitResumed.code !== 0) process.exit(exitResumed.code);
-    return;
+    return finish(done2, resumed, exitResumed.code);
   }
   const loaded = await loadVxilConfig();
   const cwd = process.cwd();
@@ -20589,7 +20787,7 @@ apply ${done2.apply_id}: ${done2.status}`);
   const cfg = hasFlag("skip-functions") ? rest2 : loaded;
   const fnNames = Object.keys(cfg.functions ?? {});
   if (hasFlag("skip-functions") && declaredFns && Object.keys(declaredFns).length) {
-    console.log(`functions: skipped (--skip-functions) \u2014 ${Object.keys(declaredFns).length} declared function(s) not deployed`);
+    say(`functions: skipped (--skip-functions) \u2014 ${Object.keys(declaredFns).length} declared function(s) not deployed`);
   }
   if (fnNames.length) {
     const ent = await probeFunctionsEntitlement(api, fnNames[0]);
@@ -20614,33 +20812,30 @@ apply ${done2.apply_id}: ${done2.status}`);
     bundle,
     allowDestructive: hasFlag("allow-destructive"),
     onPlan: (plan) => {
-      console.log(`plan (apply ${plan.apply_id}):`);
-      console.log(formatApplySteps(plan.steps));
-      for (const w of plan.warnings ?? []) console.log(`  ! ${w}`);
-      console.log("\napplying server-side\u2026");
+      say(`plan (apply ${plan.apply_id}):`);
+      say(formatApplySteps(plan.steps));
+      for (const w of plan.warnings ?? []) say(`  ! ${w}`);
+      say("\napplying server-side\u2026");
     }
   });
-  console.log(formatApplySteps(done.steps));
-  console.log(`
-apply ${done.apply_id}: ${done.status}`);
   if (done.status === "running") {
     const errored = done.steps.filter((st) => st.status === "pending" && st.error);
     const onlyDeferredApiState = errored.length > 0 && errored.every((st) => st.kind === "api-state" && (st.error ?? "").startsWith("deferred:"));
     if (onlyDeferredApiState) {
-      console.log("  \u2026 declared API state deferred (the feature config is still propagating) \u2014 waiting 30 s, then resuming the same apply");
+      report(done, false);
+      say("  \u2026 declared API state deferred (the feature config is still propagating) \u2014 waiting 30 s, then resuming the same apply");
       await new Promise((r) => setTimeout(r, 3e4));
       done = await serverApply({ api, resume: done.apply_id });
-      console.log(formatApplySteps(done.steps));
-      console.log(`
-apply ${done.apply_id}: ${done.status}`);
     }
   }
+  report(done, true);
+  const problems = { hard: [], strict: [] };
+  armWith(done, problems);
   if (done.status === "running") {
-    fail(`a transient step failure interrupted the apply \u2014 resume with: vxil push --server --resume ${done.apply_id}`);
+    return finish(done, problems, 1, `a transient step failure interrupted the apply \u2014 resume with: vxil push --server --resume ${done.apply_id}`);
   }
   const standing = done.steps.filter((st) => st.kind === "api-state" && st.status === "failed");
   const onlyApiStateFailed = done.steps.every((st) => st.status !== "failed" || st.kind === "api-state");
-  const problems = { hard: [], strict: [] };
   if (done.status === "partial" && standing.length && onlyApiStateFailed && done.failed_step?.kind === "api-state" && done.steps.every((st) => st.status !== "rolled_back")) {
     for (const st of standing) {
       console.error(`vxil: warning \u2014 ${st.target} not converged: ${st.error ?? ""} (the config stands; fix the cause and re-push)`);
@@ -20648,7 +20843,7 @@ apply ${done.apply_id}: ${done.status}`);
     }
   } else if (done.status !== "succeeded") {
     const f = done.failed_step;
-    fail(`apply ${done.status}${f ? ` \u2014 step ${f.seq} (${f.kind} ${f.target}): ${f.error}` : ""} (config/functions were rolled back to their pre-apply versions; cms schema additions were kept)`);
+    return finish(done, problems, 1, `apply ${done.status}${f ? ` \u2014 step ${f.seq} (${f.kind} ${f.target}): ${f.error}` : ""} (config/functions were rolled back to their pre-apply versions; cms schema additions were kept)`);
   }
   applyHookProblems(done, problems);
   if (!hasFlag("skip-functions") && (fnNames.length || cfg.features.functions || await backendListsFunctions(api))) {
@@ -20662,24 +20857,26 @@ apply ${done.apply_id}: ${done.status}`);
       for (const name of deployed.filter((n) => !fnNames.includes(n)).sort()) {
         if (hasFlag("allow-destructive")) {
           const del = await deleteRemoteFunction(api, name);
-          console.log(`  - ${name} [deployed, not in vxil.config] \u2014 ${del.gone ? "already gone" : "deleted (--allow-destructive)"}`);
+          say(`  - ${name} [deployed, not in vxil.config] \u2014 ${del.gone ? "already gone" : "deleted (--allow-destructive)"}`);
           if (del.hook && del.hook.failed > 0) problems.hard.push(`trigger wiring: ${del.hook.failed} subscription(s) failed to reconcile after deleting ${name} \u2014 ${hookReconcileRemedy(fnNames[0])}`);
         } else {
-          console.log(`  - ${name} [deployed, not in vxil.config] \u2014 kept; \`vxil push --server --allow-destructive\` deletes it`);
+          say(`  - ${name} [deployed, not in vxil.config] \u2014 kept; \`vxil push --server --allow-destructive\` deletes it`);
           problems.strict.push(`deployed but not declared (kept): ${name}`);
         }
       }
     }
   }
-  if (!hasFlag("no-gen")) await runGen(sel);
-  const exitWith = pushExitCode(problems, hasFlag("strict"));
+  await gen();
+  const exitWith = pushExitCode(problems, strict);
   for (const line of exitWith.lines) console.error(`vxil: ${line}`);
-  if (exitWith.code !== 0) process.exit(exitWith.code);
+  return finish(done, problems, exitWith.code);
+}
+function armServerApplyJsonFail() {
+  if (jsonOut) jsonFailDoc = (error, exitCode) => JSON.stringify(serverApplyErrorJson({ error, exitCode }));
 }
 function applyHookProblems(done, problems) {
   const hook = hookReconcileOf(done);
   if (!hook || hook.failed === 0) return;
-  console.error(`  ! trigger wiring: ${hook.warning ?? `${hook.failed} trigger subscription(s) could not be written`}`);
   problems.hard.push(`trigger wiring: ${hook.failed} subscription(s) failed to reconcile \u2014 a function may be wired to nothing; re-run \`vxil push --server\` (every executed apply re-runs the reconcile)`);
 }
 async function runSeed(sel, opts = {}) {
@@ -21877,6 +22074,7 @@ ${formatSummary(state)}`);
       break;
     }
     case "push": {
+      if (hasFlag("server") || flag("resume") !== void 0) armServerApplyJsonFail();
       if (hasFlag("prod") && (hasFlag("dev") || flag("target") !== void 0)) fail("--prod cannot be combined with --dev / --target \u2014 pick one target");
       const sel = selector();
       const pushTarget = resolveTargetOrFail(sel);
@@ -22374,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.11.1",
+  "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,9 +46,9 @@
   },
   "devDependencies": {
     "miniflare": "^4.20260611.0",
-    "@vxil/config": "0.7.0",
-    "@vxil/feature-configs": "0.7.0",
+    "@vxil/config": "0.8.0",
     "@vxil/runtime": "0.0.1",
+    "@vxil/feature-configs": "0.7.0",
     "@vxil/types": "0.0.1"
   },
   "scripts": {