waygraph 0.12.19 → 0.12.21

package/README.md

@@ -228,11 +228,14 @@ real acts). `--ff-expand` is the older expand-only flag (same flatten). Saucedem
 `checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays expanded for
 Sign In narration.
 
-`waygraph traverse` walks the Block graph (Phase B+D). `--parallel N` (default
+`waygraph traverse` walks the Block graph (Phase B-E). `--parallel N` (default
 `--session clone`) bootstraps one context, forks N workers with `storageState` + mem
 snapshot, partitions edges by hash, and claims via in-process edge leases (audit under
-`.waygraph-traverse/`). `--session inherit` is refused when `parallel > 1`. See
-`docs/proposals/traverse-ffcompose-rfc.md`.
+`.waygraph-traverse/`). `--session inherit` is refused when `parallel > 1`. Phase E
+writes `.waygraph-traverse/coverage.json` and prints `[Coverage edges=H/T ratio=R%...]`;
+`--min-edge-coverage 80%` fails the suite with exit 2 when the ratio is below the gate
+(even if every worker leaf-PASSed). `--coverage-out PATH` / `--no-coverage-report` adjust
+the JSON. See `docs/proposals/traverse-ffcompose-rfc.md`.
 
 **Richer demo narration:** automation rings are **gray**; authored stubs/slides can use
 `tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus

package/dist/auto-explore-run.js

