…SCHEMA

Adds the pure projection helper that every MCP tool will run through at
the dispatch boundary (wired in U4). Helper is the single source of
truth for the two-gate contract.

- import jmespath from 'jmespath'.
- JMESPATH_MAX_EXPR_BYTES=1024, JMESPATH_MAX_OUTPUT_BYTES=262144
  (256 KB) as named exports — tests assert on them.
- JmespathFailKind = 'expression_too_long' | 'projection_too_large' |
  'invalid_expression'. Same enum string is used in BOTH the helper's
  `failed` field AND as the `_jmespath_error` envelope prefix, so the
  two surfaces can never drift.
- utf8ByteLength(s) = new TextEncoder().encode(s).length. Edge-safe
  (no Buffer dep, no String.length undercount on non-ASCII content).
- applyJmespath(value, exprArg) returns { text, failed? }. Pure;
  never throws. Identity path returns JSON.stringify(value) for
  undefined/empty/non-string exprArg. Input gate rejects before
  parser. Output gate stringifies once, checks utf8ByteLength, soft-
  fails on overrun. Failure envelope echoes original_keys (capped at
  50) so the LLM can self-correct in one retry.
- JMESPATH_SCHEMA near SUMMARY_SCHEMA — intentionally terse (~110
  bytes) to avoid x38 bloat across tools/list; full grammar + examples
  + caps + quota note live in initialize.instructions (U5).
- typecheck:api green, no new @ts-expect-error.
- Bundle delta (api/mcp.ts): +57,837 bytes raw / +9,377 bytes gzipped.
  Just over the 50 KB raw soft-trigger but gzipped is tiny; total
  bundle 466 KB / 92 KB gzipped — well under Vercel's 1 MB edge limit.

… RPC)

Extends the existing TOOL_LIST_RESPONSE build-time injection so every
tool's advertised inputSchema.properties gains `jmespath`. Cache tools
keep `summary`; RPC tools were not summarizable but ARE projectable
(JMESPath is shape-agnostic).

- No TOOL_REGISTRY mutation — purely a derived-response edit.
- Single new property per tool over the wire (cache tools already had
  `summary` from v1.3.0).
- Collision guard at module load: throws if any tool hand-declares
  `jmespath` (or a cache tool hand-declares `summary`) on its own
  inputSchema. Forces resolution at edit time rather than silent
  overwrite.
- 90/90 existing mcp.test.mjs cases still green.

…ingify)

Single insertion point at the dispatch boundary, after the cache (executeTool)
and RPC (tool._execute) branches converge. Both tool kinds are now
projectable via the same code path, no per-tool plumbing.

- applyJmespath returns the wire-ready JSON text; dispatch writes it
  straight into content[0].text. One JSON.stringify per request (no
  double-serialization cost).
- Sits INSIDE the existing try block, but does NOT participate in the
  Pro-quota DECR rollback path: applyJmespath never throws, soft-fails
  return a `_jmespath_error` envelope. A bad expression is a user
  error after successful tool dispatch, not a system error.
- Genuine tool-execution throws (e.g. cache_all_null) still hit the
  existing catch + DECR rollback unchanged.
- Composition order with the existing knobs: _postFilter -> summary
  (both inside executeTool) -> jmespath (here, at dispatch).
- Inline comment documents the contract so a future refactor doesn't
  silently relocate the wiring.
- 90/90 existing mcp.test.mjs cases still green; typecheck:api clean.

…rd sync

Teaches the LLM the JMESPath contract once at session-init via
MCP 2025-03-26's `initialize.result.instructions` field — grammar URL,
three worked examples, byte caps, and the bad-expression quota note.
~600 bytes emitted once per session vs the x38 bloat that would result
from duplicating the same text into every tool's description.

- SERVER_VERSION 1.3.0 -> 1.4.0 with full version-history block
  (bundle delta numbers + composition order documented).
- public/.well-known/mcp/server-card.json: serverInfo.version 1.4.0;
  new features.responseProjection: "jmespath" for discovery scanners.
- JMESPATH_MAX_EXPR_BYTES / JMESPATH_MAX_OUTPUT_BYTES / JmespathFailKind
  relocated to sit before SERVER_INSTRUCTIONS so the template can
  inline the caps without a temporal-dead-zone error at module load.
- 90/90 baseline mcp.test.mjs cases still green; typecheck:api clean;
  smoke script still green.

Two scripts that implement the U6 reproducible byte-savings A/B once
the three response fixtures are checked in:

- scripts/capture-mcp-fixture.mjs: one-shot prod capture. Hits the
  prod MCP endpoint with a bearer (env-key or Pro), unwraps the
  content[0].text JSON envelope, writes pretty-printed JSON to
  tests/fixtures/jmespath-samples/<name>.response.json. Supports
  --arg key=value for filter args.
