fix(architecture): "overview" compact subset + aspects schema enum + server-side validation

[Kirchlive]

Summary

get_architecture(aspects=["overview"]) previously returned only {total_nodes, total_edges} — "overview" was never registered in either aspect guard, and the JSON schema accepted any string (no enum), so the typo / unregistered token was silently accepted and produced an empty payload.

This PR turns that footgun into a useful, validated tool.

What this PR does (3 layers)

1. "overview" is a useful compact subset, not an alias to "all"

The naive fix (treat "overview" as a synonym for "all") still produces the ~30k-char overflow payload — file_tree alone is ~275 entries on a mid-size repo, pushing the response past MAX_MCP_OUTPUT_TOKENS.

"overview" now expands to every aspect except file_tree, gated by a small static helper present in both files:

/* "overview" = compact architecture summary: every aspect EXCEPT the large
   per-file listing (file_tree), which alone dominates the payload (~275 entries)
   and pushes the response past MAX_MCP_OUTPUT_TOKENS. */
static bool aspect_in_overview(const char *name) {
    return strcmp(name, "file_tree") != 0;
}

src/store/store.c (gates DB sub-queries) and src/mcp/mcp.c (gates JSON serialization) both use it. Extending the block-list (e.g. also drop clusters) is one line.

2. JSON-Schema enum on aspects (advisory, client-side)

"aspects": {
  "type": "array",
  "items": {
    "type": "string",
    "enum": ["all","overview","structure","dependencies","routes","languages",
             "packages","entry_points","hotspots","boundaries","layers",
             "file_tree","clusters"]
  },
  "description": "Aspects to include. 'all' = everything; 'overview' = compact summary (all except file_tree); omit = all."
}

Self-documenting and gives well-behaved MCP clients a clean client-side error on typos.

3. Server-side validation (authoritative)

The enum alone is advisory — many MCP clients (Claude Code included) do not validate against tool schemas before sending. Verified empirically: with only the enum in place, aspects=["bogus"] still produced silent-empty.

Server-side validation closes the loop:

/* Canonical list of valid aspect tokens for get_architecture.
 * SSOT consumed by both the JSON-Schema enum (advisory, client-side)
 * and the server-side validation (authoritative). Update both together
 * if the aspect set changes. */
static const char *VALID_ASPECTS[] = {
    "all", "overview",
    "structure", "dependencies", "routes",
    "languages", "packages", "entry_points",
    "hotspots", "boundaries", "layers",
    "file_tree", "clusters",
    NULL
};

In handle_get_architecture, after parsing the aspects array, each token is checked against VALID_ASPECTS. On the first unknown token the handler returns isError: true with a model-friendly message listing the valid values, so an agent can self-correct without re-prompting:

Unknown aspect 'bogus'. Valid: all, overview, structure, dependencies, routes, languages, packages, entry_points, hotspots, boundaries, layers, file_tree, clusters.

Defense in depth: client-side enum catches well-behaved clients early; server-side aspect_is_valid catches everyone else.

Behavior matrix

Call	Before PR	After PR
omit aspects	full payload (=all)	unchanged
aspects=["all"]	full payload incl. file_tree	unchanged
aspects=["overview"]	silent {total_nodes,total_edges}	full payload minus file_tree, stays under cap
aspects=["hotspots"]	only hotspots	unchanged
aspects=["bogus"]	silent {total_nodes,total_edges}	isError: true with valid-values list

Locally verified

Built without libgit2 (make -f Makefile.cbm cbm LIBGIT2_FLAGS= LIBGIT2_LIBS=), installed to ~/.local/bin/codebase-memory-mcp. Hand-tests on an ~8k-node project after binary reload:

• ["overview"] → 13 keys, no file_tree, comfortably under output cap
• ["all"] → full payload incl. file_tree (unchanged)
• ["hotspots"] → only hotspots (unchanged)
• ["bogus"] → server returns the validation error string above

Commits

1. refactor(get_architecture): make "overview" a compact aspect subset + add aspects schema enum
2. feat(get_architecture): server-side aspect validation (defense in depth)

(Both are kept separate so the subset semantics and the validation layer can be reviewed independently.)

Test plan

• get_architecture(aspects=["overview"]) → rich payload without file_tree, fits under the MCP token cap
• get_architecture(aspects=["all"]) → unchanged, still includes file_tree
• get_architecture(aspects=["bogus"]) → isError: true with valid-values list
• get_architecture(aspects=["hotspots"]) → only hotspots
• get_architecture() (no aspects) → unchanged, returns all

[Kirchlive]

v3 summary — the PR went through three iterations; the final state to review is the combination of both commits:

1. aspects=["overview"] is a compact subset (every aspect except file_tree, which alone dominates the payload). Not an alias to ["all"]. ["all"] is unchanged.
2. JSON-Schema enum on aspects (advisory, client-side).
3. Server-side validation in handle_get_architecture: unknown aspects return isError: true with the valid-values list — the authoritative layer, since many MCP clients (Claude Code included) don't validate against tool schemas before sending. Both the enum and the validator are backed by a single VALID_ASPECTS[] SSOT array, so future additions stay in sync.

All four behaviors hand-verified after binary reload: ["overview"] 13 keys minus file_tree, ["all"] unchanged with file_tree, ["hotspots"] only hotspots, ["bogus"] → server validation error.

[DeusData]

Thanks @Kirchlive — the overview alias plus the aspect validation look good. Two CI items to clear before merge:

1. lint is failing — please run make -f Makefile.cbm lint-ci locally and fix what it reports.
2. DCO — the commit author email must match the Signed-off-by email (git commit --amend -s, or git rebase --signoff).

A small unit test for the bogus-aspect → error path would also be welcome. 🙏

[DeusData]

Thanks @Kirchlive — the core fix is real and well-diagnosed: aspects=["overview"] was silently accepted but returned an empty payload because "overview" was never registered in want_aspect/aspect_wanted. Mapping it to "all aspects except file_tree" is the right call.

A few things before it can land:

1. CI is red — dco (commits need Signed-off-by matching your author email; git rebase --signoff) and lint (clang-format-20 on the new code in store.c/mcp.c). Both must be green.
2. Rebase — it now conflicts with main: PR fix: get_architecture should honor path scope #614 (path-scoping for get_architecture) just merged and touches the same region.
3. Scope — the server-side aspect validation (returning isError for unknown tokens) is a behavior change beyond the overview fix; you've already isolated it as its own feat commit, so consider splitting it into a separate PR so the overview fix can land quickly on its own.
4. Tests — please add coverage for ["overview"] (non-empty payload) and, if you keep the validation, ["bogus"] (rejected).

The overview fix itself is small and valuable — happy to fast-track it once DCO/lint/rebase are sorted. Thanks!