@@ -194,20 +194,23 @@ async function runOneBlock(engine, entry, context, page, mem, headful) {
     const flow = engine.defineFlow([start, entry.block, end]);
     const BLOCK_TIMEOUT_MS = 45_000;
     let timer;
+    let result;
     try {
-        await Promise.race([
+        const ran = await Promise.race([
             flow.run(context, mem, { page, closeOnFinish: false }),
             new Promise((_, reject) => {
                 timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s - ` +
                     "click Quit and retry, or check network / mem credentials")), BLOCK_TIMEOUT_MS);
             }),
         ]);
+        result = ran.result;
     }
     finally {
         if (timer)
             clearTimeout(timer);
     }
     await page.evaluate("delete window.__wgPendingNavClickLabel").catch(() => { });
+    return result;
 }
 const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
     "max-width:min(92vw,720px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
@@ -540,13 +543,16 @@ export async function runAutoExplore(projectDir, options = {}) {
         }
         wiredPage = target;
     }
+    let here = null;
     try {
         for (;;) {
             page = await ensureLivePage(context, page, startUrl);
             await wirePage(page);
             const pickWait = armPickWait();
             pickSlot.resolve = pickWait.resolve;
-            const here = await detectHere(page, library.navBlocks);
+            if (here === null) {
+                here = await detectHere(page, library.navBlocks);
+            }
             if (cli)
                 console.error("waygraph auto: scanning page for moves ...");
             const menu = await buildExploreMenu(page, graph, library, here);
@@ -595,10 +601,11 @@ export async function runAutoExplore(projectDir, options = {}) {
                 }
                 const pickLabel = edge.label ?? entry.block.name;
                 console.error(`waygraph auto: running [${pick.index + 1}] ${pickLabel} ...`);
-                await runOneBlock(engine, entry, context, page, mem, !cli);
-                const landed = await detectHere(page, library.navBlocks);
-                lastRunNote = `${entry.block.name} -> ${landed ?? edge.to}`;
-                console.error(`waygraph auto: ran ${entry.block.name} -> ${landed ?? edge.to}`);
+                const result = await runOneBlock(engine, entry, context, page, mem, !cli);
+                // Trust block output over locate() - nav verify traits collide on /dashboard.
+                here = result.__state ?? edge.to;
+                lastRunNote = `${entry.block.name} -> ${here}`;
+                console.error(`waygraph auto: ran ${entry.block.name} -> ${here}`);
             }
             catch (err) {
                 lastRunNote = `${entry.block.name} failed`;

package/dist/cli.js

@@ -21,6 +21,7 @@ import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./gra
 import { runAutoExplore } from "./auto-explore-run.js";
 import { runAgentDive } from "./agent-dive.js";
 import { runTraverse } from "./traverse-run.js";
+import { parseMinEdgeCoverage } from "./traverse-coverage.js";
 import { isFileSelectToken, parseBlocksSelect, } from "./blocks-select.js";
 // ---------------------------------------------------------------------------
 // Filesystem
@@ -3950,7 +3951,7 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
-  waygraph traverse [project]              Graph crawl (Phase B+D)
+  waygraph traverse [project]              Graph crawl (Phase B-E)
                  --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
                  --parallel N              Phase D: N clone workers (max 4)
                  --session clone|inherit   Phase D: default clone
@@ -4076,6 +4077,9 @@ async function main() {
             let blocksFilter;
             let parallel;
             let session;
+            let minEdgeCoverageRaw;
+            let coverageOut;
+            let noCoverageReport = false;
             let projectDir = process.cwd();
             for (let i = 0; i < rest.length; i++) {
                 const a = rest[i];
@@ -4115,6 +4119,22 @@ async function main() {
                     session = v;
                     continue;
                 }
+                if (a === "--min-edge-coverage" || a.startsWith("--min-edge-coverage=")) {
+                    minEdgeCoverageRaw = a.startsWith("--min-edge-coverage=")
+                        ? a.slice("--min-edge-coverage=".length)
+                        : rest[++i];
+                    continue;
+                }
+                if (a === "--coverage-out" || a.startsWith("--coverage-out=")) {
+                    coverageOut = a.startsWith("--coverage-out=")
+                        ? a.slice("--coverage-out=".length)
+                        : rest[++i];
+                    continue;
+                }
+                if (a === "--no-coverage-report") {
+                    noCoverageReport = true;
+                    continue;
+                }
                 if (a === "--max-steps" || a.startsWith("--max-steps=")) {
                     const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
                     maxSteps = Number(v);
@@ -4143,12 +4163,15 @@ async function main() {
                 if (a === "--help" || a === "-h") {
                     console.log(`waygraph traverse [project] [flags]
 
-Graph crawl (RFC Phase B+D). Walks unused legal edges until a leaf,
+Graph crawl (RFC Phase B-E). Walks unused legal edges until a leaf,
 budget kill, or first broken edge. --parallel N uses session clone + edge leases.
 
   --blocks <glob|/regex/|substr>  Phase C: filter *.block.ts discovery
   --parallel N            Phase D: N clone workers (default 1, max 4)
   --session clone|inherit Phase D: default clone; inherit refused if parallel>1
+  --min-edge-coverage X   Phase E: suite gate 0.8 | 80% | 80 (exit 2 if below)
+  --coverage-out PATH     Phase E: write JSON (default .waygraph-traverse/coverage.json)
+  --no-coverage-report    Phase E: print Coverage line only (no JSON file)
   --from <Checkpoint>     start checkpoint (optional)
   --data '{...}'          Mem seed JSON
   --max-steps N           default 50 (per worker)
@@ -4160,9 +4183,11 @@ budget kill, or first broken edge. --parallel N uses session clone + edge leases
 Examples:
   waygraph traverse --blocks '**/mailpit/**/*.block.ts'
   waygraph traverse --parallel 2 --session clone --max-steps 20
+  waygraph traverse --min-edge-coverage 80% --coverage-out ./cov.json
 
 PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
 FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
+COVER: [Coverage edges=H/T ratio=R% min=M% PASS|FAIL]
 `);
                     process.exit(0);
                 }
@@ -4177,6 +4202,15 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
             const blocksSelect = blocksFilter
                 ? parseBlocksSelect(blocksFilter)
                 : undefined;
+            let minEdgeCoverage;
+            if (minEdgeCoverageRaw !== undefined) {
+                const parsed = parseMinEdgeCoverage(minEdgeCoverageRaw);
+                if (parsed === null) {
+                    console.error(`waygraph traverse: --min-edge-coverage expects 0.8, 80%, or 80 (got ${JSON.stringify(minEdgeCoverageRaw)})`);
+                    process.exit(1);
+                }
+                minEdgeCoverage = parsed;
+            }
             const code = await runTraverse(projectDir, {
                 ...(from ? { from } : {}),
                 ...(data ? { data } : {}),
@@ -4192,6 +4226,9 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                 ...(blocksSelect ? { blocksSelect } : {}),
                 ...(parallel !== undefined && Number.isFinite(parallel) ? { parallel } : {}),
                 ...(session ? { session } : {}),
+                ...(minEdgeCoverage !== undefined ? { minEdgeCoverage } : {}),
+                ...(coverageOut ? { coverageOut: resolve(coverageOut) } : {}),
+                ...(noCoverageReport ? { noCoverageReport: true } : {}),
             });
             process.exit(code);
         }

package/dist/index.d.ts

@@ -13,4 +13,6 @@ export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp,
 export type { BlocksSelect, BlocksSelectKind } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";
 export { runTraverse } from "./traverse-run.js";
-export type { TraverseOptions, TraverseSessionMode } from "./traverse-run.js";
+export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse-run.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
+export type { TraverseCoverageReport } from "./traverse-coverage.js";

package/dist/index.js

@@ -7,3 +7,4 @@ export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./gra
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";
 export { runTraverse } from "./traverse-run.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";

package/dist/traverse-coverage.d.ts

@@ -0,0 +1,59 @@
+export interface TraverseCoverageReport {
+    version: 1;
+    generatedAt: string;
+    projectDir: string;
+    parallel: number;
+    /** Unique edge keys in the discovered graph (block names). */
+    edgesTotal: number;
+    /** Graph edges successfully walked this suite (after instance normalize). */
+    edgesHit: number;
+    /** edgesHit / edgesTotal (0 when total is 0). */
+    ratio: number;
+    /** Optional suite gate that was applied (0-1). */
+    minEdgeCoverage?: number;
+    /** true when minEdgeCoverage was set and ratio met it. */
+    coveragePass?: boolean;
+    /** Sorted graph edge keys that were hit. */
+    hit: string[];
+    /** Sorted graph edge keys never walked. */
+    missed: string[];
+    /** Raw worker hit keys (may include block::instanceId). */
+    rawHit?: string[];
+    workers?: Array<{
+        traverseId: string;
+        exitCode: number;
+        steps: number;
+        edgesHit: number;
+        leaf?: string;
+    }>;
+}
+/** Static graph edge key = Block runtime name. */
+export declare function edgeKeyFromGraphEdge(edge: {
+    block: string;
+}): string;
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export declare function collectGraphEdgeKeys(edges: ReadonlyArray<{
+    block: string;
+}>): string[];
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export declare function normalizeHitKey(hitKey: string, graphKeys: ReadonlySet<string>): string | null;
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export declare function parseMinEdgeCoverage(raw: unknown): number | null;
+export declare function buildCoverageReport(opts: {
+    projectDir: string;
+    parallel: number;
+    allEdgeKeys: readonly string[];
+    hitKeys: ReadonlySet<string> | readonly string[];
+    minEdgeCoverage?: number | null;
+    workers?: TraverseCoverageReport["workers"];
+}): TraverseCoverageReport;
+/** Greppable one-liner for agents/CI. */
+export declare function formatCoverageLine(report: TraverseCoverageReport): string;
+export declare function defaultCoverageOutPath(projectDir: string): string;
+export declare function writeCoverageReport(path: string, report: TraverseCoverageReport): void;

package/dist/traverse-coverage.js

@@ -0,0 +1,127 @@
+/**
+ * Phase E: traverse edge coverage report + suite gate.
+ * Coverage is independent of leaf PASS - a green leaf can still fail CI
+ * when --min-edge-coverage is set and ratio is too low.
+ *
+ * Denominator = unique static graph edge block names (FF inners stay as their
+ * own graph edges when discovered; RFC open Q deferred - no covered-via-prefix yet).
+ * A hit of `block::instanceId` counts as covering `block`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Static graph edge key = Block runtime name. */
+export function edgeKeyFromGraphEdge(edge) {
+    return edge.block;
+}
+/** Collect unique edge keys from a WaygraphGraph-like edges list. */
+export function collectGraphEdgeKeys(edges) {
+    const set = new Set();
+    for (const e of edges)
+        set.add(edgeKeyFromGraphEdge(e));
+    return [...set].sort();
+}
+/**
+ * Map a worker hit key onto the static graph key it covers.
+ * `add-to-cart::sku-1` -> `add-to-cart` when that block is in the graph.
+ */
+export function normalizeHitKey(hitKey, graphKeys) {
+    if (graphKeys.has(hitKey))
+        return hitKey;
+    const base = hitKey.includes("::") ? hitKey.slice(0, hitKey.indexOf("::")) : hitKey;
+    if (graphKeys.has(base))
+        return base;
+    return null;
+}
+/**
+ * Parse --min-edge-coverage: `0.8`, `80%`, `80` (as percent when > 1).
+ * Returns 0-1 fraction, or null when unset/invalid.
+ */
+export function parseMinEdgeCoverage(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        if (raw < 0)
+            return null;
+        if (raw <= 1)
+            return raw;
+        if (raw <= 100)
+            return raw / 100;
+        return null;
+    }
+    if (typeof raw !== "string")
+        return null;
+    const t = raw.trim().toLowerCase();
+    if (!t)
+        return null;
+    if (t.endsWith("%")) {
+        const n = Number(t.slice(0, -1));
+        if (!Number.isFinite(n) || n < 0 || n > 100)
+            return null;
+        return n / 100;
+    }
+    const n = Number(t);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    if (n <= 1)
+        return n;
+    if (n <= 100)
+        return n / 100;
+    return null;
+}
+export function buildCoverageReport(opts) {
+    const all = [...new Set(opts.allEdgeKeys)].sort();
+    const graphSet = new Set(all);
+    const rawList = Array.isArray(opts.hitKeys) ? [...opts.hitKeys] : [...opts.hitKeys];
+    const covered = new Set();
+    for (const raw of rawList) {
+        const n = normalizeHitKey(raw, graphSet);
+        if (n)
+            covered.add(n);
+    }
+    const hit = all.filter((k) => covered.has(k));
+    const missed = all.filter((k) => !covered.has(k));
+    const edgesTotal = all.length;
+    const edgesHit = hit.length;
+    const ratio = edgesTotal === 0 ? 0 : edgesHit / edgesTotal;
+    const min = opts.minEdgeCoverage != null && Number.isFinite(opts.minEdgeCoverage)
+        ? Math.min(1, Math.max(0, opts.minEdgeCoverage))
+        : undefined;
+    const coveragePass = min === undefined ? undefined : ratio + 1e-12 >= min;
+    const coverageExtra = min !== undefined && coveragePass !== undefined
+        ? { minEdgeCoverage: min, coveragePass }
+        : {};
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        projectDir: opts.projectDir,
+        parallel: opts.parallel,
+        edgesTotal,
+        edgesHit,
+        ratio: Math.round(ratio * 10000) / 10000,
+        ...coverageExtra,
+        hit,
+        missed,
+        rawHit: [...new Set(rawList)].sort(),
+        ...(opts.workers ? { workers: opts.workers } : {}),
+    };
+}
+/** Greppable one-liner for agents/CI. */
+export function formatCoverageLine(report) {
+    const pct = (report.ratio * 100).toFixed(1);
+    const minPart = report.minEdgeCoverage !== undefined
+        ? ` min=${(report.minEdgeCoverage * 100).toFixed(1)}%` +
+            (report.coveragePass === false
+                ? " FAIL"
+                : report.coveragePass === true
+                    ? " PASS"
+                    : "")
+        : "";
+    return `[Coverage edges=${report.edgesHit}/${report.edgesTotal} ratio=${pct}%${minPart}]`;
+}
+export function defaultCoverageOutPath(projectDir) {
+    return join(projectDir, ".waygraph-traverse", "coverage.json");
+}
+export function writeCoverageReport(path, report) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(report, null, 2) + "\n", "utf-8");
+}

package/dist/traverse-run.d.ts

@@ -1,4 +1,10 @@
 export type TraverseSessionMode = "clone" | "inherit";
+export interface TraverseWorkerResult {
+    exitCode: number;
+    steps: number;
+    edgesHit: string[];
+    leaf?: string;
+}
 export interface TraverseOptions {
     baseURL?: string;
     startUrl?: string;
@@ -24,8 +30,18 @@ export interface TraverseOptions {
     parallel?: number;
     /** Phase D: clone (default) or inherit. Inherit refused when parallel > 1. */
     session?: TraverseSessionMode;
+    /**
+     * Phase E: fail suite (exit 2) when hit/total ratio is below this 0-1 fraction.
+     * Leaf PASS alone does not satisfy the gate.
+     */
+    minEdgeCoverage?: number;
+    /** Phase E: write coverage JSON here (default `.waygraph-traverse/coverage.json`). */
+    coverageOut?: string;
+    /** Phase E: skip writing coverage.json (still prints the Coverage line). */
+    noCoverageReport?: boolean;
 }
 /**
- * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL + Coverage lines.
+ * Exit: 0 leaf ok (+ coverage ok), 1 break/timeout, 2 coverage gate fail (Phase E).
  */
 export declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;

package/dist/traverse-run.js

@@ -9,6 +9,7 @@ import { MemPage } from "./mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { defaultMemValueForKey } from "./auto-explore-run.js";
 import { EdgeLeaseCoordinator } from "./traverse-lease.js";
+import { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, writeCoverageReport, } from "./traverse-coverage.js";
 function resolveBaseUrl(projectDir) {
     if (process.env.WAYGRAPH_BASE_URL)
         return process.env.WAYGRAPH_BASE_URL;
@@ -132,6 +133,7 @@ async function runTraverseWorker(opts) {
     const startedAt = Date.now();
     let lastHere = opts.from ?? null;
     let exitCode = 0;
+    let leaf;
     try {
         for (;;) {
             if (Date.now() - startedAt > timeoutMs) {
@@ -171,6 +173,7 @@ async function runTraverseWorker(opts) {
             });
             if (candidates.length === 0) {
                 const label = here ?? detected ?? "unknown";
+                leaf = label;
                 console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
                 console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
                 break;
@@ -227,10 +230,16 @@ async function runTraverseWorker(opts) {
     finally {
         console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
     }
-    return exitCode;
+    return {
+        exitCode,
+        steps,
+        edgesHit: [...edgesHit],
+        ...(leaf ? { leaf } : {}),
+    };
 }
 /**
- * Serial or parallel graph crawl. Prints greppable PASS/FAIL lines; non-zero on break.
+ * Serial or parallel graph crawl. Prints greppable PASS/FAIL + Coverage lines.
+ * Exit: 0 leaf ok (+ coverage ok), 1 break/timeout, 2 coverage gate fail (Phase E).
  */
 export async function runTraverse(projectDir, options = {}) {
     let parallel = Math.max(1, Math.floor(options.parallel ?? 1));
@@ -250,11 +259,16 @@ export async function runTraverse(projectDir, options = {}) {
     const headed = options.headed === true || process.env.WAYGRAPH_HEADED === "1";
     const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
     const startUrl = options.startUrl ?? baseURL;
+    const minEdgeCoverage = options.minEdgeCoverage != null && Number.isFinite(options.minEdgeCoverage)
+        ? options.minEdgeCoverage
+        : undefined;
+    const coverageOut = options.coverageOut ?? defaultCoverageOutPath(projectDir);
     const { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
     if (options.blocksSelect) {
         console.error(`waygraph traverse: --blocks ${options.blocksSelect.raw} -> ` +
             `${library.byName.size} block(s), ${graph.edges.length} edge(s)`);
     }
+    const allEdgeKeys = collectGraphEdgeKeys(graph.edges);
     const leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
     const { chromium } = await import("@playwright/test");
@@ -268,7 +282,46 @@ export async function runTraverse(projectDir, options = {}) {
     console.error(`waygraph traverse: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
         (baseURL ? ` base=${baseURL}` : "") +
         ` parallel=${parallel} session=${session}` +
-        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}`);
+        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}` +
+        (minEdgeCoverage !== undefined
+            ? ` minEdgeCoverage=${(minEdgeCoverage * 100).toFixed(1)}%`
+            : ""));
+    const emitCoverage = (workers) => {
+        const hitUnion = new Set();
+        for (const w of workers) {
+            for (const k of w.result.edgesHit)
+                hitUnion.add(k);
+        }
+        const report = buildCoverageReport({
+            projectDir,
+            parallel,
+            allEdgeKeys,
+            hitKeys: hitUnion,
+            ...(minEdgeCoverage !== undefined ? { minEdgeCoverage } : {}),
+            workers: workers.map(({ traverseId, result }) => ({
+                traverseId,
+                exitCode: result.exitCode,
+                steps: result.steps,
+                edgesHit: result.edgesHit.length,
+                ...(result.leaf ? { leaf: result.leaf } : {}),
+            })),
+        });
+        console.log(formatCoverageLine(report));
+        console.error(`waygraph traverse: coverage hit=${report.edgesHit}/${report.edgesTotal}` +
+            (report.missed.length
+                ? ` missed=${report.missed.slice(0, 8).join(",")}${report.missed.length > 8 ? "..." : ""}`
+                : "") +
+            (options.noCoverageReport ? "" : ` report=${coverageOut}`));
+        if (!options.noCoverageReport) {
+            writeCoverageReport(coverageOut, report);
+        }
+        if (report.coveragePass === false) {
+            console.error(`waygraph traverse: FAIL coverage gate ratio=${(report.ratio * 100).toFixed(1)}%` +
+                ` < min=${((report.minEdgeCoverage ?? 0) * 100).toFixed(1)}%`);
+            return 2;
+        }
+        return 0;
+    };
     try {
         if (parallel <= 1) {
             const contextOpts = {
@@ -284,8 +337,9 @@ export async function runTraverse(projectDir, options = {}) {
                 await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
                 await page.waitForLoadState("load").catch(() => { });
             }
-            const code = await runTraverseWorker({
-                traverseId: options.traverseId ?? "traverse-1",
+            const traverseId = options.traverseId ?? "traverse-1";
+            const result = await runTraverseWorker({
+                traverseId,
                 workerIndex: 0,
                 parallel: 1,
                 maxSteps,
@@ -305,7 +359,10 @@ export async function runTraverse(projectDir, options = {}) {
                 leases,
             });
             await context.close().catch(() => { });
-            return code;
+            const coverageCode = emitCoverage([{ traverseId, result }]);
+            if (result.exitCode !== 0)
+                return result.exitCode;
+            return coverageCode;
         }
         // Phase D: bootstrap one context for storageState, then N clones.
         const bootOpts = {
@@ -325,7 +382,7 @@ export async function runTraverse(projectDir, options = {}) {
         const memSnap = snapshotMem(library.byName, bootMem);
         await bootContext.close().catch(() => { });
         console.error(`waygraph traverse: forked ${parallel} clone workers (storageState + mem snapshot)`);
-        const codes = await Promise.all(Array.from({ length: parallel }, async (_, i) => {
+        const workerMeta = await Promise.all(Array.from({ length: parallel }, async (_, i) => {
             const traverseId = `traverse-${i + 1}`;
             const ctxOpts = {
                 viewport: { width: 1280, height: 720 },
@@ -341,7 +398,7 @@ export async function runTraverse(projectDir, options = {}) {
                 await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
             }
             try {
-                return await runTraverseWorker({
+                const result = await runTraverseWorker({
                     traverseId,
                     workerIndex: i,
                     parallel,
@@ -361,15 +418,20 @@ export async function runTraverse(projectDir, options = {}) {
                     mem,
                     leases,
                 });
+                return { traverseId, result };
             }
             finally {
                 await context.close().catch(() => { });
             }
         }));
-        const worst = codes.reduce((a, b) => Math.max(a, b), 0);
-        const pass = codes.filter((c) => c === 0).length;
+        const results = workerMeta.map((w) => w.result);
+        const worst = results.reduce((a, b) => Math.max(a, b.exitCode), 0);
+        const pass = results.filter((c) => c.exitCode === 0).length;
         console.error(`waygraph traverse: suite parallel=${parallel} pass=${pass}/${parallel} exit=${worst}`);
-        return worst;
+        const coverageCode = emitCoverage(workerMeta);
+        if (worst !== 0)
+            return worst;
+        return coverageCode;
     }
     finally {
         await browser.close().catch(() => { });

package/examples/saucedemo/README.md

@@ -34,6 +34,9 @@ npx playwright install chromium
 | Headless suite | `npm test` |
 | Interactive explore (headed panel) | `npm run auto` |
 | Interactive explore (terminal menu) | `npm run auto:cli` |
+| Graph crawl (Phase B-E) | `npm run traverse` |
+| Parallel crawl + leases | `npm run traverse:parallel` |
+| Coverage JSON + min gate (10%) | `npm run traverse:coverage` |
 | Shop demo stepper | `npm run demo:step` |
 | Shop demo autoplay | `npm run demo:autoplay` |
 | **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
@@ -47,6 +50,7 @@ npx playwright install chromium
 | **`run --blocks`** | `npm run run:bulk` — Block names + `--data` | No |
 | **`demo --blocks`** | `npm run demo:bulk` — named flow + `--data` | Optional (`cartBulkFlow`) |
 | **`auto`** | `npm run auto` / `auto:cli` | No — live menu |
+| **`traverse`** | `npm run traverse` / `traverse:parallel` / `traverse:coverage` | No — graph crawl + `.waygraph-traverse/coverage.json` |
 | **`auto --blocks From To`** | path-find on graph | No — checkpoints only |
 
 QA watch+record: `npm run demo:bulk:video` (`--auto-play-video`).

package/examples/saucedemo/package.json

@@ -14,6 +14,9 @@
     "auto": "waygraph auto",
     "auto:cli": "waygraph auto --cli --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
     "prove:auto-cli": "node scripts/drive-auto-cli.mjs",
+    "traverse": "waygraph traverse --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
+    "traverse:parallel": "waygraph traverse --parallel 2 --session clone --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 30",
+    "traverse:coverage": "waygraph traverse --min-edge-coverage 10% --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
     "graph": "waygraph graph",
     "graph:mermaid": "waygraph graph --mermaid",
     "demo:stub-on-error": "waygraph demo --blocks stubOnErrorFlow --auto-next --fast --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --title \"stubOnError prove\"",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.19",
+  "version": "0.12.21",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "tsx": "^4.0.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.55.0",
+    "@playwright/test": "^1.63.0",
     "@types/node": "^26.0.0",
     "typescript": "^5.6.0"
   }

package/templates/quickstart/package.json

@@ -9,6 +9,9 @@
     "check": "waygraph check",
     "auto": "waygraph auto",
     "auto:cli": "waygraph auto --cli --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
+    "traverse": "waygraph traverse --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
+    "traverse:parallel": "waygraph traverse --parallel 2 --session clone --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 30",
+    "traverse:coverage": "waygraph traverse --min-edge-coverage 10% --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
     "graph": "waygraph graph",
     "graph:mermaid": "waygraph graph --mermaid",
     "demo": "waygraph demo --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
@@ -23,7 +26,7 @@
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.11.0"
+    "waygraph": "^0.12.20"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/scaffold/package.json

@@ -24,7 +24,7 @@
     "baseUrl": "http://127.0.0.1:4177"
   },
   "dependencies": {
-    "waygraph": "^0.12.7"
+    "waygraph": "^0.12.20"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",