@delali/narsil 0.2.2-next.29 → 0.2.3-next.32

package/dist/server.mjs

@@ -1,6 +1,19 @@
-import { NarsilError, ErrorCodes } from './chunk-UNJZ7ZDB.mjs';
+import { ServerErrorCodes, NarsilError, ErrorCodes } from './chunk-EMI63EXP.mjs';
+export { ServerErrorCodes } from './chunk-EMI63EXP.mjs';
 import { randomUUID } from 'crypto';
 
+// src/server/capabilities.ts
+var ASYNC_IMPORT_CAPABILITY = "documents.import.async";
+var TASK_CANCEL_CAPABILITY = "tasks.cancel";
+var TASK_FILTER_CAPABILITY = "tasks.filter";
+var REBUILD_ANALYSIS_CAPABILITY = "indexes.rebuildAnalysis";
+var SERVER_CAPABILITIES = [
+  ASYNC_IMPORT_CAPABILITY,
+  TASK_CANCEL_CAPABILITY,
+  TASK_FILTER_CAPABILITY,
+  REBUILD_ANALYSIS_CAPABILITY
+];
+
 // src/server/cors.ts
 function resolveCors(cors) {
   if (!cors) return null;
@@ -29,20 +42,20 @@ function corsWriter(cors) {
 }
 
 // src/server/errors.ts
-var ServerErrorCodes = {
-  INVALID_REQUEST: "INVALID_REQUEST",
-  INVALID_JSON: "INVALID_JSON",
-  EMPTY_BODY: "EMPTY_BODY",
-  PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
-  UNSUPPORTED_MEDIA_TYPE: "UNSUPPORTED_MEDIA_TYPE",
-  NOT_FOUND: "NOT_FOUND",
-  TASK_NOT_FOUND: "TASK_NOT_FOUND",
-  TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS",
-  HOOK_ERROR: "HOOK_ERROR",
-  INTERNAL_ERROR: "INTERNAL_ERROR",
-  REQUEST_ABORTED: "REQUEST_ABORTED"
-};
 var STATUS_BY_CODE = {
+  INVALID_REQUEST: 400,
+  INVALID_JSON: 400,
+  EMPTY_BODY: 400,
+  PAYLOAD_TOO_LARGE: 413,
+  NOT_FOUND: 404,
+  TASK_NOT_FOUND: 404,
+  TASK_NOT_CANCELLABLE: 409,
+  TASK_OWNED_BY_ANOTHER_INSTANCE: 409,
+  TOO_MANY_REQUESTS: 429,
+  HOOK_ERROR: 500,
+  INTERNAL_ERROR: 500,
+  ENVELOPE_INVALID_MAGIC: 400,
+  ENVELOPE_VERSION_MISMATCH: 400,
   SCHEMA_INVALID_TYPE: 400,
   SCHEMA_MISSING_FIELD: 400,
   SCHEMA_DEPTH_EXCEEDED: 400,
@@ -56,6 +69,7 @@ var STATUS_BY_CODE = {
   SEARCH_INVALID_FILTER: 400,
   SEARCH_INVALID_MODE: 400,
   SEARCH_INVALID_CURSOR: 400,
+  SEARCH_RESULT_WINDOW_EXCEEDED: 400,
   LANGUAGE_NOT_SUPPORTED: 400,
   CONFIG_INVALID: 400,
   EMBEDDING_DIMENSION_MISMATCH: 400,
@@ -64,6 +78,7 @@ var STATUS_BY_CODE = {
   INDEX_NOT_FOUND: 404,
   DOC_NOT_FOUND: 404,
   INDEX_ALREADY_EXISTS: 409,
+  INDEX_ORPHANED: 409,
   DOC_ALREADY_EXISTS: 409,
   PARTITION_REBALANCING_BACKPRESSURE: 409,
   PARTITION_CAPACITY_EXCEEDED: 409,
@@ -82,6 +97,7 @@ var STATUS_BY_CODE = {
   QUERY_PARTIAL_FAILURE: 503,
   QUERY_NODE_TIMEOUT: 503,
   QUERY_NO_ACTIVE_REPLICA: 503,
+  CLUSTER_OPERATION_UNSUPPORTED: 501,
   REPLICATION_ENTRY_INVALID: 503,
   REPLICATION_INSYNC_REMOVAL_FAILED: 503,
   REPLICATION_ROLLBACK_FAILED: 503,
@@ -92,7 +108,44 @@ var STATUS_BY_CODE = {
   REPLICATION_SYNC_FAILED: 503,
   PARTITION_NOT_PRIMARY: 503,
   PARTITION_UNASSIGNED: 503,
-  INSUFFICIENT_REPLICAS: 503
+  INSUFFICIENT_REPLICAS: 503,
+  TRANSPORT_DEPENDENCY_MISSING: 500,
+  ALLOCATION_INVALID_CONFIG: 400,
+  ALLOCATION_NO_DATA_NODES: 503,
+  ALLOCATION_FAILED: 503,
+  CONTROLLER_LEASE_LOST: 503,
+  CONTROLLER_NOT_ACTIVE: 503,
+  NODE_ALREADY_JOINED: 409,
+  NODE_NOT_JOINED: 503,
+  NODE_BOOTSTRAP_FAILED: 503,
+  COORDINATOR_DEPENDENCY_MISSING: 500,
+  SNAPSHOT_SYNC_UNAUTHORIZED: 403,
+  SNAPSHOT_SYNC_REQUEST_INVALID: 400,
+  SNAPSHOT_SYNC_HEADER_INVALID: 400,
+  SNAPSHOT_SYNC_FRAME_INVALID: 400,
+  SNAPSHOT_SYNC_INDEX_NOT_FOUND: 404,
+  SNAPSHOT_SYNC_TOO_LARGE: 413,
+  SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: 413,
+  SNAPSHOT_SYNC_ABORTED: 409,
+  SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: 503,
+  SNAPSHOT_SYNC_SNAPSHOT_FAILED: 503,
+  SNAPSHOT_SYNC_DECODE_FAILED: 503,
+  SNAPSHOT_SYNC_HEADER_MISMATCH: 503,
+  SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: 503,
+  SNAPSHOT_SYNC_CHUNK_OVERFLOW: 503,
+  SNAPSHOT_SYNC_CHUNK_MISSING: 503,
+  SNAPSHOT_SYNC_END_MISSING: 503,
+  SNAPSHOT_SYNC_CHECKSUM_MISMATCH: 503,
+  SNAPSHOT_SYNC_PRIMARY_ERROR: 503,
+  SNAPSHOT_SYNC_NO_TARGETS: 503,
+  SNAPSHOT_SYNC_TRANSPORT_FAILED: 503,
+  SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: 503,
+  SNAPSHOT_SYNC_RESTORE_FAILED: 503,
+  SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: 503,
+  SNAPSHOT_SYNC_TIMEOUT: 503,
+  SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: 503,
+  SNAPSHOT_SYNC_NOT_ASSIGNED: 503,
+  CONTROLLER_METADATA_INVALID: 500
 };
 function httpStatusForNarsilError(code) {
   return STATUS_BY_CODE[code] ?? 500;
@@ -111,6 +164,17 @@ function toHttpError(err) {
   };
 }
 
+// src/json-encoding.ts
+function toPlainNumbers(key, value) {
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    return Array.from(value);
+  }
+  return value;
+}
+function encodeJson(value) {
+  return JSON.stringify(value, toPlainNumbers);
+}
+
 // src/server/response.ts
 var STATUS_TEXT = {
   200: "200 OK",
@@ -149,7 +213,7 @@ function streamBody(res, abort, body, status, contentType) {
   });
 }
 function sendJson(res, data, status = 200, abort) {
-  const payload = JSON.stringify(data);
+  const payload = encodeJson(data);
   if (abort && payload !== void 0 && Buffer.byteLength(payload) >= STREAM_THRESHOLD) {
     streamBody(res, abort, Buffer.from(payload, "utf8"), status, "application/json");
     return;
@@ -160,7 +224,7 @@ function sendJson(res, data, status = 200, abort) {
 }
 function sendError(res, status, code, message, details) {
   const body = { error: details ? { code, message, details } : { code, message } };
-  const payload = JSON.stringify(body);
+  const payload = encodeJson(body);
   res.cork(() => {
     res.writeStatus(statusLine(status)).writeHeader("Content-Type", "application/json").end(payload);
   });
@@ -220,6 +284,7 @@ function serializeBatchResult(result) {
 }
 
 // src/server/validation.ts
+var MAX_LIST_SORT_FIELDS = 8;
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -278,6 +343,45 @@ function validateMultiGet(body, maxFetch) {
   }
   return null;
 }
+function validateList(params, maxFetch) {
+  if (params.cursor !== void 0 && typeof params.cursor !== "string") {
+    return { message: 'Field "cursor" must be a string' };
+  }
+  if (params.limit !== void 0 && typeof params.limit !== "number") {
+    return { message: 'Field "limit" must be a number' };
+  }
+  if (typeof params.limit === "number" && params.limit > maxFetch) {
+    return {
+      message: `Field "limit" exceeds the maximum of ${maxFetch} documents per request`,
+      details: { value: params.limit, limit: maxFetch }
+    };
+  }
+  return validateListSort(params.sort);
+}
+function validateListSort(sort) {
+  if (sort === void 0) return null;
+  if (typeof sort !== "object" || sort === null) {
+    return { message: 'Field "sort" must be an object keyed by field name, or a list of fields' };
+  }
+  const entries = Array.isArray(sort) ? sort.map(
+    (entry) => typeof entry === "object" && entry !== null ? [entry.field, entry.direction] : [entry, void 0]
+  ) : Object.entries(sort);
+  if (entries.length > MAX_LIST_SORT_FIELDS) {
+    return {
+      message: `Field "sort" exceeds the maximum of ${MAX_LIST_SORT_FIELDS} fields`,
+      details: { count: entries.length, limit: MAX_LIST_SORT_FIELDS }
+    };
+  }
+  for (const [field, direction] of entries) {
+    if (typeof field !== "string" || field.length === 0) {
+      return { message: 'Every entry of "sort" must name a field', details: { value: field } };
+    }
+    if (direction !== "asc" && direction !== "desc") {
+      return { message: `Field "sort.${field}" must be "asc" or "desc"`, details: { value: direction } };
+    }
+  }
+  return null;
+}
 function validateBatch(body) {
   const action = body.action ?? "insert";
   if (action === "insert") {
@@ -310,13 +414,63 @@ function validateRebalance(body) {
   }
   return null;
 }
+var TASK_TYPES = ["optimizeVectors", "rebalance", "restore", "import", "rebuildAnalysis"];
+var TASK_STATUSES = ["queued", "running", "succeeded", "failed", "cancelled"];
+function parseCountParam(raw, field, minimum) {
+  if (raw === null) return minimum;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < minimum) {
+    return { message: `Query parameter "${field}" must be an integer of ${minimum} or more`, details: { value: raw } };
+  }
+  return value;
+}
+function parseEnumParam(raw, field, allowed) {
+  if (raw === null) return void 0;
+  const requested = raw.split(",").map((entry) => entry.trim());
+  const unknown = requested.filter((entry) => !allowed.includes(entry));
+  if (requested.length === 0 || unknown.length > 0) {
+    return {
+      message: `Query parameter "${field}" accepts only ${allowed.join(", ")}`,
+      details: { unknown }
+    };
+  }
+  return requested;
+}
+function isFailure(value) {
+  return isPlainObject(value) && typeof value.message === "string";
+}
+function parseTaskListQuery(params, maxPageSize) {
+  const type = parseEnumParam(params.get("type"), "type", TASK_TYPES);
+  if (isFailure(type)) return { failure: type };
+  const status = parseEnumParam(params.get("status"), "status", TASK_STATUSES);
+  if (isFailure(status)) return { failure: status };
+  const from = parseCountParam(params.get("from"), "from", 0);
+  if (isFailure(from)) return { failure: from };
+  const limit = parseCountParam(params.get("limit"), "limit", 1);
+  if (isFailure(limit)) return { failure: limit };
+  if (params.get("limit") !== null && limit > maxPageSize) {
+    return {
+      failure: {
+        message: `Query parameter "limit" exceeds the maximum page size of ${maxPageSize}`,
+        details: { value: limit, limit: maxPageSize }
+      }
+    };
+  }
+  const indexName = params.get("indexName");
+  return {
+    query: {
+      ...indexName === null ? {} : { indexName },
+      ...type === void 0 ? {} : { type },
+      ...status === void 0 ? {} : { status },
+      from,
+      ...params.get("limit") === null ? {} : { limit }
+    }
+  };
+}
 
 // src/server/handlers/admin.ts
-function taskResponse(record) {
-  return { taskId: record.id, type: record.type, status: record.status };
-}
 function createAdminHandlers(deps) {
-  const { engine, tasks } = deps;
+  const { engine, tasks, limits } = deps;
   async function checkpoint(ctx) {
     try {
       await engine.checkpoint(ctx.params[0]);
@@ -382,7 +536,18 @@ function createAdminHandlers(deps) {
       return;
     }
     const record = await tasks.start("optimizeVectors", name, () => engine.optimizeVectors(name, body.field));
-    respondJson(ctx, taskResponse(record), 202);
+    respondJson(ctx, record, 202);
+  }
+  async function rebuildAnalysis(ctx) {
+    const name = ctx.params[0];
+    try {
+      requireIndexExists(name);
+    } catch (err) {
+      respondError(ctx, err);
+      return;
+    }
+    const record = await tasks.start("rebuildAnalysis", name, () => engine.rebuildAnalysis(name));
+    respondJson(ctx, record, 202);
   }
   async function rebalance(ctx) {
     const body = parseJsonOptional(ctx);
@@ -401,7 +566,7 @@ function createAdminHandlers(deps) {
       return;
     }
     const record = await tasks.start("rebalance", name, () => engine.rebalance(name, target));
-    respondJson(ctx, taskResponse(record), 202);
+    respondJson(ctx, record, 202);
   }
   async function restore(ctx) {
     const raw = ctx.rawBody;
@@ -412,7 +577,7 @@ function createAdminHandlers(deps) {
     const name = ctx.params[0];
     const bytes = new Uint8Array(raw);
     const record = await tasks.start("restore", name, () => engine.restore(name, bytes));
-    respondJson(ctx, taskResponse(record), 202);
+    respondJson(ctx, record, 202);
   }
   async function getTask(ctx) {
     const record = await tasks.get(ctx.params[0]);
@@ -423,7 +588,41 @@ function createAdminHandlers(deps) {
     respondJson(ctx, record);
   }
   async function listTasks(ctx) {
-    respondJson(ctx, { tasks: await tasks.list() });
+    const parsed = parseTaskListQuery(ctx.query, limits.maxTaskPageSize);
+    if ("failure" in parsed) {
+      rejectInvalid(ctx, parsed.failure);
+      return;
+    }
+    respondJson(ctx, await tasks.list(parsed.query));
+  }
+  async function cancelTask(ctx) {
+    const taskId = ctx.params[0];
+    const { outcome, record } = await tasks.cancel(taskId);
+    if (outcome === "not-found") {
+      sendError(ctx.res, 404, ServerErrorCodes.TASK_NOT_FOUND, `Task "${taskId}" not found`);
+      return;
+    }
+    if (outcome === "already-finished") {
+      sendError(
+        ctx.res,
+        409,
+        ServerErrorCodes.TASK_NOT_CANCELLABLE,
+        `Task "${taskId}" has already finished`,
+        record === null ? void 0 : { status: record.status }
+      );
+      return;
+    }
+    if (outcome === "owned-by-another-instance") {
+      sendError(
+        ctx.res,
+        409,
+        ServerErrorCodes.TASK_OWNED_BY_ANOTHER_INSTANCE,
+        `Task "${taskId}" runs on another server instance, which is the only one that can stop it`,
+        record === null ? void 0 : { owner: record.owner }
+      );
+      return;
+    }
+    respondJson(ctx, record, 202);
   }
   return {
     checkpoint,
@@ -434,12 +633,22 @@ function createAdminHandlers(deps) {
     memory,
     optimize,
     rebalance,
+    rebuildAnalysis,
     restore,
     getTask,
-    listTasks
+    listTasks,
+    cancelTask
   };
 }
 
+// src/server/handlers/capabilities.ts
+function createCapabilitiesHandler() {
+  function report(ctx) {
+    respondJson(ctx, { capabilities: [...SERVER_CAPABILITIES] });
+  }
+  return { report };
+}
+
 // src/server/handlers/documents.ts
 function createDocumentHandlers(deps) {
   const { engine, limits } = deps;
@@ -545,6 +754,20 @@ function createDocumentHandlers(deps) {
       respondError(ctx, err);
     }
   }
+  async function list(ctx) {
+    const params = parseJson(ctx);
+    if (!params) return;
+    const failure = validateList(params, limits.maxFetchDocuments);
+    if (failure) {
+      rejectInvalid(ctx, failure);
+      return;
+    }
+    try {
+      respondJson(ctx, await engine.listDocuments(ctx.params[0], params));
+    } catch (err) {
+      respondError(ctx, err);
+    }
+  }
   async function batch(ctx) {
     const body = parseJson(ctx);
     if (!body) return;
@@ -569,7 +792,7 @@ function createDocumentHandlers(deps) {
       respondError(ctx, err);
     }
   }
-  return { insert, get, exists, put, patch, remove, count, multiGet, batch };
+  return { insert, get, exists, put, patch, remove, count, list, multiGet, batch };
 }
 function indexDocNotFound(docId) {
   return new NarsilError(ErrorCodes.DOC_NOT_FOUND, `Document "${docId}" not found`, { docId });
@@ -593,10 +816,11 @@ function createHealthHandlers(deps) {
 // src/server/ndjson.ts
 var NEWLINE = 10;
 var CARRIAGE_RETURN = 13;
-var NdjsonLineTooLongError = class extends Error {
+var NdjsonLineTooLongError = class extends NarsilError {
   constructor(lineNumber) {
-    super(`NDJSON line ${lineNumber} exceeds the configured per-line size limit`);
-    this.lineNumber = lineNumber;
+    super(ServerErrorCodes.PAYLOAD_TOO_LARGE, `NDJSON line ${lineNumber} exceeds the configured per-line size limit`, {
+      line: lineNumber
+    });
     this.name = "NdjsonLineTooLongError";
   }
 };
@@ -612,7 +836,7 @@ function* iterateNdjson(buffer, maxLineBytes) {
     if (contentEnd > start && buffer[contentEnd - 1] === CARRIAGE_RETURN) contentEnd--;
     if (contentEnd > start) {
       lineNumber++;
-      yield { lineNumber, text: buffer.toString("utf8", start, contentEnd) };
+      yield { lineNumber, text: buffer.toString("utf8", start, contentEnd), bytesConsumed: Math.min(end + 1, length) };
     }
     start = end + 1;
   }
@@ -625,71 +849,110 @@ function yieldToEventLoop() {
 function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+async function runImport(engine, options) {
+  const { indexName, body, maxLineBytes, batchSize, maxErrors, signal, onProgress } = options;
+  const bytesTotal = body.length;
+  const errors = [];
+  let indexed = 0;
+  let failed = 0;
+  let bytesProcessed = 0;
+  let pending = [];
+  const recordFailure = (error) => {
+    failed += 1;
+    if (errors.length < maxErrors) errors.push(error);
+  };
+  const flush = async () => {
+    if (pending.length === 0) return;
+    const documents = pending.map((entry) => entry.document);
+    pending = [];
+    const result = await engine.insertBatch(indexName, documents, { skipClone: true });
+    indexed += result.succeeded.length;
+    for (const failure of result.failed) {
+      const serialized = failure.error instanceof NarsilError ? serializeNarsilError(failure.error) : { code: ServerErrorCodes.INTERNAL_ERROR, message: String(failure.error) };
+      recordFailure({ docId: failure.docId, code: serialized.code, message: serialized.message });
+    }
+  };
+  const report = () => {
+    onProgress?.({ indexed, failed, bytesProcessed, bytesTotal });
+  };
+  for (const line of iterateNdjson(body, maxLineBytes)) {
+    bytesProcessed = line.bytesConsumed;
+    let parsed;
+    try {
+      parsed = JSON.parse(line.text);
+    } catch {
+      recordFailure({ line: line.lineNumber, code: ServerErrorCodes.INVALID_JSON, message: "Line is not valid JSON" });
+      continue;
+    }
+    if (!isPlainObject2(parsed)) {
+      recordFailure({
+        line: line.lineNumber,
+        code: ServerErrorCodes.INVALID_REQUEST,
+        message: "Line is not a JSON object"
+      });
+      continue;
+    }
+    pending.push({ document: parsed, line: line.lineNumber });
+    if (pending.length >= batchSize) {
+      signal?.throwIfAborted();
+      await flush();
+      report();
+      await yieldToEventLoop();
+      signal?.throwIfAborted();
+    }
+  }
+  await flush();
+  bytesProcessed = bytesTotal;
+  report();
+  return { indexed, failed, errors, errorsTruncated: failed > errors.length };
+}
 function createImportHandler(deps) {
-  const { engine, limits } = deps;
+  const { engine, limits, tasks } = deps;
   return async function importNdjson(ctx) {
     const raw = ctx.rawBody;
     if (!raw || raw.length === 0) {
       sendError(ctx.res, 400, ServerErrorCodes.EMPTY_BODY, "Request body is empty");
       return;
     }
-    const name = ctx.params[0];
-    const errors = [];
-    let indexed = 0;
-    let pending = [];
-    const flush = async () => {
-      if (pending.length === 0) return true;
-      const documents = pending.map((p) => p.document);
+    const indexName = ctx.params[0];
+    const runOptions = {
+      indexName,
+      body: raw,
+      maxLineBytes: limits.maxLineBytes,
+      batchSize: limits.importBatchSize,
+      maxErrors: limits.maxImportErrors
+    };
+    if (ctx.query.get("async") === "true") {
       try {
-        const result = await engine.insertBatch(name, documents);
-        indexed += result.succeeded.length;
-        for (const failure of result.failed) {
-          const serialized = failure.error instanceof NarsilError ? serializeNarsilError(failure.error) : { code: "INTERNAL_ERROR", message: String(failure.error) };
-          errors.push({ docId: failure.docId, code: serialized.code, message: serialized.message });
-        }
-        pending = [];
-        return true;
+        await engine.countDocuments(indexName);
       } catch (err) {
         respondError(ctx, err);
-        return false;
+        return;
       }
-    };
-    try {
-      for (const { lineNumber, text } of iterateNdjson(raw, limits.maxLineBytes)) {
-        let parsed;
-        try {
-          parsed = JSON.parse(text);
-        } catch {
-          errors.push({ line: lineNumber, code: ServerErrorCodes.INVALID_JSON, message: "Line is not valid JSON" });
-          continue;
-        }
-        if (!isPlainObject2(parsed)) {
-          errors.push({
-            line: lineNumber,
-            code: ServerErrorCodes.INVALID_REQUEST,
-            message: "Line is not a JSON object"
+      const record = await tasks.start(
+        "import",
+        indexName,
+        async (context) => {
+          const result = await runImport(engine, {
+            ...runOptions,
+            signal: context.signal,
+            onProgress: context.reportProgress
           });
-          continue;
-        }
-        pending.push({ document: parsed, line: lineNumber });
-        if (pending.length >= limits.importBatchSize) {
-          if (!await flush()) return;
-          if (ctx.abort.aborted) return;
-          await yieldToEventLoop();
-          if (ctx.abort.aborted) return;
-        }
-      }
+          context.reportResult(result);
+        },
+        { indexed: 0, failed: 0, bytesProcessed: 0, bytesTotal: raw.length }
+      );
+      respondJson(ctx, record, 202);
+      return;
+    }
+    const controller = new AbortController();
+    ctx.abort.onAbort(() => controller.abort());
+    try {
+      respondJson(ctx, await runImport(engine, { ...runOptions, signal: controller.signal }));
     } catch (err) {
-      if (err instanceof NdjsonLineTooLongError) {
-        sendError(ctx.res, 413, ServerErrorCodes.PAYLOAD_TOO_LARGE, err.message, { line: err.lineNumber });
-        return;
-      }
+      if (ctx.abort.aborted) return;
       respondError(ctx, err);
-      return;
     }
-    if (!await flush()) return;
-    if (ctx.abort.aborted) return;
-    respondJson(ctx, { indexed, failed: errors.length, errors });
   };
 }
 
@@ -924,6 +1187,14 @@ var ConcurrencyGate = class {
     if (this.inFlight > 0) this.inFlight--;
   }
 };
+function decodePathParameter(raw) {
+  if (!raw.includes("%")) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return null;
+  }
+}
 function isDenial(value) {
   return typeof value === "object" && value !== null && "status" in value;
 }
@@ -950,7 +1221,15 @@ function createRouteRunner(deps) {
     const gated = !opts.skipHooks;
     return (res, req) => {
       const params = [];
-      for (let i = 0; i < paramCount; i++) params.push(req.getParameter(i) ?? "");
+      let malformed = null;
+      for (let i = 0; i < paramCount; i++) {
+        const decoded = decodePathParameter(req.getParameter(i) ?? "");
+        if (decoded === null) {
+          malformed = req.getParameter(i) ?? "";
+          break;
+        }
+        params.push(decoded);
+      }
       const query = new URLSearchParams(req.getQuery() ?? "");
       const contentType = req.getHeader("content-type");
       let hookCtx = null;
@@ -968,12 +1247,22 @@ function createRouteRunner(deps) {
       }
       if (writeCors) writeCors(res, req);
       const abort = initAbortHandler(res);
+      if (malformed !== null) {
+        sendError(
+          res,
+          400,
+          ServerErrorCodes.INVALID_REQUEST,
+          "A path segment holds a percent-escape the server cannot decode",
+          { segment: malformed }
+        );
+        return;
+      }
       const bodyPromise = needsBody ? readBody(res, opts.maxBytes, abort) : Promise.resolve(null);
       const hookPromise = hookCtx && onRequest ? runHook(res, hookCtx, onRequest) : Promise.resolve(true);
       Promise.all([bodyPromise, hookPromise]).then(async ([rawBody, allowed]) => {
         if (abort.aborted || !allowed) return;
         if (gated && !gate.tryAcquire()) {
-          sendError(res, 503, ServerErrorCodes.TOO_MANY_REQUESTS, "The server is at capacity; retry shortly");
+          sendError(res, 429, ServerErrorCodes.TOO_MANY_REQUESTS, "The server is at capacity; retry shortly");
           return;
         }
         try {
@@ -1071,14 +1360,38 @@ var InMemoryTaskStore = class {
 };
 var RUNNING_TTL_MS = 24 * 60 * 60 * 1e3;
 var TERMINAL_TTL_MS = 60 * 60 * 1e3;
+var PROGRESS_WRITE_INTERVAL_MS = 250;
+var DEFAULT_TASK_PAGE_SIZE = 20;
+function byNewestFirst(left, right) {
+  if (left.createdAt !== right.createdAt) return right.createdAt - left.createdAt;
+  return left.id.localeCompare(right.id);
+}
+function matchesQuery(record, query) {
+  if (query.indexName !== void 0 && record.indexName !== query.indexName) return false;
+  if (query.type !== void 0 && query.type.length > 0 && !query.type.includes(record.type)) return false;
+  if (query.status !== void 0 && query.status.length > 0 && !query.status.includes(record.status)) return false;
+  return true;
+}
 var TaskRegistry = class {
-  constructor(store, instanceId) {
+  constructor(store, instanceId, maxConcurrent = 0) {
     this.store = store;
     this.instanceId = instanceId;
+    this.maxConcurrent = maxConcurrent;
   }
+  live = /* @__PURE__ */ new Map();
   /** Records a task as running and drives `op` to completion in the background.
-   * Returns the record once it is persisted so the caller can respond 202. */
-  async start(type, indexName, op) {
+   * Returns the record once it is persisted so the caller can respond 202.
+   * @throws A `NarsilError` with `TOO_MANY_REQUESTS` where this instance
+   * already drives {@link ServerLimits.maxConcurrentTasks} tasks, because each
+   * one holds its own working set until it finishes. */
+  async start(type, indexName, op, progress) {
+    if (this.maxConcurrent > 0 && this.live.size >= this.maxConcurrent) {
+      throw new NarsilError(
+        ServerErrorCodes.TOO_MANY_REQUESTS,
+        `This instance already drives ${this.maxConcurrent} tasks; poll one to completion before starting another`,
+        { running: this.live.size, limit: this.maxConcurrent }
+      );
+    }
     const now = Date.now();
     const record = {
       id: randomUUID(),
@@ -1087,17 +1400,54 @@ var TaskRegistry = class {
       owner: this.instanceId,
       status: "running",
       createdAt: now,
-      startedAt: now
+      startedAt: now,
+      ...progress === void 0 ? {} : { progress }
     };
-    await this.store.set(record, RUNNING_TTL_MS);
-    void this.drive(record, op);
+    const task = {
+      record,
+      controller: new AbortController(),
+      writes: Promise.resolve(),
+      lastProgressWriteAt: now,
+      settled: false
+    };
+    this.live.set(record.id, task);
+    await this.enqueueWrite(task, record, RUNNING_TTL_MS);
+    void this.drive(task, op);
     return record;
   }
   get(id) {
     return this.store.get(id);
   }
-  list() {
-    return this.store.list();
+  /** Reads one page of task records, newest first, keeping only what the query
+   * matches. Filtering happens here rather than in the store, so every custom
+   * {@link TaskStore} works unchanged. */
+  async list(query = {}) {
+    const from = Math.max(0, Math.trunc(query.from ?? 0));
+    const limit = Math.max(1, Math.trunc(query.limit ?? DEFAULT_TASK_PAGE_SIZE));
+    const matched = (await this.store.list()).filter((record) => matchesQuery(record, query)).sort(byNewestFirst);
+    const page = matched.slice(from, from + limit);
+    const consumed = from + page.length;
+    return { tasks: page, total: matched.length, from, limit, next: consumed < matched.length ? consumed : null };
+  }
+  /** Asks a running task to stop. The work stops between units, so the task
+   * reaches `cancelled` only once it actually stopped, and a request that
+   * arrives too late leaves it `succeeded`. */
+  async cancel(id) {
+    const stored = await this.store.get(id);
+    if (!stored) return { outcome: "not-found", record: null };
+    if (stored.status !== "running" && stored.status !== "queued") {
+      return { outcome: "already-finished", record: stored };
+    }
+    const task = this.live.get(id);
+    if (!task) {
+      const outcome = stored.owner === this.instanceId ? "already-finished" : "owned-by-another-instance";
+      return { outcome, record: stored };
+    }
+    task.controller.abort(new Error("The task was cancelled"));
+    const record = { ...task.record, cancelRequestedAt: Date.now() };
+    task.record = record;
+    await this.enqueueWrite(task, record, RUNNING_TTL_MS);
+    return { outcome: "cancelling", record };
   }
   /** Fails this instance's previously-running tasks after a restart. A task can
    * only be advanced by the process that owns it, so its own running tasks from
@@ -1127,20 +1477,45 @@ var TaskRegistry = class {
       }
     }
   }
-  async drive(record, op) {
-    const result = { ...record };
+  enqueueWrite(task, record, ttlMs) {
+    task.writes = task.writes.then(
+      () => this.store.set(record, ttlMs),
+      () => this.store.set(record, ttlMs)
+    );
+    return task.writes.catch(() => {
+    });
+  }
+  reportProgress(task, progress) {
+    if (task.settled) return;
+    task.record = { ...task.record, progress };
+    const now = Date.now();
+    if (now - task.lastProgressWriteAt < PROGRESS_WRITE_INTERVAL_MS) return;
+    task.lastProgressWriteAt = now;
+    void this.enqueueWrite(task, task.record, RUNNING_TTL_MS);
+  }
+  async drive(task, op) {
+    const context = {
+      signal: task.controller.signal,
+      reportProgress: (progress) => this.reportProgress(task, progress),
+      reportResult: (result) => {
+        task.record = { ...task.record, result };
+      }
+    };
+    let settled;
     try {
-      await op();
-      result.status = "succeeded";
+      await op(context);
+      settled = { ...task.record, status: "succeeded" };
     } catch (err) {
-      result.status = "failed";
-      result.error = err instanceof NarsilError ? serializeNarsilError(err) : { code: "INTERNAL_ERROR", message: "The operation failed" };
-    }
-    result.completedAt = Date.now();
-    try {
-      await this.store.set(result, TERMINAL_TTL_MS);
-    } catch {
+      settled = task.controller.signal.aborted ? { ...task.record, status: "cancelled" } : {
+        ...task.record,
+        status: "failed",
+        error: err instanceof NarsilError ? serializeNarsilError(err) : { code: "INTERNAL_ERROR", message: "The operation failed" }
+      };
     }
+    task.settled = true;
+    task.record = { ...settled, completedAt: Date.now() };
+    await this.enqueueWrite(task, task.record, TERMINAL_TTL_MS);
+    this.live.delete(task.record.id);
   }
 };
 
@@ -1154,7 +1529,10 @@ function resolveLimits(limits) {
     importBatchSize: limits?.importBatchSize ?? 1e3,
     maxConcurrentRequests: limits?.maxConcurrentRequests ?? 0,
     maxResultWindow: limits?.maxResultWindow ?? 1e4,
-    maxFetchDocuments: limits?.maxFetchDocuments ?? 1e4
+    maxFetchDocuments: limits?.maxFetchDocuments ?? 1e4,
+    maxImportErrors: limits?.maxImportErrors ?? 100,
+    maxTaskPageSize: limits?.maxTaskPageSize ?? 1e3,
+    maxConcurrentTasks: limits?.maxConcurrentTasks ?? 4
   };
 }
 function resolveBuild(build) {
@@ -1192,10 +1570,11 @@ var NarsilHttpServer = class {
     }
     const taskStore = options.taskStore ?? new InMemoryTaskStore();
     const instanceId = options.instanceId ?? randomUUID();
+    const limits = resolveLimits(options.limits);
     this.deps = {
       engine,
-      tasks: new TaskRegistry(taskStore, instanceId),
-      limits: resolveLimits(options.limits),
+      tasks: new TaskRegistry(taskStore, instanceId, limits.maxConcurrentTasks),
+      limits,
       isReady: () => this.ready,
       build: resolveBuild(options.build)
     };
@@ -1244,6 +1623,7 @@ var NarsilHttpServer = class {
     const admin = createAdminHandlers(this.deps);
     const health = createHealthHandlers(this.deps);
     const version = createVersionHandler(this.deps);
+    const capabilities = createCapabilitiesHandler();
     const importNdjson = createImportHandler(this.deps);
     const json = (handler, opts) => run(handler, opts);
     if (cors) {
@@ -1260,9 +1640,11 @@ var NarsilHttpServer = class {
     app.get("/readyz", json(health.readyz, { maxBytes: 0, skipHooks: true }));
     app.get("/health", json(health.livez, { maxBytes: 0, skipHooks: true }));
     app.get("/version", json(version.report, { maxBytes: 0, skipHooks: true }));
+    app.get("/capabilities", json(capabilities.report, { maxBytes: 0, skipHooks: true }));
     app.get("/stats/memory", json(admin.memory, { maxBytes: 0 }));
     app.get("/tasks", json(admin.listTasks, { maxBytes: 0 }));
     app.get("/tasks/:id", json(admin.getTask, { paramCount: 1, maxBytes: 0 }));
+    app.post("/tasks/:id/_cancel", json(admin.cancelTask, { paramCount: 1, maxBytes: 0 }));
     app.post("/indexes", json(idx.create, { needsBody: true, maxBytes: maxBodyBytes }));
     app.get("/indexes", json(idx.list, { maxBytes: 0 }));
     app.del("/indexes/:name", json(idx.drop, { paramCount: 1, maxBytes: 0 }));
@@ -1275,6 +1657,10 @@ var NarsilHttpServer = class {
       "/indexes/:name/documents/_batch",
       json(doc.batch, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
     );
+    app.post(
+      "/indexes/:name/documents/_list",
+      json(doc.list, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
+    );
     app.post(
       "/indexes/:name/documents/_multi-get",
       json(doc.multiGet, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes })
@@ -1298,6 +1684,7 @@ var NarsilHttpServer = class {
     );
     app.post("/indexes/:name/suggest", json(search.suggest, { paramCount: 1, needsBody: true, maxBytes: maxBodyBytes }));
     app.post("/indexes/:name/_checkpoint", json(admin.checkpoint, { paramCount: 1, maxBytes: 0 }));
+    app.post("/indexes/:name/_rebuild-analysis", json(admin.rebuildAnalysis, { paramCount: 1, maxBytes: 0 }));
     app.get("/indexes/:name/snapshot", json(admin.snapshot, { paramCount: 1, maxBytes: 0 }));
     app.get("/indexes/:name/vector-maintenance", json(admin.vectorMaintenance, { paramCount: 1, maxBytes: 0 }));
     app.post(
@@ -1329,4 +1716,4 @@ function createServer(engine, options) {
   return new NarsilHttpServer(engine, options);
 }
 
-export { InMemoryTaskStore, ServerErrorCodes, createServer, httpStatusForNarsilError };
+export { ASYNC_IMPORT_CAPABILITY, InMemoryTaskStore, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createServer, httpStatusForNarsilError };