vmware-debug 1.9.0__tar.gz → 1.11.0__tar.gz

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-debug",
   "displayName": "VMware Debug",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Read-only VMware incident correlation: timeline, spikes, root-cause routing. 2 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==1.9.0",
+        "vmware-debug==1.11.0",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-debug
-Version: 1.9.0
+Version: 1.11.0
 Summary: VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Debug

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/RELEASE_NOTES.md

@@ -1,3 +1,87 @@
+## v1.11.0 — the correlation engine, on a real incident
+
+A tester fed the investigation layer a genuine failure: on 08-03 at 05:49, four
+ESXi hosts went `EnteringMaintenanceMode` → `EnteredMaintenanceMode` →
+`HostShutdown` → `HostConnectionLost` → `HostSyncFailed` ×24 within 32 seconds,
+and never came back. 3,818 real vCenter events over 40 days, pulled per this
+skill's own envelope documentation. The case-management layer held up. The
+correlation engine — the thing this skill is named for — did not.
+
+**80% of events were `uncategorized`, and the headline conclusion was "cannot
+classify, widen your search window".** The classification table's
+`power_lifecycle` keywords were all VM-centric (`power on`/`power off`, `vmx`,
+`ovf`, `clone`, `snapshot`); nothing covered host maintenance mode or host
+shutdown, and `"Shut down of esxi05"` does not match `"power off"`. There is now
+a `host_lifecycle` category — a separate category rather than more keywords,
+because it is a separate investigation, routed to monitor + logs + harden (a
+host that left service on cue was usually told to). `classification_coverage()`
+reports what went unread in every result, and above ~25% it reaches
+`next_checks`. The "widen the window" remedy is gone: the window was already 40
+days, and widening makes the incident *less* findable.
+
+**The only spike detected was the day the hosts came back up.**
+`_auto_bin_seconds` was `span/30`, so a 29-day window gave 23.2-hour buckets;
+the incident hour was the second-busiest in the dataset and absent from the
+spike list, while `--bin-seconds 3600` found it at z=8.25. Binning now chooses
+by event *density*, from a floor of 4 events per bin that is derived rather than
+tuned: spikes flag at mean+2σ, and a count only exceeds twice its mean once the
+mean reaches 4. The chosen width, how it was chosen, and the bin count are
+reported.
+
+**The same incident described five ways routed five different ways** — decided
+by an incidental noun, with the most accurate description routing nowhere.
+Categories are now ranked by matched-keyword length, so a long phrase beats a
+stray word, and the losing categories are named.
+
+Also fixed: `case_timeline`'s payload contract was undocumented and its MCP
+parameter type refused the array shape the docstring implied; pure-Chinese
+summaries collapsed to one `case_id` per second, with a collision message that
+was false; and skill names were compared as raw strings, so `monitor` and
+`vmware-monitor` counted as two independent evidence sources — buying *Probable*
+out of orthography, in the layer built to prevent exactly that.
+
+## v1.10.0 — the knowledge layer is implemented, not just described
+
+v1.9.0 shipped the investigation layer with `applies_to` documented as the thing
+that makes a knowledge entry decisive. Nothing parsed a knowledge file and
+nothing checked applicability. Any file at all under the knowledge root raised
+the reported ceiling, and anything labelled `knowledge-kb` counted as decisive.
+The route to a wrong Confirmed that the design was written to close was open the
+whole time, and the metric said zero only because no fixture walked it.
+
+`case_knowledge` (the 14th tool) answers the first question anyone mounting a
+library asks — which formats are taken — without them reading a design document:
+
+    .md .markdown   YAML front-matter between --- fences, body below (preferred)
+    .yaml .yml      the whole file is one entry
+    .json           one entry per file
+    .jsonl          one JSON object per line (what ticketing systems export)
+    .csv .tsv       one entry per row; dotted columns for nested constraints
+    .txt .log       a sibling <name>.yaml carries the metadata
+
+PDF, DOCX, PPTX and HTML are named as needing conversion rather than ignored,
+and a file that cannot be parsed is reported rather than skipped.
+
+**An entry is decisive only if its own `applies_to` was checked against the
+case's recorded versions and passed.** Three things follow, each found by
+reviewing the version before it:
+
+* Knowledge evidence must say WHICH entry it is. "Some applicable entry is
+  mounted somewhere" is a different claim from "this one applies", and the first
+  version accepted it — an agent citing the entry written for 9.x could confirm
+  a case about 8.0.3 as long as an unrelated entry happened to match.
+* A constraint the case scope cannot answer is not a match. Silence is not a
+  pass; reading it as one is how an entry for different hardware ends a case.
+* **A constraint the checker cannot evaluate is not a pass either.** The first
+  version understood product, build, driver and firmware and treated every other
+  key as satisfied, so `build` without a `product`, a `hardware_model` list, and
+  an outright typo all came back decisive. Unknown and satisfied must never be
+  the same answer.
+
+Given two entries that read identically — one for `>=8.0, <9.0`, one for
+`>=9.0` — a case scoped to vSphere 8.0.3 now reaches Confirmed citing the first
+and stays at Probable citing the second, naming the range that excluded it.
+
 ## v1.9.0 — the investigation layer: 2 tools become 13
 
 Correlating events answers "what happened together". A case answers "what do we

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "1.9.0"
+version = "1.11.0"
 description = "VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family"
 readme = "README.md"
 license = "MIT"

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/server.json

