ondata
diff --git a/‎CLAUDE.md‎
Lines changed: 17 additions & 16 deletions b/‎CLAUDE.md‎
Lines changed: 17 additions & 16 deletions
diff --git a/‎LOG.md‎
Lines changed: 33 additions & 0 deletions b/‎LOG.md‎
Lines changed: 33 additions & 0 deletions
diff --git a/‎docs/DEPLOYMENT.md‎
Lines changed: 4 additions & 0 deletions b/‎docs/DEPLOYMENT.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎docs/JSON-OUTPUT.md‎
Lines changed: 1 addition & 0 deletions b/‎docs/JSON-OUTPUT.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎openspec/changes/add-effective-query-json/proposal.md‎
Lines changed: 30 additions & 0 deletions b/‎openspec/changes/add-effective-query-json/proposal.md‎
Lines changed: 30 additions & 0 deletions
diff --git a/‎openspec/changes/add-effective-query-json/specs/ckan-search/spec.md‎
Lines changed: 15 additions & 0 deletions b/‎openspec/changes/add-effective-query-json/specs/ckan-search/spec.md‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎openspec/changes/add-effective-query-json/tasks.md‎
Lines changed: 15 additions & 0 deletions b/‎openspec/changes/add-effective-query-json/tasks.md‎
Lines changed: 15 additions & 0 deletions
diff --git a/‎package.json‎
Lines changed: 2 additions & 1 deletion b/‎package.json‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎scripts/README.md‎
Lines changed: 23 additions & 0 deletions b/‎scripts/README.md‎
Lines changed: 23 additions & 0 deletions
@@ -210,16 +210,16 @@ The server (`src/index.ts`):
    - `tools/datastore.ts`: `ckan_datastore_search`
    - `tools/status.ts`: `ckan_status_show`
 
-3. **MCP Resource Templates** (`resources/`)
+4. **MCP Resource Templates** (`resources/`)
    - `ckan://{server}/dataset/{id}` - Dataset metadata
    - `ckan://{server}/resource/{id}` - Resource metadata
    - `ckan://{server}/organization/{name}` - Organization metadata
 
-4. **Utility Functions** (`utils/`)
+5. **Utility Functions** (`utils/`)
    - `http.ts`: `makeCkanRequest<T>()` - HTTP client for CKAN API v3
    - `formatting.ts`: `truncateText()`, `formatDate()`, `formatBytes()`
 
-5. **Type Definitions** (`types.ts`)
+6. **Type Definitions** (`types.ts`)
    - `ResponseFormat` enum (MARKDOWN, JSON)
    - `ResponseFormatSchema` Zod validator
    - `CHARACTER_LIMIT` constant
@@ -228,11 +228,11 @@ The server (`src/index.ts`):
    - `stdio.ts`: Standard input/output (Claude Desktop)
    - `http.ts`: HTTP server (remote access)
 
-6. **Validation Schema**
+7. **Validation Schema**
    - Uses Zod to validate all tool inputs
    - Each tool has a strict schema that rejects extra parameters
 
-7. **Output Formatting**
+8. **Output Formatting**
    - All tools support two formats: `markdown` (default) and `json`
    - Markdown format optimized for human readability
    - JSON format returns compact objects with only essential fields (~70% token reduction vs raw CKAN API)
@@ -460,20 +460,21 @@ npm cannot resolve relative paths from the tarball.
 When releasing a new version:
 
 1. **Update version**: Edit the version field in `package.json`, `package-lock.json`, `manifest.json`, **`server.json`** (in `server.json` there are **two** fields: top-level `version` and `packages[0].version` — both must match), **`src/server.ts`** (MCP server version) and **`src/worker.ts`** (`/health` response). The two source files are easy to forget: v0.4.119 shipped with them still at 0.4.118. Check with `grep -rn "<old version>" package.json manifest.json server.json src/server.ts src/worker.ts` — it must return nothing
