@hiai-gg/docsmint 0.7.6 → 0.8.2

package/dist/backend/index.js

@@ -45791,6 +45791,8 @@ var init_schema2 = __esm(() => {
     completedBatches: integer("completed_batches").notNull().default(0),
     failedBatches: integer("failed_batches").notNull().default(0),
     errorCode: text("error_code"),
+    graphErrorCode: text("graph_error_code"),
+    summarizeErrorCode: text("summarize_error_code"),
     attempts: integer("attempts").notNull().default(0),
     requestedAt: timestamp("requested_at").defaultNow().notNull(),
     startedAt: timestamp("started_at"),
@@ -79815,10 +79817,26 @@ var init_kysely_adapter = __esm(() => {
   init_dist3();
 });
 
+// ../../backend/src/lib/openrouter-public-matrix.ts
+var OPENROUTER_PUBLIC_BASE_URL = "https://openrouter.ai/api/v1", OPENROUTER_PUBLIC_EXPANSION_MODELS, OPENROUTER_PUBLIC_RERANK_MODELS;
+var init_openrouter_public_matrix = __esm(() => {
+  OPENROUTER_PUBLIC_EXPANSION_MODELS = {
+    primary: "poolside/laguna-xs-2.1",
+    fallback: "openai/gpt-5.6-luna",
+    fallback_2: "google/gemini-3.5-flash-lite"
+  };
+  OPENROUTER_PUBLIC_RERANK_MODELS = {
+    primary: "voyageai/rerank-2.5",
+    fallback: "cohere/rerank-v3.5",
+    fallback_2: "nvidia/llama-nemotron-rerank-vl-1b-v2:free"
+  };
+});
+
 // ../../backend/src/lib/config-schema.ts
 var adminApiKeyPlaceholder, envSchema;
 var init_config_schema = __esm(() => {
   init_zod();
+  init_openrouter_public_matrix();
   adminApiKeyPlaceholder = /^(?:change[-_ ]?me|changeme|your[-_ ]?api[-_ ]?key)(?:\b|[-_ ])/i;
   envSchema = exports_external2.object({
     DATABASE_URL: exports_external2.string().default("postgresql://hiai_app:changeme@localhost:5437/hiai_docs"),
@@ -79875,6 +79893,9 @@ var init_config_schema = __esm(() => {
     EMBEDDING_FALLBACK_BASE_URL: exports_external2.string().optional(),
     EMBEDDING_FALLBACK_API_KEY: exports_external2.string().optional(),
     EMBEDDING_FALLBACK_MODEL: exports_external2.string().optional(),
+    EMBEDDING_FALLBACK_2_BASE_URL: exports_external2.string().optional(),
+    EMBEDDING_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    EMBEDDING_FALLBACK_2_MODEL: exports_external2.string().optional(),
     API_PORT: exports_external2.coerce.number().default(50700),
     NODE_ENV: exports_external2.enum(["development", "production", "test"]).default("development"),
     LOG_LEVEL: exports_external2.enum(["trace", "debug", "info", "warn", "error", "fatal"]).default("info"),
@@ -79901,14 +79922,34 @@ var init_config_schema = __esm(() => {
     GRAPH_EXTRACT_FALLBACK_BASE_URL: exports_external2.string().optional(),
     GRAPH_EXTRACT_FALLBACK_API_KEY: exports_external2.string().optional(),
     GRAPH_EXTRACT_FALLBACK_MODEL: exports_external2.string().optional(),
+    GRAPH_EXTRACT_FALLBACK_2_BASE_URL: exports_external2.string().optional(),
+    GRAPH_EXTRACT_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    GRAPH_EXTRACT_FALLBACK_2_MODEL: exports_external2.string().optional(),
     GRAPH_EXTRACT_MIN_CONFIDENCE: exports_external2.coerce.number().min(0).max(1).default(0.5),
     SEARCH_EXPANSION_ENABLED: exports_external2.string().optional().default("true").transform((v2) => v2 === "true"),
-    SEARCH_EXPANSION_BASE_URL: exports_external2.string().default("https://openrouter.ai/api/v1"),
+    SEARCH_EXPANSION_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
     SEARCH_EXPANSION_API_KEY: exports_external2.string().optional(),
-    SEARCH_EXPANSION_MODEL: exports_external2.string().default("mistralai/ministral-14b-2512"),
-    SEARCH_EXPANSION_FALLBACK_BASE_URL: exports_external2.string().default("https://openrouter.ai/api/v1"),
+    SEARCH_EXPANSION_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.primary),
+    SEARCH_EXPANSION_FALLBACK_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
     SEARCH_EXPANSION_FALLBACK_API_KEY: exports_external2.string().optional(),
-    SEARCH_EXPANSION_FALLBACK_MODEL: exports_external2.string().default("google/gemma-4-31b-it"),
+    SEARCH_EXPANSION_FALLBACK_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.fallback),
+    SEARCH_EXPANSION_FALLBACK_2_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_EXPANSION_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    SEARCH_EXPANSION_FALLBACK_2_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.fallback_2),
+    SEARCH_RERANK_ENABLED: exports_external2.string().optional().default("true").transform((v2) => v2 === "true"),
+    SEARCH_RERANK_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_RERANK_API_KEY: exports_external2.string().optional(),
+    SEARCH_RERANK_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.primary),
+    SEARCH_RERANK_FALLBACK_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_RERANK_FALLBACK_API_KEY: exports_external2.string().optional(),
+    SEARCH_RERANK_FALLBACK_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.fallback),
+    SEARCH_RERANK_FALLBACK_2_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_RERANK_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    SEARCH_RERANK_FALLBACK_2_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.fallback_2),
+    SEARCH_RERANK_TIMEOUT_MS: exports_external2.coerce.number().int().min(250).max(30000).default(3000),
+    SEARCH_RERANK_TOP_N: exports_external2.coerce.number().int().min(1).max(100).default(20),
+    SEARCH_RERANK_MAX_CHARS: exports_external2.coerce.number().int().min(120).max(8000).default(1500),
+    SEARCH_RERANK_GRAPH_POSITION: exports_external2.enum(["before", "after"]).default("after"),
     SEARCH_EXPANSION_TIMEOUT_MS: exports_external2.coerce.number().int().min(1000).max(300000).default(6000),
     SEARCH_VECTOR_PROVIDER_TIMEOUT_MS: exports_external2.coerce.number().int().min(250).max(30000).default(2500),
     SEARCH_EXPANSION_CACHE_TTL_SECONDS: exports_external2.coerce.number().int().min(0).max(2592000).default(86400),
@@ -195670,6 +195711,10 @@ var METRIC_NAMES = {
   SEARCH_EXPANSION_LOW_VECTOR_SIMILARITY_TOTAL: "search_expansion_reason_low_vector_similarity_total",
   SEARCH_EXPANSION_LANGUAGE_MISMATCH_TOTAL: "search_expansion_reason_language_mismatch_total",
   SEARCH_EXPANSION_EMPTY_CANDIDATES_TOTAL: "search_expansion_reason_empty_candidates_total",
+  SEARCH_RERANK_DURATION_MS: "search_rerank_duration_ms",
+  SEARCH_RERANK_SUCCESS_TOTAL: "search_rerank_success_total",
+  SEARCH_RERANK_FALLBACK_TOTAL: "search_rerank_fallback_total",
+  SEARCH_RERANK_CANDIDATES_TOTAL: "search_rerank_candidates_total",
   SEARCH_EXACT_DURATION_MS: "search_exact_duration_ms",
   SEARCH_EXACT_ERRORS_TOTAL: "search_exact_errors_total",
   SEARCH_EXACT_CANDIDATES_TOTAL: "search_exact_candidates_total",
@@ -195841,7 +195886,7 @@ function recordSearchExpansionMetrics(input) {
         break;
     }
   }
-  if (input.used !== false && input.model && input.model === input.fallbackModel) {
+  if (input.used !== false && input.model && (input.model === input.fallbackModel || input.model === input.fallback2Model)) {
     incrementCounter(METRIC_NAMES.SEARCH_EXPANSION_FALLBACK_TOTAL);
   } else if (input.used !== false && input.model) {
     incrementCounter(METRIC_NAMES.SEARCH_EXPANSION_PRIMARY_TOTAL);
@@ -196176,31 +196221,52 @@ async function getEmbedding(text3) {
     recordDuration(METRIC_NAMES.EMBEDDING_DURATION_MS, Date.now() - start);
   }
 }
-async function getEmbeddingInner(text3) {
-  const providers = [];
-  if (config3.EMBEDDING_BASE_URL && config3.EMBEDDING_MODEL) {
-    providers.push({
+function configuredEmbeddingProviders() {
+  const slots = [
+    {
       baseUrl: config3.EMBEDDING_BASE_URL,
       apiKey: config3.EMBEDDING_API_KEY,
       model: config3.EMBEDDING_MODEL,
       provider: "primary"
-    });
-  }
-  if (config3.EMBEDDING_FALLBACK_BASE_URL && config3.EMBEDDING_FALLBACK_MODEL) {
-    providers.push({
+    },
+    {
       baseUrl: config3.EMBEDDING_FALLBACK_BASE_URL,
       apiKey: config3.EMBEDDING_FALLBACK_API_KEY,
       model: config3.EMBEDDING_FALLBACK_MODEL,
       provider: "fallback"
-    });
-  }
+    },
+    {
+      baseUrl: config3.EMBEDDING_FALLBACK_2_BASE_URL,
+      apiKey: config3.EMBEDDING_FALLBACK_2_API_KEY,
+      model: config3.EMBEDDING_FALLBACK_2_MODEL,
+      provider: "fallback_2"
+    }
+  ];
+  return slots.flatMap((slot) => slot.baseUrl && slot.model ? [
+    {
+      baseUrl: slot.baseUrl,
+      apiKey: slot.apiKey,
+      model: slot.model,
+      provider: slot.provider
+    }
+  ] : []);
+}
+function assignProviderError(provider, message2, errors6) {
+  if (provider === "primary")
+    errors6.primaryError = message2;
+  else if (provider === "fallback")
+    errors6.fallbackError = message2;
+  else
+    errors6.fallback2Error = message2;
+}
+async function getEmbeddingInner(text3) {
+  const providers = configuredEmbeddingProviders();
   if (providers.length === 0) {
     logger3.warn("No embedding provider configured (primary or fallback); embedding result is unavailable");
     incrementCounter(METRIC_NAMES.EMBEDDING_ZERO);
     return { ok: false, code: "not_configured" };
   }
-  let primaryError;
-  let fallbackError;
+  const errors6 = {};
   let finalCode = "provider_error";
   for (const provider of providers) {
     try {
@@ -196208,11 +196274,7 @@ async function getEmbeddingInner(text3) {
       const validation = validateEmbeddingVector(vector5);
       if (!validation.ok) {
         finalCode = validation.code;
-        const message2 = `provider returned ${validation.code}`;
-        if (provider.provider === "primary")
-          primaryError = message2;
-        else
-          fallbackError = message2;
+        assignProviderError(provider.provider, `provider returned ${validation.code}`, errors6);
         logger3.warn({
           model: provider.model,
           provider: provider.provider,
@@ -196235,11 +196297,7 @@ async function getEmbeddingInner(text3) {
       };
     } catch (err) {
       finalCode = failureCodeFromError(err);
-      const message2 = safeErrorMessage(err);
-      if (provider.provider === "primary")
-        primaryError = message2;
-      else
-        fallbackError = message2;
+      assignProviderError(provider.provider, safeErrorMessage(err), errors6);
       logger3.warn({ err, model: provider.model, provider: provider.provider }, "Embedding provider failed, trying next configured provider");
     }
   }
@@ -196247,8 +196305,7 @@ async function getEmbeddingInner(text3) {
   return {
     ok: false,
     code: finalCode,
-    ...primaryError ? { primaryError } : {},
-    ...fallbackError ? { fallbackError } : {}
+    ...errors6
   };
 }
 function safeErrorMessage(error53) {
@@ -196359,7 +196416,8 @@ var basePipelineJobFields = {
   requestedAt: exports_external2.iso.datetime(),
   source: pipelineSourceSchema,
   refreshMode: pipelineRefreshModeSchema,
-  embeddingContextHash: exports_external2.string().min(1).optional()
+  embeddingContextHash: exports_external2.string().min(1).optional(),
+  warningRetry: exports_external2.literal(true).optional()
 };
 function normalizeLegacyPipelineJob(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
@@ -228592,6 +228650,33 @@ function encodeS3CopySource(bucket, key) {
 // ../../backend/src/api/routes/documents.ts
 init_logger3();
 
+// ../../backend/src/lib/pipeline-error.ts
+class PipelineProviderError extends Error {
+  code;
+  retryable;
+  constructor(code2, retryable, message2 = code2) {
+    super(message2);
+    this.code = code2;
+    this.retryable = retryable;
+    this.name = "PipelineProviderError";
+  }
+}
+function pipelineErrorCode(error53, fallback) {
+  if (error53 instanceof PipelineProviderError)
+    return error53.code;
+  return fallback;
+}
+function isRetryablePipelineError(code2) {
+  return new Set([
+    "provider_failure",
+    "provider_timeout",
+    "invalid_provider_response",
+    "queue_enqueue_failed",
+    "age_unavailable",
+    "age_persist_failed"
+  ]).has(code2);
+}
+
 // ../../backend/src/lib/version-prune.ts
 init_schema2();
 init_drizzle_orm();
@@ -228627,6 +228712,30 @@ async function maybePruneVersions(documentId) {
 }
 
 // ../../backend/src/api/routes/documents.ts
+init_names();
+
+// ../../backend/src/queue/pipeline-warning-retry.ts
+function resolveActiveWarningRetry(stageStarted, retryJobExists) {
+  if (!stageStarted)
+    return "enqueue";
+  return retryJobExists ? "deduplicate" : "conflict";
+}
+function warningRetryJobId(stage, generationId) {
+  return `${stage}-warning-retry-${generationId}`;
+}
+function summaryJobIdForPipeline(job2) {
+  return job2.warningRetry ? warningRetryJobId("summarize", job2.generationId) : JOB_IDS.summarize(job2.generationId, job2.workspaceId);
+}
+function planWarningStageRetry(state) {
+  const graph = state.graphStatus === "failed" && isRetryablePipelineError(state.graphErrorCode ?? "graph_failed");
+  const summarize = state.summarizeStatus === "failed" && isRetryablePipelineError(state.summarizeErrorCode ?? "summary_failed");
+  if (!graph && !summarize)
+    return null;
+  return { graph, summarize, entryStage: graph ? "graph" : "summarize" };
+}
+
+// ../../backend/src/api/routes/documents.ts
+init_queues();
 class DocumentPurgeNotFoundError extends Error {
   constructor() {
     super("document_purge_not_found");
@@ -229182,6 +229291,8 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       embedStatus: documentPipelineRuns.embedStatus,
       graphStatus: documentPipelineRuns.graphStatus,
       summarizeStatus: documentPipelineRuns.summarizeStatus,
+      graphErrorCode: documentPipelineRuns.graphErrorCode,
+      summarizeErrorCode: documentPipelineRuns.summarizeErrorCode,
       finalizeStatus: documentPipelineRuns.finalizeStatus,
       totalBatches: documentPipelineRuns.totalBatches,
       completedBatches: documentPipelineRuns.completedBatches,
@@ -229211,6 +229322,22 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
         completed: run3.completedBatches,
         failed: run3.failedBatches
       },
+      warnings: [
+        ...run3.graphStatus === "failed" ? [
+          {
+            stage: "graph",
+            code: run3.graphErrorCode ?? "graph_failed",
+            retryable: isRetryablePipelineError(run3.graphErrorCode ?? "graph_failed")
+          }
+        ] : [],
+        ...run3.summarizeStatus === "failed" ? [
+          {
+            stage: "summarize",
+            code: run3.summarizeErrorCode ?? "summary_failed",
+            retryable: isRetryablePipelineError(run3.summarizeErrorCode ?? "summary_failed")
+          }
+        ] : []
+      ],
       updatedAt: run3.updatedAt
     };
   } catch (err) {
@@ -229218,6 +229345,194 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
     set2.status = 500;
     return { error: "Failed to load pipeline progress" };
   }
+}).post("/documents/:id/pipeline/retry-warnings", async ({ params: params2, set: set2, request }) => {
+  const parsedParams = documentIdParamsSchema.safeParse(params2);
+  if (!parsedParams.success) {
+    set2.status = 400;
+    return { error: "Invalid document id" };
+  }
+  const documentId = parsedParams.data.id;
+  const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "unknown";
+  const rl = await writeRateLimiter(ip, request);
+  if (!rl.allowed) {
+    set2.status = 429;
+    set2.headers = rateLimitHeaders(0, rl.retryAfter);
+    return { error: "Too many requests" };
+  }
+  set2.headers = rateLimitHeaders(rl.remaining);
+  const access = await resolveContentAccess(request);
+  const ctx = access.ctx;
+  if (ctx.role === "none") {
+    set2.status = 401;
+    return { error: "Unauthorized" };
+  }
+  if (!canAccessContent(access, "write")) {
+    set2.status = 403;
+    return { error: "Forbidden" };
+  }
+  let claimed;
+  try {
+    const retry2 = await withTenant(ctx, async (tx) => {
+      await acquireDocumentPipelineLock(tx, documentId);
+      const [run3] = await tx.select({
+        status: documentPipelineRuns.status,
+        generationId: documentPipelineRuns.generationId,
+        revision: documentPipelineRuns.revision,
+        ownerId: documentPipelineRuns.ownerId,
+        workspaceId: documentPipelineRuns.workspaceId,
+        refreshMode: documentPipelineRuns.refreshMode,
+        embeddingContextHash: documentPipelineRuns.embeddingContextHash,
+        embedStatus: documentPipelineRuns.embedStatus,
+        graphStatus: documentPipelineRuns.graphStatus,
+        summarizeStatus: documentPipelineRuns.summarizeStatus,
+        graphErrorCode: documentPipelineRuns.graphErrorCode,
+        summarizeErrorCode: documentPipelineRuns.summarizeErrorCode
+      }).from(documentPipelineRuns).innerJoin(documents, and(eq(documents.id, documentPipelineRuns.documentId), eq(documents.activeEmbeddingGeneration, documentPipelineRuns.generationId), eq(documents.contentHash, documentPipelineRuns.revision))).where(and(eq(documentPipelineRuns.documentId, documentId), tenantOwnerCondition(documents.ownerId, documents.workspaceId, ctx), eq(documentPipelineRuns.embedStatus, "ready"), isNull(documents.deletedAt), ...access.restricted ? [
+        access.categoryId ? effectiveDocumentCategoryCondition(documents.categoryId, documents.folderId, ctx, access.categoryId) : sql`false`
+      ] : [])).orderBy(desc(documentPipelineRuns.updatedAt)).limit(1).for("update");
+      if (!run3)
+        return null;
+      if (run3.status === "processing") {
+        const graph2 = ["retrying", "processing"].includes(run3.graphStatus);
+        const summarize2 = ["retrying", "processing"].includes(run3.summarizeStatus);
+        return graph2 || summarize2 ? {
+          ...run3,
+          graph: graph2,
+          summarize: summarize2,
+          deduplicated: true,
+          stageStarted: run3.graphStatus === "processing" || run3.summarizeStatus === "processing"
+        } : null;
+      }
+      if (run3.status !== "ready_with_warnings")
+        return null;
+      const plan = planWarningStageRetry(run3);
+      if (!plan)
+        return null;
+      const { graph, summarize } = plan;
+      await tx.update(documentPipelineRuns).set({
+        status: "processing",
+        finalizeStatus: "pending",
+        ...graph ? { graphStatus: "retrying", graphErrorCode: null } : {},
+        ...summarize ? {
+          summarizeStatus: "retrying",
+          summarizeErrorCode: null
+        } : {},
+        updatedAt: new Date
+      }).where(eq(documentPipelineRuns.generationId, run3.generationId));
+      return {
+        ...run3,
+        graph,
+        summarize,
+        deduplicated: false,
+        stageStarted: false
+      };
+    });
+    if (!retry2) {
+      set2.status = 409;
+      return { error: "No retryable warning stages" };
+    }
+    if (!retry2.deduplicated)
+      claimed = retry2;
+    const stage = retry2.graph ? "graph" : "summarize";
+    const retryJobId = warningRetryJobId(stage, retry2.generationId);
+    const staleJobs = [
+      ...retry2.graph ? [
+        [
+          "graph",
+          JOB_IDS.graph(retry2.generationId, retry2.workspaceId ?? undefined)
+        ]
+      ] : [],
+      ...retry2.summarize ? [
+        [
+          "summarize",
+          JOB_IDS.summarize(retry2.generationId, retry2.workspaceId ?? undefined)
+        ]
+      ] : [],
+      [
+        "finalize",
+        JOB_IDS.finalize(retry2.generationId, retry2.workspaceId ?? undefined)
+      ]
+    ];
+    if (!retry2.deduplicated) {
+      for (const [queuedStage, jobId] of staleJobs) {
+        const oldJob = await getPipelineQueue(queuedStage, config3.REDIS_URL).getJob(jobId);
+        await oldJob?.remove();
+      }
+    }
+    const queue2 = getPipelineQueue(stage, config3.REDIS_URL);
+    const existingRetryJob = await queue2.getJob(retryJobId);
+    if (retry2.deduplicated) {
+      const activeRetry = resolveActiveWarningRetry(retry2.stageStarted, Boolean(existingRetryJob));
+      if (activeRetry === "conflict") {
+        set2.status = 409;
+        return { error: "No retryable warning stages" };
+      }
+      if (activeRetry === "deduplicate")
+        return {
+          documentId,
+          generationId: retry2.generationId,
+          deduplicated: true,
+          retriedStages: [
+            ...retry2.graph ? ["graph"] : [],
+            ...retry2.summarize ? ["summarize"] : []
+          ]
+        };
+    }
+    const existingRetryState = await existingRetryJob?.getState();
+    if (existingRetryState === "completed" || existingRetryState === "failed") {
+      await existingRetryJob?.remove();
+    }
+    const data = {
+      schemaVersion: PIPELINE_SCHEMA_VERSION,
+      stage,
+      documentId,
+      ownerId: retry2.ownerId,
+      ...retry2.workspaceId ? { workspaceId: retry2.workspaceId } : {},
+      generationId: retry2.generationId,
+      revision: retry2.revision,
+      requestedAt: new Date().toISOString(),
+      source: "api",
+      refreshMode: retry2.refreshMode === "incremental" ? "incremental" : "full",
+      ...retry2.embeddingContextHash ? { embeddingContextHash: retry2.embeddingContextHash } : {},
+      warningRetry: true
+    };
+    await queue2.add(stage, data, {
+      ...DEFAULT_JOB_OPTIONS,
+      jobId: retryJobId,
+      priority: SOURCE_PRIORITY.api
+    });
+    return {
+      documentId,
+      generationId: retry2.generationId,
+      deduplicated: retry2.deduplicated,
+      retriedStages: [
+        ...retry2.graph ? ["graph"] : [],
+        ...retry2.summarize ? ["summarize"] : []
+      ]
+    };
+  } catch (err) {
+    const failedClaim = claimed;
+    if (failedClaim) {
+      await withTenant(ctx, (tx) => tx.update(documentPipelineRuns).set({
+        status: "ready_with_warnings",
+        finalizeStatus: "ready",
+        ...failedClaim.graph ? {
+          graphStatus: "failed",
+          graphErrorCode: "queue_enqueue_failed"
+        } : {},
+        ...failedClaim.summarize ? {
+          summarizeStatus: "failed",
+          summarizeErrorCode: "queue_enqueue_failed"
+        } : {},
+        updatedAt: new Date
+      }).where(and(eq(documentPipelineRuns.generationId, failedClaim.generationId), eq(documentPipelineRuns.status, "processing")))).catch(() => {
+        return;
+      });
+    }
+    logger3.error({ err, documentId }, "Failed to retry warning stages");
+    set2.status = 500;
+    return { error: "Failed to retry warning stages" };
+  }
 }).get("/documents/:id/knowledge-summary", async ({ params: params2, set: set2, request }) => {
   const parsedParams = documentIdParamsSchema.safeParse(params2);
   if (!parsedParams.success) {
@@ -229307,6 +229622,8 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       embedStatus: documentPipelineRuns.embedStatus,
       graphStatus: documentPipelineRuns.graphStatus,
       summarizeStatus: documentPipelineRuns.summarizeStatus,
+      graphErrorCode: documentPipelineRuns.graphErrorCode,
+      summarizeErrorCode: documentPipelineRuns.summarizeErrorCode,
       finalizeStatus: documentPipelineRuns.finalizeStatus,
       totalBatches: documentPipelineRuns.totalBatches,
       completedBatches: documentPipelineRuns.completedBatches,
@@ -229350,6 +229667,22 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
         completed: run3.completedBatches,
         failed: run3.failedBatches
       },
+      warnings: [
+        ...run3.graphStatus === "failed" ? [
+          {
+            stage: "graph",
+            code: run3.graphErrorCode ?? "graph_failed",
+            retryable: isRetryablePipelineError(run3.graphErrorCode ?? "graph_failed")
+          }
+        ] : [],
+        ...run3.summarizeStatus === "failed" ? [
+          {
+            stage: "summarize",
+            code: run3.summarizeErrorCode ?? "summary_failed",
+            retryable: isRetryablePipelineError(run3.summarizeErrorCode ?? "summary_failed")
+          }
+        ] : []
+      ],
       updatedAt: run3.updatedAt
     } : null
   };
@@ -231076,8 +231409,9 @@ async function expandFromQueryPlan(plan, limit = 20) {
   const boundedLimit = Math.max(1, Math.min(Math.floor(limit), 100));
   try {
     const cypher = buildQuerySeedCypher(terms, boundedLimit);
-    const queryString = buildCypherSql(cypher, "neighbor_id agtype, generation_id agtype, relation agtype, hops agtype");
-    const rows = await sql6.unsafe(queryString);
+    const rows = await runCypher(sql6, cypher, {
+      columns: "neighbor_id agtype, generation_id agtype, relation agtype, hops agtype"
+    });
     const seen = new Set;
     const out = [];
     for (const row of rows) {
@@ -231112,8 +231446,9 @@ async function expandResults(docIds, maxHops = DEFAULT_MAX_HOPS) {
   const sql6 = await getGraphDbRequired();
   try {
     const cypher = buildTraversalCypher(seeds, clampedHops);
-    const queryString = buildCypherSql(cypher, "seed_id agtype, seed_generation_id agtype, neighbor_id agtype, generation_id agtype, relation agtype, hops agtype");
-    const rows = await sql6.unsafe(queryString);
+    const rows = await runCypher(sql6, cypher, {
+      columns: "seed_id agtype, seed_generation_id agtype, neighbor_id agtype, generation_id agtype, relation agtype, hops agtype"
+    });
     for (const row of rows) {
       const seedId = stripQuotes(String(row.seed_id ?? ""));
       const neighborId = stripQuotes(String(row.neighbor_id ?? ""));
@@ -231185,6 +231520,13 @@ function buildCypherSql(cypher, columns2) {
   const quoted = `$${tag2}$ ${cypher} $${tag2}$`;
   return `SELECT * FROM cypher('docs_graph', ${quoted}) AS (${columns2})`;
 }
+async function runCypher(sql6, cypher, options) {
+  const queryString = buildCypherSql(cypher, options.columns);
+  return sql6.begin(async (tx) => {
+    await tx.unsafe("SET LOCAL search_path = ag_catalog, public");
+    return await tx.unsafe(queryString);
+  });
+}
 function stripQuotes(value) {
   const trimmed = value.trim();
   if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
@@ -231571,7 +231913,7 @@ function createHealthRoutes(dependencies) {
       set2.status = 503;
     return {
       status: readiness.status === "unhealthy" ? "unhealthy" : "ok",
-      service: "hiai-docs",
+      service: "docsmint",
       timestamp: new Date().toISOString(),
       database: databaseAvailable ? "ok" : "error",
       redis: redisAvailable ? "ok" : "error",
@@ -231876,9 +232218,10 @@ async function retrieveGraphCandidates(ctx, request, adapters = {}) {
   const requestedSeeds = dedupe2(request.documentSeeds).slice(0, config3.SEARCH_GRAPH_SEED_LIMIT);
   const visibilityScope = request.visibilityScope ?? _buildGraphVisibilityScope(ctx);
   const tenantTransaction = adapters.withTenant ?? withTenant;
-  const authorizedSeeds = requestedSeeds.length === 0 ? new Set : await resolveVisibleIds(ctx, requestedSeeds, adapters.visibleDocumentIds, visibilityScope, request.categoryId, tenantTransaction);
+  const categoryId = visibilityScope.kind === "share" ? undefined : request.categoryId;
+  const authorizedSeeds = requestedSeeds.length === 0 ? new Set : await resolveVisibleIds(ctx, requestedSeeds, adapters.visibleDocumentIds, visibilityScope, categoryId, tenantTransaction);
   const seeds = requestedSeeds.filter((id3) => authorizedSeeds.has(id3));
-  const activeSeedGenerations = await resolveActiveGenerations(ctx, seeds, adapters.visibleDocumentGenerations, visibilityScope, request.categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
+  const activeSeedGenerations = await resolveActiveGenerations(ctx, seeds, adapters.visibleDocumentGenerations, visibilityScope, categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
   const expand2 = adapters.expandResults ?? expandResults;
   const expandQuery = adapters.expandFromQueryPlan ?? expandFromQueryPlan;
   let related = [];
@@ -231902,8 +232245,8 @@ async function retrieveGraphCandidates(ctx, request, adapters = {}) {
     });
   });
   const allIds = dedupe2(relatedWithCurrentSeed.map((candidate) => candidate.docId));
-  const visible = await resolveVisibleIds(ctx, allIds, adapters.visibleDocumentIds, visibilityScope, request.categoryId, tenantTransaction);
-  const activeGenerations = await resolveActiveGenerations(ctx, allIds, adapters.visibleDocumentGenerations, visibilityScope, request.categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
+  const visible = await resolveVisibleIds(ctx, allIds, adapters.visibleDocumentIds, visibilityScope, categoryId, tenantTransaction);
+  const activeGenerations = await resolveActiveGenerations(ctx, allIds, adapters.visibleDocumentGenerations, visibilityScope, categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
   const unique = new Map;
   for (const candidate of relatedWithCurrentSeed) {
     if (!visible.has(candidate.docId))
@@ -232168,19 +232511,59 @@ function resolveChatProviderKey(baseUrl, explicitKey, sharedOpenRouterKey) {
     return "";
   return sharedOpenRouterKey?.trim() ?? "";
 }
+function uniqueChatProviders(providers) {
+  const seen = new Set;
+  const unique = [];
+  for (const provider of providers) {
+    if (!provider?.baseUrl || !provider.model)
+      continue;
+    const identity = [
+      provider.baseUrl,
+      provider.model,
+      provider.apiKey ?? ""
+    ].join("|");
+    if (seen.has(identity))
+      continue;
+    seen.add(identity);
+    unique.push(provider);
+  }
+  return unique;
+}
 async function requestStructuredChat(options) {
-  const providers = [options.primary, options.fallback].filter((provider) => Boolean(provider?.baseUrl));
+  const attempt = await requestStructuredChatDetailed(options);
+  return attempt.ok ? attempt.result : null;
+}
+async function requestStructuredChatDetailed(options) {
+  const providers = uniqueChatProviders([
+    options.primary,
+    options.fallback,
+    ...options.fallbacks ?? []
+  ]);
+  let lastError = new PipelineProviderError("provider_unavailable", false, "No chat provider was configured");
   for (const provider of providers) {
     try {
       const raw = await requestChatContent(provider, options);
-      const parsed = parseJson(raw);
+      let parsed;
+      try {
+        parsed = parseJson(raw);
+      } catch {
+        lastError = new PipelineProviderError("invalid_provider_response", true);
+        continue;
+      }
       const result = options.outputSchema.safeParse(parsed);
-      if (!result.success)
+      if (!result.success) {
+        lastError = new PipelineProviderError("permanent_validation_failure", false);
         continue;
-      return { data: result.data, model: provider.model };
-    } catch {}
+      }
+      return {
+        ok: true,
+        result: { data: result.data, model: provider.model }
+      };
+    } catch (error53) {
+      lastError = error53 instanceof PipelineProviderError ? error53 : error53 instanceof Error && error53.name === "AbortError" ? new PipelineProviderError("provider_timeout", true) : new PipelineProviderError("provider_failure", true);
+    }
   }
-  return null;
+  return { ok: false, error: lastError };
 }
 async function requestChatContent(provider, options) {
   const controller = new AbortController;
@@ -232205,11 +232588,16 @@ async function requestChatContent(provider, options) {
       })
     });
     if (!response.ok)
-      throw new Error(`chat provider returned ${response.status}`);
-    const body = await response.json();
+      throw new PipelineProviderError("provider_failure", true, `chat provider returned ${response.status}`);
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new PipelineProviderError("invalid_provider_response", true);
+    }
     const content50 = body.choices?.[0]?.message?.content;
     if (typeof content50 !== "string" || !content50.trim()) {
-      throw new Error("chat provider returned empty content");
+      throw new PipelineProviderError("invalid_provider_response", true);
     }
     return content50;
   } finally {
@@ -232241,13 +232629,18 @@ async function expandQuery(plan, scope) {
   const tenantScope = typeof scope === "string" ? scope.trim() : (scope.tenantScope ?? scope.tenantId ?? scope.ownerId ?? "").trim();
   if (!tenantScope || !plan.normalized.trim())
     return null;
-  const primary = providerConfig(config3.SEARCH_EXPANSION_BASE_URL, config3.SEARCH_EXPANSION_API_KEY, config3.SEARCH_EXPANSION_MODEL);
-  const fallback = providerConfig(config3.SEARCH_EXPANSION_FALLBACK_BASE_URL, config3.SEARCH_EXPANSION_FALLBACK_API_KEY, config3.SEARCH_EXPANSION_FALLBACK_MODEL);
-  const providerCount = fallback.baseUrl ? 2 : 1;
-  const providerTimeoutMs = Math.max(250, Math.floor(config3.SEARCH_EXPANSION_TIMEOUT_MS / providerCount));
-  primary.timeoutMs = providerTimeoutMs;
-  fallback.timeoutMs = providerTimeoutMs;
-  const key = await expansionCacheKey(tenantScope, plan.normalized, primary, fallback);
+  const chain3 = uniqueChatProviders([
+    providerConfig(config3.SEARCH_EXPANSION_BASE_URL, config3.SEARCH_EXPANSION_API_KEY, config3.SEARCH_EXPANSION_MODEL),
+    providerConfig(config3.SEARCH_EXPANSION_FALLBACK_BASE_URL, config3.SEARCH_EXPANSION_FALLBACK_API_KEY, config3.SEARCH_EXPANSION_FALLBACK_MODEL),
+    providerConfig(config3.SEARCH_EXPANSION_FALLBACK_2_BASE_URL, config3.SEARCH_EXPANSION_FALLBACK_2_API_KEY, config3.SEARCH_EXPANSION_FALLBACK_2_MODEL)
+  ]);
+  const providerTimeoutMs = Math.max(250, Math.floor(config3.SEARCH_EXPANSION_TIMEOUT_MS / Math.max(1, chain3.length)));
+  for (const provider of chain3)
+    provider.timeoutMs = providerTimeoutMs;
+  const [primary, ...fallbacks] = chain3;
+  if (!primary)
+    return null;
+  const key = await expansionCacheKey(tenantScope, plan.normalized, primary, fallbacks);
   const ttl = config3.SEARCH_EXPANSION_CACHE_TTL_SECONDS;
   if (ttl > 0) {
     try {
@@ -232272,7 +232665,7 @@ async function expandQuery(plan, scope) {
   }
   const result = await requestStructuredChat({
     primary,
-    fallback,
+    fallbacks,
     messages: [
       {
         role: "system",
@@ -232352,12 +232745,15 @@ var cachedResultSchema = exports_external2.object({
   }),
   model: exports_external2.string()
 });
-async function expansionCacheKey(tenantScope, normalizedQuery, primary = providerConfig(config3.SEARCH_EXPANSION_BASE_URL, config3.SEARCH_EXPANSION_API_KEY, config3.SEARCH_EXPANSION_MODEL), fallback = undefined) {
+async function expansionCacheKey(tenantScope, normalizedQuery, primary = {
+  baseUrl: config3.SEARCH_EXPANSION_BASE_URL,
+  model: config3.SEARCH_EXPANSION_MODEL,
+  timeoutMs: config3.SEARCH_EXPANSION_TIMEOUT_MS
+}, fallbacks = []) {
   const modelProfile = [
     primary.baseUrl,
     primary.model,
-    fallback?.baseUrl ?? "",
-    fallback?.model ?? ""
+    ...fallbacks.flatMap((provider) => [provider.baseUrl, provider.model])
   ].join("|");
   const input = [
     tenantScope,
@@ -232369,6 +232765,8 @@ async function expansionCacheKey(tenantScope, normalizedQuery, primary = provide
   return `hiai-docs:search:expansion:${digest4}`;
 }
 function providerConfig(baseUrl, explicitKey, model) {
+  if (!baseUrl || !model)
+    return;
   return {
     baseUrl,
     model,
@@ -232396,6 +232794,179 @@ function normalizeVariant(value) {
   return value.normalize("NFKC").trim().replace(/\s+/g, " ").toLocaleLowerCase();
 }
 
+// ../../backend/src/search/rerank.ts
+var DEFAULT_RERANK_MAX_CHARS = 1500;
+function normalizeRerankText(title, content50, maxChars = DEFAULT_RERANK_MAX_CHARS) {
+  const cleaned = `${title.trim()}
+${content50}`.replace(/data:[^\s)>]+/gi, " ").replace(/\s+/g, " ").trim();
+  if (cleaned.length <= maxChars)
+    return cleaned;
+  return cleaned.slice(0, maxChars);
+}
+function applyRerankOrder(ranked, hits, topN) {
+  if (ranked.length === 0 || hits.length === 0 || topN < 1)
+    return ranked;
+  const window2 = ranked.slice(0, Math.min(topN, ranked.length));
+  const rest = ranked.slice(window2.length);
+  const byId = new Map(window2.map((item) => [item.documentId, item]));
+  const seen = new Set;
+  const reordered = [];
+  const sortedHits = [...hits].sort((left, right) => {
+    if (right.score !== left.score)
+      return right.score - left.score;
+    return left.rank - right.rank;
+  });
+  for (const hit of sortedHits) {
+    const item = byId.get(hit.id);
+    if (!item || seen.has(hit.id))
+      continue;
+    seen.add(hit.id);
+    reordered.push(item);
+  }
+  for (const item of window2) {
+    if (seen.has(item.documentId))
+      continue;
+    reordered.push(item);
+  }
+  return [...reordered, ...rest];
+}
+
+// ../../backend/src/search/rerank-provider.ts
+init_config();
+init_logger3();
+function configuredSlots() {
+  const slots = [
+    {
+      baseUrl: config3.SEARCH_RERANK_BASE_URL,
+      apiKey: config3.SEARCH_RERANK_API_KEY,
+      model: config3.SEARCH_RERANK_MODEL
+    },
+    {
+      baseUrl: config3.SEARCH_RERANK_FALLBACK_BASE_URL,
+      apiKey: config3.SEARCH_RERANK_FALLBACK_API_KEY,
+      model: config3.SEARCH_RERANK_FALLBACK_MODEL
+    },
+    {
+      baseUrl: config3.SEARCH_RERANK_FALLBACK_2_BASE_URL,
+      apiKey: config3.SEARCH_RERANK_FALLBACK_2_API_KEY,
+      model: config3.SEARCH_RERANK_FALLBACK_2_MODEL
+    }
+  ];
+  const seen = new Set;
+  const unique = [];
+  for (const slot of slots) {
+    if (!slot.baseUrl || !slot.model)
+      continue;
+    const identity = `${slot.baseUrl}|${slot.model}`;
+    if (seen.has(identity))
+      continue;
+    seen.add(identity);
+    unique.push({
+      baseUrl: slot.baseUrl,
+      model: slot.model,
+      apiKey: resolveChatProviderKey(slot.baseUrl, slot.apiKey, config3.OPENROUTER_API_KEY)
+    });
+  }
+  return unique;
+}
+function rerankUrl(baseUrl) {
+  const normalized = baseUrl.replace(/\/$/, "");
+  return normalized.endsWith("/rerank") ? normalized : `${normalized}/rerank`;
+}
+async function requestRerank(input) {
+  const candidates = input.candidates.map((candidate, originalIndex) => ({
+    id: candidate.id,
+    document: candidate.text.trim(),
+    originalIndex
+  })).filter((candidate) => candidate.document.length > 0);
+  if (candidates.length === 0)
+    return null;
+  const topN = Math.min(input.topN ?? config3.SEARCH_RERANK_TOP_N, candidates.length);
+  const timeoutMs = config3.SEARCH_RERANK_TIMEOUT_MS;
+  const started = performance.now();
+  incrementCounterBy(METRIC_NAMES.SEARCH_RERANK_CANDIDATES_TOTAL, candidates.length);
+  try {
+    for (const slot of configuredSlots()) {
+      try {
+        const hits = await callRerankSlot(slot, input.query, candidates, {
+          topN,
+          timeoutMs
+        });
+        if (hits.length === 0)
+          continue;
+        incrementCounter(METRIC_NAMES.SEARCH_RERANK_SUCCESS_TOTAL);
+        return { hits, model: slot.model };
+      } catch (error53) {
+        logger3.warn({ err: error53, model: slot.model }, "Rerank provider failed, trying next configured provider");
+      }
+    }
+    incrementCounter(METRIC_NAMES.SEARCH_RERANK_FALLBACK_TOTAL);
+    return null;
+  } finally {
+    recordDuration(METRIC_NAMES.SEARCH_RERANK_DURATION_MS, performance.now() - started);
+  }
+}
+async function callRerankSlot(slot, query, candidates, options) {
+  const controller = new AbortController;
+  const timer2 = setTimeout(() => controller.abort(), options.timeoutMs);
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (slot.apiKey)
+    headers.Authorization = `Bearer ${slot.apiKey}`;
+  try {
+    const response = await fetch(rerankUrl(slot.baseUrl), {
+      method: "POST",
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify({
+        model: slot.model,
+        query,
+        documents: candidates.map((candidate) => candidate.document),
+        top_n: options.topN
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`rerank provider returned ${response.status}`);
+    }
+    const body = await response.json();
+    const hits = [];
+    const seenIds = new Set;
+    for (const [rank, row] of (body.results ?? []).entries()) {
+      if (typeof row.index !== "number" || !Number.isInteger(row.index) || row.index < 0)
+        continue;
+      const candidate = candidates[row.index];
+      if (!candidate || seenIds.has(candidate.id))
+        continue;
+      seenIds.add(candidate.id);
+      const score = typeof row.relevance_score === "number" && Number.isFinite(row.relevance_score) ? row.relevance_score : 0;
+      hits.push({ id: candidate.id, score, rank: rank + 1 });
+    }
+    return hits;
+  } finally {
+    clearTimeout(timer2);
+  }
+}
+
+// ../../backend/src/search/rerank-texts.ts
+init_schema2();
+init_drizzle_orm();
+init_config();
+async function loadRerankTexts(ctx, documentIds, maxChars = config3.SEARCH_RERANK_MAX_CHARS) {
+  const texts = new Map;
+  if (documentIds.length === 0)
+    return texts;
+  const rows = await withTenant(ctx, async (tx) => tx.select({
+    id: documents.id,
+    title: documents.title,
+    content: documents.content
+  }).from(documents).where(and(isNull(documents.deletedAt), inArray(documents.id, documentIds))));
+  for (const row of rows) {
+    texts.set(row.id, normalizeRerankText(row.title, row.content ?? "", maxChars));
+  }
+  return texts;
+}
+
 // ../../backend/src/search/retrievers.ts
 init_drizzle_orm();
 init_config();
@@ -232714,6 +233285,8 @@ async function searchDocuments(ctx, request, adapters = {}) {
   const embeddingProvider = adapters.getEmbedding ?? getEmbedding;
   const expand2 = adapters.expand ?? expandQuery;
   const retrieveGraph = adapters.retrieveGraph ?? retrieveGraphCandidates;
+  const rerankDocuments = adapters.rerank ?? requestRerank;
+  const loadTexts = adapters.loadRerankTexts ?? loadRerankTexts;
   const filterRanked = adapters.filterRanked ?? applySearchFilters;
   const channelErrors = {};
   const embeddingCache = new Map;
@@ -232807,27 +233380,36 @@ async function searchDocuments(ctx, request, adapters = {}) {
       model: expansionModel,
       primaryModel: config3.SEARCH_EXPANSION_MODEL,
       fallbackModel: config3.SEARCH_EXPANSION_FALLBACK_MODEL,
+      fallback2Model: config3.SEARCH_EXPANSION_FALLBACK_2_MODEL,
       estimatedCostMicrounits: expansionUsed ? config3.SEARCH_EXPANSION_ESTIMATED_COST_MICROUNITS : 0
     });
     recordDuration(METRIC_NAMES.SEARCH_EXPANDED_DURATION_MS, performance.now() - expandedStarted);
   }
-  const direct = fuseCandidates([...fast, ...expanded].flatMap((result) => result.candidates), {
+  const rrfOptions = {
     rrfK: config3.SEARCH_RRF_K,
     exactBoost: config3.SEARCH_EXACT_BOOST,
     channelAgreementBoost: config3.SEARCH_CHANNEL_AGREEMENT_BOOST,
     graphMaxContribution: config3.SEARCH_GRAPH_MAX_CONTRIBUTION,
     vectorMinSimilarity: config3.SEARCH_VECTOR_MIN_SIMILARITY
-  });
+  };
+  const direct = fuseCandidates([...fast, ...expanded].flatMap((result) => result.candidates), rrfOptions);
   const graphPlan = expandedPlan ?? plan;
-  const graphSeeds = direct.slice(0, config3.SEARCH_GRAPH_SEED_LIMIT).map((result) => result.documentId);
+  const graphAttempted = request.graphEnabled !== false;
+  const rerankEnabled = request.rerankEnabled ?? config3.SEARCH_RERANK_ENABLED;
+  const graphPosition = request.rerankGraphPosition ?? config3.SEARCH_RERANK_GRAPH_POSITION;
   let graph = [];
   let graphFailed = false;
-  const graphAttempted = request.graphEnabled !== false;
-  if (graphAttempted) {
+  let ranked;
+  let rerankAttempted = false;
+  let rerankUsed = false;
+  let rerankFallback = false;
+  let rerankModel;
+  const runGraph = async (seeds) => {
     const graphStarted = performance.now();
+    let next = [];
     try {
-      graph = await retrieveGraph(ctx, {
-        documentSeeds: graphSeeds,
+      next = await retrieveGraph(ctx, {
+        documentSeeds: seeds,
         queryPlan: graphPlan,
         limit: Math.min(limit * 2, config3.SEARCH_GRAPH_RESULT_LIMIT),
         maxHops: request.maxGraphHops ?? config3.SEARCH_GRAPH_MAX_HOPS,
@@ -232837,25 +233419,82 @@ async function searchDocuments(ctx, request, adapters = {}) {
     } catch {
       graphFailed = true;
     }
-    graph = restrictCandidates(graph, request.documentIds);
+    next = restrictCandidates(next, request.documentIds);
     recordSearchChannelMetrics({
       channel: "graph",
       durationMs: performance.now() - graphStarted,
-      candidateCount: graph.length,
+      candidateCount: next.length,
       errorCode: graphFailed ? "query_failed" : undefined
     });
+    return next;
+  };
+  const seedIds = (items2) => items2.slice(0, config3.SEARCH_GRAPH_SEED_LIMIT).map((item) => item.documentId);
+  const applyOptionalRerank = async (items2) => {
+    if (!rerankEnabled || items2.length === 0)
+      return items2;
+    rerankAttempted = true;
+    try {
+      const topN = Math.min(config3.SEARCH_RERANK_TOP_N, items2.length);
+      const window2 = items2.slice(0, topN);
+      const texts = await loadTexts(ctx, window2.map((item) => item.documentId));
+      const candidates = window2.map((item, index2) => ({
+        id: item.documentId,
+        text: texts.get(item.documentId) ?? "",
+        sourceRank: index2 + 1,
+        rrfScore: item.score
+      }));
+      if (candidates.every((candidate) => candidate.text.length === 0)) {
+        rerankFallback = true;
+        return items2;
+      }
+      const result = await rerankDocuments({
+        query: plan.original,
+        candidates,
+        topN
+      });
+      if (!result || result.hits.length === 0) {
+        rerankFallback = true;
+        return items2;
+      }
+      rerankUsed = true;
+      rerankModel = result.model;
+      return applyRerankOrder(items2, result.hits, topN);
+    } catch {
+      rerankFallback = true;
+      return items2;
+    }
+  };
+  if (!rerankEnabled) {
+    if (graphAttempted)
+      graph = await runGraph(seedIds(direct));
+    ranked = fuseCandidates([
+      ...fast.flatMap((result) => result.candidates),
+      ...expanded.flatMap((result) => result.candidates),
+      ...graph
+    ], rrfOptions);
+  } else if (graphPosition === "before") {
+    if (graphAttempted)
+      graph = await runGraph(seedIds(direct));
+    ranked = fuseCandidates([
+      ...fast.flatMap((result) => result.candidates),
+      ...expanded.flatMap((result) => result.candidates),
+      ...graph
+    ], rrfOptions);
+    ranked = await applyOptionalRerank(ranked);
+  } else {
+    ranked = await applyOptionalRerank(direct);
+    if (graphAttempted)
+      graph = await runGraph(seedIds(ranked));
+    ranked = annotateGraphChannels(ranked, graph);
+    const present = new Set(ranked.map((item) => item.documentId));
+    const extra = graph.filter((candidate) => !present.has(candidate.documentId));
+    if (extra.length > 0) {
+      ranked = [
+        ...ranked,
+        ...fuseCandidates(extra, rrfOptions).filter((item) => !present.has(item.documentId))
+      ];
+    }
   }
-  const ranked = fuseCandidates([
-    ...fast.flatMap((result) => result.candidates),
-    ...expanded.flatMap((result) => result.candidates),
-    ...graph
-  ], {
-    rrfK: config3.SEARCH_RRF_K,
-    exactBoost: config3.SEARCH_EXACT_BOOST,
-    channelAgreementBoost: config3.SEARCH_CHANNEL_AGREEMENT_BOOST,
-    graphMaxContribution: config3.SEARCH_GRAPH_MAX_CONTRIBUTION,
-    vectorMinSimilarity: config3.SEARCH_VECTOR_MIN_SIMILARITY
-  });
   const filters = request.filters;
   const hasFilters = Boolean(filters && Object.values(filters).some((value) => Array.isArray(value) ? value.length > 0 : value !== undefined));
   const filtered = hasFilters || request.visibilityScope !== undefined ? await filterRanked(ctx, ranked, filters ?? {}, request.visibilityScope) : ranked;
@@ -232881,7 +233520,11 @@ async function searchDocuments(ctx, request, adapters = {}) {
     graphAttempted,
     graphFailed,
     graphContribution,
-    confidenceReasons: confidence.reasons
+    confidenceReasons: confidence.reasons,
+    rerankAttempted,
+    rerankUsed,
+    rerankFallback,
+    ...rerankModel ? { rerankModel } : {}
   };
   return {
     items,
@@ -233049,6 +233692,24 @@ function clampPage(value) {
     return 1;
   return Math.max(1, Math.floor(value));
 }
+function annotateGraphChannels(items, graphCandidates) {
+  if (graphCandidates.length === 0)
+    return items;
+  const graphIds = new Set(graphCandidates.map((candidate) => candidate.documentId));
+  return items.map((item) => {
+    if (!graphIds.has(item.documentId) || item.channels.includes("graph")) {
+      return item;
+    }
+    return {
+      ...item,
+      channels: [...item.channels, "graph"],
+      explanations: [
+        ...item.explanations,
+        { channel: "graph", label: "Related document" }
+      ]
+    };
+  });
+}
 
 // ../../backend/src/api/routes/search.ts
 var BENCHMARK_SEARCH_PROFILE_HEADER = "x-docsmint-search-profile";
@@ -235540,7 +236201,11 @@ async function extractEntities(chunkText2, documentId, options = {}) {
     } catch (err) {
       await releaseDedupClaim();
       logger3.warn({ err, documentId }, "Entity extraction LLM call failed \u2014 skipping");
-      return { status: "failed", warning: "provider_failed", entities: [] };
+      return {
+        status: "failed",
+        warning: err instanceof Error && err.message ? err.message : "provider_failure",
+        entities: []
+      };
     }
   }
   if (entities === null) {
@@ -235564,7 +236229,42 @@ async function extractEntities(chunkText2, documentId, options = {}) {
   return { status: "ready", entities };
 }
 function hasConfiguredGraphProvider(options) {
-  return Boolean(options.llmBaseUrl || config3.GRAPH_EXTRACT_BASE_URL || config3.GRAPH_EXTRACT_FALLBACK_BASE_URL);
+  return Boolean(options.llmBaseUrl || config3.GRAPH_EXTRACT_BASE_URL || config3.GRAPH_EXTRACT_FALLBACK_BASE_URL || config3.GRAPH_EXTRACT_FALLBACK_2_BASE_URL);
+}
+function graphExtractProviders(options) {
+  const timeoutMs = config3.GRAPH_EXTRACT_TIMEOUT_MS;
+  const primaryModel = options.llmModel ?? config3.GRAPH_EXTRACT_MODEL ?? "gpt-4o-mini";
+  const slots = [
+    {
+      baseUrl: options.llmBaseUrl ?? config3.GRAPH_EXTRACT_BASE_URL,
+      explicitKey: options.llmApiKey ?? config3.GRAPH_EXTRACT_API_KEY,
+      model: primaryModel,
+      reasoningEffort: options.reasoningEffort ?? config3.GRAPH_EXTRACT_REASONING_EFFORT
+    },
+    {
+      baseUrl: config3.GRAPH_EXTRACT_FALLBACK_BASE_URL,
+      explicitKey: config3.GRAPH_EXTRACT_FALLBACK_API_KEY,
+      model: config3.GRAPH_EXTRACT_FALLBACK_MODEL ?? primaryModel,
+      reasoningEffort: config3.GRAPH_EXTRACT_REASONING_EFFORT
+    },
+    {
+      baseUrl: config3.GRAPH_EXTRACT_FALLBACK_2_BASE_URL,
+      explicitKey: config3.GRAPH_EXTRACT_FALLBACK_2_API_KEY,
+      model: config3.GRAPH_EXTRACT_FALLBACK_2_MODEL,
+      reasoningEffort: config3.GRAPH_EXTRACT_REASONING_EFFORT
+    }
+  ];
+  return uniqueChatProviders(slots.map((slot) => {
+    if (!slot.baseUrl || !slot.model)
+      return;
+    return {
+      baseUrl: slot.baseUrl,
+      apiKey: resolveGraphProviderKey(slot.baseUrl, slot.explicitKey),
+      model: slot.model,
+      timeoutMs,
+      reasoningEffort: slot.reasoningEffort
+    };
+  }));
 }
 var SYSTEM_PROMPT = [
   "You are an entity-extraction assistant for a knowledge-base system.",
@@ -235600,39 +236300,13 @@ var extractionOutputSchema = exports_external2.object({
   entities: exports_external2.array(exports_external2.unknown())
 });
 async function callEntityExtractionLLM(text4, options) {
-  const primaryBase = options.llmBaseUrl ?? config3.GRAPH_EXTRACT_BASE_URL;
-  const primaryExplicitKey = options.llmApiKey ?? config3.GRAPH_EXTRACT_API_KEY;
-  const primaryModel = options.llmModel ?? config3.GRAPH_EXTRACT_MODEL ?? "gpt-4o-mini";
-  const primaryKey2 = primaryBase ? resolveGraphProviderKey(primaryBase, primaryExplicitKey) : "";
-  const fallbackBase = config3.GRAPH_EXTRACT_FALLBACK_BASE_URL;
-  const fallbackExplicitKey = config3.GRAPH_EXTRACT_FALLBACK_API_KEY;
-  const fallbackModel = config3.GRAPH_EXTRACT_FALLBACK_MODEL ?? primaryModel;
-  const fallbackKey = fallbackBase ? resolveGraphProviderKey(fallbackBase, fallbackExplicitKey) : "";
-  const providers = [];
-  if (primaryBase) {
-    providers.push({
-      baseUrl: primaryBase,
-      apiKey: primaryKey2,
-      model: primaryModel,
-      timeoutMs: config3.GRAPH_EXTRACT_TIMEOUT_MS,
-      reasoningEffort: options.reasoningEffort ?? config3.GRAPH_EXTRACT_REASONING_EFFORT
-    });
-  }
-  if (fallbackBase && (fallbackBase !== primaryBase || fallbackKey !== primaryKey2 || fallbackModel !== primaryModel)) {
-    providers.push({
-      baseUrl: fallbackBase,
-      apiKey: fallbackKey,
-      model: fallbackModel,
-      timeoutMs: config3.GRAPH_EXTRACT_TIMEOUT_MS,
-      reasoningEffort: config3.GRAPH_EXTRACT_REASONING_EFFORT
-    });
-  }
-  const [primary, fallback] = providers;
+  const providers = graphExtractProviders(options);
+  const [primary, ...fallbacks] = providers;
   if (!primary)
     return null;
-  const result = await requestStructuredChat({
+  const attempt = await requestStructuredChatDetailed({
     primary,
-    fallback,
+    fallbacks,
     messages: [
       { role: "system", content: SYSTEM_PROMPT },
       { role: "user", content: text4 }
@@ -235641,7 +236315,9 @@ async function callEntityExtractionLLM(text4, options) {
     maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
     temperature: options.temperature ?? DEFAULT_TEMPERATURE
   });
-  return result ? parseExtractionResponse(JSON.stringify(result.data)) : null;
+  if (!attempt.ok)
+    throw attempt.error;
+  return parseExtractionResponse(JSON.stringify(attempt.result.data));
 }
 function resolveGraphProviderKey(baseUrl, explicitKey) {
   return resolveChatProviderKey(baseUrl, explicitKey, config3.OPENROUTER_API_KEY);
@@ -235835,11 +236511,11 @@ async function buildKnowledgeSummary(document2, provider) {
   }
   const output = await provider(document2);
   if (!output)
-    throw new Error("summary_provider_failed");
+    throw new Error("provider_failure");
   const language = output.language.trim();
   const description = output.description.trim();
   if (!language || !description)
-    throw new Error("summary_provider_invalid");
+    throw new Error("permanent_validation_failure");
   const seen = new Set;
   const keywords = [];
   for (const raw of output.keywords) {
@@ -235890,10 +236566,13 @@ async function requestKnowledgeSummary(document2) {
   const primary = provider(config3.GRAPH_EXTRACT_BASE_URL, config3.GRAPH_EXTRACT_API_KEY, config3.GRAPH_EXTRACT_MODEL);
   if (!primary)
     return null;
-  const fallback = provider(config3.GRAPH_EXTRACT_FALLBACK_BASE_URL, config3.GRAPH_EXTRACT_FALLBACK_API_KEY, config3.GRAPH_EXTRACT_FALLBACK_MODEL);
-  const result = await requestStructuredChat({
+  const fallbacks = [
+    provider(config3.GRAPH_EXTRACT_FALLBACK_BASE_URL, config3.GRAPH_EXTRACT_FALLBACK_API_KEY, config3.GRAPH_EXTRACT_FALLBACK_MODEL),
+    provider(config3.GRAPH_EXTRACT_FALLBACK_2_BASE_URL, config3.GRAPH_EXTRACT_FALLBACK_2_API_KEY, config3.GRAPH_EXTRACT_FALLBACK_2_MODEL)
+  ].filter((item) => Boolean(item));
+  const attempt = await requestStructuredChatDetailed({
     primary,
-    fallback,
+    fallbacks,
     messages: [
       { role: "system", content: systemPrompt },
       {
@@ -235907,7 +236586,9 @@ ${document2.content.slice(0, 50000)}`
     maxTokens: 768,
     temperature: 0
   });
-  return result ? { ...result.data, model: result.model } : null;
+  if (!attempt.ok)
+    throw attempt.error;
+  return { ...attempt.result.data, model: attempt.result.model };
 }
 
 // ../../backend/src/queue/document-revision.ts
@@ -236328,7 +237009,7 @@ function providerProfile(name) {
   };
 }
 function configuredEmbeddingProvider() {
-  const model = config3.EMBEDDING_MODEL ?? config3.EMBEDDING_FALLBACK_MODEL ?? "";
+  const model = config3.EMBEDDING_MODEL ?? config3.EMBEDDING_FALLBACK_MODEL ?? config3.EMBEDDING_FALLBACK_2_MODEL ?? "";
   return {
     model,
     profile: embeddingProfileId(model, EMBEDDING_DIMENSIONS, "v1"),
@@ -236339,6 +237020,10 @@ function configuredEmbeddingProvider() {
         config3.EMBEDDING_FALLBACK_BASE_URL ?? "",
         config3.EMBEDDING_FALLBACK_MODEL ?? ""
       ],
+      fallback_2: [
+        config3.EMBEDDING_FALLBACK_2_BASE_URL ?? "",
+        config3.EMBEDDING_FALLBACK_2_MODEL ?? ""
+      ],
       dimensions: EMBEDDING_DIMENSIONS,
       profileVersion: "v1"
     })
@@ -236404,6 +237089,14 @@ function stagePatch(stage, status2) {
     return { summarizeStatus: status2 };
   return { finalizeStatus: status2 };
 }
+function stageErrorPatch(stage, status2, errorCode) {
+  const value = status2 === "failed" ? errorCode ?? "unknown_failure" : null;
+  if (stage === "graph")
+    return { graphErrorCode: value };
+  if (stage === "summarize")
+    return { summarizeErrorCode: value };
+  return {};
+}
 function pipelineStageStatus(value) {
   return value === "ready_with_warnings" ? "failed" : value;
 }
@@ -236433,6 +237126,7 @@ async function cancelStalePipelineRun(job2, errorCode = "stale_revision") {
 async function setStageStatus(generationId, stage, status2, errorCode) {
   await withTenant(admin, (tx) => tx.update(documentPipelineRuns).set({
     ...stagePatch(stage, status2),
+    ...stageErrorPatch(stage, status2, errorCode),
     ...errorCode ? { errorCode } : {},
     updatedAt: new Date
   }).where(and(eq(documentPipelineRuns.generationId, generationId), ne(documentPipelineRuns.status, "cancelled"))));
@@ -236743,7 +237437,8 @@ function createPipelineStageDependencies(redisUrl) {
           generationId: run3.generationId,
           revision: run3.revision,
           embeddingContextHash: run3.embeddingContextHash ?? undefined,
-          embedStatus: pipelineStageStatus(run3.embedStatus)
+          embedStatus: pipelineStageStatus(run3.embedStatus),
+          summarizeStatus: pipelineStageStatus(run3.summarizeStatus)
         } : null;
       },
       async extract(job2) {
@@ -236771,7 +237466,15 @@ function createPipelineStageDependencies(redisUrl) {
         const data = { ...job2, stage: "summarize" };
         await enqueueIfActive("summarize", "summarize", data, {
           ...DEFAULT_JOB_OPTIONS,
-          jobId: JOB_IDS.summarize(job2.generationId, job2.workspaceId),
+          jobId: summaryJobIdForPipeline(job2),
+          priority: SOURCE_PRIORITY[job2.source]
+        });
+      },
+      async enqueueFinalize(job2) {
+        const data = { ...job2, stage: "finalize" };
+        await enqueueIfActive("finalize", "finalize", data, {
+          ...DEFAULT_JOB_OPTIONS,
+          jobId: `${JOB_IDS.finalize(job2.generationId, job2.workspaceId)}-graph-retry-${job2.requestedAt.replace(/\D/g, "")}`,
           priority: SOURCE_PRIORITY[job2.source]
         });
       }
@@ -237266,10 +237969,12 @@ async function processSummaryStage(job2, dependencies) {
   } catch (error53) {
     if (!await continueIfCurrent())
       return;
-    await dependencies.setSummaryStatus(job2.generationId, "failed", error53 instanceof Error ? error53.name : "summary_failed");
+    await dependencies.setSummaryStatus(job2.generationId, "failed", pipelineErrorCode(error53, "summary_failed"));
     if (!await continueIfCurrent())
       return;
     await dependencies.enqueueFinalize(job2);
+    if (error53 instanceof PipelineProviderError && error53.retryable)
+      throw error53;
     return;
   }
   if (!await continueIfCurrent())
@@ -237284,7 +237989,7 @@ async function processGraphStageFailure(job2, error53, dependencies) {
   }
   if (await dependencies.isCancelled?.(job2))
     throw error53;
-  await dependencies.setGraphStatus(job2.generationId, "failed", error53 instanceof Error ? error53.name : "graph_failed");
+  await dependencies.setGraphStatus(job2.generationId, "failed", pipelineErrorCode(error53, "graph_failed"));
   if (!await dependencies.isCancelled?.(job2)) {
     await dependencies.enqueueSummarize(job2);
   }
@@ -237318,6 +238023,18 @@ function createGraphWorker(deps) {
     const run3 = await deps.getRun(job2);
     if (!run3)
       throw new Error("Pipeline run not found");
+    const continuePipeline = async () => {
+      if (await deps.isCancelled?.(job2))
+        return;
+      if (run3.summarizeStatus === "ready" || run3.summarizeStatus === "skipped") {
+        if (deps.enqueueFinalize)
+          await deps.enqueueFinalize(job2);
+        else
+          await deps.enqueueSummarize(job2);
+        return;
+      }
+      await deps.enqueueSummarize(job2);
+    };
     if (run3.ownerId !== job2.ownerId || run3.documentId !== job2.documentId) {
       throw new Error("Pipeline owner mismatch");
     }
@@ -237335,8 +238052,7 @@ function createGraphWorker(deps) {
       if (await deps.isCancelled?.(job2))
         return;
       await deps.setGraphStatus(job2.generationId, "skipped", "embedding_not_ready");
-      if (!await deps.isCancelled?.(job2))
-        await deps.enqueueSummarize(job2);
+      await continuePipeline();
       return;
     }
     if (await deps.isCancelled?.(job2))
@@ -237356,15 +238072,27 @@ function createGraphWorker(deps) {
         return;
       }
       if (outcome.status === "unavailable" || outcome.status === "failed") {
+        if (outcome.status === "failed" && [
+          "provider_failure",
+          "provider_timeout",
+          "invalid_provider_response"
+        ].includes(outcome.warning)) {
+          throw new PipelineProviderError(outcome.warning, true);
+        }
         await deps.setGraphStatus(job2.generationId, "failed", outcome.warning);
-        if (!await deps.isCancelled?.(job2))
-          await deps.enqueueSummarize(job2);
+        await continuePipeline();
         return;
       }
       await deps.setGraphStatus(job2.generationId, "ready");
-      if (!await deps.isCancelled?.(job2))
-        await deps.enqueueSummarize(job2);
+      await continuePipeline();
     } catch (error53) {
+      if (error53 instanceof PipelineProviderError) {
+        await deps.setGraphStatus(job2.generationId, "failed", error53.code);
+        await continuePipeline();
+        if (error53.retryable)
+          throw error53;
+        return;
+      }
       await processGraphStageFailure(job2, error53, deps);
     }
   };
@@ -237571,7 +238299,7 @@ var swaggerConfig = {
     },
     info: {
       title: "DocsMint API",
-      version: "0.7.6",
+      version: "0.8.2",
       description: "Self-hosted AI-native knowledge workspace and installable PWA with hybrid search, GraphRAG, REST, SDK, CLI, and MCP access for people and AI agents.",
       contact: { name: "HiAi-gg", url: "https://github.com/HiAi-gg/docsmint" },
       license: {
@@ -237632,7 +238360,7 @@ app.listen({
   idleTimeout: 30,
   maxRequestBodySize: MAX_BODY_SIZE_BYTES
 });
-logger3.info({ port: config3.API_PORT }, "hiai-docs API started");
+logger3.info({ port: config3.API_PORT }, "DocsMint API started");
 var stopDocsMintApi = async () => {
   logger3.info("Shutting down...");
   attachmentUploadCleanup.stop();