@@ -7,12 +7,21 @@
     "url": "https://github.com/vmware-skills/VMware-Debug",
     "source": "github"
   },
-  "version": "1.9.0",
+  "version": "1.11.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "1.9.0",
+      "version": "1.11.0",
+      "runtimeHint": "uvx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "valueHint": "subcommand",
+          "value": "mcp",
+          "description": "Starts the stdio MCP server. Without it the console script runs the human CLI and exits."
+        }
+      ],
       "transport": {
         "type": "stdio"
       }

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/skills/vmware-debug/SKILL.md

@@ -100,7 +100,7 @@ a recommended plan.
 - **MCP** (in an agent): the agent calls the other skills' read tools, then `incident_timeline` to correlate. This is the primary mode — that's where the cross-skill "联动" happens.
 - **CLI** (humans): `vmware-debug triage --events events.json` correlates a JSON array you collected yourself.
 
-## MCP Tools (13 — 6 read, 7 write)
+## MCP Tools (14 — 7 read, 7 write)
 
 **Correlation** — stateless, for a single look:
 
@@ -115,6 +115,7 @@ a recommended plan.
 |---|---|
 | `case_open` | [WRITE] Define the event; returns a case id and the grade this environment can reach |
 | `case_readiness` | [READ] What grade this environment can reach, per symptom category, **before** you start |
+| `case_knowledge` | [READ] Which knowledge formats are accepted, what is mounted, and which entries apply to a case |
 | `case_plan` | [READ] What to fetch next — skill, tool and purpose per step; recomputed from the case's current state |
 | `case_list` | [READ] Cases, newest first |
 | `case_get` | [READ] One case: scope, ledger sizes, grade history |
@@ -179,6 +180,52 @@ so the gap is visible now rather than when the conclusion refuses to firm up.
 "readiness 78%" cannot. Two classes served by the *same* skill count as one
 source, so it agrees with what `case_grade` will actually award.
 
+### Mounting a knowledge library
+
+`case_knowledge` answers "what can I add" without anyone reading this file.
+Entries go under `$OPS_HOME/knowledge/{kb,runbook,sr,cases}/`:
+
+| Format | How metadata travels |
+|---|---|
+| `.md` `.markdown` | YAML front-matter between `---` fences, body below — **preferred** |
+| `.yaml` `.yml` | the whole file is one entry |
+| `.json` | one entry per file |
+| `.jsonl` | one JSON object per line — what ticketing systems export |
+| `.csv` `.tsv` | one entry per row; use dotted columns (`driver.version`) for nested constraints |
+| `.txt` `.log` | a sibling `<name>.yaml` carries the metadata |
+
+PDF, DOCX, PPTX and HTML must be converted to Markdown first — `case_knowledge`
+names them rather than ignoring them.
+
+**Every entry needs an `applies_to` block to be decisive:**
+
+```yaml
+---
+id: KB-2026-0417
+applies_to:
+  product: vsphere
+  build: ">=8.0.3, <9.0"
+  driver: {name: nvme_pcie, version: ">=1.2.4"}
+  firmware: {vendor: dell, version: ">=52.26"}
+---
+```
+
+`product`, `build`, `driver` and `firmware` are the constraints the checker
+evaluates. **Any other key leaves the entry non-decisive** — including a typo —
+because an unverified constraint is not a satisfied one, and `case_knowledge`
+names the key it could not check.
+
+Knowledge evidence must say **which** entry it is
+(`case_submit_evidence(source_skill="knowledge-kb", knowledge_entry_id="KB-…")`)
+— "some applicable entry is mounted somewhere" is a different claim from "this
+one applies", and only the second can carry a conclusion.
+
+Matching is **by version applicability, never by similarity** — an entry written
+for the wrong build reads exactly like the right one, and similarity is the only
+thing that would let it through. An entry with no `applies_to` can support a
+hypothesis but can never make a case Confirmed. A constraint the case scope
+cannot answer is not a match either: silence is not a pass.
+
 > **On a stock install the ceiling is Probable.** Confirmed needs a decisive
 > source, and there is neither a hardware-diagnostic channel (no Redfish/BMC, no
 > SMART/NVMe) nor a knowledge library mounted — `~/.vmware/knowledge/` ships
