ydb-qdrant 8.1.0 → 9.0.3

package/dist/services/PointsService.js

@@ -1,12 +1,22 @@
-import { UpsertPointsReq, SearchReq, DeletePointsReq } from "../types.js";
+import { UpsertPointsReq, SearchReq, DeletePointsReq, RetrievePointsReq, } from "../qdrant/Requests.js";
 import { ensureMetaTable } from "../ydb/schema.js";
-import { getCollectionMeta, touchCollectionLastAccess, } from "../repositories/collectionsRepo.js";
-import { deletePoints as repoDeletePoints, deletePointsByPathSegments as repoDeletePointsByPathSegments, searchPoints as repoSearchPoints, upsertPoints as repoUpsertPoints, } from "../repositories/pointsRepo.js";
+import { getCollectionMeta, touchCollectionLastAccess, deleteAllPointsForCollection, } from "../repositories/collectionsRepo.js";
+import { deletePoints as repoDeletePoints, deletePointsByPathSegments as repoDeletePointsByPathSegments, searchPoints as repoSearchPoints, upsertPoints as repoUpsertPoints, retrievePointsByIds as repoRetrievePointsByIds, } from "../repositories/pointsRepo.js";
 import { logger } from "../logging/logger.js";
+import { elapsedMsSince, getElapsedMsSinceRequestStart, getMonotonicTimeNs, } from "../logging/requestContext.js";
 import { QdrantServiceError, isVectorDimensionMismatchError, } from "./errors.js";
 import { normalizeCollectionContextShared } from "./CollectionService.shared.js";
 import { resolvePointsTableAndUidOneTable } from "./CollectionService.one-table.js";
 import { normalizeSearchBodyForSearch, normalizeSearchBodyForQuery, } from "../utils/normalization.js";
