@wix/himalaya-cli 0.808.0 → 0.809.0

package/guides/himi-test.md

@@ -107,6 +107,10 @@ Only **unambiguous** defects, so a green run stays worth trusting:
 | `no-request-issued` | **warning** | A worker that uses the Wix transport but never fetches — "the screen loaded with sample data." A warning: a conditional or tap-triggered fetch is legitimate. |
 | `native-decode-failed` | error | Under `--native`, the real Swift/Kotlin decoder rejected the baked descriptor bytes (one bad enum blanks the whole screen on device). |
 | `journey-failed` | error | A `himi-test.json` journey named an action the screen lacks, threw, or never rendered its `expectText`. |
+| `inverse-pair-diverges` | **warning** | An action and the action that undoes it do not return to the state the boot settled on — `add` then `remove` leaving a different list, or a counter it forgot to put back. |
+| `refresh-not-idempotent` | **warning** | `refresh` from a fresh boot settles somewhere other than the boot did, on identical data — usually a refresh that appends instead of replacing. |
+| `list-shrank-on-load-more` | **warning** | A "load more" returned FEWER rows than before it ran: the new page replaced the list instead of extending it. |
+| `list-grew-on-filter` | **warning** | A filter, search or sort made a list longer. Narrowing can reorder or remove, never add. |
 
 **Deliberately never reported:** an empty collection · an `error` state (often the correct
 answer to empty input) · a `null` optional · whether a nav target *exists* (approximating
@@ -230,7 +234,7 @@ chromium`. Fully hermetic; `--no-shots` opts out.
 - **JSON is the default off a TTY.** `--json` forces it; a pipe or redirect gets it anyway.
 - **The envelope** carries `himiReport: 1`, `findings[]` (stable `id`s), `gaps[]` (the ledger), `artifacts[]`,
   and `evidence { runId, gitDiffHash }`; the legacy fields (`failures`, `warnings`, `crawled`, …) ride along.
-- **`himi-test.json` `skip[]`** suppresses a known-benign finding: `{ "screen"?, "action"?, "component"?, "reason" }`;
+- **`himi-test.json` `skip[]`** suppresses a known-benign finding: `{ "screen"?, "action"?, "component"?, "invariant"?, "reason" }`;
   `reason` is mandatory and every suppression is echoed as a `suppressed` ledger gap.
 - **A `functions/` dir short-circuits the crawl**: `himi test` on a content dir with local HTTP functions
   invokes each function once with a canned input instead of crawling screens.
@@ -241,6 +245,47 @@ chromium`. Fully hermetic; `--no-shots` opts out.
   map would name the wrong lines — `no-source` — no source dir exists for the bundle at all — or
   `build-failed` — the source no longer compiles. Each pairs with the exact rebuild command.
 
+## Relations — catching a wrong value without knowing the right one
+
+Every invariant above says *this can never be right*: a throw, a stuck skeleton, a `NaN`, a raw
+binding token on screen. That leaves the bug whose output is **plausible** — reading the wrong key
+off a response gives you an empty list that looks like an empty list; a total that is off by one is
+still a perfectly good number. Nothing that checks a single settled state can tell those from
+correct ones, which is why the measured catch rate for that class is zero.
+
+Relations compare **two** settled states of the same screen and assert what must hold for any
+correct reducer, whatever the right answer happens to be:
+
+| Relation | What must hold |
+|---|---|
+| **Inverse round trip** | An action and the DISTINCT action that undoes it return to where the boot started: `add` then `remove`, `archive` then `unarchive`. A toggle applied twice is deliberately NOT checked — real toggles raise toasts, reorder lists and randomise, so the round trip fired on correct code 18 times across the corpus. |
+| **Refresh idempotence** | `refresh` from a fresh boot, on identical data, lands where the boot landed. |
+| **Monotonic paging** | "Load more" never returns fewer rows than it started with. |
+| **Narrowing filters** | A filter, search or sort never makes a list longer. |
+
+They need **nothing authored**: the pairs and verbs are read from the action names your descriptor
+already declares, and each relation replays only the handful of paths it needs, from a fresh boot,
+so they run by default without `--deep`.
+
+All four are **warnings**, deliberately. A divergence is strong evidence of a bug rather than proof
+of one — a worker may legitimately reshape state in a way the relation cannot model — and a run
+where the crawl cannot replay a path faithfully skips the relation instead of guessing.
+
+Comparison ignores what legitimately differs between two correct states: freshly minted ids,
+`*At` timestamps, `_`-prefixed counters. Everything else is compared, including list contents and
+totals, because those are exactly where the plausible-wrong-value bugs live.
+
+To silence one deliberately, `skip[]` takes an `invariant` — a relation is a property of the whole
+app, so one entry covers it everywhere rather than one per screen:
+
+```json
+{ "skip": [{ "invariant": "refresh-not-idempotent", "reason": "the activity feed appends by design" }] }
+```
+
+The report always carries `relations.checked`. **Zero is the informative case**: it means no screen
+declared a pair, refresh or filter the axis could use, so "no relational warnings" does not mean
+the relations held.
+
 ## The contract — why a green run is trustworthy
 
 - **Measured, not asserted.** A committed kill-rate benchmark records what fraction of planted,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.808.0",
+  "version": "0.809.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -63,5 +63,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "dc5a7f5795e7fd8644710a8cc8bae9b5f1a66b7c5f55ff66cf165cea"
+  "falconPackageHash": "24ab5926849593b42d271f6a38201197b2ff1d7963739f2c0de07525"
 }