@@ -209,8 +256,10 @@ vmware-debug mcp                                # start stdio MCP server (proxy-
 ## Troubleshooting
 
 - **`incident_timeline` raises "event[N] could not be normalised"** — event N is missing a timestamp or has an unparseable one. Every event needs `ts` (ISO-8601, epoch seconds, or millis).
-- **All hypotheses come back "uncategorized"** — the symptom isn't in the catalogue yet; widen the window and pull from another source (aria anomalies, log-insight). Consider adding a signature (see `references/routing.md`).
-- **No spikes detected on an obvious burst** — you need ≥3 time bins for a baseline; shrink `bin_seconds`.
+- **Most events come back "uncategorized"** — read `classification` in the result: it says how many, what share, and quotes the texts that matched nothing. Do **not** widen the window; a wider window adds baseline, not signal. The spikes still tell you *when*, which is answerable without a category. If the samples name a subsystem the taxonomy does not know, add a signature (see `references/routing.md`).
+- **No spikes detected on an obvious burst** — check `binning` for the resolution you were given. The width is chosen from event density so that bins average ≥4 events; a burst shorter than one bin can still be flattened by it. Pass `bin_seconds` to narrow. Below three bins there is no baseline at all and nothing is reported.
+- **`case_timeline` says zero events after you submitted results** — check `payload_events` in each `case_submit_evidence` reply. Events are read from a bare list, or from `items`/`events`/`rows`; a *summary* of a tool's result carries none. `note` names which items carried nothing and what keys they held instead.
+- **`case_readiness` says a skill you have is not installed** — both spellings are accepted (`monitor` and `vmware-monitor`). A name it did not recognise comes back in `unrecognised_skills` rather than being read as missing.
 - **It won't execute the fix** — by design. Route to vmware-aiops or vmware-pilot.
 
 ## Audit & Safety

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/skills/vmware-debug/references/agent-guardrails.md

@@ -14,7 +14,7 @@ vmware-monitor and vmware-aria against a production vSphere estate with Llama
 cross-skill rules are identical across this family; the parts below marked
 vmware-debug are specific to this skill.
 
-vmware-debug exposes 13 MCP tools: 6 reads and 7 writes. It connects to nothing
+vmware-debug exposes 14 MCP tools: 7 reads and 7 writes. It connects to nothing
 and holds no credentials — the calling agent gathers events from the other
 skills, normalises them, and hands them over. The four writes go to the local
 investigation ledger under `~/.vmware/cases/`, never to a VMware system. That

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/skills/vmware-debug/references/capabilities.md

@@ -27,9 +27,16 @@ fixed in-process constant, so `total` is a real count and `limit` is `null`.
 
 ## Symptom categories
 
-`storage`, `network`, `compute`, `ha_drs`, `power_lifecycle`, `auth`, `platform`.
+`storage`, `network`, `compute`, `ha_drs`, `host_lifecycle`, `power_lifecycle`,
+`auth`, `platform`.
 See `references/routing.md` for keyword signatures and the skill each routes to.
 
+`host_lifecycle` is a host changing its own availability state — maintenance
+mode, shutdown, reboot, standby, connection loss, sync failure.
+`power_lifecycle` is the VM-level equivalent. They are separate because they are
+separate investigations: the second is a task question for vmware-aiops, the
+first is a cluster, DPM, vLCM or drift question.
+
 ## Design properties
 
 - **Zero cross-skill runtime deps** — correlation is pure functions over plain

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/skills/vmware-debug/references/event-envelope.md

