mapping.test.ts

mapping.test.tspackages/search/src/mapping.test.tsraw ← src5,052 B← Back to the app
1import { describe, expect, it } from "vitest";
2 
3import {
4  contentMapping,
5  DEFAULT_KNN_EF_CONSTRUCTION,
6  DEFAULT_KNN_M,
7  DEFAULT_VECTOR_DIMENSION,
8  TYPE_ENUM,
9  vectorDimensionMatches,
10} from "./mapping.js";
11import { SEARCH_TYPES } from "./types.js";
12 
13function props(m: Record<string, unknown>): Record<string, unknown> {
14  return ((m.mappings as { properties: Record<string, unknown> }).properties) as Record<string, unknown>;
15}
16 
17describe("contentMapping", () => {
18  it("uses the OpenSearch knn_vector + HNSW shape (2.15 — no dense_vector)", () => {
19    const m = contentMapping();
20    const p = props(m);
21    // TASK-0100 S5: the live OpenSearch (2.15) has no `dense_vector` handler
22    // (that is Elasticsearch's name) — the 1.x `knn_vector` + `method` HNSW
23    // form is what this distribution accepts (verified live: PUT 200).
24    //
25    // TASK-0125 (verified live against 2.15): engine = **faiss** — the hybrid
26    // kNN leg pre-filters candidates by the tenant + visibility clause, and
27    // nmslib hard-rejects kNN filters ("Engine [NMSLIB] does not support
28    // filters"); FAISS is the only engine that supports `knn.filter`. And
29    // space_type = **l2** — FAISS on 2.15 rejects `cosinesimil` and
30    // `inner_product`; l2 ranks identically to cosine for the L2-normalized
31    // real embeddings (‖a−b‖² = 2−2·cosθ).
32    expect(p.vector).toEqual(
33      expect.objectContaining({
34        type: "knn_vector",
35        dimension: DEFAULT_VECTOR_DIMENSION,
36        method: expect.objectContaining({
37          name: "hnsw",
38          space_type: "l2",
39          engine: "faiss",
40        }),
41      }),
42    );
43    const method = (p.vector as { method: { parameters: { m: number; ef_construction: number } } }).method;
44    expect(method.parameters.m).toBe(DEFAULT_KNN_M);
45    expect(method.parameters.ef_construction).toBe(DEFAULT_KNN_EF_CONSTRUCTION);
46  });
47 
48  it("matches the camelCase SearchDoc field names (the layout decision)", () => {
49    const p = props(contentMapping());
50    for (const field of [
51      "docId",
52      "type",
53      "id",
54      "workspaceId",
55      "teamId",
56      "title",
57      "body",
58      "chunkId",
59      "chunkIndex",
60      "parentDocId",
61      "vectorModel",
62      "vector",
63      "grants",
64      "archived",
65      "pageId",
66      "blockId",
67      "databaseId",
68      "recordId",
69      "createdBy",
70      "createdByName",
71      "icon",
72      "url",
73      "size",
74      "mimeType",
75      "createdAt",
76      "updatedAt",
77    ]) {
78      expect(p, `missing field ${field}`).toHaveProperty(field);
79    }
80    // the snake_case names the Phase-0 query builders drifted to are NOT here
81    for (const field of ["workspace_id", "team_id", "updated_at", "created_by", "parent_doc_id"]) {
82      expect(p, `stale snake_case field ${field}`).not.toHaveProperty(field);
83    }
84  });
85 
86  it("backs prefix + fuzzy with title.keyword", () => {
87    const p = props(contentMapping());
88    const title = p.title as { fields: { keyword: { type: string } } };
89    expect(title.fields.keyword.type).toBe("keyword");
90  });
91 
92  it("types the 7 public doc types + chunk (TASK-0099)", () => {
93    const p = props(contentMapping());
94    // TASK-0100 S5: OpenSearch 2.15 rejects a mapping-level `enum` param on
95    // keyword mappers (the index could never be created), so `type` is a
96    // plain keyword. The allowed set (TYPE_ENUM) is still the source of truth
97    // for the application layer — it includes "chunk" but the public
98    // SEARCH_TYPES never request it.
99    expect(p.type).toEqual({ type: "keyword" });
100    // "chunk" is an accepted doc type (the index must accept chunk docs) but
101    // NOT in the public SEARCH_TYPES (keyword search can never request them).
102    expect(TYPE_ENUM).toContain("chunk");
103    expect(SEARCH_TYPES).not.toContain("chunk" as never);
104    // chunkId is a plain keyword (the chunk's own stable id).
105    expect(p.chunkId).toEqual({ type: "keyword" });
106  });
107 
108  it("keeps the 1 s refresh interval (the lag SLA)", () => {
109    const m = contentMapping();
110    const settings = (m.settings as { index: { refresh_interval: string; knn: boolean } }).index;
111    expect(settings.refresh_interval).toBe("1s");
112    expect(settings.knn).toBe(true);
113  });
114 
115  it("honours the vector tuning options", () => {
116    const p = props(contentMapping({ dimension: 768, m: 32, efConstruction: 128 }));
117    expect((p.vector as { dimension: number }).dimension).toBe(768);
118    const method = (p.vector as { method: { parameters: { m: number; ef_construction: number } } }).method;
119    expect(method.parameters.m).toBe(32);
120    expect(method.parameters.ef_construction).toBe(128);
121  });
122});
123 
124describe("vectorDimensionMatches", () => {
125  it("guards the alias-rollover (dims are immutable)", () => {
126    expect(vectorDimensionMatches({ mappings: { properties: { vector: { dimension: 1536 } } } }, 1536)).toBe(true);
127    expect(vectorDimensionMatches({ mappings: { properties: { vector: { dimension: 1024 } } } }, 1536)).toBe(false);
128    expect(vectorDimensionMatches({}, 1536)).toBe(false);
129  });
130});
131