@vxil/sdk 0.11.1 → 0.13.0

package/dist/index.d.ts

@@ -741,7 +741,14 @@ export interface SearchHit {
     chunk_id: string;
     doc_id: string;
     text: string;
+    /** the fused RANK value (reciprocal-rank fusion: ≈ 1/61 for the first hit at
+     *  the default rrf_k) — it orders the hits; it is NOT a similarity, so never
+     *  threshold on it. */
     score: number;
+    /** cosine similarity of the hit to the query (−1…1, higher = closer) — the
+     *  value to threshold on. null when the query used no vector (mode
+     *  'keyword', or a bring-your-own-vectors collection queried by text only). */
+    similarity: number | null;
     /** provider relevance score — present only when the hit went through the
      *  configured BYO reranker (`reranked: true` on the result set). */
     rerank_score?: number;
@@ -1499,6 +1506,9 @@ export interface RagSearchHit {
     text: string;
     /** the raw retrieval score (RRF, or rerank relevance when reranked). */
     score: number;
+    /** cosine similarity of the hit to the query, passed through from
+     *  vector-search (−1…1; null when retrieval used no query vector). */
+    similarity?: number | null;
     /** the effective post-boost score results are RANKED by — present only when
      *  metadata boosts applied (rag.md §2f). */
     boosted_score?: number;
@@ -1989,6 +1999,12 @@ export interface CmsReindexPage {
     skipped: number;
     next_cursor: string | null;
     complete: boolean;
+    /** Present when this page certified an index (the last page of a pass over
+     *  a collection whose equality / owner index was not armed): 'armed',
+     *  'pending' (rows changed during the pass — run another) or 'timeout' (the
+     *  check ran out of time — the index stays unarmed; filters stay correct
+     *  but unaccelerated). */
+    index_certify?: 'armed' | 'pending' | 'timeout';
 }
 /** The result of a bounded filtered delete (cms.md §20). `matched` counts the
  *  rows this page selected (≤ `limit`); `deleted` counts the ones actually
@@ -3559,6 +3575,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                      *  session) still sees every field. Writes are unaffected. ≤16 entries,
                      *  each `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
                     read_roles?: 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. ≤4
+                     *  per collection; not with `index_slot` (a slot already indexes
+                     *  equality) and not on a computed field. */
+                    indexed?: boolean;
                 }>;
                 /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]` —
                  *  exactly ONE human-initiated step each; `fn` names a deployed tenant
@@ -3586,6 +3608,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  read unless the session's verified roles intersect `roles`; server-caller
              *  reads and ALL writes are unaffected. */
             setFieldReadRoles: (collection: string, field: string, type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file", roles: string[] | null, rest?: Record<string, unknown>) => Promise<void>;
+            /** Turn a field's EQUALITY INDEX on or off (cms.md §3 "Indexed equality")
+             *  — the same-type in-place alter on the fields route; `indexed` is
+             *  present-key, so no other attribute moves. Only for UNSLOTTED,
+             *  non-computed fields, ≤4 per collection (422 `eq_index_budget`).
+             *  `index_ready: false` + `reindex_required: true` on a collection over
+             *  2,000 live items: run `reindexAll` (until then filters stay on the
+             *  bounded scan — never wrong, only slower). */
+            setFieldIndexed: (collection: string, field: string, type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file", indexed: boolean) => Promise<{
+                indexed: boolean;
+                index_ready: boolean;
+                reindex_required: boolean;
+            }>;
             /** Set (or clear, with `null`) the collection's end-user owner-scope flag
              *  (design §5.1). Names an existing `string` field that holds the owner id. */
             setOwnerField: (collection: string, ownerField: string | null) => Promise<void>;
@@ -3623,6 +3657,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 updated: number;
                 skipped: number;
                 pages: number;
+                index_certify?: CmsReindexPage["index_certify"];
             }>;
             /** Replace the collection's per-record ACTION list (cms.md §17) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE
@@ -4031,11 +4066,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             hook_reconcile?: {
                 created: number;
                 updated: number;
+                unchanged?: number;
                 deleted: number;
                 failed: number;
             };
             cron_schedules?: {
                 created: number;
+                unchanged?: number;
                 deleted: number;
                 failed: number;
             };
@@ -5149,7 +5186,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }) => Promise<RagStreamHandle>;
         /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
          *  would ground on, with rerank + metadata boosts applied — no generation,
-         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config. */
+         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config.
+         *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
+         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
+         *  relevance by each hit's `similarity` (cosine, -1..1) instead. */
         search: (input: {
             query: string;
             collection?: string;

package/dist/index.js

@@ -1088,6 +1088,29 @@ export class Vxil {
             setFieldReadRoles: async (collection, field, type, roles, rest = {}) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { ...rest, field, type, read_roles: roles ?? [] });
             },
+            /** Turn a field's EQUALITY INDEX on or off (cms.md §3 "Indexed equality")
+             *  — the same-type in-place alter on the fields route; `indexed` is
+             *  present-key, so no other attribute moves. Only for UNSLOTTED,
+             *  non-computed fields, ≤4 per collection (422 `eq_index_budget`).
+             *  `index_ready: false` + `reindex_required: true` on a collection over
+             *  2,000 live items: run `reindexAll` (until then filters stay on the
+             *  bounded scan — never wrong, only slower). */
+            setFieldIndexed: async (collection, field, type, indexed) => {
+                try {
+                    const d = (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { field, type, indexed })).data ?? {};
+                    return { indexed: d.indexed ?? indexed, index_ready: d.index_ready ?? indexed, reindex_required: d.reindex_required === true };
+                }
+                catch (e) {
+                    // 409 already_exists = the field is already in that state (the
+                    // idempotent re-POST); read its readiness from the collection list.
+                    if (!(e instanceof VxilError) || e.status !== 409)
+                        throw e;
+                    const colls = (await this.call('GET', '/v1/cms/collections')).data.collections;
+                    const f = colls.find((c) => c.collection === collection)?.fields.find((x) => x.field === field);
+                    const ready = f?.index_ready === true;
+                    return { indexed: f?.indexed === true, index_ready: ready, reindex_required: f?.indexed === true && !ready };
+                }
+            },
             /** Set (or clear, with `null`) the collection's end-user owner-scope flag
              *  (design §5.1). Names an existing `string` field that holds the owner id. */
             setOwnerField: async (collection, ownerField) => {
@@ -1126,6 +1149,7 @@ export class Vxil {
                 let updated = 0;
                 let skipped = 0;
                 let pages = 0;
+                let indexCertify;
                 for (;;) {
                     let page = await this.cms.collections.reindex(collection, {
                         ...(opts?.field ? { field: opts.field } : {}),
@@ -1148,11 +1172,13 @@ export class Vxil {
                         opts?.onPage?.(page);
                     }
                     skipped += page.skipped ?? 0;
+                    if (page.index_certify)
+                        indexCertify = page.index_certify;
                     if (page.complete || !page.next_cursor)
                         break;
                     cursor = page.next_cursor;
                 }
-                return { scanned, updated, skipped, pages };
+                return { scanned, updated, skipped, pages, ...(indexCertify ? { index_certify: indexCertify } : {}) };
             },
             /** Replace the collection's per-record ACTION list (cms.md §17) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE
@@ -1905,7 +1931,10 @@ export class Vxil {
         stream: async (input) => (await this.call('POST', '/v1/rag/answer', { ...input, stream: true })).data,
         /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
          *  would ground on, with rerank + metadata boosts applied — no generation,
-         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config. */
+         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config.
+         *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
+         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
+         *  relevance by each hit's `similarity` (cosine, -1..1) instead. */
         search: async (input) => (await this.call('POST', '/v1/rag/search', input)).data,
         /** Ingest into the backing vector-search collection (chunk → embed → index). */
         ingest: async (collection, input) => (await this.call('POST', `/v1/rag/ingest/${encodeURIComponent(collection)}`, input)).data,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",