@@ -21,7 +21,7 @@ runtime dependency** on the other packages (no version lockstep, no heavy instal
 | Field | Type | Notes |
 |---|---|---|
 | `ts` | string \| number | ISO-8601, epoch **seconds**, or epoch **millis** (auto-detected). Required. |
-| `source` | string | `monitor` \| `aria` \| `loginsight` \| `nsx` \| `nsx-security` \| `storage` \| ... |
+| `source` | string | `monitor` \| `aria` \| `loginsight` \| `nsx` \| `nsx-security` \| `storage` \| ... The catalogue in `rules/evidence_sources.yaml` spells the same skills `vmware-monitor`, `vmware-aria`, `vmware-log-insight`. Both spellings are understood wherever a skill is named — `case_readiness(available_skills=...)`, and the grader's count of independent sources, which treats two spellings of one skill as one source. |
 | `severity` | string | Free text; normalised to `critical`/`error`/`warning`/`info`/`unknown`. |
 | `entity` | string | The object the event is about (VM/host/datastore). May be empty. |
 | `text` | string | Human-readable message — this is what the symptom classifier matches on. |

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/skills/vmware-debug/references/routing.md

@@ -10,6 +10,7 @@ Keep this in sync with `_CATEGORY_SIGNATURES` in `vmware_debug/ops/timeline.py`
 | **network** | vmotion, uplink, link down, mtu, firewall, dfw, segment, tier-0, bgp | vmware-nsx, vmware-nsx-security (traceflow, DFW hits) | pilot |
 | **compute** | cpu ready, memory, balloon, swap, contention, numa | vmware-aria (metrics + anomalies) | pilot (rightsizing) |
 | **ha_drs** | ha, high availability, drs, failover, admission control, isolation | vmware-monitor, vmware-aiops (cluster) | pilot |
+| **host_lifecycle** | maintenance mode, shut down of, host reboot, standby mode, lost connection to, cannot synchronize, not responding | vmware-monitor (host/cluster state), vmware-harden (drift — a host that left service on cue was told to), vmware-log-insight (vpxd/hostd) | pilot |
 | **power_lifecycle** | power on/off, failed to start, boot, vmx, ovf, clone, snapshot | vmware-aiops (task status, snapshot tree), vmware-monitor | aiops |
 | **auth** | login, authentication, denied, 401, 403, token, certificate, tls | config/.env, target cert + time sync | config fix |
 | **platform** | vpxd, hostd, service restart, crash, 503, not responding, disconnected | vmware-monitor (connection/service), vmware-log-insight (vpxd/hostd) | pilot |

{vmware_debug-1.9.0 → vmware_debug-1.11.0}/tests/eval/capability/_scores.json

@@ -9,13 +9,14 @@
           "list_symptom_categories",
           "case_open",
           "case_list",
-          "case_readiness"
+          "case_readiness",
+          "case_knowledge"
         ],
         "reachable_on_surface": 8,
         "reachable_only_via_description": 0,
         "required_entity_params": 8,
         "required_params_classified": "8/17",
-        "tool_count": 13
+        "tool_count": 14
       },
       "maximum": 8,
       "pct": 100.0,