-2. **Update LOG.md**: Add entry with date and changes
-3. **Commit changes on a branch**: `git checkout -b <type>/<description>` then `git add . && git commit -m "..."`. Code never goes straight to `main`; documentation-only changes may.
-4. **Open a PR and merge it**: `git push -u origin <branch>`, `gh pr create`, wait for green checks, `gh pr merge --squash --delete-branch`, then `git checkout main && git pull`. `main` has a `non_fast_forward` rule: a commit pushed there by mistake needs a revert, not a force-push.
-5. **Create tag**: `git tag -a v0.x.0 -m "..." && git push origin v0.x.0` — ⚠️ **this triggers the npm publish**, see step 9
-6. **Build DXT**: `npm run pack:dxt` → produces `ckan-mcp-server.dxt`
-7. **Build skill**: `npm run pack:skill` → produces `tmp/ckan-mcp.skill`
-8. **Attach to release**: `gh release upload v0.x.0 ckan-mcp-server.dxt tmp/ckan-mcp.skill`
-9. **npm publish happens automatically**: pushing the tag in step 5 starts `.github/workflows/release.yml`, which verifies the tag matches `package.json`, builds, tests, and runs `npm publish --provenance`. **Do not run `npm publish` by hand** — the two paths collide and the loser gets `EPUBLISHCONFLICT`. Watch the run: `gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId')`
-10. **Publish to the MCP Registry** — only **after** the step 9 run has finished green, since the registry validates that the npm version exists: `mcp-publisher login github && mcp-publisher publish`. If login fails with `incorrect_device_code`, the local binary is stale: compare `mcp-publisher --version` against the [latest release](https://github.com/modelcontextprotocol/registry/releases) and update it — the device-auth flow has changed between versions, and the error does not say so
-11. **Deploy to Cloudflare** (if code changed): `npm run deploy`
+2. **Run the release gate**: `npm run smoke` — known-answer search queries against live portals, asserting *which* dataset comes back rather than how many. It must be green before tagging. It exists because v0.4.122 shipped with counts verified and ranking broken: "22 results" and "the right dataset first" are different claims
+3. **Update LOG.md**: Add entry with date and changes
+4. **Commit changes on a branch**: `git checkout -b <type>/<description>` then `git add . && git commit -m "..."`. Code never goes straight to `main`; documentation-only changes may.
+5. **Open a PR and merge it**: `git push -u origin <branch>`, `gh pr create`, wait for green checks, `gh pr merge --squash --delete-branch`, then `git checkout main && git pull`. `main` has a `non_fast_forward` rule: a commit pushed there by mistake needs a revert, not a force-push.
+6. **Create tag**: `git tag -a v0.x.0 -m "..." && git push origin v0.x.0` — ⚠️ **this triggers the npm publish**, see step 10
+7. **Build DXT**: `npm run pack:dxt` → produces `ckan-mcp-server.dxt`
+8. **Build skill**: `npm run pack:skill` → produces `tmp/ckan-mcp.skill`
+9. **Attach to release**: `gh release upload v0.x.0 ckan-mcp-server.dxt tmp/ckan-mcp.skill`
+10. **npm publish happens automatically**: pushing the tag in step 6 starts `.github/workflows/release.yml`, which verifies the tag matches `package.json`, builds, tests, and runs `npm publish --provenance`. **Do not run `npm publish` by hand** — the two paths collide and the loser gets `EPUBLISHCONFLICT`. Watch the run: `gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId')`
+11. **Publish to the MCP Registry** — only **after** the step 10 run has finished green, since the registry validates that the npm version exists: `mcp-publisher login github && mcp-publisher publish`. If login fails with `incorrect_device_code`, the local binary is stale: compare `mcp-publisher --version` against the [latest release](https://github.com/modelcontextprotocol/registry/releases) and update it — the device-auth flow has changed between versions, and the error does not say so
+12. **Deploy to Cloudflare** (if code changed): `npm run deploy`
 
 See `docs/DEPLOYMENT.md` for detailed Cloudflare deployment instructions.
 
-**Why steps 1 and 10 matter**: `server.json` feeds the official MCP Registry entry, which is what clients installing via the registry resolve. It is *not* updated by `npm publish`. Skipping it silently pins public installs to an old version: between v0.4.83 (2026-03-12) and v0.4.114 (2026-08-03) the registry advertised a build predating the v0.4.108 SSRF remediation, while npm was current. Verify after publishing:
+**Why steps 1 and 11 matter**: `server.json` feeds the official MCP Registry entry, which is what clients installing via the registry resolve. It is *not* updated by `npm publish`. Skipping it silently pins public installs to an old version: between v0.4.83 (2026-03-12) and v0.4.114 (2026-08-03) the registry advertised a build predating the v0.4.108 SSRF remediation, while npm was current. Verify after publishing:
 
 ```bash
 curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.aborruso/ckan-mcp-server" | \
 
@@ -2,6 +2,39 @@
 
 ## 2026-09-05
 
+### A release gate that asserts which dataset comes back
+
+Three releases went out today, two of them to repair the one before. The verification in
+between was a sequence of commands rebuilt from memory each time, so it covered something
+different on each pass — and what it always covered was result counts. v0.4.122 shipped
+with counts verified and the ranking broken, because "22 results" and "the right dataset
+first" are different claims and only the second is what a caller asked for.
+
+`npm run smoke` is that check as a command. Twelve known-answer cases from real telemetry
+in `tests/smoke/cases.json`, each asserting which dataset must come back and carrying the
+regression it guards; the runner starts the built server over HTTP, calls each tool the
+way a client does, and exits non-zero on the first failure.
+
+Checked against the defects it claims to catch: reintroducing the v0.4.121 wrapping rule
+fails 4 of 12, and removing the parser probe from `ckan_find_relevant_datasets` — the
+v0.4.122 regression — fails the case requiring the two search tools to agree. Wired into
+the release workflow in `CLAUDE.md` (step 2, before the tag) and the checklist in
+`docs/DEPLOYMENT.md`.
+
+Two things the gate needed on the way:
+
+- the JSON format never exposed the query that actually ran, while Markdown has always
+  shown it. `effective_query` now appears in `ckan_package_search` JSON output when the
+  server rewrote the query, and is absent when it did not.
+- relevance scores summed unrounded fractions, printing totals like `8.299999999999999`.
+
+Known and not fixed: the ranking model weights every query term equally, so on
+`defibrillatori Comune di Lecce` three datasets tie at 9.7 and the right one leads on
+Solr order rather than on score. Making the `tags` field proportional like the others was
+tried and reverted — it promotes "Elenco patrocini Comune di Lecce", whose tags carry two
+of the three terms against the defibrillator dataset's one. The fix is term specificity,
+a design change, not a patch.
+
 ### v0.4.123 - relevance scoring and shared parser probe
 
 Ships #536: field scoring by share of matched terms, Italian stopwords with acronyms preserved, Unicode-aware term matching, a wider candidate window, the parser probe shared with `ckan_find_relevant_datasets`, and accent-safe filters in `ckan_organization_search` and `ckan_tag_list`. `openspec/specs/ckan-search/spec.md` rewritten around the query-building path.
 
@@ -651,6 +651,10 @@ Verify:
 Use this checklist to ensure nothing is missed:
 
 ### Pre-Release
+- [ ] **Release gate green**: `npm run smoke` — known-answer search queries against live
+      portals, asserting *which* dataset comes back rather than how many. v0.4.122 shipped
+      with counts verified and ranking broken; "22 results" and "the right dataset first"
+      are different claims, and only the second one is what a user asked for
 - [ ] Security audit clean: `npm audit` (0 vulnerabilities)
 - [ ] All tests passing: `npm test`
 - [ ] Code builds successfully: `npm run build`
 
@@ -39,6 +39,7 @@ Error paths respect the requested format too: with `response_format: "json"` a f
 | Field | Type | Notes |
 |-------|------|-------|
 | `count` | number | Total matching datasets |
+| `effective_query` | string | Present **only when the server rewrote the query** — the caller sent `aria OR acqua` and Solr received `text:(aria OR acqua)`. Absent when the query ran unchanged, which is the common case. The Markdown format has always shown this as **Effective Query**. |
 | `results[].id` | string | Dataset UUID |
 | `results[].name` | string | Machine-readable slug |
 | `results[].title` | string | Human-readable title (falls back to name) |
 
@@ -0,0 +1,30 @@
+# Expose the executed query in JSON search output
+
+## Why
+
+The server rewrites a caller's query before sending it to Solr: a boolean query on a
+portal whose default parser ignores booleans is wrapped as `text:(...)`, with its content
+escaped. The Markdown format has always reported this as **Effective Query**. The JSON
+format does not, so a JSON caller cannot tell whether the query it wrote is the query that
+ran.
+
+That gap cost real time on 2026-09-05. Diagnosing why `bonifica siti contaminati Piemonte`
+returned 5 datasets instead of 22 meant reproducing calls by hand against the portal,
+because the tool's own JSON answer did not say which query it had executed. The release
+gate added in the same change (`npm run smoke`) cannot assert the parser behaviour without
+it either.
+
+## What Changes
+
+- `ckan_package_search` JSON output gains `effective_query`, present **only when the
+  server rewrote the query** and absent when it ran unchanged.
+- No change to the Markdown format, which already carries the same information.
+- No change to any input, and no change to which datasets are returned.
+
+## Impact
+
+- Affected specs: `ckan-search`
+- Affected code: `compactSearchResult()` and its call site in `src/tools/package.ts`
+- Backwards compatible: the field is additive and optional. A client reading `count` and
+  `results` is unaffected.
+- Documented in `docs/JSON-OUTPUT.md`.
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Executed query visible in JSON output
+
+When the server rewrites a caller's query before sending it to Solr, `ckan_package_search`
+SHALL report the executed query in its JSON output, so that a JSON caller can tell which
+query actually ran. The field SHALL be omitted when the query ran unchanged.
+
+#### Scenario: Query rewritten
+- **WHEN** a JSON caller sends a query the server wraps in `text:(...)`
+- **THEN** the response carries `effective_query` with the query as executed
+
+#### Scenario: Query unchanged
+- **WHEN** a JSON caller sends a query that reaches Solr as written
+- **THEN** the response carries no `effective_query`, and its shape is unchanged
@@ -0,0 +1,15 @@
+## 1. Implementation
+
+- [x] 1.1 Add the optional `effectiveQuery` parameter to `compactSearchResult()`
+- [x] 1.2 Pass it from the `ckan_package_search` JSON branch only when it differs from the
+      caller's `q`
+- [x] 1.3 Document the field in `docs/JSON-OUTPUT.md`, stating that it is absent when the
+      query ran unchanged
+
+## 2. Verification
+
+- [x] 2.1 `npm test` green
+- [x] 2.2 Release gate asserts both branches: `wrapped` on a boolean query where the portal
+      needs it, `not_wrapped` on a plain query
+- [x] 2.3 Confirmed against a live portal that a plain query carries no `effective_query`
+      and `aria OR acqua` on dati.comune.milano.it carries `text:(aria OR acqua)`
@@ -28,7 +28,8 @@
     "pack:dxt": "rm -rf dxt-staging && mkdir -p dxt-staging/server && npm run build:dxt && echo '{\"type\":\"commonjs\"}' > dxt-staging/server/package.json && mkdir -p dxt-staging/server/node_modules && cp -r node_modules/undici dxt-staging/server/node_modules/ && cp manifest.json icon.png dxt-staging/ && dxt pack dxt-staging ckan-mcp-server.dxt && rm -rf dxt-staging",
     "pack:skill": "mkdir -p tmp && cd skills && zip -r ../tmp/ckan-mcp.skill ckan-mcp/ && cd ..",
     "prepack": "cp README.md .readme-full.md && cp .readme-npm.md README.md",
-    "postpack": "mv .readme-full.md README.md"
+    "postpack": "mv .readme-full.md README.md",
+    "smoke": "npm run build && node scripts/smoke.mjs"
   },
   "keywords": [
     "mcp",
 
@@ -95,6 +95,29 @@ schema change.
 bash scripts/worker_daily_stats.sh
 ```
 
+## smoke.mjs — the release gate
+
+`npm run smoke` runs the known-answer cases in `tests/smoke/cases.json` against live
+portals and exits non-zero on the first failed assertion. `npm run smoke -- lecce` runs
+only the cases whose name matches.
+
+Every case asserts **which** dataset comes back, not how many, and carries a `regression`
+field naming the failure it guards. That distinction is the reason the file exists:
+v0.4.122 shipped with result counts verified and the ranking broken, because a query
+returning 679 datasets and a query returning the right one first are different claims.
+
+The gate is checked against the defects it claims to catch. Reintroducing the v0.4.121
+wrapping rule fails 4 of the 12 cases; removing the parser probe from
+`ckan_find_relevant_datasets`, the v0.4.122 regression, fails the case that requires the
+two search tools to agree.
+
+Cases hit real portals, so the thresholds are loose enough to survive catalog drift and
+a failure can also mean a portal is down — check the message before assuming a code bug.
+
+```bash
+npm run build && npm run smoke
+```
+
 ## GitHub Actions
 
 `update-telemetry.yml` runs both scripts automatically twice a day (06:00 and 18:00 UTC).