- scripts/measure-jmespath-savings.mjs: reads each fixture, calls
  applyJmespath directly (bypassing executeTool / the cache fetch
  path — see README for the why), measures utf8ByteLength on the
  wire-shaped text both with and without a deterministic agent
  expression, emits a markdown table for the PR description. Uses
  the SAME utf8ByteLength helper the runtime cap uses, so reported
  numbers match the runtime contract exactly.
- tests/fixtures/jmespath-samples/README.md: refresh procedure + the
  three target tools (fat=get_market_data, medium=get_conflict_events,
  thin=get_chokepoint_status) + rationale for direct-fixture
  invocation over mcpHandler+mockDeps.

Fixtures themselves are not yet committed — first capture attempt
returned "Invalid API key" against the prod endpoint. They land in a
follow-up commit before merge.

Single test file covering the U2/U3/U4/U5 surfaces of v1.4.0:

Helper unit tests (applyJmespath, utf8ByteLength):
- Identity path (undefined / "" / non-string / null all return
  JSON.stringify(value) unchanged).
- Happy-path projections including multiselect-hash and @ identity.
- Invalid expression -> invalid_expression soft-fail.
- Input gate: oversized expression rejected before parser.
- UTF-8 byte accounting regression: a 300-emoji expression
  (.length=600, utf8=1200) is rejected because utf8 > cap, even
  though .length < cap. Catches any silent fallback to text.length.
- Output gate: 1000-item multiselect-hash duplication that bloats
  past 256 KB is rejected and returns a tiny error envelope.
- UTF-8 output gate covers 4-byte-char payloads where .length is
  under-cap but utf8 is over-cap.
- Enum consistency: failed field deep-equals the leading token of
  _jmespath_error for every failure kind.
- original_keys output for object / array / primitive / 100-key
  object truncation.

Constants + schema parity (over tools/list wire output):
- JMESPATH_MAX_EXPR_BYTES === 1024.
- JMESPATH_MAX_OUTPUT_BYTES === 256 KiB.
- JMESPATH_SCHEMA.description < 150 bytes (avoids x38 bloat).
- Description points readers to initialize.instructions.
- Every tool in tools/list advertises jmespath in inputSchema.properties.
- jmespath is never in any tool's required array.
- Cache tools have both summary + jmespath; RPC tools have only jmespath.

Initialize handshake:
- serverInfo.version === '1.4.0'.
- result.instructions present, mentions jmespath, includes grammar
  URL + both cap values + daily quota note.
- server-card.json.serverInfo.version matches SERVER_VERSION (cross-
  check that prevents future drift between the two files).
- server-card.json.features.responseProjection === 'jmespath'.
- capabilities + protocolVersion unchanged from v1.3.0.

Dispatch integration (mcpHandler direct invocation, mocked Upstash):
- Omitting jmespath returns byte-identical baseline (additive R3).
- Cache tool with projection shrinks the response.
- jmespath="" and jmespath=null behave as absent.
- Invalid expression returns soft envelope, HTTP 200, NO JSON-RPC error.
- Oversized expression returns expression_too_long soft envelope.
- Genuine cache_all_null still surfaces as -32603 — confirms
  applyJmespath's no-throw guarantee didn't regress the rollback path.
- jmespath composes with summary: true (summary first, projection second).

Test results: 37/37 green; combined 127/127 with the existing
tests/mcp.test.mjs (90 baseline + 37 new).

Closes the U6 measurement pipeline end-to-end. Three fixture files now
present so `scripts/measure-jmespath-savings.mjs` produces a markdown
table on every run (deterministic, reproducible).

Important: fixtures are SYNTHETIC stubs, not real prod captures. The
prod bearer provided during initial development was rejected by the
MCP endpoint (-32001 on both X-WorldMonitor-Key and Authorization
Bearer paths). Each fixture carries a top-level `_SYNTHETIC_` marker;
the README's first paragraph is a prominent warning. Replace before
merge via `scripts/capture-mcp-fixture.mjs` once a working bearer is
available.

What the synthetic stubs DO get right:
- envelope shape `{cached_at, stale, data: {...}}`
- cache-key label layout (e.g. `stocks-bootstrap`, `ucdp-events`,
  `transit-summaries`)
- relative field richness (fat tools have nested arrays of richly
  typed quotes, thin tools have shallow object lists)
- realistic projection expressions exercising hyphenated keys via
  JMESPath backtick-quoting

What they DON'T: absolute byte counts. Synthetic fat is ~2.8 KB;
real fat is expected ~5-10 KB. Reduction PERCENTAGES from this
fixture set:
  fat    86.5%  (2.8 KB -> 388 B)
  medium 78.2%  (2.7 KB -> 594 B)
  thin   85.6%  (1.1 KB -> 157 B)
These are in the same ballpark as the blog-cited 80-95% for similar
shapes; real captures should fall in or near this range.