@@ -43,12 +44,12 @@
     },
     "entry_point_availability": {
       "detail": {
-        "full_entry_points": 5
+        "full_entry_points": 6
       },
-      "maximum": 13,
-      "pct": 38.5,
+      "maximum": 14,
+      "pct": 42.9,
       "unit": "entry points",
-      "value": 5
+      "value": 6
     },
     "error_actionability": {
       "detail": {
@@ -77,7 +78,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "evidence.py:281"
+            "where": "evidence.py:289"
           },
           {
             "message": "gaps.json in case {} is not valid JSON: {}. It was hand-edited. Restore it rather than deleting it \u2014",
@@ -85,7 +86,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "evidence.py:283"
+            "where": "evidence.py:291"
           },
           {
             "message": "Cannot read grading_rules.yaml at {}: {}",
@@ -93,7 +94,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:55"
+            "where": "grading.py:57"
           },
           {
             "message": "grading_rules.yaml at {} is not valid YAML: {}. Fix it rather than deleting it \u2014 falling back to the",
@@ -101,7 +102,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:57"
+            "where": "grading.py:59"
           },
           {
             "message": "A hypothesis needs a statement \u2014 what you think happened, in one line. An unnamed hypothesis cannot ",
@@ -134,7 +135,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "plan.py:72"
+            "where": "plan.py:84"
           },
           {
             "message": "evidence_sources.yaml at {} is missing 'classes' or 'routing'. An empty catalogue would make every r",
@@ -166,7 +167,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "timeline.py:140"
+            "where": "timeline.py:137"
           },
           {
             "message": "Cannot read case.json for {}: {}",
@@ -174,7 +175,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "timeline.py:154"
+            "where": "timeline.py:151"
           }
         ],
         "per_dimension_pct": {
@@ -193,20 +194,20 @@
       "detail": {
         "heaviest_tools": {
           "case_open": 354,
-          "case_plan": 360,
+          "case_plan": 395,
           "case_record_gap": 337,
-          "case_submit_evidence": 549,
-          "incident_timeline": 329
+          "case_submit_evidence": 693,
+          "incident_timeline": 357
         },
-        "manifest_tokens": 3428,
-        "mean_tokens_per_tool": 263.7,
+        "manifest_tokens": 3988,
+        "mean_tokens_per_tool": 284.9,
         "reference_context": 16384,
-        "tool_count": 13
+        "tool_count": 14
       },
       "maximum": 16384,
-      "pct": 79.1,
+      "pct": 75.7,
       "unit": "tokens",
-      "value": 12956
+      "value": 12396
     },
     "parameter_documentation_coverage": {
       "detail": {
@@ -215,8 +216,7 @@
             "case_id"
           ],
           "case_submit_evidence": [
-            "fetched_at",
-            "summary"
+            "fetched_at"
           ],
           "case_timeline": [
             "bin_seconds",
@@ -226,22 +226,23 @@
           ]
         }
       },
-      "maximum": 43,
-      "pct": 83.7,
+      "maximum": 45,
+      "pct": 86.7,
       "unit": "parameters",
-      "value": 36
+      "value": 39
     },
     "per_tool_token_discipline": {
       "detail": {
         "ceiling": 350,
         "over_ceiling": {
           "case_open": 354,
-          "case_plan": 360,
-          "case_submit_evidence": 549
+          "case_plan": 395,
+          "case_submit_evidence": 693,
+          "incident_timeline": 357
         }
       },
-      "maximum": 13,
-      "pct": 76.9,
+      "maximum": 14,
+      "pct": 71.4,
       "unit": "tools",
       "value": 10
     },
@@ -263,10 +264,10 @@
       "detail": {
         "unmarked": []
       },
-      "maximum": 13,
+      "maximum": 14,
       "pct": 100.0,
       "unit": "points",
-      "value": 13
+      "value": 14
     },
     "remedy_survives_truncation": {
       "detail": {
@@ -277,10 +278,10 @@
           "envelope.py:138",
           "conclusion.py:135",
           "conclusion.py:144",
-          "evidence.py:172",
-          "evidence.py:204",
-          "evidence.py:240",
-          "grading.py:65",
+          "evidence.py:179",
+          "evidence.py:211",
+          "evidence.py:248",
+          "grading.py:67",
           "hypotheses.py:47",
           "hypotheses.py:70"
         ]
@@ -300,14 +301,14 @@
     "tool_description_quality": {
       "detail": {
         "per_dimension_pct": {
-          "args": 76.9,
-          "gotcha": 84.6,
+          "args": 78.6,
+          "gotcha": 85.7,
           "marker": 100.0,
-          "next_hop": 61.5,
+          "next_hop": 57.1,
           "what": 100.0,
-          "when": 92.3
+          "when": 92.9
         },
-        "tools_graded": 13,
+        "tools_graded": 14,
         "weakest_tools": {
           "case_close": [
             "next_hop"
@@ -319,6 +320,9 @@
             "args",
             "next_hop"
           ],
+          "case_knowledge": [
+            "next_hop"
+          ],
           "case_list": [
             "gotcha",
             "next_hop"
@@ -332,29 +336,26 @@
           ],
           "case_submit_evidence": [
             "args"
-          ],
-          "case_timeline": [
-            "args"
           ]
         }
       },
-      "maximum": 78,
-      "pct": 85.9,
+      "maximum": 84,
+      "pct": 85.7,
       "unit": "points",
-      "value": 67
+      "value": 72
     },
     "tool_failure_payload_quality": {
       "detail": {
         "bare_string_error_lines": [],
-        "carries_hint": 12,
-        "dict_shaped": 12,
-        "error_return_sites": 12,
-        "hint_names_artifact": 12
+        "carries_hint": 13,
+        "dict_shaped": 13,
+        "error_return_sites": 13,
+        "hint_names_artifact": 13
       },
-      "maximum": 36,
+      "maximum": 39,
       "pct": 100.0,
       "unit": "checks",
-      "value": 36
+      "value": 39
     }
   }
 }

