enforce lossless NodeFilter (forbid extras + kind applicability)

[HumanBean17]

Scope

Implements plans/PLAN-LOSSLESS-PERMISSIVE-NODEFILTER.md § PR-N1 - Loud-fail NodeFilter only.

Files changed:

• mcp_v2.py
• server.py
• README.md
• tests/test_mcp_v2.py

Plan / propose references

• plans/PLAN-LOSSLESS-PERMISSIVE-NODEFILTER.md
• propose/LOSSLESS-PERMISSIVE-NODEFILTER-PROPOSE.md

What changed

• Set NodeFilter.model_config = ConfigDict(extra="forbid") to reject unknown top-level filter keys.
• Added populated-field + applicability helpers with stable field ordering for deterministic error messages.
• find_v2 now returns FindOutput(success=False, message=...) for filter unknown-key ValidationError and cross-kind populated fields before querying.
• search_v2 now enforces symbol applicability and returns SearchOutput(success=False, message=...) for invalid filter contract before iterating hits.
• neighbors_v2 now wraps filter parse/model validation failures as NeighborsOutput(success=False, message=...), preserves @validate_call argument validation raises, and fails loudly on first neighbor row where populated filter fields are inapplicable to that neighbor kind.
• exclude_roles: [] is treated as absent for applicability checks.
• Updated MCP tool/public docs text to match strict schema + kind-applicability contract and removed "irrelevant keys ignored" wording.
• Replaced old silent-ignore test and added PR-N1 test coverage for unknown keys, cross-kind failures, and neighbors validate_call behavior.
• Follow-up from review: added a guard test to ensure NodeFilter fields stay in sync with _NODEFILTER_APPLICABLE_FIELDS, and documented mixed-kind neighbors fail-on-first behavior in server.py and README.md.

Contract / compatibility notes

• No ontology bump.
• No re-index required.
• No graph/Kuzu/index/ranking surface changes.

Tests run

• .venv/bin/ruff check .
• .venv/bin/python -m pytest tests/test_mcp_v2.py -v
• .venv/bin/python -m pytest tests -v

Results:

• Ruff clean.
• tests/test_mcp_v2.py: 48 passed, 3 skipped.
• Full tests: 410 passed, 10 skipped (documented skips), 2 warnings.

Intentional design divergences

• None from plan PR-N1 resolved decisions.