Issue #1272: feat: record the Query Planner's caller from an optional X-LIF-Client header

[dereck-symmetry]

Description of Change

Problem. The Query Planner cannot tell who is calling it. GraphQL, Learner Data Export and the Advisor (via the MCP server) all reach the same /query, so "who asks for what", one of the questions #341's statistics exist to answer, has no answer.

Solution. An optional X-LIF-Client request header, recorded as client in every query statistics event (LIF_QUERY_STATISTICS, #341).

• Planner (query_planner_service, query_planner_restapi):
  • /query and /query_async read the header.
  • statistics.normalize_client() reduces it to a safe value once, at the service boundary.
  • All four query_planned outcomes and the query_completed event carry it. The orchestrator's results callback carries no caller, so LIFQueryPlannerJob remembers it from submission.
• Callers:
  • Learner Data Export (query_planner_client) sends learner-data-export.
  • The MCP server (graphql_client) sends semantic-search-mcp.
  • GraphQL (openapi_to_graphql) forwards the header it received, or sends graphql when there is none.

Why GraphQL forwards rather than naming itself. The MCP server never calls the planner directly: its path is MCP → GraphQL → Query Planner. If GraphQL always sent graphql, MCP traffic would be indistinguishable from direct GraphQL traffic at the planner, which defeats the point of the issue. Forwarding keeps the original caller. That was a deliberate choice among three options (forward / each hop names itself / record both client and via).

Optional, never required. A missing header is recorded as unknown, and the query proceeds exactly as before. The planner stays usable standalone (ADR 0004).

Validation, not just escaping. The value is caller-supplied and becomes a statistics dimension, so escaping it with json.dumps isn't enough. Anything that is not a short lowercase name ([a-z0-9][a-z0-9._-]{0,63}, full match) is recorded as invalid, never as itself. That keeps free text out of the logs, bounds the dimension's cardinality, and means a caller cannot smuggle person data in through the header (#1269). GraphQL relays the value unvalidated, so the check happens once, in the planner, where the value is recorded.

Header name. No X-LIF-* convention exists in the repo. The only custom headers are X-API-Key and X-API-Tenant-Schema, so nothing conflicts.

Deploy workflow. lif_semantic_search_mcp_server.yml's paths: filter didn't include components/lif/graphql_client/** (one of the #1171 gaps). Without it, merging this would not rebuild the MCP image, and MCP traffic would stay graphql until an unrelated rebuild. This PR adds that one line. The other changed bricks are already covered: openapi_to_graphql by lif_graphql_api.yml, query_planner_client by lif_learner_data_export_api.yml, and both planner bricks by lif_query_planner_api.yml.

Out of scope, deliberately. lif_to_lif_adapter's org-to-org GraphQL call is a fourth caller the issue doesn't list. It will appear at the other org as graphql.

How to test. uv run pytest test/components/lif/query_planner_service test/bases/lif/query_planner_restapi test/components/lif/openapi_to_graphql test/components/lif/query_planner_client test/components/lif/graphql_client.

Related Issues

Closes #1272
Refs #341
Refs #1131
Refs #1171

Type of Change

• New feature (non-breaking change which adds functionality)
• Infrastructure/deployment change

Project Area(s) Affected

• bases/
• components/
• test/ or e2e/
• API endpoints
• Documentation (docs/, READMEs, ARCHITECTURE.md, CLAUDE.md)

---

Checklist

• commit message follows commit guidelines (see commitlint.config.mjs)
• tests are included (unit and/or integration tests)
• code passes linting checks (uv run ruff check)
• code passes formatting checks (uv run ruff format)
• code passes type checking (uv run ty check)
• pre-commit hooks have been run successfully
• API changes: base (Python code) documentation in docs/
  and project README updated

Testing

• Automated tests added/updated

The acceptance criteria, each with its test:

• The planner records the caller in every event, defaulting to unknown. test_every_planned_outcome_records_the_client drives all four outcomes, since each emits from its own call site. test_the_client_survives_to_the_completed_event goes from submission through the results callback.
• A query without the header still succeeds and still emits statistics. test_query_without_the_client_header_succeeds_and_still_emits_statistics runs both /query and /query_async through a real TestClient with the real service; only the planner's outbound HTTP is faked.
• Each caller sets the header. There's one test per caller. GraphQL's run through a real FastAPI app with GraphQLRouter mounted as api_graphql mounts it, because the incoming request only reaches the resolver through the router's default context (info.context["request"]).
• Validation. Person data, JSON injection, an embedded newline plus a fake statistics marker, 65 characters, uppercase, a leading dash, and whitespace are each recorded as invalid. A separate test checks the raw value never appears in the logs.

Mutation-checked. Each of these mutants fails at least one test:

• the base drops the header;
• one outcome's call site forgets the client;
• the job doesn't remember it;
• no validation;
• match instead of fullmatch;
• GraphQL never forwards;
• GraphQL sends no header;
• Learner Data Export sends none;
• the MCP client sends none.

Existing tests changed. Four graphql_client tests assert the exact header dict sent. They now include X-LIF-Client; their API-key assertions are unchanged.

Additional Notes

Merge order:

• Issue #1171: fix: make deploy workflows watch every brick they package #1274 (bjagg's CF/CI: deploy workflow paths: filters miss packaged bricks — a brick-only change merges green and never rebuilds the image (9 of 11 services affected) #1171 sweep) adds the same graphql_client/** line to the MCP workflow, in a different hunk, so there's no textual conflict. If both merge, the path is listed twice, which is harmless. Whoever merges second can drop the duplicate. This PR keeps its own line so it works whichever order they land in.
• Issue #1264: fix: surface a Query Planner failure as a GraphQL error, not an empty result #1291 also edits type_factory.py, openapi_to_graphql/README.md and CHANGELOG.md, in different regions. The new GraphQL tests live in their own file (test_lif_client_header.py) so they cannot collide with Issue #1264: fix: surface a Query Planner failure as a GraphQL error, not an empty result #1291's additions to test_core.py.
• Issue #1258: fix: narrow the identity mapping key so it is a real B-tree #1299 and Issue #212: feat: Implement LangChain message trimming #1148 also touch CHANGELOG.md.

🤖 Generated with Claude Code

[bjagg]

Approving. You anticipated the review I'd have written, so I spent it testing the implementation rather than the design.

The validator holds up under adversarial input. A caller-supplied header that becomes a logged statistic is exactly where #1269-style leaks come back, so I fuzzed normalize_client directly:

input	recorded as
learner-data-export	itself
graphql\n (trailing newline)	invalid
graphql Person:Sentinel-1234 (suffix smuggle)	invalid
x","org_key":"evil (JSON break-out)	invalid
jane.doe@stateu.edu (PII)	invalid
grаphql (Cyrillic а)	invalid
GraphQL / .hidden / 65 chars	invalid
64 chars	itself (the documented limit)
empty / absent	unknown

fullmatch rather than match or a $-anchored pattern is what makes the first two rows right. $ matches before a trailing newline, and match only anchors the start. Both are pinned. Switching to match fails a test, and so does recording raw instead of the normalized value.

Safe to accept because it's observability-only. I traced every use of client through query_planner_restapi/core.py and query_planner_service/core.py. It flows into the statistics events and into LIFQueryPlannerJob, so the completion event can carry it, and nothing else. No branch, permission or routing decision reads it. That's what makes a spoofable, unauthenticated header acceptable, and I'd keep it that way. If client ever starts gating behaviour, it has to become authenticated first.

Forwarding through GraphQL is the right call, for the reason you gave: MCP → GraphQL → planner would otherwise collapse MCP traffic into graphql, and answering "who asks for what" is the whole point. Validating once, at the planner where the value is recorded, is also right, as opposed to at every hop.

The #1171 fix is real. I ran the #1274 guard against main and against this branch. graphql_client is unwatched by lif_semantic_search_mcp_server.yml on main, and watched here. Without that line the MCP image wouldn't have rebuilt, and MCP traffic would have kept reporting graphql until some unrelated change rebuilt it. Good catch; it's exactly the failure that guard exists for.

Full suite green: 876 passed.

One note for later, not blocking. Stating that lif_to_lif_adapter's org-to-org call will appear as graphql is the honest way to leave it out of scope. Once #1302 adds org_key, that traffic is at least attributable to the calling org, which may be enough.