+import { normalizePathSegments } from "../utils/pathPrefix.js";
+const MAX_LOGGED_UPSERT_PATHS = 20;
+const MAX_LOGGED_DELETE_PATHS = 20;
+function isEmptyFilter(filter) {
+    if (typeof filter !== "object" || filter === null)
+        return false;
+    const f = filter;
+    return Array.isArray(f.must) && f.must.length === 0;
+}
 function parsePathSegmentsFilterToPaths(filter) {
     const extractMust = (must) => {
         if (!Array.isArray(must) || must.length === 0)
@@ -63,35 +73,90 @@ function parsePathSegmentsFilterToPaths(filter) {
     }
     return null;
 }
+function collectPathLogFields(pathStrings, maxLoggedPaths) {
+    const uniquePaths = new Set();
+    const paths = [];
+    for (const path of pathStrings) {
+        if (uniquePaths.has(path)) {
+            continue;
+        }
+        uniquePaths.add(path);
+        if (paths.length < maxLoggedPaths) {
+            paths.push(path);
+        }
+    }
+    return {
+        pathCount: uniquePaths.size,
+        paths,
+        pathsTruncated: uniquePaths.size > paths.length,
+    };
+}
+function collectUpsertPathLogFields(points) {
+    const pathStrings = [];
+    for (const point of points) {
+        const pathSegments = normalizePathSegments(point.payload?.pathSegments);
+        if (!pathSegments) {
+            continue;
+        }
+        pathStrings.push(pathSegments.join("/"));
+    }
+    return collectPathLogFields(pathStrings, MAX_LOGGED_UPSERT_PATHS);
+}
 export async function upsertPoints(ctx, body) {
+    const serviceStartNs = getMonotonicTimeNs();
+    const metaLookupStartNs = getMonotonicTimeNs();
     await ensureMetaTable();
-    const normalized = normalizeCollectionContextShared(ctx.tenant, ctx.collection, ctx.apiKey, ctx.userAgent);
+    const normalized = normalizeCollectionContextShared(ctx.userUid, ctx.collection, ctx.userAgent);
     const meta = await getCollectionMeta(normalized.metaKey);
+    const metaLookupMs = elapsedMsSince(metaLookupStartNs);
     if (!meta) {
         throw new QdrantServiceError(404, {
             status: "error",
             error: "collection not found",
         });
     }
+    const requestValidationStartNs = getMonotonicTimeNs();
     const parsed = UpsertPointsReq.safeParse(body);
+    const requestValidationMs = elapsedMsSince(requestValidationStartNs);
     if (!parsed.success) {
         throw new QdrantServiceError(400, {
             status: "error",
             error: parsed.error.flatten(),
         });
     }
+    const uidResolveStartNs = getMonotonicTimeNs();
     const { tableName, uid } = await resolvePointsTableAndUidOneTable(normalized);
+    const uidResolveMs = elapsedMsSince(uidResolveStartNs);
+    const upsertPathLogFields = collectUpsertPathLogFields(parsed.data.points);
+    logger.info({
+        collection: normalized.collection,
+        uid,
+        pointCount: parsed.data.points.length,
+        ...upsertPathLogFields,
+    }, "upsertPoints: payload paths");
+    logger.info({
+        phase: "upsertPrepare",
+        collection: normalized.collection,
+        uid,
+        metaLookupMs,
+        requestValidationMs,
+        uidResolveMs,
+        pointCount: parsed.data.points.length,
+        pathCount: upsertPathLogFields.pathCount,
+        timeToHandlerMs: getElapsedMsSinceRequestStart(),
+    }, "upsert: prepare phase");
+    const repoStartNs = getMonotonicTimeNs();
     let upserted;
     try {
-        upserted = await repoUpsertPoints(tableName, parsed.data.points, meta.dimension, uid);
+        upserted = await repoUpsertPoints(tableName, parsed.data.points, meta.dimension, uid, ctx.apiKey);
     }
     catch (err) {
         if (isVectorDimensionMismatchError(err)) {
             logger.warn({
-                tenant: normalized.tenant,
                 collection: normalized.collection,
                 table: tableName,
                 dimension: meta.dimension,
+                uid,
             }, "upsertPoints: vector dimension mismatch");
             throw new QdrantServiceError(400, {
                 status: "error",
@@ -100,17 +165,28 @@ export async function upsertPoints(ctx, body) {
         }
         throw err;
     }
+    const repoTotalMs = elapsedMsSince(repoStartNs);
+    const lastAccessStartNs = getMonotonicTimeNs();
     await touchCollectionLastAccess(normalized.metaKey);
+    const lastAccessMs = elapsedMsSince(lastAccessStartNs);
+    logger.info({
+        phase: "upsertComplete",
+        collection: normalized.collection,
+        uid,
+        serviceTotalMs: elapsedMsSince(serviceStartNs),
+        repoTotalMs,
+        lastAccessMs,
+        pointCount: parsed.data.points.length,
+    }, "upsert: completed");
     return { upserted };
 }
 async function executeSearch(ctx, normalizedSearch, source) {
     await ensureMetaTable();
-    const normalized = normalizeCollectionContextShared(ctx.tenant, ctx.collection, ctx.apiKey, ctx.userAgent);
-    logger.info({ tenant: normalized.tenant, collection: normalized.collection }, `${source}: resolve collection meta`);
+    const normalized = normalizeCollectionContextShared(ctx.userUid, ctx.collection, ctx.userAgent);
+    logger.info({ collection: normalized.collection }, `${source}: resolve collection meta`);
     const meta = await getCollectionMeta(normalized.metaKey);
     if (!meta) {
         logger.warn({
-            tenant: normalized.tenant,
             collection: normalized.collection,
             metaKey: normalized.metaKey,
         }, `${source}: collection not found`);
@@ -126,7 +202,6 @@ async function executeSearch(ctx, normalizedSearch, source) {
     });
     if (!parsed.success) {
         logger.warn({
-            tenant: normalized.tenant,
             collection: normalized.collection,
             issues: parsed.error.issues,
         }, `${source}: invalid payload`);
@@ -137,8 +212,8 @@ async function executeSearch(ctx, normalizedSearch, source) {
     }
     const { tableName, uid } = await resolvePointsTableAndUidOneTable(normalized);
     logger.info({
-        tenant: normalized.tenant,
         collection: normalized.collection,
+        uid,
         top: parsed.data.top,
         queryVectorLen: parsed.data.vector.length,
         collectionDim: meta.dimension,
@@ -148,16 +223,16 @@ async function executeSearch(ctx, normalizedSearch, source) {
     const filterPaths = parsePathSegmentsFilterToPaths(normalizedSearch.filter);
     let hits;
     try {
-        hits = await repoSearchPoints(tableName, parsed.data.vector, parsed.data.top, parsed.data.with_payload, meta.distance, meta.dimension, uid, filterPaths ?? undefined);
+        hits = await repoSearchPoints(tableName, parsed.data.vector, parsed.data.top, parsed.data.with_payload, meta.distance, meta.dimension, uid, ctx.apiKey, filterPaths ?? undefined);
     }
     catch (err) {
         if (isVectorDimensionMismatchError(err)) {
             logger.warn({
-                tenant: normalized.tenant,
                 collection: normalized.collection,
                 table: tableName,
                 dimension: meta.dimension,
                 queryVectorLen: parsed.data.vector.length,
+                uid,
             }, `${source}: vector dimension mismatch`);
             throw new QdrantServiceError(400, {
                 status: "error",
@@ -188,7 +263,6 @@ async function executeSearch(ctx, normalizedSearch, source) {
             return hit.score <= threshold;
         });
     logger.info({
-        tenant: normalized.tenant,
         collection: normalized.collection,
         hits: hits.length,
     }, `${source}: completed`);
@@ -202,9 +276,35 @@ export async function queryPoints(ctx, body) {
     const normalizedSearch = normalizeSearchBodyForQuery(body);
     return await executeSearch(ctx, normalizedSearch, "query");
 }
+export async function retrievePoints(ctx, body) {
+    await ensureMetaTable();
+    const normalized = normalizeCollectionContextShared(ctx.userUid, ctx.collection, ctx.userAgent);
+    const meta = await getCollectionMeta(normalized.metaKey);
+    if (!meta) {
+        throw new QdrantServiceError(404, {
+            status: "error",
+            error: "collection not found",
+        });
+    }
+    const parsed = RetrievePointsReq.safeParse(body);
+    if (!parsed.success) {
+        throw new QdrantServiceError(400, {
+            status: "error",
+            error: parsed.error.flatten(),
+        });
+    }
+    const { tableName, uid } = await resolvePointsTableAndUidOneTable(normalized);
+    const points = await repoRetrievePointsByIds(tableName, parsed.data.ids, uid, ctx.apiKey, parsed.data.with_payload);
+    await touchCollectionLastAccess(normalized.metaKey);
+    return { points };
+}
+/**
+ * @returns `deleted` — number of points removed, or `-1` when the exact count
+ *          is unavailable (e.g. bulk BATCH DELETE or clear-all-points).
+ */
 export async function deletePoints(ctx, body) {
     await ensureMetaTable();
-    const normalized = normalizeCollectionContextShared(ctx.tenant, ctx.collection, ctx.apiKey, ctx.userAgent);
+    const normalized = normalizeCollectionContextShared(ctx.userUid, ctx.collection, ctx.userAgent);
     const meta = await getCollectionMeta(normalized.metaKey);
     if (!meta) {
         throw new QdrantServiceError(404, {
@@ -222,8 +322,18 @@ export async function deletePoints(ctx, body) {
     const { tableName, uid } = await resolvePointsTableAndUidOneTable(normalized);
     let deleted;
     if ("points" in parsed.data) {
+        logger.info({
+            collection: normalized.collection,
+            uid,
+            idCount: parsed.data.points.length,
+        }, "deletePoints: by IDs");
         deleted = await repoDeletePoints(tableName, parsed.data.points, uid);
     }
+    else if (isEmptyFilter(parsed.data.filter)) {
+        logger.info({ collection: normalized.collection, uid }, "deletePoints: clear all points");
+        await deleteAllPointsForCollection(uid);
+        deleted = -1;
+    }
     else {
         const paths = parsePathSegmentsFilterToPaths(parsed.data.filter);
         if (!paths) {
@@ -232,8 +342,15 @@ export async function deletePoints(ctx, body) {
                 error: "unsupported delete filter: only pathSegments.N match filters with must/should are supported",
             });
         }
+        const deletePathLogFields = collectPathLogFields(paths.map((segments) => segments.join("/")), MAX_LOGGED_DELETE_PATHS);
+        logger.info({
+            collection: normalized.collection,
+            uid,
+            ...deletePathLogFields,
+        }, "deletePoints: by pathSegments filter");
         deleted = await repoDeletePointsByPathSegments(tableName, uid, paths);
     }
+    logger.info({ collection: normalized.collection, uid, deleted }, "deletePoints: completed");
     await touchCollectionLastAccess(normalized.metaKey);
     return { deleted };
 }

package/dist/types.d.ts

@@ -1,94 +1,4 @@
-import { z } from "zod";
-import type { QdrantDistance, QdrantPayload, QdrantWithPayloadInterface, YdbQdrantPointId, YdbQdrantUpsertPoint } from "./qdrant/QdrantRestTypes.js";
-export type DistanceKind = QdrantDistance;
-export type VectorType = "float";
-export type Payload = QdrantPayload;
-export type WithPayload = QdrantWithPayloadInterface;
-/**
- * Collection metadata from qdr__collections table.
- *
- * @property lastAccessedAt - Timestamp of last access; undefined for collections
- * created before this feature, null if explicitly unset.
- */
-export interface CollectionMeta {
-    table: string;
-    dimension: number;
-    distance: DistanceKind;
-    vectorType: VectorType;
-    lastAccessedAt?: Date | null;
-}
-export declare const CreateCollectionReq: z.ZodObject<{
-    vectors: z.ZodObject<{
-        size: z.ZodNumber;
-        distance: z.ZodType<DistanceKind>;
-        data_type: z.ZodOptional<z.ZodEnum<{
-            float: "float";
-        }>>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export declare const UpsertPointsReq: z.ZodObject<{
-    points: z.ZodArray<z.ZodObject<{
-        id: z.ZodType<YdbQdrantPointId>;
-        vector: z.ZodArray<z.ZodNumber>;
-        payload: z.ZodType<Payload | undefined>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type UpsertPoint = YdbQdrantUpsertPoint;
-export type UpsertPointsBody = {
-    points: UpsertPoint[];
-};
-export declare const SearchReq: z.ZodObject<{
-    vector: z.ZodArray<z.ZodNumber>;
-    top: z.ZodNumber;
-    with_payload: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-export type SearchPointsBody = {
-    vector: number[];
-    top?: number;
-    limit?: number;
-    with_payload?: WithPayload;
-    score_threshold?: number | null;
-};
-export declare const DeletePointsByIdsReq: z.ZodObject<{
-    points: z.ZodArray<z.ZodType<YdbQdrantPointId, unknown, z.core.$ZodTypeInternals<YdbQdrantPointId, unknown>>>;
-}, z.core.$strip>;
-export declare const DeletePointsByFilterReq: z.ZodObject<{
-    filter: z.ZodUnion<readonly [z.ZodObject<{
-        must: z.ZodArray<z.ZodObject<{
-            key: z.ZodString;
-            match: z.ZodObject<{
-                value: z.ZodString;
-            }, z.core.$strip>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>, z.ZodObject<{
-        should: z.ZodArray<z.ZodObject<{
-            must: z.ZodArray<z.ZodObject<{
-                key: z.ZodString;
-                match: z.ZodObject<{
-                    value: z.ZodString;
-                }, z.core.$strip>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>]>;
-}, z.core.$strip>;
-export declare const DeletePointsReq: z.ZodUnion<readonly [z.ZodObject<{
-    points: z.ZodArray<z.ZodType<YdbQdrantPointId, unknown, z.core.$ZodTypeInternals<YdbQdrantPointId, unknown>>>;
-}, z.core.$strip>, z.ZodObject<{
-    filter: z.ZodUnion<readonly [z.ZodObject<{
-        must: z.ZodArray<z.ZodObject<{
-            key: z.ZodString;
-            match: z.ZodObject<{
-                value: z.ZodString;
-            }, z.core.$strip>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>, z.ZodObject<{
-        should: z.ZodArray<z.ZodObject<{
-            must: z.ZodArray<z.ZodObject<{
-                key: z.ZodString;
-                match: z.ZodObject<{
-                    value: z.ZodString;
-                }, z.core.$strip>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>]>;
-}, z.core.$strip>]>;
+export type { DistanceKind, Payload, VectorType, WithPayload, YdbQdrantPointId, YdbQdrantUpsertPoint, } from "./qdrant/QdrantRestTypes.js";
+export { CreateCollectionReq, DeletePointsByFilterReq, DeletePointsByIdsReq, DeletePointsReq, RetrievePointsReq, SearchReq, UpsertPointsReq, } from "./qdrant/Requests.js";
+export type { SearchPointsBody, UpsertPoint, UpsertPointsBody, } from "./qdrant/Requests.js";
+export type { CollectionMeta } from "./repositories/collectionsRepo.js";

package/dist/types.js

@@ -1,54 +1 @@
-import { z } from "zod";
-export const CreateCollectionReq = z.object({
-    vectors: z.object({
-        size: z.number().int().positive(),
-        distance: z.enum([
-            "Cosine",
-            "Euclid",
-            "Dot",
-            "Manhattan",
-        ]),
-        data_type: z.enum(["float"]).optional(),
-    }),
-});
-export const UpsertPointsReq = z.object({
-    points: z
-        .array(z.object({
-        id: z.union([z.string(), z.number()]),
-        vector: z.array(z.number()),
-        payload: z.record(z.string(), z.unknown()).optional(),
-    }))
-        .min(1),
-});
-export const SearchReq = z.object({
-    vector: z.array(z.number()).min(1),
-    top: z.number().int().positive().max(1000),
-    with_payload: z.boolean().optional(),
-});
-export const DeletePointsByIdsReq = z.object({
-    points: z
-        .array(z.union([z.string(), z.number()]))
-        .min(1),
-});
-const DeletePointsFilterCondition = z.object({
-    key: z.string(),
-    match: z.object({
-        value: z.string(),
-    }),
-});
-const DeletePointsFilterMust = z.object({
-    must: z.array(DeletePointsFilterCondition).min(1),
-});
-const DeletePointsFilter = z.union([
-    DeletePointsFilterMust,
-    z.object({
-        should: z.array(DeletePointsFilterMust).min(1),
-    }),
-]);
-export const DeletePointsByFilterReq = z.object({
-    filter: DeletePointsFilter,
-});
-export const DeletePointsReq = z.union([
-    DeletePointsByIdsReq,
-    DeletePointsByFilterReq,
-]);
+export { CreateCollectionReq, DeletePointsByFilterReq, DeletePointsByIdsReq, DeletePointsReq, RetrievePointsReq, SearchReq, UpsertPointsReq, } from "./qdrant/Requests.js";

package/dist/utils/EnvParsers.d.ts

@@ -0,0 +1,5 @@
+export declare function parseBooleanEnv(value: string | undefined, defaultValue: boolean): boolean;
+export declare function parseIntegerEnv(value: string | undefined, defaultValue: number, opts?: {
+    min?: number;
+    max?: number;
+}): number;

package/dist/utils/EnvParsers.js

@@ -0,0 +1,30 @@
+export function parseBooleanEnv(value, defaultValue) {
+    if (value === undefined) {
+        return defaultValue;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true" || normalized === "1" || normalized === "yes") {
+        return true;
+    }
+    if (normalized === "false" || normalized === "0" || normalized === "no") {
+        return false;
+    }
+    return defaultValue;
+}
+export function parseIntegerEnv(value, defaultValue, opts) {
+    if (value === undefined) {
+        return defaultValue;
+    }
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (!Number.isFinite(parsed)) {
+        return defaultValue;
+    }
+    let result = parsed;
+    if (opts?.min !== undefined && result < opts.min) {
+        result = opts.min;
+    }
+    if (opts?.max !== undefined && result > opts.max) {
+        result = opts.max;
+    }
+    return result;
+}

package/dist/utils/PayloadSign.d.ts

@@ -0,0 +1,4 @@
+export declare function computePayloadSign(params: {
+    apiKey: string;
+    payload: unknown;
+}): string;

package/dist/utils/PayloadSign.js

@@ -0,0 +1,18 @@
+import crypto from "crypto";
+import stableStringify from "fast-json-stable-stringify";
+function canonicalizePayload(payload) {
+    const canonical = stableStringify(payload);
+    if (typeof canonical !== "string") {
+        // JSON.stringify returns undefined for top-level undefined/functions/symbols.
+        throw new Error("computePayloadSign: payload is not JSON-serializable");
+    }
+    return canonical;
+}
+export function computePayloadSign(params) {
+    const apiKey = params.apiKey.trim();
+    if (apiKey.length === 0) {
+        throw new Error("computePayloadSign: apiKey is empty");
+    }
+    const canonical = canonicalizePayload(params.payload);
+    return crypto.createHmac("sha256", apiKey).update(canonical).digest("hex");
+}

package/dist/utils/distance.d.ts

@@ -1,16 +1,5 @@
-import type { DistanceKind } from "../types.js";
+import type { DistanceKind } from "../qdrant/QdrantRestTypes.js";
 export declare function mapDistanceToKnnFn(distance: DistanceKind): {
     fn: string;
     order: "ASC" | "DESC";
 };
-/**
- * Maps a user-specified distance metric to a YDB Knn function
- * suitable for bit-quantized vectors (Phase 1 approximate candidate selection).
- * Cosine uses similarity (DESC); other metrics use distance (ASC).
- * For Dot, falls back to CosineDistance as a proxy since there is no
- * direct distance equivalent for inner product.
- */
-export declare function mapDistanceToBitKnnFn(distance: DistanceKind): {
-    fn: string;
-    order: "ASC" | "DESC";
-};

package/dist/utils/distance.js

@@ -12,24 +12,3 @@ export function mapDistanceToKnnFn(distance) {
             return { fn: "Knn::CosineDistance", order: "ASC" };
     }
 }
-/**
- * Maps a user-specified distance metric to a YDB Knn function
- * suitable for bit-quantized vectors (Phase 1 approximate candidate selection).
- * Cosine uses similarity (DESC); other metrics use distance (ASC).
- * For Dot, falls back to CosineDistance as a proxy since there is no
- * direct distance equivalent for inner product.
- */
-export function mapDistanceToBitKnnFn(distance) {
-    switch (distance) {
-        case "Cosine":
-            return { fn: "Knn::CosineSimilarity", order: "DESC" };
-        case "Dot":
-            return { fn: "Knn::CosineDistance", order: "ASC" };
-        case "Euclid":
-            return { fn: "Knn::EuclideanDistance", order: "ASC" };
-        case "Manhattan":
-            return { fn: "Knn::ManhattanDistance", order: "ASC" };
-        default:
-            return { fn: "Knn::CosineDistance", order: "ASC" };
-    }
-}

package/dist/utils/pathPrefix.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizePathSegments(value: unknown): string[] | null;
+export declare function extractPathPrefix(payload: Record<string, unknown> | undefined): string | null;
+export declare function pathSegmentsToPrefix(segments: string[]): string;

package/dist/utils/pathPrefix.js

@@ -0,0 +1,47 @@
+function isNumericPathSegmentKey(key) {
+    return /^(0|[1-9]\d*)$/.test(key);
+}
+export function normalizePathSegments(value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return null;
+        const normalized = [];
+        for (const segment of value) {
+            if (typeof segment !== "string")
+                return null;
+            normalized.push(segment);
+        }
+        return normalized;
+    }
+    if (typeof value !== "object" || value === null) {
+        return null;
+    }
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        return null;
+    }
+    const indexedSegments = [];
+    for (const [key, segment] of entries) {
+        if (!isNumericPathSegmentKey(key) || typeof segment !== "string") {
+            return null;
+        }
+        indexedSegments.push({ index: Number(key), value: segment });
+    }
+    indexedSegments.sort((left, right) => left.index - right.index);
+    for (let index = 0; index < indexedSegments.length; index += 1) {
+        if (indexedSegments[index]?.index !== index) {
+            return null;
+        }
+    }
+    return indexedSegments.map((segment) => segment.value);
+}
+export function extractPathPrefix(payload) {
+    const pathSegments = normalizePathSegments(payload?.pathSegments);
+    if (!pathSegments) {
+        return null;
+    }
+    return pathSegmentsToPrefix(pathSegments);
+}
+export function pathSegmentsToPrefix(segments) {
+    return segments.map(encodeURIComponent).join("/");
+}

package/dist/utils/prefixExpansion.d.ts

@@ -0,0 +1 @@
+export declare function expandPathPrefixes(pathPrefix: string): string[];

package/dist/utils/prefixExpansion.js

@@ -0,0 +1,11 @@
+export function expandPathPrefixes(pathPrefix) {
+    if (pathPrefix === "") {
+        return [];
+    }
+    const parts = pathPrefix.split("/");
+    const prefixes = [];
+    for (let index = 1; index <= parts.length; index += 1) {
+        prefixes.push(parts.slice(0, index).join("/"));
+    }
+    return prefixes;
+}

package/dist/utils/qdrantResponse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Qdrant-compatible response envelope.
+ *
+ * Every Qdrant REST response includes `{ status, result, time, usage }`.
+ * This helper produces that shape, measuring elapsed wall-clock time
+ * from a previously captured `process.hrtime()` start mark.
+ */
+export declare function qdrantResponse(result: unknown, startHrTime: [number, number]): {
+    status: "ok";
+    result: unknown;
+    time: number;
+    usage: null;
+};

package/dist/utils/qdrantResponse.js

@@ -0,0 +1,12 @@
+/**
+ * Qdrant-compatible response envelope.
+ *
+ * Every Qdrant REST response includes `{ status, result, time, usage }`.
+ * This helper produces that shape, measuring elapsed wall-clock time
+ * from a previously captured `process.hrtime()` start mark.
+ */
+export function qdrantResponse(result, startHrTime) {
+    const diff = process.hrtime(startHrTime);
+    const time = diff[0] + diff[1] / 1e9;
+    return { status: "ok", result, time, usage: null };
+}

package/dist/utils/requestIdentity.d.ts

@@ -0,0 +1,8 @@
+import type { Request } from "express";
+import { AnonymousIdentityError } from "./tenant.js";
+export declare function isAnonymousIdentityError(err: unknown): err is AnonymousIdentityError;
+export declare function getRequestApiKey(req: Request): string | undefined;
+export declare function getRequestClientIp(req: Request): string | undefined;
+export declare function resolveRequestUserUid(req: Request): string;
+export declare function resolveRequestNamespaceUserUid(req: Request): string;
+export declare function resolveRequestSigningKey(req: Request, userUid?: string): string;