@reticlehq/test 2.13.0 → 2.14.0

package/dist/junit.js

@@ -1,12 +1,22 @@
 import { DEFAULT_JUNIT_SUITE_NAME, JUnit, TestStatus } from './constants.js';
 import { summarize } from './summary.js';
 /**
- * XML 1.0 section 2.2: every code point below U+0020 is illegal EXCEPT tab, newline and carriage
- * return. Stated as codes rather than a regex character class, which cannot express control
- * characters without tripping `no-control-regex` and needing the rule turned off to read it.
+ * XML 1.0 section 2.2, the whole `Char` production:
+ *
+ *   #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
+ *
+ * Stated as codes rather than a regex character class, which cannot express control characters
+ * without tripping `no-control-regex` and needing the rule turned off to read it.
  *
  * Iterating code points also means an astral character (an emoji in a test name) survives intact;
  * the regex worked on UTF-16 units.
+ *
+ * Only the LOWER bound used to be enforced, which left the production's two upper holes open:
+ * the surrogate block, and the noncharacters U+FFFE and U+FFFF. A test name or an assertion message
+ * carrying U+FFFF produced a document a real parser rejects outright ("disallowed character"), which
+ * is the same outcome the strip exists to prevent: CI shows nothing instead of showing the failure.
+ * A lone surrogate is the milder case, since writing the file as UTF-8 turns it into U+FFFD, but it
+ * is illegal by the same clause and dropping it keeps the rule one thing rather than two.
  */
 const XML_MIN_LEGAL_CODE = 0x20;
 const XML_LEGAL_CONTROL_CODES = new Set([
@@ -14,12 +24,26 @@ const XML_LEGAL_CONTROL_CODES = new Set([
     0x0a, // newline
     0x0d, // carriage return
 ]);
-/** Drop the control characters no XML parser will accept. */
+/** The surrogate block: legal only as a PAIR, which iteration has already resolved to one code point. */
+const XML_SURROGATE_FIRST = 0xd800;
+const XML_SURROGATE_LAST = 0xdfff;
+/** U+FFFE and U+FFFF are noncharacters; the production stops the BMP at U+FFFD. */
+const XML_BMP_LAST_LEGAL = 0xfffd;
+const XML_ASTRAL_FIRST = 0x10000;
+function isXmlLegal(code) {
+    if (XML_LEGAL_CONTROL_CODES.has(code))
+        return true;
+    if (code < XML_MIN_LEGAL_CODE)
+        return false;
+    if (code >= XML_SURROGATE_FIRST && code <= XML_SURROGATE_LAST)
+        return false;
+    return code <= XML_BMP_LAST_LEGAL || code >= XML_ASTRAL_FIRST;
+}
+/** Drop the characters no XML parser will accept. */
 function stripXmlIllegal(value) {
     let out = '';
     for (const ch of value) {
-        const code = ch.codePointAt(0) ?? 0;
-        if (code >= XML_MIN_LEGAL_CODE || XML_LEGAL_CONTROL_CODES.has(code))
+        if (isXmlLegal(ch.codePointAt(0) ?? 0))
             out += ch;
     }
     return out;

package/dist/matchers.d.ts

@@ -1,11 +1,36 @@
 import { type ToolInvoker } from '@reticlehq/server';
-import type { ElementQuery, ElementState } from '@reticlehq/core';
+import { type ElementQuery, type ElementState } from '@reticlehq/core';
 /** The verdict envelope returned by reticle_assert / the `verdict` field of reticle_act_and_wait. */
 export interface Verdict {
+    /** The RAW predicate match, before the honesty layer has had its say. */
     pass: boolean;
+    /**
+     * `"yes" | "no" | "unknown"`, when the daemon reported one. `act_and_wait`'s schema calls this
+     * "THE field to gate on", and it is allowed to disagree with `pass`: a UI that rendered success
+     * over a POST that returned 500 comes back `pass: true, verified: "no"`, which is the flagship
+     * verdict of the product rather than an edge case.
+     */
+    verified?: string;
+    /** One sentence naming the deciding evidence behind `verified`. */
+    because?: string;
     evidence?: unknown;
     failureReason?: string;
 }
+/**
+ * Did this verdict PROVE the thing the spec asserted?
+ *
+ * Only `verified: "no"` overrides `pass`. That is the case where the daemon looked at the same
+ * evidence and overturned a raw match, and reading `pass` alone made the one verdict this product
+ * exists to produce, a contradicted green, the one a spec reported as passing.
+ *
+ * `unknown` deliberately still follows `pass`. The tool's own schema says "unknown is NOT failure,
+ * it means the evidence could not decide, which calls for a better check rather than a code
+ * change", and whether a CI spec should go red, green or skipped on that is a product decision
+ * rather than something to settle inside a false-green fix.
+ *
+ * A daemon too old to send the field falls through to `pass`, unchanged.
+ */
+export declare function proved(verdict: Verdict): boolean;
 /**
  * Throw an ReticleAssertionError carrying the verdict's own evidence + failureReason. Used by every
  * `expect*` matcher and by actAndWait, so the runner's single catch boundary marks fail with the

package/dist/matchers.js

@@ -1,6 +1,26 @@
 import { ReticleTool } from '@reticlehq/server';
+import { Verified } from '@reticlehq/core';
 import { ReticleAssertionError } from './skip.js';
 import { CONSOLE_LEVEL_ERROR, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind } from './constants.js';
+/**
+ * Did this verdict PROVE the thing the spec asserted?
+ *
+ * Only `verified: "no"` overrides `pass`. That is the case where the daemon looked at the same
+ * evidence and overturned a raw match, and reading `pass` alone made the one verdict this product
+ * exists to produce, a contradicted green, the one a spec reported as passing.
+ *
+ * `unknown` deliberately still follows `pass`. The tool's own schema says "unknown is NOT failure,
+ * it means the evidence could not decide, which calls for a better check rather than a code
+ * change", and whether a CI spec should go red, green or skipped on that is a product decision
+ * rather than something to settle inside a false-green fix.
+ *
+ * A daemon too old to send the field falls through to `pass`, unchanged.
+ */
+export function proved(verdict) {
+    if (Verified.NO === verdict.verified)
+        return false;
+    return verdict.pass;
+}
 function asVerdict(value) {
     if (typeof value !== 'object' || null === value) {
         return { pass: false, failureReason: 'assert returned a non-object result' };
@@ -8,9 +28,13 @@ function asVerdict(value) {
     const record = value;
     const pass = true === record['pass'];
     const failureReason = 'string' === typeof record['failureReason'] ? record['failureReason'] : undefined;
+    const verified = 'string' === typeof record['verified'] ? record['verified'] : undefined;
+    const because = 'string' === typeof record['because'] ? record['because'] : undefined;
     return {
         pass,
         evidence: record['evidence'],
+        ...(verified !== undefined ? { verified } : {}),
+        ...(because !== undefined ? { because } : {}),
         ...(failureReason !== undefined ? { failureReason } : {}),
     };
 }
@@ -20,7 +44,10 @@ function asVerdict(value) {
  * predicate engine's structured diagnosis intact. `extraEvidence` lets actAndWait attach its trace.
  */
 export function failFromVerdict(verdict, extraEvidence) {
-    const message = verdict.failureReason ?? 'assertion failed';
+    // `because` before the generic fallback: an overturned verdict passed its own predicate, so it has
+    // no `failureReason` to offer, and "assertion failed" would hide the contradiction that is the
+    // entire finding.
+    const message = verdict.failureReason ?? verdict.because ?? 'assertion failed';
     // actAndWait passes extra context (the reaction trace); merge it alongside the verdict evidence.
     const evidence = extraEvidence !== undefined
         ? {
@@ -41,7 +68,7 @@ async function assertPredicate(invoke, predicate, timeoutMs, sessionId) {
         ...(sessionId !== undefined ? { sessionId } : {}),
     };
     const verdict = asVerdict(await invoke(ReticleTool.ASSERT, args));
-    if (!verdict.pass)
+    if (!proved(verdict))
         failFromVerdict(verdict);
 }
 function timeout(deps) {

package/dist/test-context.js

@@ -3,7 +3,7 @@ import { ActionType } from '@reticlehq/core';
 import { resolveTestid } from './resolve.js';
 import { buildClock } from './clock.js';
 import { InputModeTracker, expectInputModeReal } from './input-mode.js';
-import { failFromVerdict } from './matchers.js';
+import { failFromVerdict, proved } from './matchers.js';
 import { expectAbsent, expectElement, expectNet, expectNoConsoleErrors, expectSignal, expectText, } from './matchers.js';
 import { DEFAULT_ASSERT_TIMEOUT_MS } from './constants.js';
 function asVerdict(value) {
@@ -14,9 +14,16 @@ function asVerdict(value) {
     }
     const v = verdict;
     const failureReason = 'string' === typeof v['failureReason'] ? v['failureReason'] : undefined;
+    // `verified` and `because` sit at the TOP level of the act_and_wait result, beside `verdict`
+    // rather than inside it: the nested object carries the raw predicate match and nothing else. That
+    // split is why reading `verdict.pass` alone could not see an overturn.
+    const verified = 'string' === typeof record['verified'] ? record['verified'] : undefined;
+    const because = 'string' === typeof record['because'] ? record['because'] : undefined;
     return {
         pass: true === v['pass'],
         evidence: v['evidence'],
+        ...(verified !== undefined ? { verified } : {}),
+        ...(because !== undefined ? { because } : {}),
         ...(failureReason !== undefined ? { failureReason } : {}),
     };
 }
@@ -60,7 +67,7 @@ export function createTestContext(invoke, options = {}) {
             };
             const raw = await invoke(ReticleTool.ACT_AND_WAIT, waitArgs);
             const verdict = asVerdict(raw);
-            if (!verdict.pass) {
+            if (!proved(verdict)) {
                 const trace = raw['trace'];
                 failFromVerdict(verdict, trace !== undefined ? { trace } : undefined);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/test",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Reticle test runner: reticleTest spec registry + a runner that drives Reticle tools without MCP/stdio.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,8 +12,8 @@
     }
   },
   "dependencies": {
-    "@reticlehq/core": "2.13.0",
-    "@reticlehq/server": "2.13.0"
+    "@reticlehq/core": "2.14.0",
+    "@reticlehq/server": "2.14.0"
   },
   "peerDependencies": {
     "vitest": "^3.2.6"