@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/schema-cli.ts

@@ -14,6 +14,7 @@ import {
   baselineMigrations,
   createDbConnection,
   type DbConnection,
+  diffReplayAgainstSnapshot,
   fetchAppliedMigrations,
   generateMigration,
   loadMigrationsFromDir,
@@ -21,6 +22,7 @@ import {
   readRebuildMarker,
   rebuildTablesFromDiff,
   type renderTablesDdl,
+  replayMigrationsDir,
   runMigrationsFromDir,
   tableExists,
   writeRebuildMarker,
@@ -36,6 +38,7 @@ import {
   createProjectionStateTable,
   rebuildProjection,
 } from "./pipeline";
+import { ensureTemporalPolyfill } from "./time";
 
 export type SchemaCliOut = {
   readonly log: (line: string) => void;
@@ -44,17 +47,28 @@ export type SchemaCliOut = {
 
 const SNAPSHOT_FILENAME = ".snapshot.json";
 
-async function loadEntityMetasFromApp(
-  schemaFile: string,
-): Promise<Parameters<typeof renderTablesDdl>[0]> {
+type SchemaMod = {
+  readonly entityMetas: Parameters<typeof renderTablesDdl>[0];
+  readonly features?: unknown;
+};
+
+// Single load-path for kumiko/schema.ts (512/3) — `generate` and `validate`
+// both need ENTITY_METAS (and validate additionally wants FEATURES); this is
+// the one place that enforces "ENTITY_METAS must be an array" so the two
+// commands can't drift on the check or its wording. Throws — callers that
+// want a graceful exit code (validate) catch it themselves.
+async function loadSchemaModFromApp(schemaFile: string): Promise<SchemaMod> {
   // bun imports TS directly — no spawn needed.
-  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown };
+  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown; FEATURES?: unknown };
   if (!Array.isArray(mod.ENTITY_METAS)) {
     throw new Error(
       `Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
     );
   }
-  return mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+  return {
+    entityMetas: mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0],
+    features: mod.FEATURES,
+  };
 }
 
 function nextSequenceNumber(migrationsDir: string): number {
@@ -115,6 +129,13 @@ export async function runSchemaCli(
   out: SchemaCliOut,
   options: RunSchemaCliOptions = {},
 ): Promise<number> {
+  // runProdApp/runDevApp install this at boot; the standalone CLI (the
+  // migrate-db initContainer, `bun kumiko.js schema apply`) never goes through
+  // that boot path, so a projection rebuild's tz/timestamp coercion throws
+  // "Temporal is not defined" — deterministically, on every rebuild-marker
+  // migration, since the crashed process still records the migration as
+  // applied and the rebuild is never retried.
+  await ensureTemporalPolyfill();
   const sub = argv[0];
   const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
   const migrationsDir = resolvePath(appCwd, "kumiko/migrations");
@@ -132,7 +153,7 @@ export async function runSchemaCli(
         out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
         return 1;
       }
-      const metas = await loadEntityMetasFromApp(schemaFile);
+      const { entityMetas: metas } = await loadSchemaModFromApp(schemaFile);
       const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
       const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
       const result = generateMigration({
@@ -179,11 +200,18 @@ export async function runSchemaCli(
 
     case "validate": {
       // Static, DB-free boot-blocking checks for CI — catches "this won't boot"
-      // before deploy. Two layers, no database:
+      // before deploy. Three layers, no database:
       //   1. schema drift: would `generate` write a migration? (= an entity was
       //      added/changed but never generated → missing table → prod 500)
       //   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
       //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES.
+      //   3. migration-content drift: replay every committed *.sql file and
+      //      diff the result against .snapshot.json — catches a migration
+      //      file whose SQL body doesn't match what its own snapshot entry
+      //      claims (e.g. an accidental copy-paste from an earlier file).
+      //      Layer 1 alone misses this: it only compares ENTITY_METAS to the
+      //      snapshot, never the snapshot to the SQL that's supposed to have
+      //      produced it.
       // The DB-level gate (assertKumikoSchemaCurrent) stays at boot/deploy.
       if (!existsSync(schemaFile)) {
         out.err(`  ${schemaFile} fehlt.`);
@@ -191,20 +219,18 @@ export async function runSchemaCli(
         out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
         return 1;
       }
-      const mod = (await import(schemaFile)) as {
-        ENTITY_METAS?: unknown;
-        FEATURES?: unknown;
-      };
-      if (!Array.isArray(mod.ENTITY_METAS)) {
-        out.err(
-          `  Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
-        );
+      let schemaMod: SchemaMod;
+      try {
+        schemaMod = await loadSchemaModFromApp(schemaFile);
+      } catch (e) {
+        out.err(`  ${e instanceof Error ? e.message : String(e)}`);
         return 1;
       }
+      const mod = { FEATURES: schemaMod.features };
       let ok = true;
 
       // 1. Schema drift — compute the diff, never write.
-      const metas = mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+      const metas = schemaMod.entityMetas;
       const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
       const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
       const drift = generateMigration({
@@ -245,6 +271,40 @@ export async function runSchemaCli(
         );
       }
 
+      // 3. Migration-content drift — replay the committed *.sql files and
+      // diff the reconstructed schema against .snapshot.json.
+      const committedSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
+      if (existsSync(migrationsDir) && committedSnapshot !== null) {
+        try {
+          const replayed = replayMigrationsDir(migrationsDir);
+          const mismatches = diffReplayAgainstSnapshot(replayed, committedSnapshot);
+          if (mismatches.length === 0) {
+            out.log("  ✓ migrations: table/column names match .snapshot.json");
+          } else {
+            ok = false;
+            out.err(
+              "  ✗ migration-content drift: committed *.sql files don't produce .snapshot.json.",
+            );
+            for (const m of mismatches) {
+              out.err(`    ${m.tableName} (${m.kind}): ${m.detail}`);
+            }
+            out.err(
+              "    Fix: a migration file's body doesn't match what it (or the snapshot) claims — hand-fix the file, or ship a corrective migration if it's already applied in prod.",
+            );
+          }
+        } catch (e) {
+          // replayMigrationsDir fail-loud's on a table-DDL statement it can't
+          // parse — that must surface as a normal ✗ line like every other
+          // check here, not a raw stack trace that kills the process before
+          // any later check (or the Fix: help) ever runs (framework#1535).
+          ok = false;
+          out.err(`  ✗ migration-content: ${e instanceof Error ? e.message : String(e)}`);
+          out.err(
+            "    Fix: a statement in a migration file isn't recognizable to the replay parser — extend the parser's recognized patterns, or reword the migration to one it understands.",
+          );
+        }
+      }
+
       return ok ? 0 : 1;
     }
 

package/src/search/__tests__/meilisearch-adapter.integration.test.ts

@@ -1,13 +1,37 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { generateId as uuid } from "@cosmicdrift/kumiko-framework/utils";
 import { Meilisearch } from "meilisearch";
-import { createMeilisearchAdapter } from "../meilisearch-adapter";
+import { createMeilisearchAdapter, meilisearchTenantIndex } from "../meilisearch-adapter";
 import type { SearchAdapter } from "../types";
 
 const MEILI_URL = process.env["MEILI_URL"] ?? "http://localhost:17700";
 const MEILI_KEY = process.env["MEILI_MASTER_KEY"] ?? "kumiko-dev-key";
 
+async function meiliAvailable(): Promise<boolean> {
+  try {
+    const health = await fetch(`${MEILI_URL}/health`, { signal: AbortSignal.timeout(2000) });
+    return health.ok;
+  } catch {
+    return false;
+  }
+}
+
+// skipIf when compose Meili is down — unit tests still cover index/doc id shaping.
+// In a dedicated integration job (REQUIRE_MEILI=1) a down Meili is a hard
+// failure, not a silent skip — the compose service is expected to be up there.
+const MEILI_UP = await meiliAvailable();
+if (!MEILI_UP) {
+  if (process.env["REQUIRE_MEILI"] === "1") {
+    throw new Error(
+      `REQUIRE_MEILI=1 but Meilisearch not reachable at ${MEILI_URL} — integration job misconfigured`,
+    );
+  }
+  console.warn(
+    `Meilisearch not reachable at ${MEILI_URL} — skipping live adapter tests ` +
+      `(docker compose up -d meilisearch, default port 17700)`,
+  );
+}
+
 // Use a fake tenantId to get a unique index name
 const TENANT = uuid();
 
@@ -15,222 +39,220 @@ let adapter: SearchAdapter;
 let client: Meilisearch;
 let indexPrefix: string;
 
-// Mirrors meilisearch-adapter.ts's tenantIndex() — used by tests that need
-// to talk to Meilisearch directly (e.g. stats before/after a no-op).
-const tenantIndex = (prefix: string, tenantId: TenantId): string => `${prefix}t${tenantId}`;
-
-beforeAll(async () => {
-  client = new Meilisearch({ host: MEILI_URL, apiKey: MEILI_KEY });
-  indexPrefix = `test_${uuid().slice(-6)}_`;
-  adapter = createMeilisearchAdapter({
-    url: MEILI_URL,
-    apiKey: MEILI_KEY,
-    indexPrefix,
-  });
+describe.skipIf(!MEILI_UP)("meilisearch adapter (live)", () => {
+  beforeAll(async () => {
+    client = new Meilisearch({ host: MEILI_URL, apiKey: MEILI_KEY });
+    indexPrefix = `test_${uuid().slice(-6)}_`;
+    adapter = createMeilisearchAdapter({
+      url: MEILI_URL,
+      apiKey: MEILI_KEY,
+      indexPrefix,
+    });
 
-  await adapter.configure(TENANT, {
-    searchableFields: ["email", "firstName", "lastName", "notes", "_roles"],
-    rankingFields: ["email", "firstName", "lastName", "notes", "_roles"],
-  });
+    await adapter.configure(TENANT, {
+      searchableFields: ["email", "firstName", "lastName", "notes", "_roles"],
+      rankingFields: ["email", "firstName", "lastName", "notes", "_roles"],
+    });
 
-  // Seed data with different entity types and weights
-  await adapter.index(TENANT, {
-    entityType: "user",
-    entityId: 1,
-    weight: 10,
-    fields: {
-      email: "marc.weber@company.de",
-      firstName: "Marc",
-      lastName: "Weber",
-      notes: "Senior developer",
-      _roles: "Admin, Developer",
-    },
-  });
-  await adapter.index(TENANT, {
-    entityType: "user",
-    entityId: 2,
-    weight: 10,
-    fields: {
-      email: "anna.schmidt@company.de",
-      firstName: "Anna",
-      lastName: "Schmidt",
-      notes: "Project manager",
-    },
-  });
-  await adapter.index(TENANT, {
-    entityType: "user",
-    entityId: 3,
-    weight: 10,
-    fields: {
-      email: "admin@company.de",
-      firstName: "Admin",
-      lastName: "User",
-      notes: "System administrator",
-    },
-  });
-  await adapter.index(TENANT, {
-    entityType: "role",
-    entityId: 1,
-    weight: 1,
-    fields: { firstName: "Admin" },
-  });
-  await adapter.index(TENANT, {
-    entityType: "role",
-    entityId: 2,
-    weight: 1,
-    fields: { firstName: "Developer" },
-  });
-  await adapter.index(TENANT, {
-    entityType: "department",
-    entityId: 1,
-    weight: 5,
-    fields: { firstName: "Engineering" },
+    // Seed data with different entity types and weights
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 1,
+      weight: 10,
+      fields: {
+        email: "marc.weber@company.de",
+        firstName: "Marc",
+        lastName: "Weber",
+        notes: "Senior developer",
+        _roles: "Admin, Developer",
+      },
+    });
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 2,
+      weight: 10,
+      fields: {
+        email: "anna.schmidt@company.de",
+        firstName: "Anna",
+        lastName: "Schmidt",
+        notes: "Project manager",
+      },
+    });
+    await adapter.index(TENANT, {
+      entityType: "user",
+      entityId: 3,
+      weight: 10,
+      fields: {
+        email: "admin@company.de",
+        firstName: "Admin",
+        lastName: "User",
+        notes: "System administrator",
+      },
+    });
+    await adapter.index(TENANT, {
+      entityType: "role",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Admin" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "role",
+      entityId: 2,
+      weight: 1,
+      fields: { firstName: "Developer" },
+    });
+    await adapter.index(TENANT, {
+      entityType: "department",
+      entityId: 1,
+      weight: 5,
+      fields: { firstName: "Engineering" },
+    });
   });
-});
 
-afterAll(async () => {
-  // Clean up all test indices
-  const indices = await client.getIndexes();
-  for (const idx of indices.results) {
-    if (idx.uid.startsWith("test_")) {
-      try {
-        await client.index(idx.uid).delete().waitTask();
-      } catch {
-        /* ok */
+  afterAll(async () => {
+    // Clean up all test indices
+    const indices = await client.getIndexes();
+    for (const idx of indices.results) {
+      if (idx.uid.startsWith("test_")) {
+        try {
+          await client.index(idx.uid).delete().waitTask();
+        } catch {
+          /* ok */
+        }
       }
     }
-  }
-});
+  });
 
-// --- Basic search ---
+  // --- Basic search ---
 
-describe("basic search", () => {
-  test("finds user by name", async () => {
-    const results = await adapter.search(TENANT, "anna");
-    expect(results.some((r) => r.entityId === 2 && r.entityType === "user")).toBe(true);
-  });
+  describe("basic search", () => {
+    test("finds user by name", async () => {
+      const results = await adapter.search(TENANT, "anna");
+      expect(results.some((r) => r.entityId === 2 && r.entityType === "user")).toBe(true);
+    });
 
-  test("returns empty for no match", async () => {
-    const results = await adapter.search(TENANT, "zzzznonexistent99999");
-    expect(results).toEqual([]);
+    test("returns empty for no match", async () => {
+      const results = await adapter.search(TENANT, "zzzznonexistent99999");
+      expect(results).toEqual([]);
+    });
   });
-});
 
-// --- Partial matching ---
+  // --- Partial matching ---
 
-describe("partial matching", () => {
-  test("finds by prefix", async () => {
-    const results = await adapter.search(TENANT, "mar");
-    expect(results.some((r) => r.entityId === 1 && r.entityType === "user")).toBe(true);
+  describe("partial matching", () => {
+    test("finds by prefix", async () => {
+      const results = await adapter.search(TENANT, "mar");
+      expect(results.some((r) => r.entityId === 1 && r.entityType === "user")).toBe(true);
+    });
   });
-});
 
-// --- Typo tolerance ---
+  // --- Typo tolerance ---
 
-describe("typo tolerance", () => {
-  test("finds despite typos", async () => {
-    const results = await adapter.search(TENANT, "schmit");
-    expect(results.some((r) => r.entityId === 2)).toBe(true);
+  describe("typo tolerance", () => {
+    test("finds despite typos", async () => {
+      const results = await adapter.search(TENANT, "schmit");
+      expect(results.some((r) => r.entityId === 2)).toBe(true);
+    });
   });
-});
 
-// --- Filter by entity type (list search) ---
+  // --- Filter by entity type (list search) ---
 
-describe("list search (filterType)", () => {
-  test("only returns specified entity type", async () => {
-    const results = await adapter.search(TENANT, "admin", { filterType: "user" });
-    expect(results.every((r) => r.entityType === "user")).toBe(true);
-    expect(results.length).toBeGreaterThan(0);
-  });
+  describe("list search (filterType)", () => {
+    test("only returns specified entity type", async () => {
+      const results = await adapter.search(TENANT, "admin", { filterType: "user" });
+      expect(results.every((r) => r.entityType === "user")).toBe(true);
+      expect(results.length).toBeGreaterThan(0);
+    });
 
-  test("role filter returns only roles", async () => {
-    const results = await adapter.search(TENANT, "admin", { filterType: "role" });
-    expect(results.every((r) => r.entityType === "role")).toBe(true);
+    test("role filter returns only roles", async () => {
+      const results = await adapter.search(TENANT, "admin", { filterType: "role" });
+      expect(results.every((r) => r.entityType === "role")).toBe(true);
+    });
   });
-});
 
-// --- Global search with weight ---
+  // --- Global search with weight ---
 
-describe("global search with searchWeight", () => {
-  test("user (weight 10) ranks before role (weight 1) for same query", async () => {
-    const results = await adapter.search(TENANT, "admin");
-    const userIdx = results.findIndex((r) => r.entityType === "user");
-    const roleIdx = results.findIndex((r) => r.entityType === "role");
-    // User should appear before Role due to _weight:desc sort
-    if (userIdx >= 0 && roleIdx >= 0) {
-      expect(userIdx).toBeLessThan(roleIdx);
-    }
+  describe("global search with searchWeight", () => {
+    test("user (weight 10) ranks before role (weight 1) for same query", async () => {
+      const results = await adapter.search(TENANT, "admin");
+      const userIdx = results.findIndex((r) => r.entityType === "user");
+      const roleIdx = results.findIndex((r) => r.entityType === "role");
+      // User should appear before Role due to _weight:desc sort
+      if (userIdx >= 0 && roleIdx >= 0) {
+        expect(userIdx).toBeLessThan(roleIdx);
+      }
+    });
   });
-});
 
-// --- Resolved relation data ---
+  // --- Resolved relation data ---
 
-describe("relation data in search", () => {
-  test("finds user by role name in _roles field", async () => {
-    const results = await adapter.search(TENANT, "developer", { filterType: "user" });
-    expect(results.some((r) => r.entityId === 1)).toBe(true);
+  describe("relation data in search", () => {
+    test("finds user by role name in _roles field", async () => {
+      const results = await adapter.search(TENANT, "developer", { filterType: "user" });
+      expect(results.some((r) => r.entityId === 1)).toBe(true);
+    });
   });
-});
 
-// --- Remove ---
+  // --- Remove ---
 
-describe("remove", () => {
-  test("removed document not found", async () => {
-    // Create temp doc
-    await adapter.index(TENANT, {
-      entityType: "temp",
-      entityId: 999,
-      weight: 1,
-      fields: { firstName: "DeleteMe" },
-    });
-    let results = await adapter.search(TENANT, "deleteme");
-    expect(results.some((r) => r.entityId === 999)).toBe(true);
+  describe("remove", () => {
+    test("removed document not found", async () => {
+      // Create temp doc
+      await adapter.index(TENANT, {
+        entityType: "temp",
+        entityId: 999,
+        weight: 1,
+        fields: { firstName: "DeleteMe" },
+      });
+      let results = await adapter.search(TENANT, "deleteme");
+      expect(results.some((r) => r.entityId === 999)).toBe(true);
 
-    await adapter.remove(TENANT, "temp", 999);
-    results = await adapter.search(TENANT, "deleteme");
-    expect(results.some((r) => r.entityId === 999)).toBe(false);
+      await adapter.remove(TENANT, "temp", 999);
+      results = await adapter.search(TENANT, "deleteme");
+      expect(results.some((r) => r.entityId === 999)).toBe(false);
+    });
   });
-});
 
-// --- Batch variants ---
+  // --- Batch variants ---
 
-describe("indexBatch / removeBatch", () => {
-  test("indexBatch indexes multiple docs in a single task", async () => {
-    const docs = Array.from({ length: 5 }, (_, i) => ({
-      entityType: "batch" as const,
-      entityId: 1000 + i,
-      weight: 1,
-      fields: { firstName: `Bulk${i}`, notes: "batchtoken" },
-    }));
-    await adapter.indexBatch?.(TENANT, docs);
-
-    const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
-    expect(hits.length).toBe(5);
-    const ids = hits.map((h) => h.entityId).sort();
-    expect(ids).toEqual([1000, 1001, 1002, 1003, 1004]);
-  });
+  describe("indexBatch / removeBatch", () => {
+    test("indexBatch indexes multiple docs in a single task", async () => {
+      const docs = Array.from({ length: 5 }, (_, i) => ({
+        entityType: "batch" as const,
+        entityId: 1000 + i,
+        weight: 1,
+        fields: { firstName: `Bulk${i}`, notes: "batchtoken" },
+      }));
+      await adapter.indexBatch?.(TENANT, docs);
 
-  test("removeBatch removes multiple docs in a single task", async () => {
-    await adapter.removeBatch?.(
-      TENANT,
-      [1000, 1001, 1002, 1003, 1004].map((id) => ({ entityType: "batch", entityId: id })),
-    );
-    const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
-    expect(hits.length).toBe(0);
-  });
+      const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
+      expect(hits.length).toBe(5);
+      const ids = hits.map((h) => h.entityId).sort();
+      expect(ids).toEqual([1000, 1001, 1002, 1003, 1004]);
+    });
 
-  test("indexBatch no-ops on empty array — no Meilisearch task created", async () => {
-    // We verify the "no-op" contract by peeking at Meilisearch's own
-    // IndexStats.numberOfDocuments + isIndexing directly. If the adapter had
-    // accidentally sent an addDocuments request (even with an empty body),
-    // isIndexing would flip to true or a task would land in the queue.
-    // numberOfDocuments must also stay unchanged — the empty batch must not
-    // replace, delete, or otherwise touch existing docs.
-    const index = client.index(tenantIndex(indexPrefix, TENANT));
-    const before = await index.getStats();
-    await expect(adapter.indexBatch?.(TENANT, [])).resolves.toBeUndefined();
-    const after = await index.getStats();
-    expect(after.numberOfDocuments).toBe(before.numberOfDocuments);
-    expect(after.isIndexing).toBe(false);
+    test("removeBatch removes multiple docs in a single task", async () => {
+      await adapter.removeBatch?.(
+        TENANT,
+        [1000, 1001, 1002, 1003, 1004].map((id) => ({ entityType: "batch", entityId: id })),
+      );
+      const hits = await adapter.search(TENANT, "batchtoken", { limit: 20, filterType: "batch" });
+      expect(hits.length).toBe(0);
+    });
+
+    test("indexBatch no-ops on empty array — no Meilisearch task created", async () => {
+      // We verify the "no-op" contract by peeking at Meilisearch's own
+      // IndexStats.numberOfDocuments + isIndexing directly. If the adapter had
+      // accidentally sent an addDocuments request (even with an empty body),
+      // isIndexing would flip to true or a task would land in the queue.
+      // numberOfDocuments must also stay unchanged — the empty batch must not
+      // replace, delete, or otherwise touch existing docs.
+      const index = client.index(meilisearchTenantIndex(indexPrefix, TENANT));
+      const before = await index.getStats();
+      await expect(adapter.indexBatch?.(TENANT, [])).resolves.toBeUndefined();
+      const after = await index.getStats();
+      expect(after.numberOfDocuments).toBe(before.numberOfDocuments);
+      expect(after.isIndexing).toBe(false);
+    });
   });
 });

package/src/search/__tests__/meilisearch-ids.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { meilisearchDocId, meilisearchTenantIndex } from "../meilisearch-adapter";
+
+describe("meilisearchTenantIndex", () => {
+  test("prefixes tenant id with t after the index prefix", () => {
+    expect(meilisearchTenantIndex("kumiko_", "00000000-0000-4000-8000-000000000001")).toBe(
+      "kumiko_t00000000-0000-4000-8000-000000000001",
+    );
+  });
+
+  test("keeps custom prefixes intact", () => {
+    expect(meilisearchTenantIndex("test_abc_", 42 as never)).toBe("test_abc_t42");
+  });
+});
+
+describe("meilisearchDocId", () => {
+  test("joins entity type and id with underscore", () => {
+    expect(meilisearchDocId("user", 7)).toBe("user_7");
+  });
+
+  test("preserves UUID dashes (legal Meilisearch primary-key chars)", () => {
+    expect(meilisearchDocId("order", "a1b2c3d4-e5f6-7890-abcd-ef1234567890" as never)).toBe(
+      "order_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    );
+  });
+
+  test("sanitizes illegal primary-key characters to underscore", () => {
+    expect(meilisearchDocId("note", "a:b/c.d" as never)).toBe("note_a_b_c_d");
+  });
+});