@openparachute/vault 0.7.7 → 0.7.8-rc.2

package/core/src/aggregate.test.ts

@@ -13,6 +13,7 @@
  *   - errors on a non-indexed / non-numeric sum field
  *   - errors on a malformed aggregate spec (missing op/group_by/field)
  *   - a note missing the group_by field collects into `group: null`
+ *   - count without group_by is the filtered total (vault#626)
  *
  * Tag-scope enforcement (server-layer, injected as an `ids` prefilter or an
  * `aggregateVisibility` predicate) is covered separately at the MCP/REST
@@ -34,6 +35,50 @@ beforeEach(() => {
   store = new SqliteStore(db);
 });
 
+describe("aggregateNotes — count without group_by (vault#626 filtered total)", () => {
+  it("returns [{group: null, value: N}] over the whole set", async () => {
+    await store.createNote("a");
+    await store.createNote("b");
+    await store.createNote("c");
+    expect(aggregateNotes(db, { aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 3 },
+    ]);
+  });
+
+  it("an empty match still returns one zero row, not []", () => {
+    expect(aggregateNotes(db, { aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 0 },
+    ]);
+  });
+
+  it("a tag prefilter narrows the total", async () => {
+    await store.createNote("a", { tags: ["work"] });
+    await store.createNote("b", { tags: ["work"] });
+    await store.createNote("c", { tags: ["personal"] });
+    expect(aggregateNotes(db, { tags: ["work"], aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 2 },
+    ]);
+  });
+
+  it("ids: [] (tag-scope empty) is a zero total, not []", () => {
+    expect(aggregateNotes(db, { ids: [], aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 0 },
+    ]);
+  });
+
+  it("sum without group_by is still INVALID_QUERY", async () => {
+    await store.upsertTagRecord("expense", { fields: { amount: { type: "integer", indexed: true } } });
+    try {
+      aggregateNotes(db, { aggregate: { op: "sum", field: "amount" } });
+      throw new Error("expected throw");
+    } catch (e: any) {
+      expect(e.name).toBe("QueryError");
+      expect(e.code).toBe("INVALID_QUERY");
+      expect(e.field).toBe("aggregate.group_by");
+    }
+  });
+});
+
 describe("aggregateNotes — count by an indexed enum field", () => {
   it("groups and counts", async () => {
     await store.upsertTagRecord("task", { fields: { status: { type: "string", indexed: true } } });

package/core/src/mcp-manifest.ts

@@ -71,7 +71,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
 - Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.
 - \`aggregate\` mode: \`[{group, value}]\` — a rollup row per group, NOT notes. See \`aggregate\` below.
 
-\`aggregate\` (group_by + count/sum): pass \`aggregate: {group_by, op, field?}\` to get counts/sums instead of note rows — e.g. "how many notes per status" (\`{group_by: "status", op: "count"}\`) or "total amount per category" (\`{group_by: "category", op: "sum", field: "amount"}\`). Every other filter (\`tag\`, \`metadata\`, date range, ...) narrows the input set FIRST, exactly like a normal query. \`group_by\` is either \"tag\" (group by tag membership) or an indexed metadata field; \`op: "sum"\` additionally requires \`field\` to be an indexed NUMERIC field. Mutually exclusive with \`search\`/\`near\`/\`cursor\`.
+\`aggregate\` (count/sum, optional group_by): pass \`aggregate: {op, group_by?, field?}\` to get counts/sums instead of note rows. \`{op: "count"}\` with no \`group_by\` is the filtered total — one row \`[{group: null, value: N}]\` (vault#626). Grouped examples: "how many notes per status" (\`{group_by: "status", op: "count"}\`) or "total amount per category" (\`{group_by: "category", op: "sum", field: "amount"}\`). Every other filter (\`tag\`, \`metadata\`, date range, ...) narrows the input set FIRST, exactly like a normal query. \`group_by\` is either \"tag\" (group by tag membership) or an indexed metadata field; omit it on \`count\` for the total. \`op: "sum"\` requires both \`group_by\` and \`field\` (indexed NUMERIC). Mutually exclusive with \`search\`/\`near\`/\`cursor\`/\`semantic\`.
 
 \`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.
 
@@ -188,12 +188,12 @@ Response shape (vault#550 — three variants, pick by what you passed):
           aggregate: {
             type: "object",
             properties: {
-              group_by: { type: "string", description: "What to group by: an indexed metadata field name (declared `indexed: true` in a tag schema — same FIELD_NOT_INDEXED contract as `metadata` operator queries / `order_by`), or the special value \"tag\" to group by tag membership. Under \"tag\", a note carrying N of the tags present in the filtered result set contributes to N separate groups (a membership rollup, not a partition)." },
-              op: { type: "string", enum: ["count", "sum"], description: "\"count\": number of matching notes per group. \"sum\": sum of `field` per group." },
+              group_by: { type: "string", description: "What to group by: an indexed metadata field name (declared `indexed: true` in a tag schema — same FIELD_NOT_INDEXED contract as `metadata` operator queries / `order_by`), or the special value \"tag\" to group by tag membership. Under \"tag\", a note carrying N of the tags present in the filtered result set contributes to N separate groups (a membership rollup, not a partition). Optional when op is \"count\" — omit it for a single filtered-total row `{group: null, value: N}` (vault#626). Required for \"sum\"." },
+              op: { type: "string", enum: ["count", "sum"], description: "\"count\": number of matching notes per group, or the filtered total when group_by is omitted. \"sum\": sum of `field` per group." },
               field: { type: "string", description: "Required when `op` is \"sum\"; ignored for \"count\". Must be an indexed metadata field with a numeric storage type (declared `type: \"integer\"` or `type: \"boolean\"` — the only indexable numeric shapes; a bare `type: \"number\"` field is never indexed and a TEXT-backed field can't be summed)." },
             },
-            required: ["group_by", "op"],
-            description: "Aggregation / rollup mode. Every OTHER filter above (tag, metadata, date range, write-attribution, ...) is applied FIRST, exactly as a normal query would; the matching notes are then grouped and the response becomes `[{group, value}]` instead of note rows — one row per group, `value` is the count/sum. A note whose group_by value is absent collects into one `{group: null, value: ...}` row rather than being dropped. Mutually exclusive with `search`, `near`, and `cursor` (a rollup has no pagination/ranking/graph-neighborhood shape). Tag-scoped sessions see the SAME visibility enforcement as every other read — the rollup is computed only over notes the token can see.",
+            required: ["op"],
+            description: "Aggregation / rollup mode. Every OTHER filter above (tag, metadata, date range, write-attribution, ...) is applied FIRST, exactly as a normal query would; the matching notes are then grouped and the response becomes `[{group, value}]` instead of note rows — one row per group, `value` is the count/sum. Omit `group_by` with `op: \"count\"` for a filtered total (`[{group: null, value: N}]`, including `value: 0` on an empty match). A note whose group_by value is absent collects into one `{group: null, value: ...}` row rather than being dropped. Mutually exclusive with `search`, `near`, `cursor`, and `semantic` (a rollup has no pagination/ranking/graph-neighborhood shape). Tag-scoped sessions see the SAME visibility enforcement as every other read — the rollup is computed only over notes the token can see.",
           },
           near: {
             type: "object",

package/core/src/mcp.ts

@@ -757,7 +757,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
         }
 
         // --- Aggregation / rollup mode (top new-feature ask from a UX round) ---
-        // Mutually exclusive with `search`/`near`/`cursor` — a rollup returns
+        // Mutually exclusive with `search`/`near`/`cursor`/`semantic` — a rollup returns
         // one row per group, not a paginated / graph-scoped / ranked note
         // list — so reject those combos loudly before touching the DB.
         if (params.aggregate) {
@@ -792,7 +792,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           const aggRaw = params.aggregate as Record<string, unknown>;
           if (typeof aggRaw !== "object" || aggRaw === null || Array.isArray(aggRaw)) {
             throw new QueryError(
-              `aggregate must be an object: {group_by, op, field?}`,
+              `aggregate must be an object: {op, group_by?, field?}`,
               "INVALID_QUERY",
               { error_type: "invalid_query", field: "aggregate", got: aggRaw },
             );
@@ -802,7 +802,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           // `aggregateNotes` itself, reusing the exact FIELD_NOT_INDEXED /
           // INVALID_QUERY contract every other query surface uses.
           const aggregateSpec = {
-            group_by: aggRaw.group_by as string,
+            ...(typeof aggRaw.group_by === "string" ? { group_by: aggRaw.group_by } : {}),
             op: aggRaw.op as "count" | "sum",
             field: aggRaw.field as string | undefined,
           };
@@ -843,7 +843,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           // Core stays scope-unaware — it only invokes the plain closure.
           const aggAllMatches = await store.queryNotes({ ...aggFilterOpts, limit: 1000000 });
           const aggVisibleIds = aggAllMatches.filter(aggregateVisibility).map((n) => n.id);
-          if (aggVisibleIds.length === 0) return [];
+          // Always run the rollup, even on an empty visible set: ungrouped
+          // count (vault#626) must return `[{group:null,value:0}]`, not `[]`.
           return await store.aggregateNotes({ ids: aggVisibleIds, aggregate: aggregateSpec });
         }
 

package/core/src/notes.ts

@@ -1507,6 +1507,11 @@ export function queryNotes(db: Database, opts: QueryOpts, _outUpdatedAtMs?: Map<
  * `indexed-fields.ts`'s `TYPE_MAP` — and a `TEXT`-backed field can't be
  * summed). `op: "count"` ignores `field`.
  *
+ * `op: "count"` with no `group_by` (vault#626) is the filtered total: one
+ * row `[{group: null, value: N}]` so list parsers keep a single shape.
+ * `op: "sum"` still requires `group_by`. An empty match set still returns
+ * that one row with `value: 0`, never `[]`.
+ *
  * A note whose group_by value is absent/null collects into one
  * `{group: null, ...}` row — standard SQL `GROUP BY` behavior, not silently
  * dropped.
@@ -1520,29 +1525,34 @@ export function aggregateNotes(db: Database, opts: QueryOpts): AggregateRow[] {
       {
         error_type: "invalid_query",
         field: "aggregate",
-        hint: `pass { group_by, op } — group_by is an indexed metadata field or "tag"; op is "count" or "sum"`,
+        hint: `pass { op, group_by? } — op is "count" or "sum"; group_by is an indexed metadata field or "tag" (required for sum, optional for count)`,
       },
     );
   }
-  if (typeof spec.group_by !== "string" || spec.group_by.length === 0) {
+  if (spec.op !== "count" && spec.op !== "sum") {
+    throw new QueryError(
+      `invalid aggregate.op: ${JSON.stringify(spec.op)} — must be "count" or "sum"`,
+      "INVALID_QUERY",
+      { error_type: "invalid_query", field: "aggregate.op", got: spec.op, hint: `pass "count" or "sum"` },
+    );
+  }
+  const ungroupedCount = spec.op === "count" && spec.group_by === undefined;
+  if (!ungroupedCount && (typeof spec.group_by !== "string" || spec.group_by.length === 0)) {
     throw new QueryError(
-      `aggregate.group_by is required — an indexed metadata field name, or "tag"`,
+      spec.op === "sum"
+        ? `aggregate.group_by is required when aggregate.op is "sum" — an indexed metadata field name, or "tag"`
+        : `aggregate.group_by is required — an indexed metadata field name, or "tag"`,
       "INVALID_QUERY",
       {
         error_type: "invalid_query",
         field: "aggregate.group_by",
         got: spec.group_by,
-        hint: `pass an indexed metadata field name, or "tag"`,
+        hint: spec.op === "count"
+          ? `omit group_by for a filtered total, or pass an indexed metadata field name / "tag"`
+          : `pass an indexed metadata field name, or "tag"`,
       },
     );
   }
-  if (spec.op !== "count" && spec.op !== "sum") {
-    throw new QueryError(
-      `invalid aggregate.op: ${JSON.stringify(spec.op)} — must be "count" or "sum"`,
-      "INVALID_QUERY",
-      { error_type: "invalid_query", field: "aggregate.op", got: spec.op, hint: `pass "count" or "sum"` },
-    );
-  }
   if (spec.op === "sum" && (typeof spec.field !== "string" || spec.field.length === 0)) {
     throw new QueryError(
       `aggregate.field is required when aggregate.op is "sum"`,
@@ -1556,6 +1566,14 @@ export function aggregateNotes(db: Database, opts: QueryOpts): AggregateRow[] {
   }
 
   const { conditions, params } = buildFilterConditions(db, opts);
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+
+  if (ungroupedCount) {
+    const row = db.prepare(
+      `SELECT COUNT(*) AS value FROM notes n ${whereClause}`,
+    ).get(...params) as { value: number | null } | null;
+    return [{ group: null, value: row?.value ?? 0 }];
+  }
 
   const groupByTag = spec.group_by === "tag";
   let groupExpr: string;
@@ -1567,7 +1585,7 @@ export function aggregateNotes(db: Database, opts: QueryOpts): AggregateRow[] {
     // `group_by` came from indexed_fields (validated via FIELD_NAME_RE at
     // declaration time), so interpolating the column name is safe — same
     // justification `orderBy`/`buildOperatorClause` use.
-    requireIndexedField(db, spec.group_by);
+    requireIndexedField(db, spec.group_by!);
     groupExpr = `"meta_${spec.group_by}"`;
     fromClause = "FROM notes n";
   }
@@ -1592,7 +1610,6 @@ export function aggregateNotes(db: Database, opts: QueryOpts): AggregateRow[] {
     valueExpr = `SUM("meta_${spec.field}")`;
   }
 
-  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const sql = `
     SELECT ${groupExpr} AS group_key, ${valueExpr} AS value
     ${fromClause}

package/core/src/types.ts

@@ -337,9 +337,13 @@ export interface AggregateSpec {
    * `"tag"` to group by tag membership. Under `"tag"`, a note carrying N of
    * the tags in the (filtered) result set contributes to N separate groups
    * — this is a membership rollup, not a partition.
+   *
+   * Optional when `op` is `"count"` (vault#626): omitting `group_by` returns
+   * a single filtered-total row `[{group: null, value: N}]` instead of a
+   * per-group rollup. Required for `"sum"`.
    */
-  group_by: string;
-  /** `"count"` — number of matching notes per group. `"sum"` — sum of `field` per group. */
+  group_by?: string;
+  /** `"count"` — number of matching notes per group (or the filtered total when `group_by` is omitted). `"sum"` — sum of `field` per group. */
   op: "count" | "sum";
   /**
    * Required when `op` is `"sum"`; ignored for `"count"`. Must be an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.7",
+  "version": "0.7.8-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/aggregate-routes.test.ts

@@ -149,6 +149,72 @@ describe("REST GET /notes — aggregate errors", () => {
     const body: any = await res.json();
     expect(body.field).toBe("aggregate");
   });
+
+  it("400s when aggregate is combined with search (no silent fall-through to rows)", async () => {
+    const res = await get("?search=hello&aggregate[op]=count");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.field).toBe("aggregate");
+    expect(body.code).toBe("INVALID_QUERY");
+    expect(body.error_type).toBe("invalid_query");
+  });
+
+  it("400s when aggregate is combined with semantic (no silent fall-through to rows)", async () => {
+    const res = await get("?semantic=true&near_text=hello&aggregate[op]=count");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.field).toBe("aggregate");
+    expect(body.code).toBe("INVALID_QUERY");
+    expect(body.error_type).toBe("invalid_query");
+  });
+
+  it("400s when sum has no group_by", async () => {
+    await store.upsertTagRecord("expense", { fields: { amount: { type: "integer", indexed: true } } });
+    const res = await get("?aggregate[op]=sum&aggregate[field]=amount");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.field).toBe("aggregate.group_by");
+  });
+});
+
+describe("REST GET /notes — aggregate: count without group_by (vault#626)", () => {
+  it("returns [{group: null, value: N}] for the filtered set", async () => {
+    await store.createNote("a", { tags: ["work"] });
+    await store.createNote("b", { tags: ["work"] });
+    await store.createNote("c", { tags: ["personal"] });
+
+    const all = await get("?aggregate[op]=count");
+    expect(all.status).toBe(200);
+    expect(await all.json()).toEqual([{ group: null, value: 3 }]);
+
+    const filtered = await get("?tag=work&aggregate[op]=count");
+    expect(filtered.status).toBe(200);
+    expect(await filtered.json()).toEqual([{ group: null, value: 2 }]);
+  });
+
+  it("an empty vault still returns the zero row, not []", async () => {
+    const res = await get("?aggregate[op]=count");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ group: null, value: 0 }]);
+  });
+
+  it("a scoped token with no visible matches gets a zero total, not a leak", async () => {
+    await store.createNote("out-of-scope only", { tags: ["work"] });
+    const scoped: TagScopeCtx = { allowed: new Set(["health"]), raw: ["health"] };
+    const res = await get("?aggregate[op]=count", scoped);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ group: null, value: 0 }]);
+  });
+
+  it("a scoped token's total excludes out-of-scope notes", async () => {
+    await store.createNote("in", { tags: ["health"] });
+    await store.createNote("out 1", { tags: ["work"] });
+    await store.createNote("out 2", { tags: ["work"] });
+    const scoped: TagScopeCtx = { allowed: new Set(["health"]), raw: ["health"] };
+    const res = await get("?aggregate[op]=count", scoped);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([{ group: null, value: 1 }]);
+  });
 });
 
 describe("REST GET /notes — aggregate: group_by \"tag\"", () => {

package/src/mcp-query-notes-aggregate-scope.test.ts

@@ -154,6 +154,48 @@ describe("MCP query-notes aggregate × tag-scope — group_by \"tag\"", () => {
   });
 });
 
+describe("MCP query-notes aggregate — count without group_by (vault#626)", () => {
+  test("returns [{group: null, value: N}] for the filtered set", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("a", { tags: ["work"] });
+    await store.createNote("b", { tags: ["work"] });
+    await store.createNote("c", { tags: ["personal"] });
+
+    const tool = await queryNotesTool("journal", null);
+    expect(await tool.execute({ aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 3 },
+    ]);
+    expect(await tool.execute({ tag: "work", aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 2 },
+    ]);
+  });
+
+  test("a scoped token's total excludes out-of-scope notes", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("in", { tags: ["health"] });
+    await store.createNote("out 1", { tags: ["work"] });
+    await store.createNote("out 2", { tags: ["work"] });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    expect(await scopedTool.execute({ aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 1 },
+    ]);
+  });
+
+  test("a scoped token with no visible matches gets a zero total, not []", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("out-of-scope only", { tags: ["work"] });
+
+    const scopedTool = await queryNotesTool("journal", ["health"]);
+    expect(await scopedTool.execute({ aggregate: { op: "count" } })).toEqual([
+      { group: null, value: 0 },
+    ]);
+  });
+});
+
 describe("MCP query-notes aggregate — mutual exclusivity with search/near/cursor", () => {
   test("aggregate + search is rejected", async () => {
     seedVault("journal");

package/src/routes.ts

@@ -977,30 +977,34 @@ export function parseNotesQueryOpts(url: URL): {
  * aggregation params (bracket-style, consistent with `meta[field][op]=`
  * above) into an `AggregateSpec`. Absent entirely (none of the three keys
  * present) → `{}` — no aggregate intent, the caller falls through to a
- * normal query. `group_by` + `op` are required together when ANY of the
- * three is present; `field` is optional at the parser level (its
- * requiredness depends on `op`, enforced by `aggregateNotes` itself). Value
- * validity beyond shape (indexed field, numeric type, sum-requires-field)
- * is ALSO enforced by `aggregateNotes` — same FIELD_NOT_INDEXED /
- * INVALID_QUERY contract every other query surface uses.
+ * normal query. `op` is required when ANY of the three is present.
+ * `group_by` is required for `sum` and optional for `count` (vault#626 —
+ * `?aggregate[op]=count` alone is the filtered total). `field` is optional
+ * at the parser level (its requiredness depends on `op`, enforced by
+ * `aggregateNotes` itself). Value validity beyond shape (indexed field,
+ * numeric type, sum-requires-field) is ALSO enforced by `aggregateNotes` —
+ * same FIELD_NOT_INDEXED / INVALID_QUERY contract every other query
+ * surface uses.
  *
  * Returns `{ aggregate? }` or `{ error }` (a 400 Response) on a malformed
- * shape (missing `group_by`/`op`, or an unrecognized `op`).
+ * shape (missing `op`, `sum` without `group_by`, or an unrecognized `op`).
  */
 function parseAggregateParam(url: URL): { aggregate?: AggregateSpec; error?: Response } {
-  const groupBy = parseQuery(url, "aggregate[group_by]");
+  const groupByRaw = parseQuery(url, "aggregate[group_by]");
   const op = parseQuery(url, "aggregate[op]");
   const field = parseQuery(url, "aggregate[field]");
+  // Empty `aggregate[group_by]=` is omitted, not an empty grouping key.
+  const groupBy = groupByRaw === "" ? null : groupByRaw;
   if (groupBy === null && op === null && field === null) return {};
-  if (groupBy === null || op === null) {
+  if (op === null) {
     return {
       error: json(
         {
-          error: `aggregate requires both aggregate[group_by] and aggregate[op] — group_by is an indexed metadata field or "tag"; op is "count" or "sum".`,
+          error: `aggregate requires aggregate[op] ("count" or "sum"). group_by is optional for count (filtered total) and required for sum.`,
           code: "INVALID_QUERY",
           error_type: "invalid_query",
           field: "aggregate",
-          hint: `pass ?aggregate[group_by]=<field|tag>&aggregate[op]=<count|sum>[&aggregate[field]=<numeric field>]`,
+          hint: `pass ?aggregate[op]=count or ?aggregate[group_by]=<field|tag>&aggregate[op]=<count|sum>[&aggregate[field]=<numeric field>]`,
         },
         400,
       ),
@@ -1021,7 +1025,27 @@ function parseAggregateParam(url: URL): { aggregate?: AggregateSpec; error?: Res
       ),
     };
   }
-  return { aggregate: { group_by: groupBy, op, field: field ?? undefined } };
+  if (op === "sum" && groupBy === null) {
+    return {
+      error: json(
+        {
+          error: `aggregate[group_by] is required when aggregate[op] is "sum"`,
+          code: "INVALID_QUERY",
+          error_type: "invalid_query",
+          field: "aggregate.group_by",
+          hint: `pass ?aggregate[group_by]=<field|tag>&aggregate[op]=sum&aggregate[field]=<numeric field>`,
+        },
+        400,
+      ),
+    };
+  }
+  return {
+    aggregate: {
+      ...(groupBy !== null ? { group_by: groupBy } : {}),
+      op,
+      field: field ?? undefined,
+    },
+  };
 }
 
 /**
@@ -1259,6 +1283,20 @@ async function handleNotesInner(
             400,
           );
         }
+        const semanticAggregate = parseAggregateParam(url);
+        if (semanticAggregate.error) return semanticAggregate.error;
+        if (semanticAggregate.aggregate) {
+          return json(
+            {
+              error: "aggregate is incompatible with semantic search — a rollup returns groups, not ranked notes.",
+              code: "INVALID_QUERY",
+              error_type: "invalid_query",
+              field: "aggregate",
+              hint: "drop `semantic`/`near_text` when using `aggregate`",
+            },
+            400,
+          );
+        }
         if (parseQuery(url, "cursor") !== null) {
           return json(
             {
@@ -1374,6 +1412,25 @@ async function handleNotesInner(
         );
       }
 
+      // vault#626 — `search=` used to silently ignore `aggregate[...]` and
+      // return note rows. MCP already rejects the combo; REST must too.
+      if (search) {
+        const searchAggregate = parseAggregateParam(url);
+        if (searchAggregate.error) return searchAggregate.error;
+        if (searchAggregate.aggregate) {
+          return json(
+            {
+              error: "aggregate is incompatible with full-text search — pick one.",
+              code: "INVALID_QUERY",
+              error_type: "invalid_query",
+              field: "aggregate",
+              hint: "drop `search` when using `aggregate`",
+            },
+            400,
+          );
+        }
+      }
+
       // Full-text search
       if (search) {
         // vault#647: parse the structured filter grammar here too. Pre-fix
@@ -1612,9 +1669,9 @@ async function handleNotesInner(
             // (reusing the `ids` filter `near` already pushes into SQL).
             const allMatches = await store.queryNotes({ ...queryOpts, limit: 1000000, offset: 0 });
             const visible = filterNotesByTagScope(allMatches, tagScope.allowed, tagScope.raw);
-            rows = visible.length === 0
-              ? []
-              : await store.aggregateNotes({ ids: visible.map((n) => n.id), aggregate: aggregateParsed.aggregate });
+            // Always run the rollup, even on an empty visible set: ungrouped
+            // count (vault#626) must return `[{group:null,value:0}]`, not `[]`.
+            rows = await store.aggregateNotes({ ids: visible.map((n) => n.id), aggregate: aggregateParsed.aggregate });
             // That note-level narrowing isn't sufficient on its own under
             // `group_by: "tag"`: a note can be in scope via one tag while
             // ALSO carrying an out-of-scope co-tag, and a tag rollup's