@medicine-wheel/app 0.6.3 → 0.7.0

package/README.md

@@ -222,6 +222,36 @@ mw node list
 The `mw` CLI uses HTTP against the running server by default; MCP fallback is
 available via a local `MW_MCP_PATH`.
 
+## Contributors
+
+### Code Contributors
+
+This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
+<a href="https://github.com/undefined/undefined/graphs/contributors"><img src="https://opencollective.com/@medicine-wheel/app/contributors.svg?width=890&button=false" /></a>
+
+### Financial Contributors
+
+Become a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/@medicine-wheel/app/contribute)]
+
+#### Individuals
+
+<a href="https://opencollective.com/@medicine-wheel/app"><img src="https://opencollective.com/@medicine-wheel/app/individuals.svg?width=890"></a>
+
+#### Organizations
+
+Support this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/@medicine-wheel/app/contribute)]
+
+<a href="https://opencollective.com/@medicine-wheel/app/organization/0/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/0/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/1/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/1/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/2/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/2/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/3/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/3/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/4/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/4/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/5/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/5/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/6/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/6/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/7/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/7/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/8/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/8/avatar.svg"></a>
+<a href="https://opencollective.com/@medicine-wheel/app/organization/9/website"><img src="https://opencollective.com/@medicine-wheel/app/organization/9/avatar.svg"></a>
+
 ## License
 
 MIT  see [LICENSE](LICENSE)

package/app/accountability/page.tsx

