@@ -4052,6 +4052,19 @@ enum {
40524052static const double BM25_LABEL_WEIGHT = 1.0;
40534053static const double BM25_LABEL_WEIGHT_SCOPED = 0.0;
40544054
4055+ /* Labels an UNLABELLED query never ranks: path-shaped File/Folder nodes, the
4056+ * Project node and Variables match almost any token through their qualified
4057+ * name and file path, and would crowd definitions out of the result. They are
4058+ * still in nodes_fts, so an explicit `label` that names one of them is served
4059+ * from its own label-scoped window like any other label (?7 is the caller's
4060+ * label, NULL when none was given). Excluding them there too returned 0 rows
4061+ * -- often with an exact "eq" total -- although such nodes match. Section and
4062+ * Module are NOT excluded (#518/#519): they carry the prose the body column
4063+ * indexes. Shared by the ranked and the count query, so the two cannot
4064+ * desynchronise. */
4065+ #define BM25_UNLABELLED_EXCLUSION \
4066+ "(?7 IS NOT NULL OR n.label NOT IN ('File','Folder','Variable','Project'))"
4067+
40554068/* Module-local SQLITE_TRANSIENT wrapper to dodge performance-no-int-to-ptr.
40564069 * See the matching helper in src/store/store.c for the same pattern. */
40574070static sqlite3_destructor_type mcp_sqlite_transient(void) {
@@ -4134,6 +4147,52 @@ static double bm25_scope_match_to_label(const char *tokens, const char *label, c
41344147 return BM25_LABEL_WEIGHT_SCOPED;
41354148}
41364149
4150+ /* A BM25 result is empty although nodes match when the label is spelled in a
4151+ * case no node carries: labels are case-sensitive, so `label=class` finds
4152+ * nothing while Class nodes match the query. Returns a hint (memory core,
4153+ * CBM_MEM_CLASS_OTHER) naming the label this project actually holds, or NULL
4154+ * when the label exists exactly (a true zero). The exact probe is an index
4155+ * seek on (project, label); the case-insensitive scan runs only when it
4156+ * misses. The caller's label is never echoed back, only the stored spelling. */
4157+ static char *bm25_label_zero_hint(sqlite3 *db, const char *project, const char *label) {
4158+ enum { HINT_BIND_PROJECT = 1, HINT_BIND_LABEL = 2, HINT_COL_LABEL = 0, HINT_PROBE_EXACT = 0 };
4159+ if (!db || !label || !label[0]) {
4160+ return NULL;
4161+ }
4162+ static const char *const probes[] = {
4163+ "SELECT label FROM nodes WHERE project = ?1 AND label = ?2 LIMIT 1",
4164+ "SELECT label FROM nodes WHERE project = ?1 AND label = ?2 COLLATE NOCASE LIMIT 1",
4165+ };
4166+ char found[CBM_SZ_256] = "";
4167+ for (size_t i = 0; i < sizeof(probes) / sizeof(probes[0]) && !found[0]; i++) {
4168+ sqlite3_stmt *st = NULL;
4169+ if (sqlite3_prepare_v2(db, probes[i], BM25_SQL_AUTO_LEN, &st, NULL) != SQLITE_OK) {
4170+ return NULL;
4171+ }
4172+ sqlite3_bind_text(st, HINT_BIND_PROJECT, project, BM25_SQL_AUTO_LEN, MCP_SQLITE_TRANSIENT);
4173+ sqlite3_bind_text(st, HINT_BIND_LABEL, label, BM25_SQL_AUTO_LEN, MCP_SQLITE_TRANSIENT);
4174+ if (sqlite3_step(st) == SQLITE_ROW) {
4175+ const char *stored = (const char *)sqlite3_column_text(st, HINT_COL_LABEL);
4176+ snprintf(found, sizeof(found), "%s", stored ? stored : "");
4177+ }
4178+ sqlite3_finalize(st);
4179+ if (found[0] && i == HINT_PROBE_EXACT) {
4180+ return NULL;
4181+ }
4182+ }
4183+ if (!found[0]) {
4184+ return cbm_mem_strdup(CBM_MEM_CLASS_OTHER,
4185+ "no node in this project carries this label; get_graph_schema "
4186+ "lists the labels this index holds");
4187+ }
4188+ char hint[CBM_SZ_512];
4189+ snprintf(hint, sizeof(hint),
4190+ "no node carries this label as spelled; labels are case-sensitive -- retry with "
4191+ "label=\"%s\"",
4192+ found);
4193+ return cbm_mem_strdup(CBM_MEM_CLASS_OTHER, hint);
4194+ }
4195+
41374196static char *bm25_file_pattern_like(const char *file_pattern) {
41384197 if (!file_pattern) {
41394198 return NULL;
@@ -4185,7 +4244,8 @@ static void bm25_lines_str(char *out, size_t size, int start, int end) {
41854244
41864245static void bm25_emit_metadata_tree(cbm_sb_t *sb, int total, int offset, int returned,
41874246 bool candidate_window_saturated, bool budget_hit,
4188- bool floor_exceeded, size_t max_output_bytes) {
4247+ bool floor_exceeded, size_t max_output_bytes,
4248+ const char *zero_hint) {
41894249 bool has_more = total > offset + returned;
41904250 cbm_tree_scalar_int(sb, "total", total);
41914251 cbm_tree_scalar_str(sb, "total_relation", candidate_window_saturated ? "gte" : "eq");
@@ -4216,12 +4276,15 @@ static void bm25_emit_metadata_tree(cbm_sb_t *sb, int total, int offset, int ret
42164276 cbm_tree_scalar_str(sb, "hint",
42174277 "first identity row exceeds max_output_bytes; raise "
42184278 "max_output_tokens");
4279+ } else if (zero_hint) {
4280+ cbm_tree_scalar_str(sb, "hint", zero_hint);
42194281 }
42204282}
42214283
42224284static void bm25_emit_metadata_json(yyjson_mut_doc *doc, yyjson_mut_val *root, int total,
42234285 int offset, int returned, bool candidate_window_saturated,
4224- bool budget_hit, bool floor_exceeded, size_t max_output_bytes) {
4286+ bool budget_hit, bool floor_exceeded, size_t max_output_bytes,
4287+ const char *zero_hint) {
42254288 bool has_more = total > offset + returned;
42264289 yyjson_mut_obj_add_int(doc, root, "total", total);
42274290 yyjson_mut_obj_add_str(doc, root, "total_relation", candidate_window_saturated ? "gte" : "eq");
@@ -4253,12 +4316,14 @@ static void bm25_emit_metadata_json(yyjson_mut_doc *doc, yyjson_mut_val *root, i
42534316 yyjson_mut_obj_add_str(doc, root, "hint",
42544317 "first identity row exceeds max_output_bytes; raise "
42554318 "max_output_tokens");
4319+ } else if (zero_hint) {
4320+ yyjson_mut_obj_add_strcpy(doc, root, "hint", zero_hint);
42564321 }
42574322}
42584323
42594324static char *bm25_render(const bm25_output_row_t *rows, int returned, int total, int offset,
42604325 bool candidate_window_saturated, bool tree_format, bool budget_hit,
4261- bool floor_exceeded, size_t max_output_bytes) {
4326+ bool floor_exceeded, size_t max_output_bytes, const char *zero_hint ) {
42624327 if (tree_format) {
42634328 cbm_sb_t sb;
42644329 cbm_sb_init(&sb);
@@ -4276,7 +4341,7 @@ static char *bm25_render(const bm25_output_row_t *rows, int returned, int total,
42764341 cbm_tree_row_end(&sb);
42774342 }
42784343 bm25_emit_metadata_tree(&sb, total, offset, returned, candidate_window_saturated,
4279- budget_hit, floor_exceeded, max_output_bytes);
4344+ budget_hit, floor_exceeded, max_output_bytes, zero_hint );
42804345 return cbm_sb_finish(&sb);
42814346 }
42824347
@@ -4303,7 +4368,7 @@ static char *bm25_render(const bm25_output_row_t *rows, int returned, int total,
43034368 }
43044369 yyjson_mut_obj_add_val(doc, root, "rows", result_rows);
43054370 bm25_emit_metadata_json(doc, root, total, offset, returned, candidate_window_saturated,
4306- budget_hit, floor_exceeded, max_output_bytes);
4371+ budget_hit, floor_exceeded, max_output_bytes, zero_hint );
43074372 char *json = yy_doc_to_str(doc);
43084373 yyjson_mut_doc_free(doc);
43094374 return json;
@@ -4372,12 +4437,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
43724437 ") fts "
43734438 "JOIN nodes n ON n.id = fts.rowid "
43744439 "WHERE n.project = ?2 "
4375- /* Section and Module are NO LONGER excluded (#518/#519): they are the
4376- * labels that carry prose — a Markdown section's body, a config file's
4377- * description — so excluding them made the body column unreachable.
4378- * This exclusion list is MIRRORED in the count query below; the two
4379- * must be changed together or results desynchronise from counts. */
4380- " AND n.label NOT IN ('File','Folder','Variable','Project') "
4440+ " AND " BM25_UNLABELLED_EXCLUSION " "
43814441 " AND (?6 IS NULL OR n.file_path LIKE ?6) "
43824442 /* The caller's label filter applies in query mode exactly as it does
43834443 * in the structural mode (2026-09-16 probe: `label=Class` was ignored
@@ -4444,7 +4504,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
44444504 /* MIRRORS the ranked query's filter verbatim — same weights, same
44454505 * label exclusions. Changing one alone reports a total that does
44464506 * not describe the rows returned. */
4447- " AND n.label NOT IN ('File','Folder','Variable','Project') "
4507+ " AND " BM25_UNLABELLED_EXCLUSION " "
44484508 " AND (?6 IS NULL OR n.file_path LIKE ?6)"
44494509 " AND (?7 IS NULL OR n.label = ?7)"
44504510 " AND (?9 IS NULL OR (CASE WHEN json_valid(n.properties) "
@@ -4535,13 +4595,15 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
45354595 if (!rows) {
45364596 return heap_strdup("out of memory");
45374597 }
4598+ /* Never a silent zero for a label the index spells differently. */
4599+ char *zero_hint = total == 0 ? bm25_label_zero_hint(db, project, label) : NULL;
45384600
45394601 int returned = row_count;
45404602 bool budget_hit = false;
45414603 char *payload = NULL;
45424604 for (;;) {
45434605 payload = bm25_render(rows, returned, total, offset, candidate_window_saturated,
4544- tree_format, budget_hit, false, max_output_bytes);
4606+ tree_format, budget_hit, false, max_output_bytes, zero_hint );
45454607 if (!payload || strlen(payload) <= max_output_bytes || returned == 0) {
45464608 break;
45474609 }
@@ -4554,8 +4616,9 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
45544616 if (!payload || strlen(payload) > max_output_bytes || (row_count > 0 && returned == 0)) {
45554617 free(payload);
45564618 payload = bm25_render(rows, 0, total, offset, candidate_window_saturated, tree_format, true,
4557- row_count > 0, max_output_bytes);
4619+ row_count > 0, max_output_bytes, zero_hint );
45584620 }
4621+ cbm_free(CBM_MEM_CLASS_OTHER, zero_hint);
45594622 bm25_output_rows_free(rows, row_count);
45604623 return payload;
45614624}
0 commit comments