@cosmicdrift/kumiko-framework 0.306.0 → 0.308.0

package/src/pipeline/system-hooks.ts

@@ -1,4 +1,4 @@
-import type { SseBroker } from "../api/sse-broker";
+import type { AccessInvalidationScope, SseBroker } from "../api/sse-broker";
 import {
   collectSearchableSubjectFields,
   configuredPiiSubjectKms,
@@ -18,6 +18,7 @@ import type {
   SessionUser,
   TenantId,
 } from "../engine/types";
+import type { StoredEvent } from "../event-store";
 import type { SearchAdapter, SearchDocument } from "../search/types";
 import type { EventConsumer } from "./event-dispatcher";
 
@@ -50,11 +51,171 @@ import type { EventConsumer } from "./event-dispatcher";
 // instead, so the same sensitive+searchable boot-guard (entity-handler.ts)
 // keeps them out there too.
 //
-// No batch variant right now — every event triggers its own index() call.
-// If a scale measurement later calls for it, the event-dispatcher could
-// grow a batch-handler variant.
+// batchHandler collapses a turn's events to one search-op per
+// (tenantId, entityType, entityId) and issues one indexBatch/removeBatch
+// call per tenant instead of one round-trip per event; handler stays the
+// per-event fallback the dispatcher falls back to when a batch throws.
 export const SEARCH_CONSUMER_NAME = "system:consumer:search";
 
+// #3227 — one resolved search operation for a single event: either the
+// document to (re-)index or the entityType/entityId to remove. A
+// discriminated union so the batch collapse step (last op per key wins)
+// doesn't need to special-case index vs remove.
+export type SearchOperation =
+  | { readonly kind: "index"; readonly tenantId: TenantId; readonly doc: SearchDocument }
+  | {
+      readonly kind: "remove";
+      readonly tenantId: TenantId;
+      readonly entityType: string;
+      readonly entityId: EntityId;
+    };
+
+// Resolves what one event implies for the search index, without touching
+// the adapter — same decision tree the old per-event handler ran inline.
+async function resolveSearchOperation(
+  event: StoredEvent,
+  ctx: AppContext,
+  registry: Registry,
+): Promise<SearchOperation | undefined> {
+  const entityName = event.aggregateType;
+  const verb = event.type.split(".").pop();
+  const tenantId = event.tenantId;
+
+  // skip: delete/forgotten remove the index entry — reconstruct only
+  // makes sense for created/updated/restored (field data in payload).
+  if (verb === "deleted" || verb === "forgotten") {
+    return { kind: "remove", tenantId, entityType: entityName, entityId: event.aggregateId };
+  }
+
+  let state: Record<string, unknown>;
+  if (verb === "created" || verb === "updated" || verb === "restored") {
+    state = reconstructStateForSearch(event.payload, verb);
+  } else {
+    // #2765 — named domain event: no fixed payload shape to reconstruct
+    // state from. Only worth a projection read when the entity actually
+    // declared searchable fields/extensions — same check
+    // buildSearchDocument makes below, done here first so a non-
+    // searchable entity's named events stay a no-op like before.
+    const entity = registry.getEntity(entityName);
+    const isSearchable =
+      entity !== undefined &&
+      (registry.getSearchableFields(entityName).length > 0 ||
+        registry.getSearchPayloadExtensions(entityName).length > 0);
+    // skip: entity declares no searchable fields/extensions — nothing to
+    // index, stays a no-op with no extra query, same as before #2765.
+    if (!entity || !isSearchable) return undefined;
+
+    const row = await readProjectionRowForSearch(
+      ctx,
+      registry,
+      entityName,
+      entity,
+      tenantId,
+      event.aggregateId,
+    );
+    // skip: no live row (hard-deleted stream, or soft-deleted) — same
+    // outcome as the deleted/forgotten branch above.
+    if (!row) {
+      return { kind: "remove", tenantId, entityType: entityName, entityId: event.aggregateId };
+    }
+    state = row;
+  }
+
+  state = await decryptSearchableSubjectFields(entityName, state, registry);
+  // skip: erased subject — drop the doc so a rebuild cannot resurrect plaintext.
+  if (hasErasedSearchableSubjectField(entityName, state, registry)) {
+    return { kind: "remove", tenantId, entityType: entityName, entityId: event.aggregateId };
+  }
+  const doc = await buildSearchDocument(entityName, event.aggregateId, state, registry);
+  // skip: entity isn't searchable (no searchable fields declared)
+  if (!doc) return undefined;
+  return { kind: "index", tenantId, doc };
+}
+
+async function applySearchOperation(
+  searchAdapter: SearchAdapter,
+  op: SearchOperation,
+): Promise<void> {
+  if (op.kind === "index") {
+    await searchAdapter.index(op.tenantId, op.doc);
+  } else {
+    await searchAdapter.remove(op.tenantId, op.entityType, op.entityId);
+  }
+}
+
+// Collapse key for one search op — same (tenant, entity) target as the old
+// per-event index()/remove() calls addressed, index and remove share the
+// key so a later op in the same turn always overwrites an earlier one
+// (update-then-delete ⇒ remove wins, delete-then-restore ⇒ index wins).
+function searchOperationKey(op: SearchOperation): string {
+  const entityType = op.kind === "index" ? op.doc.entityType : op.entityType;
+  const entityId = op.kind === "index" ? op.doc.entityId : op.entityId;
+  return `${op.tenantId}\u0000${entityType}\u0000${String(entityId)}`;
+}
+
+type SearchOperationsByTenant = Map<
+  TenantId,
+  { toIndex: SearchDocument[]; toRemove: { entityType: string; entityId: EntityId }[] }
+>;
+
+// Resolves every event's op sequentially (the named-event path does DB
+// reads, so resolving in parallel would fan out uncapped concurrent
+// queries for one turn) and collapses to the last op per
+// (tenantId, entityType, entityId) — update-then-delete ⇒ remove wins,
+// delete-then-restore ⇒ index wins.
+async function resolveSearchOperationsByTenant(
+  events: readonly StoredEvent[],
+  ctx: AppContext,
+  registry: Registry,
+): Promise<SearchOperationsByTenant> {
+  const byKey = new Map<string, SearchOperation>();
+  for (const event of events) {
+    const op = await resolveSearchOperation(event, ctx, registry);
+    if (!op) continue;
+    byKey.set(searchOperationKey(op), op);
+  }
+
+  const perTenant: SearchOperationsByTenant = new Map();
+  for (const op of byKey.values()) {
+    let bucket = perTenant.get(op.tenantId);
+    if (!bucket) {
+      bucket = { toIndex: [], toRemove: [] };
+      perTenant.set(op.tenantId, bucket);
+    }
+    if (op.kind === "index") bucket.toIndex.push(op.doc);
+    else bucket.toRemove.push({ entityType: op.entityType, entityId: op.entityId });
+  }
+  return perTenant;
+}
+
+// Flushes one tenant's collapsed ops — indexBatch/removeBatch when the
+// adapter implements them, otherwise falls back to looping the single-doc
+// methods for that group. Keys were already made disjoint by the collapse
+// in resolveSearchOperationsByTenant, so index-vs-remove order here
+// doesn't matter.
+async function flushSearchOperationsForTenant(
+  searchAdapter: SearchAdapter,
+  tenantId: TenantId,
+  bucket: { toIndex: SearchDocument[]; toRemove: { entityType: string; entityId: EntityId }[] },
+): Promise<void> {
+  if (bucket.toIndex.length > 0) {
+    if (searchAdapter.indexBatch) {
+      await searchAdapter.indexBatch(tenantId, bucket.toIndex);
+    } else {
+      for (const doc of bucket.toIndex) await searchAdapter.index(tenantId, doc);
+    }
+  }
+  if (bucket.toRemove.length > 0) {
+    if (searchAdapter.removeBatch) {
+      await searchAdapter.removeBatch(tenantId, bucket.toRemove);
+    } else {
+      for (const item of bucket.toRemove) {
+        await searchAdapter.remove(tenantId, item.entityType, item.entityId);
+      }
+    }
+  }
+}
+
 export function createSearchEventConsumer(
   searchAdapter: SearchAdapter,
   registry: Registry,
@@ -69,64 +230,14 @@ export function createSearchEventConsumer(
     // dead-lettering in event-dispatcher-delivery.ts if 2min isn't enough.
     errorPolicy: { maxAttempts: 1200 },
     handler: async (event, ctx) => {
-      const entityName = event.aggregateType;
-      const verb = event.type.split(".").pop();
-      const tenantId = event.tenantId;
-
-      // skip: delete/forgotten remove the index entry — reconstruct only
-      // makes sense for created/updated/restored (field data in payload).
-      if (verb === "deleted" || verb === "forgotten") {
-        await searchAdapter.remove(tenantId, entityName, event.aggregateId);
-        return;
-      }
-
-      let state: Record<string, unknown>;
-      if (verb === "created" || verb === "updated" || verb === "restored") {
-        state = reconstructStateForSearch(event.payload, verb);
-      } else {
-        // #2765 — named domain event: no fixed payload shape to reconstruct
-        // state from. Only worth a projection read when the entity actually
-        // declared searchable fields/extensions — same check
-        // buildSearchDocument makes below, done here first so a non-
-        // searchable entity's named events stay a no-op like before.
-        const entity = registry.getEntity(entityName);
-        const isSearchable =
-          entity !== undefined &&
-          (registry.getSearchableFields(entityName).length > 0 ||
-            registry.getSearchPayloadExtensions(entityName).length > 0);
-        // skip: entity declares no searchable fields/extensions — nothing to
-        // index, stays a no-op with no extra query, same as before #2765.
-        if (!entity || !isSearchable) return;
-
-        const row = await readProjectionRowForSearch(
-          ctx,
-          registry,
-          entityName,
-          entity,
-          tenantId,
-          event.aggregateId,
-        );
-        // skip: no live row (hard-deleted stream, or soft-deleted) — same
-        // outcome as the deleted/forgotten branch above.
-        if (!row) {
-          await searchAdapter.remove(tenantId, entityName, event.aggregateId);
-          return;
-        }
-        state = row;
-      }
-
-      state = await decryptSearchableSubjectFields(entityName, state, registry);
-      // skip: erased subject — drop the doc so a rebuild cannot resurrect plaintext.
-      if (hasErasedSearchableSubjectField(entityName, state, registry)) {
-        await searchAdapter.remove(tenantId, entityName, event.aggregateId);
-        return;
-      }
-      const doc = await buildSearchDocument(entityName, event.aggregateId, state, registry);
-      if (!doc) {
-        // skip: entity isn't searchable (no searchable fields declared)
-        return;
+      const op = await resolveSearchOperation(event, ctx, registry);
+      if (op) await applySearchOperation(searchAdapter, op);
+    },
+    batchHandler: async (events, ctx) => {
+      const perTenant = await resolveSearchOperationsByTenant(events, ctx, registry);
+      for (const [tenantId, bucket] of perTenant) {
+        await flushSearchOperationsForTenant(searchAdapter, tenantId, bucket);
       }
-      await searchAdapter.index(tenantId, doc);
     },
   };
 }
@@ -451,11 +562,19 @@ export function createJobTriggerEventConsumer(
 //
 //   "sessions:event:session-revoked" — payload.userId direct (own aggregate,
 //     see bundled-features/sessions/session-revoked-event.ts). Fired for
-//     both self-service revoke and the privileged cross-tenant
-//     revoke-all-for-user (SYSTEM_TENANT_ID-anchored DSGVO Art.18 freeze).
+//     self-service revoke, the privileged cross-tenant revoke-all-for-user
+//     (SYSTEM_TENANT_ID-anchored DSGVO Art.18 freeze), and the raw
+//     sessionRevoker callback (logout / tenant-switch — the only source
+//     that also sets payload.streamScope, see readSessionRevokedScope below).
 //     fetchPendingEvents has no tenant predicate, so the SYSTEM_TENANT_ID-
 //     anchored event reaches this consumer the same as any other — routing
 //     is purely on payload.userId, never on event.tenantId.
+//   "personal-access-tokens:event:pat-revoked" — payload.userId direct (own
+//     aggregate, see bundled-features/personal-access-tokens/pat-revoked-event.ts).
+//     Fired by both the self-service revoke handler and
+//     revokeAllPatTokensForUser (password-change / MFA-toggle / DSGVO
+//     forget-subject). Always scoped to payload.tokenIds — a PAT revoke
+//     never touches another credential's stream.
 //   "tenant-membership.updated" / "tenant-membership.deleted" — role change
 //     or member removal. userId isn't in payload.changes (update only
 //     carries the changed fields, e.g. { roles }) so it's read from
@@ -480,6 +599,7 @@ export function createJobTriggerEventConsumer(
 export const ACCESS_INVALIDATION_CONSUMER_NAME = "system:consumer:access-invalidation";
 
 const SESSION_REVOKED_EVENT_TYPE = "sessions:event:session-revoked";
+const PAT_REVOKED_EVENT_TYPE = "personal-access-tokens:event:pat-revoked";
 const TENANT_MEMBERSHIP_UPDATED_EVENT_TYPE = "tenant-membership.updated";
 const TENANT_MEMBERSHIP_DELETED_EVENT_TYPE = "tenant-membership.deleted";
 
@@ -490,6 +610,40 @@ function readUserIdFromPreviousSnapshot(payload: Record<string, unknown>): strin
   return typeof userId === "string" && userId.length > 0 ? userId : undefined;
 }
 
+function readNonEmptyStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  return value.every((v): v is string => typeof v === "string") ? value : undefined;
+}
+
+// session-revoked's scope resolution, in order:
+//   1. streamScope === "revoked-sessions" with a non-empty sessionIds array
+//      (only the raw sessionRevoker callback sets this) → narrow "sessions"
+//      scope, closes exactly those sids.
+//   2. Otherwise, a non-empty keptSessionId ("revoke all others") → spares
+//      that one sid, same as before streamScope existed.
+//   3. Otherwise → userwide. Events appended before streamScope existed have
+//      neither field and fall straight through to this same userwide default
+//      they always had — a replay is unaffected.
+function readSessionRevokedScope(payload: Record<string, unknown>): AccessInvalidationScope {
+  if (payload["streamScope"] === "revoked-sessions") {
+    const sessionIds = readNonEmptyStringArray(payload["sessionIds"]);
+    if (sessionIds) return { kind: "sessions", sessionIds };
+  }
+  const keptSessionId = payload["keptSessionId"];
+  if (typeof keptSessionId === "string" && keptSessionId.length > 0) {
+    return { kind: "all-except-session", keptSessionId };
+  }
+  return { kind: "user" };
+}
+
+// pat-revoked is always narrow — a PAT revoke never has a reason to close
+// another credential's stream. Malformed tokenIds fail closed to userwide
+// rather than silently dropping the invalidation.
+function readPatRevokedScope(payload: Record<string, unknown>): AccessInvalidationScope {
+  const tokenIds = readNonEmptyStringArray(payload["tokenIds"]);
+  return tokenIds ? { kind: "pat-tokens", tokenIds } : { kind: "user" };
+}
+
 export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): EventConsumer {
   return {
     name: ACCESS_INVALIDATION_CONSUMER_NAME,
@@ -511,7 +665,15 @@ export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): Eve
         // poison would otherwise permanently stop access-invalidation for
         // every user behind one bad row).
         if (typeof userId !== "string" || userId.length === 0) return;
-        sseBroker.publishAccessInvalidation(userId);
+        sseBroker.publishAccessInvalidation(userId, readSessionRevokedScope(event.payload));
+      }
+
+      if (event.type === PAT_REVOKED_EVENT_TYPE) {
+        const userId = event.payload["userId"];
+        // skip: malformed pat-revoked payload — same fail-open reasoning as
+        // session-revoked above.
+        if (typeof userId !== "string" || userId.length === 0) return;
+        sseBroker.publishAccessInvalidation(userId, readPatRevokedScope(event.payload));
       }
 
       if (

package/src/pipeline/write-origin.ts

@@ -1,6 +1,8 @@
 // The static check in boot-validator/access-declarations.ts only sees a handler's own
 // input schema; writes reached via ctx.write/writeAs/queryAs, hooks or foreign-feature
 // tables are only visible at the actual write, so the gate runs there at runtime.
+import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import * as z from "zod";
 import { buildEntityTable } from "../db/table-builder";
 import { type PersonalDataGate, tableNameOf } from "../db/tenant-db";
 import {
@@ -15,12 +17,29 @@ import { AccessDeniedError } from "../errors";
 import { FrameworkReasons } from "../errors/reasons";
 import { toSnakeCase } from "../utils/case";
 
-export type WriteOrigin = {
-  readonly rootHandler: string;
-  readonly anonymousRoot: boolean;
-  // Only a write-handler root can declare public-intake; a query/stream root never does.
-  readonly publicIntake: boolean;
-};
+export { isPersonalDataGated, type WriteOrigin };
+
+// Only narrows: an inherited origin can add a gate, never lift the root's.
+export function effectiveWriteOrigin(root: WriteOrigin, inherited?: WriteOrigin): WriteOrigin {
+  if (!inherited) return root;
+  if (isPersonalDataGated(root)) return root;
+  if (isPersonalDataGated(inherited)) return inherited;
+  return root;
+}
+
+const writeOriginSchema = z
+  .object({
+    rootHandler: z.string(),
+    anonymousRoot: z.boolean(),
+    publicIntake: z.boolean(),
+    viaJob: z.string().optional(),
+  })
+  .strict();
+
+export function parseWriteOrigin(value: unknown): WriteOrigin | undefined {
+  const parsed = writeOriginSchema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+}
 
 function declaresPublicIntake(access: AccessRule): boolean {
   return accessAllowsAnonymous(access) && declaredPersonalData(access) === "public-intake";
@@ -67,7 +86,7 @@ function personalDataTableMap(registry: Registry): ReadonlyMap<string, ReadonlyS
 }
 
 // Names fields only, never values: the error reaches the anonymous HTTP caller.
-function publicIntakeRequiredError(
+export function publicIntakeRequiredError(
   origin: WriteOrigin,
   target: string,
   fields: readonly string[],
@@ -75,14 +94,16 @@ function publicIntakeRequiredError(
   return new AccessDeniedError({
     message:
       `Anonymous root handler "${origin.rootHandler}" wrote personal-data field(s) ` +
-      `${fields.map((f) => `"${f}"`).join(", ")} on "${target}". Declare ` +
-      'access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
+      `${fields.map((f) => `"${f}"`).join(", ")} on "${target}"` +
+      (origin.viaJob ? ` via job "${origin.viaJob}"` : "") +
+      '. Declare access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
       `"${origin.rootHandler}" to allow anonymous callers to write personal data.`,
     details: {
       reason: FrameworkReasons.publicIntakeRequired,
       rootHandler: origin.rootHandler,
       target,
       fields,
+      ...(origin.viaJob !== undefined && { job: origin.viaJob }),
     },
   });
 }
@@ -93,7 +114,7 @@ export function buildPersonalDataGate(
   registry: Registry,
   origin: WriteOrigin,
 ): PersonalDataGate | undefined {
-  if (!origin.anonymousRoot || origin.publicIntake) return undefined;
+  if (!isPersonalDataGated(origin)) return undefined;
   const map = personalDataTableMap(registry);
   return (tableName, keys, entity) => {
     const personalFields = entity ? personalColumnNames(entity) : map.get(tableName);

package/src/rate-limit/__tests__/dispatcher-l3.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { defineFeature, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { z } from "zod";
+import * as z from "zod";
 import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
 
 // Full-stack L3 proof: a handler with `rateLimit` opt-in is gated by the

package/src/search/__tests__/derive-search-adapter-config.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEmbeddedField,
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineFeature,
+} from "../../engine";
+import { deriveSearchAdapterConfig } from "../derive-search-adapter-config";
+
+describe("deriveSearchAdapterConfig", () => {
+  test("returns undefined for an empty registry", () => {
+    expect(deriveSearchAdapterConfig(createRegistry([]))).toBeUndefined();
+  });
+
+  test("returns undefined when no entity has a searchable field", () => {
+    const feature = defineFeature("plain", (r) => {
+      r.entity(
+        "note",
+        createEntity({
+          table: "notes",
+          fields: { title: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+    });
+
+    expect(deriveSearchAdapterConfig(createRegistry([feature]))).toBeUndefined();
+  });
+
+  test("unions searchable fields across entities, deduplicated, in first-occurrence order", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({
+          table: "customers",
+          fields: {
+            title: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+            email: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+          },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "orders",
+          fields: {
+            title: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+            note: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+            address: createEmbeddedField(
+              { city: { type: "text", searchable: true } },
+              { personal: false, reason: "test_fixture" },
+            ),
+          },
+        }),
+      );
+    });
+
+    const config = deriveSearchAdapterConfig(createRegistry([feature]));
+
+    expect(config).toEqual({
+      searchableFields: ["title", "email", "note", "address_city"],
+      rankingFields: ["title", "email", "note", "address_city"],
+    });
+  });
+});

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

@@ -255,3 +255,94 @@ describe.skipIf(!MEILI_UP)("meilisearch adapter (live)", () => {
     });
   });
 });
+
+// Lazy tenant-index configuration off setDefaultConfig, with no
+// explicit per-tenant configure() call from the app.
+describe.skipIf(!MEILI_UP)("meilisearch adapter — lazy default config", () => {
+  let lazyClient: Meilisearch;
+  let lazyPrefix: string;
+
+  beforeAll(() => {
+    lazyClient = new Meilisearch({ host: MEILI_URL, apiKey: MEILI_KEY });
+    lazyPrefix = `test_lazy_${uuid()}_`;
+  });
+
+  afterAll(async () => {
+    const indices = await lazyClient.getIndexes();
+    for (const idx of indices.results) {
+      if (idx.uid.startsWith(lazyPrefix)) {
+        try {
+          await lazyClient.index(idx.uid).delete().waitTask();
+        } catch {
+          /* ok */
+        }
+      }
+    }
+  });
+
+  test("first access via index() configures the tenant index off the default config", async () => {
+    const tenant = uuid();
+    const lazyAdapter = createMeilisearchAdapter({
+      url: MEILI_URL,
+      apiKey: MEILI_KEY,
+      indexPrefix: lazyPrefix,
+    });
+    lazyAdapter.setDefaultConfig?.({ searchableFields: ["firstName"] });
+
+    await lazyAdapter.index(tenant, {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { firstName: "Lazy" },
+    });
+
+    // Mutation-check target: without ensureConfigured() in index(), Meili
+    // auto-creates the index on addDocuments but never sets filterable/
+    // searchable attributes — assert those directly instead of relying on
+    // adapter.search(), which would itself lazily configure the index and
+    // mask the mutation.
+    const index = lazyClient.index(meilisearchTenantIndex(lazyPrefix, tenant));
+    expect(await index.getFilterableAttributes()).toEqual(
+      expect.arrayContaining(["_type", "_weight"]),
+    );
+    expect(await index.getSearchableAttributes()).toEqual(["firstName"]);
+
+    const results = await lazyAdapter.search(tenant, "lazy", { filterType: "user" });
+    expect(results.some((r) => r.entityId === 1 && r.entityType === "user")).toBe(true);
+  });
+
+  test("first access via search() with filterType on a never-written tenant returns empty, not an error", async () => {
+    const tenant = uuid();
+    const lazyAdapter = createMeilisearchAdapter({
+      url: MEILI_URL,
+      apiKey: MEILI_KEY,
+      indexPrefix: lazyPrefix,
+    });
+    lazyAdapter.setDefaultConfig?.({ searchableFields: ["firstName"] });
+
+    const results = await lazyAdapter.search(tenant, "anything", { filterType: "user" });
+    expect(results).toEqual([]);
+  });
+
+  test("explicit configure() wins over a later setDefaultConfig() — never overwritten", async () => {
+    const tenant = uuid();
+    const lazyAdapter = createMeilisearchAdapter({
+      url: MEILI_URL,
+      apiKey: MEILI_KEY,
+      indexPrefix: lazyPrefix,
+    });
+
+    await lazyAdapter.configure(tenant, { searchableFields: ["a"] });
+    lazyAdapter.setDefaultConfig?.({ searchableFields: ["b"] });
+
+    await lazyAdapter.index(tenant, {
+      entityType: "user",
+      entityId: 1,
+      weight: 1,
+      fields: { a: "value" },
+    });
+
+    const index = lazyClient.index(meilisearchTenantIndex(lazyPrefix, tenant));
+    expect(await index.getSearchableAttributes()).toEqual(["a"]);
+  });
+});