Also corrects a pre-existing bug in the measurement script that this
end-to-end run surfaced: the script's CASES had projection expressions
referencing `data.stocks` etc., but real labels are `stocks-bootstrap`
(hyphenated, requiring JMESPath quoting). Fixed alongside.

typecheck:api clean; 127/127 combined tests still green.

Self-review nit picked up during the U7 wrap. No functional change.

User testing surfaced that search_flights returns 0 results for many
popular routes (e.g. JFK→LHR) when cabin_class is omitted, even though
the tool description advertises "default economy".

Live probe (HTTP 200, same date+route):
  - no cabin_class  → {"flights":[],"degraded":false,"error":""}
  - cabin_class=economy → 10+ real Delta/JetBlue/VS flights

Root cause: the relay / SerpAPI upstream returns empty for some routes
when cabin_class is unset. The MCP _execute was only forwarding the
param when the LLM explicitly provided it (`...(params.cabin_class ?
{cabin_class: ...} : {})`), so the LLM-default flow never sent it.

Fix: always forward cabin_class, defaulting to 'economy' (matching the
tool description's advertised default). Applied to both flight tools:
  - search_flights (api/mcp.ts:2336 region)
  - search_flight_prices_by_date (api/mcp.ts:2381 region)

The underlying handler at server/worldmonitor/aviation/v1/search-
google-flights.ts has the same shape for direct API callers — leaving
that alone for now since changing handler defaults is a behaviour
change for non-MCP consumers. Worth a follow-up.

typecheck:api clean; 127/127 tests still green.

…with fix

Companion to 315a98e (default cabin_class to 'economy' for both flight
tools). That fix changed runtime behaviour for search_flight_prices_by_date
but didn't update the inputSchema description — it still said "(optional)"
while the _execute now defaults to economy.

Updated to "(optional, default economy)" so the contract advertised to
the LLM matches what the tool actually sends.

Found during a broader audit prompted by user asking "what if 10 other
MCP tools have the same bug?". Audit result: NO other tools had the
exact "advertised default not enforced" bug. All 23 cache-tool
limit:default 30 claims are enforced via argNum(params.limit) ??
DEFAULT_LIST_LIMIT; the remaining 4 RPC-tool defaults are correctly
applied. Two smaller follow-ups identified — this commit fixes one;
the other (trip_duration validation gap when is_round_trip=true)
deferred to a separate scoped commit.

…nforced)

Regression guard against the bug class that broke search_flights — a
tool description that claims "(default X)" but whose _execute uses the
conditional-spread anti-pattern `...(params.<key> ? { <key>: ... } : {})`,
so the LLM-default flow never sends the param to the upstream.

Three checks:

1. Matcher self-check (3 cases) — proves the regex actually catches the
   exact flight-bug shape and doesn't false-positive on the fixed shape
   or on other keys.

2. Source-wide audit — for every tool block in api/mcp.ts, for every
   inputSchema property whose description contains "default", asserts
   the conditional-spread anti-pattern does NOT appear for that key.
   This is the systemic guard: any future tool addition that has the
   bug shape fails CI on day one.

3. Cache-tool limit:default 30 enforcement — for every cache tool that
   advertises "limit: default 30" in its description, asserts the block
   references DEFAULT_LIST_LIMIT somewhere (the centrally-applied cap
   from v1.3.0 / issue #3678).

Plus a positive assertion that the flight fix shape (`cabin_class:
String(params.cabin_class ?? 'economy')`) appears exactly twice in
api/mcp.ts — belt-and-braces in case a future PR deletes both the
description claim AND the conditional-spread, which the negative-only
checks would accept.

Note: this is a source-text test, not a behavioural one. It reads
api/mcp.ts as a string and regexes over tool blocks. Pros: catches
the bug class without needing __TESTING__ exports or behavioural
mocking. Cons: if the build pipeline ever transforms source before
tests run, this needs reworking — but we run tsx against source
directly, so it's fine today.

Result: 6/6 new tests pass; combined 133/133 with the existing
mcp.test.mjs + mcp-jmespath.test.mjs.

Reviewer P1: the prior change at .github/workflows/test.yml:46
expanded the existing edge-bundle find loop from api/*.js to
api/*.{js,ts}. That recursive pull caught unrelated TS endpoints
that esbuild can't bundle without extra loaders — specifically
api/brief/carousel/[userId]/[issueDate]/[page].ts which uses
@vercel/og's WASM imports:

  No loader is configured for ".wasm" files

The PR only needed api/mcp.ts in the loop (the entry that gets the
new jmespath import). Restored the original api/*.js find loop
unchanged, added a separate explicit allowlist loop for the TS
entries we actually want to bundle-check. New entries are opt-in
with an inline comment requiring a local esbuild dry-run before
addition — prevents this regression class from recurring.

Verified locally: JS loop succeeds across all existing api/*.js;
TS allowlist succeeds on api/mcp.ts; no other endpoints pulled in.

…jection