@@ -21,8 +21,8 @@ export default function AccountabilityPage() {
   useEffect(() => {
     Promise.all([
       fetch("/api/resources").then((r) => r.json()),
-      fetch("/api/nodes").then((r) => r.json()),
-      fetch("/api/edges").then((r) => r.json()),
+      fetch("/api/nodes?limit=all").then((r) => r.json()),
+      fetch("/api/edges?limit=all").then((r) => r.json()),
       fetch("/api/ceremonies").then((r) => r.json()),
       fetch("/api/narrative/beats").then((r) => r.json()),
     ]).then(([res, nodesResponse, e, c, b]) => {

package/app/api/ceremonies/[id]/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from "next/server";
+import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
+
+type RouteContext = { params: Promise<{ id: string }> };
+
+export async function GET(_request: Request, context: RouteContext) {
+  try {
+    const { id } = await context.params;
+    const store = await createProvider();
+    const ceremony = await store.getCeremony(id);
+
+    if (!ceremony) {
+      return NextResponse.json(
+        { error: `Ceremony not found: ${id}` },
+        { status: 404 },
+      );
+    }
+
+    return NextResponse.json({ ceremony, provider: detectProvider() });
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/api/ceremonies/route.ts

@@ -1,14 +1,21 @@
 import { NextResponse } from "next/server";
 import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
+import { ceremonyBelongsToEpisode } from "@/lib/ceremony-response";
 
 export async function GET(request: Request) {
   try {
     const { searchParams } = new URL(request.url);
     const direction = searchParams.get("direction");
     const type = searchParams.get("type");
+    const episodePath = searchParams.get("episode_path");
 
     const store = await createProvider();
-    let ceremonies = await store.getAllCeremonies();
+    // Provider list methods intentionally default to one page (100). A scoped
+    // episode query must search the complete ceremony store before filtering,
+    // or an older but valid ceremony silently disappears from its episode.
+    let ceremonies = await store.getAllCeremonies(
+      episodePath ? Number.MAX_SAFE_INTEGER : undefined,
+    );
 
     if (direction) {
       ceremonies = ceremonies.filter((c) => c.direction === direction);
@@ -18,6 +25,12 @@ export async function GET(request: Request) {
       ceremonies = ceremonies.filter((c) => c.type === type);
     }
 
+    if (episodePath) {
+      ceremonies = ceremonies.filter((ceremony) =>
+        ceremonyBelongsToEpisode(ceremony, episodePath),
+      );
+    }
+
     return NextResponse.json({ 
       ceremonies, 
       provider: detectProvider(),

package/app/api/edges/route.ts

@@ -5,6 +5,7 @@ import {
   detectProvider,
   EdgeNotFoundError,
 } from "@medicine-wheel/storage-provider";
+import { parseLimit } from "@/lib/api-paging";
 
 const EdgeCreateSchema = z.object({
   from_id: z.string({ required_error: "from_id is required" }).trim().min(1),
@@ -83,10 +84,27 @@ function unexpected(error: unknown) {
   return NextResponse.json({ error: message }, { status: 500 });
 }
 
-export async function GET() {
+/**
+ * Relations, oldest-visible-first as the provider orders them.
+ *
+ * The response stays a bare array. Five callers parse it that way — the graph,
+ * relations, nodes and accountability pages, and `mcp/src/http-store.ts` — so
+ * wrapping it in an object to carry a total would break the MCP server to fix a
+ * page. `?limit=all` is the honest ask instead, and a caller that wants the
+ * count of what it received can read `.length` of a complete answer.
+ *
+ * Without it this route took `getAllEdges()`'s 100-row default in silence: the
+ * graph drew 100 of 191 relations, and 27 of those 100 pointed at nodes the
+ * nodes route had not sent, so React Flow dropped them without a word.
+ */
+export async function GET(request: Request) {
   try {
+    const { searchParams } = new URL(request.url);
+    const limit = parseLimit(searchParams.get("limit"));
+    if (limit instanceof NextResponse) return limit;
+
     const store = await createProvider();
-    const edges = await store.getAllEdges();
+    const edges = await store.getAllEdges(limit ?? Number.MAX_SAFE_INTEGER);
     return NextResponse.json(edges);
   } catch (error: unknown) {
     return unexpected(error);

package/app/api/nodes/[id]/web/route.ts

@@ -0,0 +1,287 @@
+import { NextResponse } from "next/server";
+import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
+import { traverse } from "@medicine-wheel/relational-query";
+import type { TraversalDirection } from "@medicine-wheel/relational-query";
+import type { RelationalNode } from "@medicine-wheel/ontology-core";
+import type { RelationalEdge as OntologyEdge } from "@medicine-wheel/ontology-core";
+import type { RelationalEdge as StoredEdge } from "@medicine-wheel/storage-provider";
+
+/**
+ * One node's relational web — the node, everything within N hops, and the
+ * relations among them.
+ *
+ * `@medicine-wheel/relational-query` has shipped `traverse` and `neighborhood`
+ * with depth limits, direction filters, ceremony boundaries and OCAP guards for
+ * some time, and has been a declared dependency of this app the whole while.
+ * Nothing imported it: `grep -rn "@medicine-wheel/relational-query" app/ lib/`
+ * returned nothing. The wheel could always answer "this node and what touches
+ * it" and had no way to be asked. This route is the asking.
+ *
+ * It exists because the graph draws every node it is given on one wheel. At 205
+ * nodes that is a field of dots in which 37% have no edge at all and the largest
+ * hubs are systemd units, and no amount of layout work fixes a question nobody
+ * can narrow. The fix for "I cannot navigate" is not a prettier wheel; it is
+ * being able to ask for less.
+ */
+
+/**
+ * Hops from the root.
+ *
+ * One, not two. Two was the first default and it was a trap: with a chronicle
+ * root that every episode `belongs_to`, depth 2 from any episode goes
+ * episode → root → all 81 other episodes. Episode 011 has exactly one relation
+ * and its "2-hop neighbourhood" was 83 nodes — the corpus, wearing the name of a
+ * neighbourhood. `maxExpandDegree` below fixes the cause; this default keeps the
+ * first thing a person sees small.
+ */
+const DEFAULT_DEPTH = 1;
+
+/**
+ * A node with more relations than this is shown but not expanded through.
+ *
+ * 20 is chosen against the measured shape of this wheel rather than as a round
+ * number: the chronicle root sits at **82**, and the next-largest nodes are
+ * `gaia` at 17, `ilex` at 14 and `episode-332` at 14. So the threshold separates
+ * the one true container from the busiest ordinary nodes with room on both
+ * sides, and a corpus that grows a second container will cross it before any
+ * episode does. Override per request with `?hub=`; `?hub=0` disables suppression.
+ */
+const DEFAULT_MAX_EXPAND_DEGREE = 20;
+
+/**
+ * Beyond this the answer stops being a neighbourhood and becomes the store with
+ * extra steps — at depth 6 a connected component is usually fully covered, and
+ * the caller wanted `/api/nodes?limit=all` instead.
+ */
+const MAX_DEPTH = 6;
+
+/**
+ * `follow`, not `direction`.
+ *
+ * This route has two unrelated notions of direction and collapsing them would be
+ * a quiet, permanent trap: the wheel's `DirectionName` (east/south/west/north)
+ * and the traversal's `TraversalDirection` (outgoing/incoming/both). `direction`
+ * already means the former on `/api/nodes`, and a reader who assumed it meant
+ * the same here would get a silently different query. So edge-following is
+ * `follow`, and `direction` keeps its established meaning.
+ */
+const FOLLOW_VALUES = ["outgoing", "incoming", "both"] as const;
+
+const WEB_QUERY_PARAMS = ["depth", "follow", "direction", "kind", "type", "hub"] as const;
+
+function badRequest(error: string, extra: Record<string, unknown> = {}) {
+  return NextResponse.json({ error, ...extra }, { status: 400 });
+}
+
+function parseDepth(raw: string | null): number | NextResponse {
+  if (raw === null || raw === "") return DEFAULT_DEPTH;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_DEPTH) {
+    return badRequest(`Invalid depth: ${raw} — nothing was traversed.`, {
+      hint: `depth must be an integer from 1 to ${MAX_DEPTH}.`,
+    });
+  }
+  return parsed;
+}
+
+function parseFollow(raw: string | null): TraversalDirection | NextResponse {
+  if (raw === null || raw === "") return "both";
+  if ((FOLLOW_VALUES as readonly string[]).includes(raw)) return raw as TraversalDirection;
+  return badRequest(`Invalid follow: ${raw} — nothing was traversed.`, {
+    accepted: [...FOLLOW_VALUES],
+  });
+}
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  try {
+    const { id } = await params;
+    const { searchParams } = new URL(request.url);
+
+    // The same contract as /api/nodes: an unrecognised parameter is a 400 naming
+    // what is accepted, never a filtered-looking payload that filtered nothing.
+    const unknown = [...new Set(searchParams.keys())].filter(
+      (key) => !(WEB_QUERY_PARAMS as readonly string[]).includes(key),
+    );
+    if (unknown.length > 0) {
+      return badRequest(
+        `Unknown query parameter${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} — nothing was traversed.`,
+        { accepted: [...WEB_QUERY_PARAMS] },
+      );
+    }
+
+    const depth = parseDepth(searchParams.get("depth"));
+    if (depth instanceof NextResponse) return depth;
+
+    const follow = parseFollow(searchParams.get("follow"));
+    if (follow instanceof NextResponse) return follow;
+
+    const rawHub = searchParams.get("hub");
+    let maxExpandDegree: number | undefined = DEFAULT_MAX_EXPAND_DEGREE;
+    if (rawHub !== null && rawHub !== "") {
+      const parsed = Number(rawHub);
+      if (!Number.isInteger(parsed) || parsed < 0) {
+        return badRequest(`Invalid hub: ${rawHub} — nothing was traversed.`, {
+          hint: "hub must be a non-negative integer; 0 expands through everything.",
+        });
+      }
+      // 0 means "no suppression", which is the honest spelling of "expand
+      // through everything" — not "suppress nodes with more than zero edges".
+      maxExpandDegree = parsed === 0 ? undefined : parsed;
+    }
+
+    const store = await createProvider();
+
+    // The whole store, deliberately. A traversal over a 100-row page would walk
+    // a graph the store does not have and return a neighbourhood that is missing
+    // arbitrary neighbours — the same silent truncation the paging fix closed on
+    // the list routes, but harder to notice here because the answer is small by
+    // design and looks complete.
+    const [allNodes, allEdges] = await Promise.all([
+      store.getAllNodes(Number.MAX_SAFE_INTEGER),
+      store.getAllEdges(Number.MAX_SAFE_INTEGER),
+    ]);
+
+    const root = allNodes.find((n) => n.id === id);
+    if (!root) {
+      return NextResponse.json(
+        {
+          error: `No node with id ${id}.`,
+          hint: "Check the id on /nodes, or list them with /api/nodes?limit=all.",
+        },
+        { status: 404 },
+      );
+    }
+
+    // `storage-provider`'s RelationalEdge deliberately makes `id` optional —
+    // relations are identified by their (from_id, to_id) pair, which is why
+    // /api/edges addresses them as `?id=<from>:<to>`. `traverse` takes
+    // ontology-core's edge, where `id` is required. Rather than loosen the
+    // ontology or tighten the store, the pair-derived id is supplied here, using
+    // the composite form the edges route already established.
+    const traversable: OntologyEdge[] = allEdges.map((e) => ({
+      ...e,
+      id: e.id ?? `${e.from_id}:${e.to_id}`,
+    }));
+
+    const result = traverse(id, allNodes, traversable, [], {
+      maxDepth: depth,
+      direction: follow,
+      maxExpandDegree,
+      // The corpus already spells "container" directly, so say it rather than
+      // inferring it from degree. `chronicle_root` is one by definition however
+      // many episodes it holds; degree stays as the backstop for containers
+      // nobody has named. Suppressible with `?hub=0` along with the threshold.
+      containerKinds: maxExpandDegree === undefined ? [] : ["chronicle_root"],
+    });
+
+    const nodeById = new Map(allNodes.map((n) => [n.id, n]));
+    let nodes = [...result.visitedNodes]
+      .map((visitedId) => nodeById.get(visitedId))
+      .filter((n): n is RelationalNode => n !== undefined);
+
+    // Filters narrow what is *returned*, never what is *walked*. Filtering during
+    // the walk would cut the graph at every non-matching node and silently hide
+    // matches that sit two hops behind one — a neighbourhood is defined by the
+    // relations, and the filter is a view of it.
+    const kind = searchParams.get("kind") || undefined;
+    const type = searchParams.get("type") || undefined;
+    const direction = searchParams.get("direction") || undefined;
+    if (kind) nodes = nodes.filter((n) => n.metadata?.kind === kind);
+    if (type) nodes = nodes.filter((n) => n.type === type);
+    if (direction) nodes = nodes.filter((n) => n.direction === direction);
+
+    // The root always comes back, even when it fails its own filter. A web with
+    // no centre is not a web, and dropping it would make an empty result
+    // indistinguishable from a missing node.
+    if (!nodes.some((n) => n.id === root.id)) nodes = [root, ...nodes];
+
+    // Induced edges only: both endpoints present. An edge to a node that was not
+    // returned is exactly the dangling reference that made the main graph draw
+    // 53 unconnected dots out of 100 — a renderer receives it, cannot place one
+    // end, and drops it without a word.
+    // Filtered from the stored edges, not the traversable copy, so the response
+    // carries what the store actually holds rather than this route's synthetic
+    // ids. A consumer that round-trips an edge back to /api/edges must send the
+    // store's own shape.
+    // Reported by the traversal that made the decision, never recomputed here.
+    // The first version re-derived it from undirected whole-store degree while
+    // the walk had suppressed on direction-filtered degree — so under
+    // `?follow=outgoing` the walk expanded straight through the chronicle root
+    // (out-degree 0) while this told the caller it held 82 relations. Only one
+    // place can know, and it is not this one.
+    const nameById = new Map(allNodes.map((n) => [n.id, n.name]));
+    const hubsHeld = result.heldAtHubs.map((hold) => ({
+      id: hold.nodeId,
+      name: nameById.get(hold.nodeId) ?? hold.nodeId,
+      degree: hold.degree,
+      reason: hold.reason,
+      unexpanded: hold.unexpanded.length,
+    }));
+
+    const returnedIds = new Set(nodes.map((n) => n.id));
+
+    /**
+     * "There is more further out" — measured at the frontier, not inferred from
+     * why the walk stopped.
+     *
+     * `maxDepthReached` is the traversal's own flag and it means *the walk hit
+     * the limit*, which is not the same claim: a walk that reached every node in
+     * a component at exactly its depth limit sets it, with nothing beyond. And
+     * hub suppression sets nothing at all, so a walk that withheld 81 nodes
+     * reported `false` — the failure that started this fix, pointing the other
+     * way. Both are answered by asking the graph instead: does any returned node
+     * have an edge to a node that was not returned?
+     */
+    const hasMoreBeyond = allEdges.some(
+      (e) =>
+        (returnedIds.has(e.from_id) && !returnedIds.has(e.to_id)) ||
+        (returnedIds.has(e.to_id) && !returnedIds.has(e.from_id)),
+    );
+    const edges: StoredEdge[] = allEdges.filter(
+      (e) => returnedIds.has(e.from_id) && returnedIds.has(e.to_id),
+    );
+
+    return NextResponse.json({
+      root,
+      nodes,
+      edges,
+      provider: detectProvider(),
+      count: nodes.length,
+      depth,
+      follow,
+      // Which returned nodes were reached but not expanded through, and how much
+      // sits behind each. Reported rather than silently applied: a neighbourhood
+      // that quietly stopped at a container is the same class of lie as a list
+      // that quietly stopped at 100 rows.
+      hubs: hubsHeld,
+      maxExpandDegree: maxExpandDegree ?? null,
+      // True when there is more further out, for either reason: the walk hit the
+      // depth limit, or it stopped at a container.
+      //
+      // `maxDepthReached` alone was wrong here and wrong in the direction that
+      // hides things. Suppression skips the queue push, so a hub-terminated walk
+      // never sets it — measured on the live wheel, episode 011 at depth 3 came
+      // back `truncated: false` with 81 nodes withheld, and the page's "there is
+      // more further out" line went dark for exactly the node that motivated the
+      // feature. Both are the same claim to a reader: you are not seeing all of it.
+      //
+      // A container is only truncating when it actually withheld something. A
+      // `chronicle_root` with one child is held by kind and hides nothing, and
+      // saying "there is more further out" there would be the same false claim
+      // pointing the other way.
+      truncated: hasMoreBeyond,
+      // Kept apart so a caller can still tell the two reasons apart.
+      depthLimited: result.maxDepthReached,
+      // Crossings a ceremony or OCAP guard refused. Empty here because this route
+      // sets no guards, but carried so the shape does not change when it does.
+      escalations: result.escalations,
+      ...(kind || type || direction ? { filters: { kind, type, direction } } : {}),
+    });
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/api/nodes/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";
 import { z } from "zod";
 import { DirectionNameSchema, NodeTypeSchema } from "@medicine-wheel/ontology-core";
 import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
+import { parseLimit } from "@/lib/api-paging";
 
 const NodeCreateSchema = z.object({
   id: z.string().trim().min(1).optional(),
@@ -37,6 +38,20 @@ const NodeCreateSchema = z.object({
  */
 const NODE_FILTER_PARAMS = ["type", "direction", "kind", "parent_id"] as const;
 
+/**
+ * `limit` is accepted but is not a filter — it pages, it does not narrow. Kept in
+ * its own list so `filters` stays a description of what was *matched*, and so the
+ * echoed `filters` object never claims a page size was a predicate.
+ *
+ * It exists because the provider's default page size is 100 and a bare read took
+ * it silently: the graph drew 100 of 205 nodes and its own panel reported "100
+ * Nodes" as though that were the store. `?limit=all` asks for everything;
+ * `?limit=<n>` asks for n. The response now always carries `total`, so a caller
+ * that forgets to ask can still tell it was handed a window.
+ */
+const NODE_PAGING_PARAMS = ["limit"] as const;
+const NODE_QUERY_PARAMS = [...NODE_FILTER_PARAMS, ...NODE_PAGING_PARAMS] as const;
+
 /**
  * A silently-ignored filter is the failure this route exists to prevent: a
  * consumer that asks `?kinds=service` and gets a filtered-looking payload it
@@ -45,14 +60,14 @@ const NODE_FILTER_PARAMS = ["type", "direction", "kind", "parent_id"] as const;
  */
 function rejectUnknownParams(searchParams: URLSearchParams) {
   const unknown = [...new Set(searchParams.keys())].filter(
-    (key) => !(NODE_FILTER_PARAMS as readonly string[]).includes(key),
+    (key) => !(NODE_QUERY_PARAMS as readonly string[]).includes(key),
   );
   if (unknown.length === 0) return null;
 
   return NextResponse.json(
     {
       error: `Unknown query parameter${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} — nothing was filtered.`,
-      accepted: [...NODE_FILTER_PARAMS],
+      accepted: [...NODE_QUERY_PARAMS],
     },
     { status: 400 },
   );
@@ -72,17 +87,25 @@ export async function GET(request: Request) {
     ) as Partial<Record<(typeof NODE_FILTER_PARAMS)[number], string>>;
     const filtering = Object.values(filters).some(Boolean);
 
+    const limit = parseLimit(searchParams.get("limit"));
+    if (limit instanceof NextResponse) return limit;
+
     const store = await createProvider();
 
-    // Unfiltered reads keep the provider's own default page size, so this route
-    // answers a bare GET exactly as it always has. A *filtered* read must see
-    // the whole store or it answers from a truncated window — `getAllNodes()`
-    // defaults to 100 and the live wheel already holds 76, so filtering after
-    // the default slice would start returning quietly incomplete sets rather
-    // than failing loudly.
-    let nodes = filtering
-      ? await store.getAllNodes(Number.MAX_SAFE_INTEGER)
-      : await store.getAllNodes();
+    // Always read the whole store, then page here. Two reasons, both paid for:
+    //
+    // A *filtered* read must see everything or it answers from a truncated
+    // window — filtering after the provider's 100-row slice returns quietly
+    // incomplete sets rather than failing loudly.
+    //
+    // An *unfiltered* read must know the true size even when it returns a page,
+    // because the previous behaviour let `getAllNodes()` take its 100-row default
+    // in silence: the graph rendered 100 of 205 nodes and reported "100 Nodes".
+    // `total` below is what makes a windowed answer legible as one.
+    const allNodes = await store.getAllNodes(Number.MAX_SAFE_INTEGER);
+    const total = allNodes.length;
+
+    let nodes = allNodes;
 
     // Every supplied filter narrows (AND). Previously `type` and `direction`
     // were `else if`, so `?type=x&direction=y` silently dropped the direction —
@@ -95,10 +118,20 @@ export async function GET(request: Request) {
       nodes = nodes.filter((n) => n.metadata?.parent_id === filters.parent_id);
     }
 
+    // Paging is applied after filtering so `?kind=x&limit=10` means "ten of the
+    // matching nodes", not "the matches among the first ten".
+    const matched = nodes.length;
+    if (limit !== null && nodes.length > limit) nodes = nodes.slice(0, limit);
+
     return NextResponse.json({
       nodes,
       provider: detectProvider(),
       count: nodes.length,
+      // `total` is the whole store; `matched` is what the filters selected. When
+      // count < matched the caller is holding a page, and can now see that it is.
+      total,
+      ...(filtering ? { matched } : {}),
+      truncated: nodes.length < matched,
       // Echoed only when asked for, so an unfiltered response stays byte-identical
       // to what every existing consumer already parses — and so a caller can tell
       // an empty result from an unapplied filter.