@ai-ecoverse/slicc-browsers 1.21.0 → 1.22.0

package/README.md

@@ -7,7 +7,7 @@ The browser knowledge that SLICC's tools share. SLICC drives a real Chromium bro
 - which origins browser control must **never** touch, starting with seven's own origin and the vault;
 - how to prove that a CDP guard really keeps a client away from them.
 
-These programs can't share code, so they share data: one catalog, four sets of test vectors and their JSON schemas, published as a Go module, a Rust crate and an npm package at the same version.
+These programs can't share code, so they share data: one catalog, four vector sets and schemas, as a Go module, Rust crate and npm package at one version.
 
 | who | uses it for |
 | --- | --- |
@@ -223,7 +223,7 @@ await fixture.close();
 You supply:
 - **a guarded client** per row: your guard's CDP connection, with `send(method, params, sessionId)`, `waitEvent(predicate, ms)` and an `events` array;
 - **an unguarded observer**: a direct CDP connection to the same browser, which runs the controls and checks liveness;
-- **origins**: the fixture server reachable as seven, the vault and an ordinary site. Point the protected hostnames at it with Chrome's `--host-resolver-rules`, so no test ever touches the real seven;
+- **origins**: the fixture server reachable as seven, the vault and an ordinary site. Point the protected hostnames at it with Chrome's `--host-resolver-rules`, so tests never touch the real seven;
 - **capabilities**: what your transport can do. A row that needs something you don't declare is skipped as `not-supported:<capability>`.
 
 | capability | means the transport can |
@@ -239,6 +239,7 @@ You supply:
 | `siteIsolationOff`, `inboundDelay`, `forwardAudit` | no site isolation; hold inbound; audit forwarded commands |
 | `secureOrigin` | HTTPS origins (service workers) |
 | `stockSetup`, `syntheticAutoAttach` | admit stock clients' setup calls; synthesize auto-attach |
+| `closeProtected` | close a protected tab |
 
 ### Reading the result
 
@@ -248,13 +249,13 @@ Each row reports `control`, `guarded` and `live` as `pass`, `fail`, `skip`, `inc
 GUARD-PASS my-guard@1a2b3c4 (vectors @ai-ecoverse/slicc-browsers@1.18.5)
 ```
 
-The run passes only when every row passes and none is missing. A skip with a reason the runner would never give, such as a made-up capability, is reported as forged, and skipped and incomplete rows are counted on the line, so the line can't overstate what was tested.
+The run passes only when every row passes and none is missing. A skip with a reason the runner would never give is forged; skipped and incomplete rows are counted on the line, so it can't overstate what was tested.
 
 To find out what a vector checks, read it in `guard-vectors.json`: each one lists its steps, each observation's `means`, its `live` condition and its expected outcome. [`schema/guard-vectors.schema.json`](schema/guard-vectors.schema.json) defines the format.
 
 ## Development
 
-You need Go 1.26, Rust stable with the `wasm32-wasip1` target, Node 24 or later, and Chrome or Chromium for the browser tests: they take `CHROME_PATH`, or the Chrome for Testing that `npx slicc-cdp install-browser` installs, and run it headless unless `CI` is set (`SLICC_HEADLESS=1` or `0` overrides).
+You need Go 1.26, Rust stable with `wasm32-wasip1`, Node 24+, and Chrome or Chromium for the browser tests: they take `CHROME_PATH`, or Chrome for Testing from `npx slicc-cdp install-browser`, and run headless unless `CI` is set (`SLICC_HEADLESS=1` or `0` overrides).
 
 | command | what it does |
 | --- | --- |

package/guard-driver.mjs

@@ -197,7 +197,9 @@ export function judge(vector, side, observed) {
   }
   const skipped = Object.keys(want).filter(
     (k) =>
-      (observed?.[k] === 'not-supported' && vector.observe?.[k]?.requires?.length > 0) ||
+      (observed?.[k] === 'not-supported' &&
+        ((vector.observe?.[k]?.requires?.length ?? 0) > 0 ||
+          (vector.observe?.[k]?.unless?.length ?? 0) > 0)) ||
       (vector.observe?.[k]?.dependsOn ?? []).some((d) => refused.includes(d))
   );
   const incomplete = Object.keys(want).filter(
@@ -310,7 +312,9 @@ const capabilities = (value) =>
     ? value.flatMap(capabilities)
     : value && typeof value === 'object'
       ? Object.entries(value).flatMap(([key, item]) =>
-          key === 'requires' && Array.isArray(item) ? item : capabilities(item)
+          (key === 'requires' || key === 'unless') && Array.isArray(item)
+            ? item
+            : capabilities(item)
         )
       : [];
 
@@ -389,6 +393,17 @@ function skipWhy(vector, row, known, guard, declared) {
   return `skip with a reason the runner never gives: ${reason}`;
 }
 
+function observationWhy(vector, row, declared) {
+  return (row.notSupported ?? []).flatMap((name) => {
+    const observation = vector?.observe?.[name];
+    if (!observation) return [`not-supported observation ${name} the vector lacks`];
+    const missing = (observation.requires ?? []).some((cap) => !declared.includes(cap));
+    const unless = (observation.unless ?? []).some((cap) => declared.includes(cap));
+    if (missing || unless) return [];
+    return [`not-supported:${name} while the observation should run`];
+  });
+}
+
 function forgeries(set, results, guard, capabilitiesList) {
   const vectors = new Map(set.vectors.map((v) => [v.id, v]));
   const declared = declaredCapabilities(capabilitiesList);
@@ -405,6 +420,7 @@ function forgeries(set, results, guard, capabilitiesList) {
     if (legs.includes('not-run') && vector?.kind !== 'text')
       why.push('not-run on a vector that is not kind text');
     if (legs.includes('skip')) why.push(skipWhy(vector, row, known, guard, declared));
+    why.push(...observationWhy(vector, row, declared));
     const found = why.filter(Boolean);
     if (!found.length) return [];
     const { id, target, variant, transport } = row;

package/guard-runner.mjs

@@ -50,6 +50,13 @@ const supported = (requires, capabilities) =>
   (requires ?? []).every((c) =>
     Array.isArray(capabilities) ? capabilities.includes(c) : capabilities[c] === true
   );
+const declared = (capability, capabilities) =>
+  Array.isArray(capabilities)
+    ? capabilities.includes(capability)
+    : capabilities[capability] === true;
+const gatedOut = (observation, capabilities) =>
+  !supported(observation?.requires, capabilities) ||
+  (observation?.unless ?? []).some((capability) => declared(capability, capabilities));
 const matches = (value, predicate) => {
   if (predicate === null || typeof predicate !== 'object') return value === predicate;
   return Object.entries(predicate).every(([key, want]) => {
@@ -1616,7 +1623,7 @@ class Execution {
     const observed = { ...this.refused };
     const incomplete = [];
     for (const [name, observation] of Object.entries(this.vector.observe ?? {})) {
-      if (!supported(observation.requires, this.options.capabilities)) {
+      if (gatedOut(observation, this.options.capabilities)) {
         observed[name] = 'not-supported';
         continue;
       }