vmware_debug-1.11.0/tests/eval/regression/test_case_id_non_ascii.py

@@ -0,0 +1,86 @@
+"""A case opened in Chinese got no identity of its own.
+
+``slugify`` reduces on ``[^a-z0-9]+``, so a summary written entirely in Chinese
+leaves nothing behind and the id falls back to the literal word ``case``:
+``20260830-061014-case``. Two completely different investigations opened in the
+same second then collide — and the collision message said they were "the same
+summary", which was false, and sent the reporter looking for a duplicate that
+did not exist.
+
+The id has to stay inside its character set: it is a directory name, and
+``validate_case_id`` is the only thing between a model-chosen string and
+``open(root / case_id)``. So the fix is not to widen the alphabet. It is that an
+id must distinguish summaries that differ, and that the collision message must
+describe what actually collided.
+
+The control is readability: an ASCII summary must still produce the readable
+slug the listing was designed around, not a digest for everybody.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from vmware_debug.ops.cases.ids import new_case_id, validate_case_id
+from vmware_debug.ops.cases.model import Scope
+from vmware_debug.ops.cases.store import CaseExists, create_case
+
+AT = "2026-08-30T06:10:14Z"
+
+#: Both must be free of Latin characters. An earlier draft wrote the first one
+#: as "四台 ESXi 主机…", and "esxi" survived slugify — so the two ids differed
+#: whatever the fallback did, and the test passed against the defect it was
+#: written to catch.
+ZH_A = "四台主机同时进入维护模式后关机"
+ZH_B = "存储集群延迟升高导致虚拟机无响应"
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(tmp_path, monkeypatch):
+    monkeypatch.setenv("OPS_HOME", str(tmp_path / "vmware"))
+
+
+class TestANonAsciiSummaryStillGetsAnIdentity:
+    def test_two_different_chinese_summaries_do_not_collide(self):
+        assert new_case_id(ZH_A, AT) != new_case_id(ZH_B, AT)
+
+    def test_the_id_is_still_a_safe_directory_name(self):
+        validate_case_id(new_case_id(ZH_A, AT))
+
+    def test_the_same_summary_still_yields_the_same_id(self):
+        """Ids are replayable: a case folder re-opened from its scope has to
+        reconstruct the id it already has."""
+        assert new_case_id(ZH_A, AT) == new_case_id(ZH_A, AT)
+
+    def test_both_cases_can_actually_be_opened_in_the_same_second(self):
+        create_case(Scope(summary=ZH_A, determined_by="user report"), at=AT)
+        create_case(Scope(summary=ZH_B, determined_by="user report"), at=AT)
+
+
+class TestTheCollisionMessageIsTrue:
+    def test_it_does_not_claim_the_summaries_were_identical(self):
+        """Two summaries that differ only outside the id character set still
+        collide, and telling the reporter they submitted the same summary sends
+        them looking for something that is not there."""
+        create_case(Scope(summary="vsan latency!", determined_by="a"), at=AT)
+        with pytest.raises(CaseExists) as exc:
+            create_case(Scope(summary="vsan latency?", determined_by="a"), at=AT)
+        assert "same summary" not in str(exc.value)
+
+    def test_it_says_what_to_do_about_it(self):
+        create_case(Scope(summary="vsan latency", determined_by="a"), at=AT)
+        with pytest.raises(CaseExists) as exc:
+            create_case(Scope(summary="vsan latency", determined_by="a"), at=AT)
+        assert "case_get" in str(exc.value)
+
+
+class TestControlReadabilityIsNotSacrificed:
+    def test_an_ascii_summary_still_gets_its_readable_slug(self):
+        """A digest for every case would pass every test above and destroy the
+        one property the slug exists for — a directory listing you can read."""
+        assert new_case_id("vSAN datastore latency on cluster-01", AT).endswith(
+            "-vsan-datastore-latency-on-cluster-01"
+        )
+
+    def test_a_mixed_summary_keeps_the_part_that_survives(self):
+        assert "esxi05" in new_case_id("主机 esxi05 关机", AT)