@clear-capabilities/agentic-security-scanner 0.147.0 → 0.147.5

package/CHANGELOG.md

@@ -11,6 +11,133 @@
 
 
 
+## 0.147.5 — Fix: `bench:provenance:check`'s cold-memory sample size was unreliable on GitHub Actions
+
+`v0.147.4`'s tag was pushed but its hosted release-gate run failed before
+reaching `npm publish` — the `dataflow-watch` fix held (the full test suite
+passed cleanly), but `bench/provenance/runner.mjs`'s `bench:provenance:check`
+failed: "only 8/20 iterations produced a usable sample (need >= 10)" for
+`cold.memOverheadRatio`. This is the SAME failure `v0.147.3`'s release run
+also hit (7/20 that time) — two consecutive, reproducible failures on
+GitHub's runners specifically, while this bench passes cleanly (~20/20)
+every time locally, so this is a real platform gap, not one-off noise.
+
+Root cause: `cold.memOverheadRatio` is a per-iteration ratio against the
+without-provenance arm's own peak-RSS delta, and `measure()` skips the
+ratio entirely for an iteration where that delta is `0`
+(`if (without.rssDeltaBytes > 0) { ... }`) — the without-provenance scan is
+only ~40-60ms, short enough that the 10ms-interval peak-RSS poller can
+genuinely observe no net growth for it, especially under a shared runner's
+different GC pacing. `BASELINE.json` itself already records this as
+expected (`memOverheadRatio.n: 19`, one dropped iteration out of 20 even on
+the machine that captured it) — GitHub Actions just drops far more of them
+(a ~35-40% survival rate against RELIABLE_N=10 at N=20 leaves no margin).
+
+Raises `N` from 20 to 60 in `bench/provenance/runner.mjs` — the same
+already-established remedy this exact file used once before for a related
+small-sample fragility (doubling 10→20), extended further given the new,
+worse-than-expected survival rate. `RELIABLE_N` (10) and the regression
+thresholds are unchanged; `BASELINE.json`'s reference values were not
+touched (the measured overhead is well within budget — this was purely a
+sample-count reliability failure, not a regression). Verified locally:
+passes with real margin (cold memory p95 11.42x vs a 24.38x limit), at a
+real but bounded cost — this one bench step now takes ~2:23 instead of
+~40-60s, a release-time-only cost. `v0.147.4` was never published to any
+registry (confirmed via `npm view`). Carries the identical fixes from
+0.147.1-0.147.4 forward.
+
+## 0.147.4 — Fix: close a real fs.watch startup race in `dataflow watch` (test-only; no product behavior change)
+
+`v0.147.3`'s tag was pushed but its hosted release-gate run failed before
+reaching `npm publish` — again `cli/dataflow-watch-2`, but this time raising
+the wait timeout (0.147.3's own fix) did NOT help: it timed out at the
+*full* 90000ms budget with zero rescan output, which the real rescan
+pipeline (~1-2s once triggered) rules out as "merely slow." Root cause: `bin/
+agentic-security.js`'s `cmdDataflowWatch` prints its "watching ... Ctrl-C to
+stop" banner — the exact string these tests poll for as the "watcher is
+live" signal — *before* calling `watchProject()`, which is where
+`fs.watch()` actually arms its (possibly recursive, whole-tree-walking on
+Linux) inotify descriptors. A test file-write landing in that gap produces
+an event inotify never delivers at all — a permanent miss, not a delay —
+which a longer timeout cannot fix by construction.
+
+Fixed with a 1000ms settle delay in the test, inserted between seeing the
+startup banner and writing the trigger file, in both `dataflow-watch-1` and
+`dataflow-watch-2` (`test/cli/dataflow-watch.test.js`). No product code
+changed — `cmdDataflowWatch`'s banner-before-watchProject ordering is real,
+pre-existing behavior, unrelated to anything in 0.147.1-0.147.3, and left
+alone here rather than reordered under release time pressure without full
+confidence in every caller depending on today's ordering. `v0.147.3` was
+never published to any registry (confirmed via `npm view`). Carries the
+identical fixes from 0.147.1-0.147.3 forward.
+
+## 0.147.3 — CI fix: raise dataflow-watch's live-subprocess wait timeout (no functional change from 0.147.2)
+
+Same story as 0.147.2, different test: `v0.147.2`'s hosted release-gate run
+also failed before reaching `npm publish` — `test/cli/dataflow-watch.test.js`'s
+`cli/dataflow-watch-2` polls a real subprocess's live stderr for a
+`DRIFT POLICY VIOLATION` line after triggering a file-watch-driven rescan,
+with a 30000ms budget. That step completes in ~1.4s on a normal machine (a
+~20x margin) but still timed out on this run — this repo's watch mode uses
+Node's native `fs.watch(..., { recursive: true })`
+(`src/posture/watch-mode.js`), documented as slower/less reliable under
+Linux CI runners' inotify handling than on a dev machine. `v0.147.2` was
+never published to any registry (confirmed via `npm view`).
+
+Raises the wait budget from 30000ms to a shared `WAIT_TIMEOUT_MS = 90000`
+across both real-subprocess tests in that file (the ones that depend on the
+file-watch path — an unrelated fast-fail test in the same file was left
+untouched). No product code changed; this carries the identical fixes from
+0.147.1 and 0.147.2 forward.
+
+## 0.147.2 — CI fix: raise the headless-Chrome render timeout (no functional change from 0.147.1)
+
+`v0.147.1`'s tag was pushed but its hosted release-gate run failed before
+ever reaching `npm publish` — `scripts/export-image.mjs`'s `exportPng` test
+hit its own hardcoded 15000ms Chrome render timeout on a slower draw of the
+GitHub Actions runner (the same render took 7983ms on the immediately
+preceding v0.147.0 release run — a ~2x runner-speed swing well within
+normal CI variance, not a regression). `v0.147.1` was never published to
+any registry; this release carries the identical `explore`/`dataflow
+export --format html` fix described below under 0.147.1, plus this one
+timeout change: `RENDER_TIMEOUT_MS` default raised from 15000ms to 30000ms
+in `scripts/export-image.mjs`, giving roughly 4x headroom over the observed
+good-case render time. No other code changed.
+
+## 0.147.1 — Fix: `explore` and `dataflow export --format html` were broken for every real npm/npx install
+
+Both commands located the Data Flow Explorer frontend (`frontend/`, a
+repo-root sibling of `scanner/` in this monorepo) via a fixed relative path
+computed from each module's own `import.meta.url`
+(`path.resolve(HERE, '../../../frontend')` in `static-assets.js`,
+`'../../frontend'` in `generate-html-report.mjs`). That math was correct
+only for the unbundled dev checkout. Once `npm run build` (ncc) split those
+modules into their own `dist/*.index.js` chunks, `import.meta.url` inside
+them reflected `dist/`'s own, shallower location, and the same fixed
+relative math resolved *outside the installed package entirely* — and
+`frontend/` was never part of the published npm tarball to begin with. The
+practical effect: `agentic-security explore .` 404'd on `GET /` for every
+real `npx`/`npm install` user (`{"error":"not found"}`, never an
+index.html), and `dataflow export . --format html` failed outright
+(`ENOENT: no such file or directory, scandir '.../frontend/styles'`). Both
+only ever worked when run from a full monorepo clone.
+
+Fixed by shipping the frontend's servable files inside the published
+package: `scanner/scripts/copy-frontend.mjs` (new) copies `frontend/`'s
+allowlisted files (`index.html`, `src/**/*.js`, top-level `styles/*.css` —
+the exact same allowlist `static-assets.js` already enforced for serving)
+into `scanner/dist/frontend/` as part of `npm run build`; a new shared
+resolver, `scanner/src/shared/frontend-root.js`, replaces both hardcoded
+relative paths with a search-upward strategy that finds the frontend
+correctly regardless of bundling depth. Verified by packing a real tarball
+(`npm pack`) and installing it into an isolated directory with no monorepo
+present: `explore`'s `GET /` now returns 200 with the real `index.html`
+(previously 404), static JS/CSS assets and the token-authenticated
+`/api/v1/graph` endpoint both 200, and `dataflow export --format html`
+exits 0 and writes a real self-contained report (previously exited 2).
+`dpia`/`ropa` export formats were already unaffected (a separate,
+already-self-contained code path) and are unchanged.
+
 ## 0.147.0 — Documentation overhaul: a cohesive assurance-platform story, verified against the shipped code
 
 The 0.144.0 Assurance Hardening release shipped a real 3-state ship verdict,

package/dist/1122.index.js

@@ -232,7 +232,12 @@ function export_image_validTimeoutMs(raw, fallback) {
   if (!Number.isSafeInteger(n) || n < 0 || Object.is(n, -0)) return fallback;
   return n;
 }
-const RENDER_TIMEOUT_MS = export_image_validTimeoutMs(process.env.AGENTIC_SECURITY_CHROME_RENDER_TIMEOUT_MS, 15000);
+// 15000 (the original default) left no headroom: the v0.147.0 release run
+// took 7983ms for this same render on a good draw of the CI runner, and the
+// v0.147.1 run timed out at ~15000ms on a slower draw — a 2x runner-speed
+// swing entirely within normal GitHub Actions variance, not a regression.
+// 30000 gives ~4x headroom over the observed good-case time.
+const RENDER_TIMEOUT_MS = export_image_validTimeoutMs(process.env.AGENTIC_SECURITY_CHROME_RENDER_TIMEOUT_MS, 30000);
 
 function _writeTempHtml(graph, opts) {
   const html = (0,generate_html_report.generateHtmlReport)(graph, opts);
@@ -592,6 +597,8 @@ function bundleFrontendModules(entryAbsPath) {
 
 // EXTERNAL MODULE: ./src/lineage/export-json.js
 var export_json = __webpack_require__(859);
+// EXTERNAL MODULE: ./src/shared/frontend-root.js
+var frontend_root = __webpack_require__(1185);
 ;// CONCATENATED MODULE: ./scripts/generate-html-report.mjs
 // generate-html-report.mjs — Milestone 4, sub-project Self-contained
 // HTML report. Assembles ONE offline-safe HTML document: inline CSS,
@@ -605,8 +612,14 @@ var export_json = __webpack_require__(859);
 
 
 
+
 const HERE = external_node_path_.dirname((0,external_node_url_.fileURLToPath)(import.meta.url));
-const FRONTEND_ROOT = external_node_path_.resolve(HERE, '../../frontend');
+// See src/shared/frontend-root.js: a hardcoded `../../frontend` resolved
+// correctly for this file's unbundled dev location (scanner/scripts/) but
+// broke for the published package, whose build now copies frontend/ into
+// scanner/dist/frontend/ — a different relative depth from this same
+// module once ncc bundles it into a dist/ chunk.
+const FRONTEND_ROOT = (0,frontend_root/* resolveFrontendRoot */.D)(HERE);
 const STYLES_DIR = external_node_path_.join(FRONTEND_ROOT, 'styles');
 const ENTRY_PATH = external_node_path_.join(FRONTEND_ROOT, 'src', 'export-entry.js');
 
@@ -697,6 +710,70 @@ ${bundledJs}
 }
 
 
+/***/ }),
+
+/***/ 1185:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   D: () => (/* binding */ resolveFrontendRoot)
+/* harmony export */ });
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3024);
+/* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6760);
+// frontend-root.js — locates the Data Flow Explorer's `frontend/` assets
+// (index.html/src/styles) regardless of whether this code is running:
+//   - unbundled, straight out of scanner/src/ or scanner/scripts/ (dev/test —
+//     frontend/ is a monorepo sibling of scanner/, 2-3 levels up), or
+//   - bundled by `npm run build` (ncc splits a dynamic import() into its own
+//     chunk file physically written into scanner/dist/, so import.meta.url
+//     inside that chunk reflects dist/'s own location, not the original
+//     source file's — a fixed relative-levels-up path that was correct for
+//     one depth breaks silently at the other), or
+//   - installed from the published npm package, where the build copies
+//     frontend/'s servable files into scanner/dist/frontend/ (a sibling of
+//     the chunk file itself, i.e. 0 levels up) — see scripts/copy-frontend.mjs.
+//
+// Rather than hardcode one of those depths (the bug this file fixes: every
+// consumer used to hardcode the dev-only depth), search upward from the
+// caller's own directory and take the first candidate that actually has a
+// frontend/index.html on disk. Never guessed silently past that — a caller
+// with no match anywhere gets a clear, actionable error instead of a
+// downstream ENOENT/404 with no indication why.
+
+
+
+
+const MAX_LEVELS_UP = 4;
+
+/**
+ * @param {string} startDir - `path.dirname(fileURLToPath(import.meta.url))`
+ *   of the CALLING module (not this file) — each caller's own bundled/
+ *   unbundled location determines which candidate depth resolves.
+ * @returns {string} absolute path to a real `frontend/` directory containing
+ *   `index.html`.
+ * @throws if no candidate directory up to MAX_LEVELS_UP contains one.
+ */
+function resolveFrontendRoot(startDir) {
+  const tried = [];
+  for (let up = 0; up <= MAX_LEVELS_UP; up++) {
+    const candidate = node_path__WEBPACK_IMPORTED_MODULE_1__.resolve(startDir, ...Array(up).fill('..'), 'frontend');
+    tried.push(candidate);
+    // Every caller invokes resolveFrontendRoot() once, at module-load time,
+    // to compute a top-level FRONTEND_ROOT const (see static-assets.js /
+    // generate-html-report.mjs) — never per-request inside the explore
+    // server's request handler. At most MAX_LEVELS_UP+1 (5) sync stat calls
+    // at process startup is not a request-path DoS surface.
+    if (node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(node_path__WEBPACK_IMPORTED_MODULE_1__.join(candidate, 'index.html'))) return candidate; // agentic-security-ignore: dos-sync-io
+  }
+  throw new Error(
+    `resolveFrontendRoot: no frontend/index.html found searching up from ${startDir}. ` +
+    `Tried: ${tried.join(', ')}. If you're running from a source checkout, run \`npm run build\` ` +
+    `first (it copies frontend/ into scanner/dist/frontend/); if you're running the published ` +
+    `package, this indicates a packaging defect — report it.`
+  );
+}
+
+
 /***/ })
 
 };

package/dist/3180.index.js

@@ -197,6 +197,8 @@ function bundleFrontendModules(entryAbsPath) {
 
 // EXTERNAL MODULE: ./src/lineage/export-json.js
 var export_json = __webpack_require__(859);
+// EXTERNAL MODULE: ./src/shared/frontend-root.js
+var frontend_root = __webpack_require__(1185);
 ;// CONCATENATED MODULE: ./scripts/generate-html-report.mjs
 // generate-html-report.mjs — Milestone 4, sub-project Self-contained
 // HTML report. Assembles ONE offline-safe HTML document: inline CSS,
@@ -210,8 +212,14 @@ var export_json = __webpack_require__(859);
 
 
 
+
 const HERE = external_node_path_.dirname((0,external_node_url_.fileURLToPath)(import.meta.url));
-const FRONTEND_ROOT = external_node_path_.resolve(HERE, '../../frontend');
+// See src/shared/frontend-root.js: a hardcoded `../../frontend` resolved
+// correctly for this file's unbundled dev location (scanner/scripts/) but
+// broke for the published package, whose build now copies frontend/ into
+// scanner/dist/frontend/ — a different relative depth from this same
+// module once ncc bundles it into a dist/ chunk.
+const FRONTEND_ROOT = (0,frontend_root/* resolveFrontendRoot */.D)(HERE);
 const STYLES_DIR = external_node_path_.join(FRONTEND_ROOT, 'styles');
 const ENTRY_PATH = external_node_path_.join(FRONTEND_ROOT, 'src', 'export-entry.js');
 
@@ -302,6 +310,70 @@ ${bundledJs}
 }
 
 
+/***/ }),
+
+/***/ 1185:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   D: () => (/* binding */ resolveFrontendRoot)
+/* harmony export */ });
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3024);
+/* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6760);
+// frontend-root.js — locates the Data Flow Explorer's `frontend/` assets
+// (index.html/src/styles) regardless of whether this code is running:
+//   - unbundled, straight out of scanner/src/ or scanner/scripts/ (dev/test —
+//     frontend/ is a monorepo sibling of scanner/, 2-3 levels up), or
+//   - bundled by `npm run build` (ncc splits a dynamic import() into its own
+//     chunk file physically written into scanner/dist/, so import.meta.url
+//     inside that chunk reflects dist/'s own location, not the original
+//     source file's — a fixed relative-levels-up path that was correct for
+//     one depth breaks silently at the other), or
+//   - installed from the published npm package, where the build copies
+//     frontend/'s servable files into scanner/dist/frontend/ (a sibling of
+//     the chunk file itself, i.e. 0 levels up) — see scripts/copy-frontend.mjs.
+//
+// Rather than hardcode one of those depths (the bug this file fixes: every
+// consumer used to hardcode the dev-only depth), search upward from the
+// caller's own directory and take the first candidate that actually has a
+// frontend/index.html on disk. Never guessed silently past that — a caller
+// with no match anywhere gets a clear, actionable error instead of a
+// downstream ENOENT/404 with no indication why.
+
+
+
+
+const MAX_LEVELS_UP = 4;
+
+/**
+ * @param {string} startDir - `path.dirname(fileURLToPath(import.meta.url))`
+ *   of the CALLING module (not this file) — each caller's own bundled/
+ *   unbundled location determines which candidate depth resolves.
+ * @returns {string} absolute path to a real `frontend/` directory containing
+ *   `index.html`.
+ * @throws if no candidate directory up to MAX_LEVELS_UP contains one.
+ */
+function resolveFrontendRoot(startDir) {
+  const tried = [];
+  for (let up = 0; up <= MAX_LEVELS_UP; up++) {
+    const candidate = node_path__WEBPACK_IMPORTED_MODULE_1__.resolve(startDir, ...Array(up).fill('..'), 'frontend');
+    tried.push(candidate);
+    // Every caller invokes resolveFrontendRoot() once, at module-load time,
+    // to compute a top-level FRONTEND_ROOT const (see static-assets.js /
+    // generate-html-report.mjs) — never per-request inside the explore
+    // server's request handler. At most MAX_LEVELS_UP+1 (5) sync stat calls
+    // at process startup is not a request-path DoS surface.
+    if (node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(node_path__WEBPACK_IMPORTED_MODULE_1__.join(candidate, 'index.html'))) return candidate; // agentic-security-ignore: dos-sync-io
+  }
+  throw new Error(
+    `resolveFrontendRoot: no frontend/index.html found searching up from ${startDir}. ` +
+    `Tried: ${tried.join(', ')}. If you're running from a source checkout, run \`npm run build\` ` +
+    `first (it copies frontend/ into scanner/dist/frontend/); if you're running the published ` +
+    `package, this indicates a packaging defect — report it.`
+  );
+}
+
+
 /***/ })
 
 };

package/dist/5051.index.js

@@ -25,6 +25,8 @@ var security = __webpack_require__(6944);
 var routes = __webpack_require__(4268);
 // EXTERNAL MODULE: external "node:url"
 var external_node_url_ = __webpack_require__(3136);
+// EXTERNAL MODULE: ./src/shared/frontend-root.js
+var frontend_root = __webpack_require__(1185);
 ;// CONCATENATED MODULE: ./src/server/static-assets.js
 // static-assets.js — Milestone 3, sub-project Wire.
 //
@@ -43,13 +45,18 @@ var external_node_url_ = __webpack_require__(3136);
 
 
 
-// Located the SAME way scanner/src/mcp/server.js locates files relative to
-// its own module (path.dirname(fileURLToPath(import.meta.url))) — the real,
-// existing precedent for this pattern in this codebase, not a new one.
-// scanner/src/server/ -> ../../../frontend, computed (not guessed) and
-// confirmed to resolve to the real frontend/ directory.
+
+// Located relative to this module's own directory (path.dirname(
+// fileURLToPath(import.meta.url)), the same pattern scanner/src/mcp/server.js
+// uses), but via resolveFrontendRoot's search-upward strategy rather than a
+// single hardcoded relative depth — a fixed `../../../frontend` resolved
+// correctly for this file's unbundled dev location but broke (silently, at
+// runtime, for every real npx/npm user) once `npm run build` split this
+// module into its own dist/ chunk, whose import.meta.url reflects dist/'s
+// own shallower location. See src/shared/frontend-root.js for the full story
+// and scripts/copy-frontend.mjs for the build-time copy this now finds.
 const _here = external_node_path_.dirname((0,external_node_url_.fileURLToPath)(import.meta.url));
-const FRONTEND_ROOT = external_node_path_.resolve(_here, '..', '..', '..', 'frontend');
+const FRONTEND_ROOT = (0,frontend_root/* resolveFrontendRoot */.D)(_here);
 
 const CONTENT_TYPE_MAP = Object.freeze({
   '.html': 'text/html; charset=utf-8',
@@ -765,6 +772,70 @@ function isValidHost(hostHeader, expectedPort) {
 const CSP_HEADER_VALUE = "default-src 'none'; frame-ancestors 'none'";
 
 
+/***/ }),
+
+/***/ 1185:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   D: () => (/* binding */ resolveFrontendRoot)
+/* harmony export */ });
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3024);
+/* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6760);
+// frontend-root.js — locates the Data Flow Explorer's `frontend/` assets
+// (index.html/src/styles) regardless of whether this code is running:
+//   - unbundled, straight out of scanner/src/ or scanner/scripts/ (dev/test —
+//     frontend/ is a monorepo sibling of scanner/, 2-3 levels up), or
+//   - bundled by `npm run build` (ncc splits a dynamic import() into its own
+//     chunk file physically written into scanner/dist/, so import.meta.url
+//     inside that chunk reflects dist/'s own location, not the original
+//     source file's — a fixed relative-levels-up path that was correct for
+//     one depth breaks silently at the other), or
+//   - installed from the published npm package, where the build copies
+//     frontend/'s servable files into scanner/dist/frontend/ (a sibling of
+//     the chunk file itself, i.e. 0 levels up) — see scripts/copy-frontend.mjs.
+//
+// Rather than hardcode one of those depths (the bug this file fixes: every
+// consumer used to hardcode the dev-only depth), search upward from the
+// caller's own directory and take the first candidate that actually has a
+// frontend/index.html on disk. Never guessed silently past that — a caller
+// with no match anywhere gets a clear, actionable error instead of a
+// downstream ENOENT/404 with no indication why.
+
+
+
+
+const MAX_LEVELS_UP = 4;
+
+/**
+ * @param {string} startDir - `path.dirname(fileURLToPath(import.meta.url))`
+ *   of the CALLING module (not this file) — each caller's own bundled/
+ *   unbundled location determines which candidate depth resolves.
+ * @returns {string} absolute path to a real `frontend/` directory containing
+ *   `index.html`.
+ * @throws if no candidate directory up to MAX_LEVELS_UP contains one.
+ */
+function resolveFrontendRoot(startDir) {
+  const tried = [];
+  for (let up = 0; up <= MAX_LEVELS_UP; up++) {
+    const candidate = node_path__WEBPACK_IMPORTED_MODULE_1__.resolve(startDir, ...Array(up).fill('..'), 'frontend');
+    tried.push(candidate);
+    // Every caller invokes resolveFrontendRoot() once, at module-load time,
+    // to compute a top-level FRONTEND_ROOT const (see static-assets.js /
+    // generate-html-report.mjs) — never per-request inside the explore
+    // server's request handler. At most MAX_LEVELS_UP+1 (5) sync stat calls
+    // at process startup is not a request-path DoS surface.
+    if (node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(node_path__WEBPACK_IMPORTED_MODULE_1__.join(candidate, 'index.html'))) return candidate; // agentic-security-ignore: dos-sync-io
+  }
+  throw new Error(
+    `resolveFrontendRoot: no frontend/index.html found searching up from ${startDir}. ` +
+    `Tried: ${tried.join(', ')}. If you're running from a source checkout, run \`npm run build\` ` +
+    `first (it copies frontend/ into scanner/dist/frontend/); if you're running the published ` +
+    `package, this indicates a packaging defect — report it.`
+  );
+}
+
+
 /***/ })
 
 };

package/dist/frontend/index.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Data Flow Explorer — Illustrative demo data</title>
+  <link rel="stylesheet" href="styles/tokens.css" />
+  <link rel="stylesheet" href="styles/shell.css" />
+  <link rel="stylesheet" href="styles/architecture-view.css" />
+  <link rel="stylesheet" href="styles/inspector.css" />
+  <link rel="stylesheet" href="styles/privacy-view.css" />
+  <link rel="stylesheet" href="styles/trace-view.css" />
+  <link rel="stylesheet" href="styles/filter-rail.css" />
+  <link rel="stylesheet" href="styles/inventory-view.css" />
+  <link rel="stylesheet" href="styles/query-bar.css" />
+</head>
+<body>
+  <div id="app-root"></div>
+  <script type="module" src="./src/main.js"></script>
+</body>
+</html>

package/dist/frontend/src/app.js

@@ -0,0 +1,176 @@
+import { mountShell, buildContextRailText } from './shell.js';
+import { computeArchitectureViewModel, renderArchitectureView, renderFlowSummary } from './views/architecture-view.js';
+import { computePrivacyViewModel, renderPrivacyView } from './views/privacy-view.js';
+import { computeTraceViewModel, renderTraceView } from './views/trace-view.js';
+import { computeInventoryViewModel, renderInventoryView } from './views/inventory-view.js';
+import { computeInspectorViewModel, renderInspector } from './components/evidence-inspector.js';
+import { computeFilterFacets, renderFilterRail } from './components/filter-rail.js';
+import { computeQueryBarViewModel, renderQueryBar, compileQuerySafely } from './components/query-bar.js';
+import {
+  showUpstream, showDownstream, showAllPaths, showShortestPath,
+  showExternalPathsOnly, showUnprotectedPathsOnly, showAliases, showDisconnected,
+} from './lib/focus-controls.js';
+import { el, clear } from './lib/dom.js';
+
+// Milestone 3, sub-project M3-UX-Query, Task 4's own resolution of the task
+// brief's Step 4 open design question: a focus control's own {nodeIds,
+// edgeIds} result (from lib/focus-controls.js) has no single canonical
+// `selectedId` to thread through the existing shell.js state mechanism, and
+// is real-but-transient UI state (not meaningfully shareable — it holds
+// Sets, which don't serialize to the URL hash cleanly), matching the same
+// precedent A11y's own `inspectorOverlayOpen` and M3-Render's own
+// `currentViewport` already established: module-local state, not persisted.
+// Lives here (app.js), the one place that already orchestrates every view's
+// own compute/render call, rather than inside architecture-view.js itself.
+let currentFocusSelection = null;
+
+const FOCUS_CONTROLS = [
+  { id: 'upstream', label: 'Show upstream', needsNode: true, run: (graph, anchor) => showUpstream(graph, anchor.nodeId) },
+  { id: 'downstream', label: 'Show downstream', needsNode: true, run: (graph, anchor) => showDownstream(graph, anchor.nodeId) },
+  { id: 'all-paths', label: 'Show all paths', needsNode: true, run: (graph, anchor) => showAllPaths(graph, anchor.nodeId) },
+  { id: 'shortest-path', label: 'Show shortest path', needsEdge: true, run: (graph, anchor) => showShortestPath(graph, anchor.edge.from, anchor.edge.to) },
+  { id: 'external-only', label: 'Show external paths only', run: (graph) => showExternalPathsOnly(graph) },
+  { id: 'unprotected-only', label: 'Show unprotected paths only', run: (graph) => showUnprotectedPathsOnly(graph) },
+  { id: 'aliases', label: 'Show aliases', needsNode: true, run: (graph, anchor) => showAliases(graph, anchor.nodeId) },
+  { id: 'disconnected', label: 'Show disconnected', run: (graph) => showDisconnected(graph) },
+  // resetToOverview is deliberately NOT a lib/focus-controls.js function
+  // (per that file's own header note) — it is implemented here directly:
+  // clear the focus override AND the underlying single selection.
+  { id: 'reset', label: 'Reset to application overview', isReset: true },
+];
+
+// Determines which node/edge a focus control acts on for the CURRENT
+// selection. A directly-selected NODE is its own anchor. A directly-
+// selected EDGE carries both endpoints, used only by "Show shortest path"
+// (the one control that genuinely needs two nodes). A directly-selected
+// FLOW has no single node id of its own, so its own source node is used as
+// a reasonable "origin" anchor — a real, disclosed scoping choice, not an
+// oversight (the query language and focus controls are both real DSLs over
+// this graph, but a flow selection's own node-shaped controls have to pick
+// SOME node, and the flow's source is the least arbitrary choice available).
+function resolveFocusAnchor(graph, state) {
+  if (!state.selectedId) return null;
+  const node = graph.nodes.find((n) => n.id === state.selectedId);
+  if (node) return { nodeId: node.id, edge: null };
+  const edge = graph.edges.find((e) => e.id === state.selectedId);
+  if (edge) return { nodeId: edge.from, edge };
+  const flow = graph.flows.find((f) => f.id === state.selectedId);
+  if (flow) return { nodeId: flow.source, edge: null };
+  return null;
+}
+
+// Appends the focus-control button group into an already-populated context
+// rail (the architecture-view.js's own renderFlowSummary(), or the shell's
+// plain textContent fallback, has already run and populated it — this
+// APPENDS, it never clears). Only rendered on Architecture View, since a
+// focus selection's {nodeIds, edgeIds} only has a visible effect there
+// (computeArchitectureViewModel's own new 3rd parameter). Gated on there
+// being an active selection at all, matching the task brief's own wording
+// ("offering the 9 named controls when a node/flow is selected").
+function renderFocusControlMenu(graph, state, contextRailEl, shellApi, rerender) {
+  const anchor = resolveFocusAnchor(graph, state);
+  if (!anchor && !currentFocusSelection) return;
+
+  const buttons = FOCUS_CONTROLS.filter((control) => {
+    if (control.isReset) return true;
+    if (control.needsEdge) return Boolean(anchor?.edge);
+    if (control.needsNode) return Boolean(anchor?.nodeId);
+    return true; // graph-wide controls (external/unprotected/disconnected) need no anchor
+  }).map((control) =>
+    el(
+      'button',
+      {
+        class: 'focus-control-menu__button',
+        type: 'button',
+        'data-focus-control': control.id,
+        onClick: () => {
+          if (control.isReset) {
+            currentFocusSelection = null;
+            shellApi.setSelection(null); // notifies onStateChange, which re-invokes rerender itself
+            return;
+          }
+          currentFocusSelection = control.run(graph, anchor);
+          rerender();
+        },
+      },
+      control.label,
+    ),
+  );
+
+  contextRailEl.appendChild(el('div', { class: 'focus-control-menu' }, buttons));
+}
+
+export function bootstrap(rootEl, graph) {
+  const shellApi = mountShell(rootEl, graph);
+  const filterFacets = computeFilterFacets(graph);
+
+  // Any NEW single-item selection made through an EXISTING selection path
+  // (a node/edge click on Architecture View, a Privacy/Trace/Inventory row
+  // click) must clear a stale focus-control override — otherwise a user
+  // could click "Show upstream" and then click an unrelated node, and see
+  // the OLD focus set still applied instead of the new plain selection.
+  function selectAndClearFocus(id) {
+    currentFocusSelection = null;
+    shellApi.setSelection(id);
+  }
+
+  function rerender() {
+    const state = shellApi.getState();
+
+    const queryBarViewModel = computeQueryBarViewModel(state);
+    let queryPredicate = () => true;
+    if (!queryBarViewModel.error) {
+      const compiled = compileQuerySafely(graph, state.filters?.query ?? '');
+      queryPredicate = compiled.predicate;
+      // A syntax-clean query can still fail at evaluation time (an
+      // unrecognized field name, thrown by query-language.js's own
+      // evaluateNode — see compileQuerySafely's own comment). Surface that
+      // the same way a syntax error is surfaced, rather than silently
+      // falling back to "no filter" with no visible explanation.
+      if (compiled.error) queryBarViewModel.error = compiled.error;
+    }
+    renderQueryBar(queryBarViewModel, shellApi.getQueryBarEl(), (nextQuery) => {
+      shellApi.setFilters({ ...(state.filters ?? {}), query: nextQuery });
+    });
+
+    if (state.view === 'architecture') {
+      const viewModel = computeArchitectureViewModel(graph, state, currentFocusSelection);
+      renderArchitectureView(viewModel, shellApi.getCanvasEl(), selectAndClearFocus);
+      const contextRailEl = shellApi.getContextRailEl();
+      if (viewModel.flowSummary) {
+        renderFlowSummary(viewModel.flowSummary, contextRailEl);
+      } else {
+        clear(contextRailEl);
+        contextRailEl.textContent = buildContextRailText(graph);
+      }
+      renderFocusControlMenu(graph, state, contextRailEl, shellApi, rerender);
+    } else if (state.view === 'privacy') {
+      const viewModel = computePrivacyViewModel(graph, state, queryPredicate);
+      renderPrivacyView(viewModel, shellApi.getCanvasEl(), selectAndClearFocus);
+      shellApi.getContextRailEl().textContent = buildContextRailText(graph);
+    } else if (state.view === 'trace') {
+      const viewModel = computeTraceViewModel(graph, state);
+      renderTraceView(viewModel, shellApi.getCanvasEl(), selectAndClearFocus);
+      shellApi.getContextRailEl().textContent = buildContextRailText(graph);
+    } else if (state.view === 'inventory') {
+      const viewModel = computeInventoryViewModel(graph, state, queryPredicate);
+      renderInventoryView(viewModel, shellApi.getCanvasEl(), selectAndClearFocus, (tableId) => shellApi.setTable(tableId));
+      shellApi.getContextRailEl().textContent = buildContextRailText(graph);
+    }
+
+    const inspectorViewModel = computeInspectorViewModel(graph, state.selectedId);
+    renderInspector(inspectorViewModel, shellApi.getInspectorEl());
+
+    if (state.view === 'privacy' || state.view === 'inventory') {
+      renderFilterRail(filterFacets, state.filters ?? {}, shellApi.getLeftRailEl(), (nextFilters) => shellApi.setFilters(nextFilters));
+    } else {
+      const railEl = shellApi.getLeftRailEl();
+      railEl.textContent = 'Filters apply to Privacy View and some Inventory tables.';
+    }
+  }
+
+  shellApi.onStateChange(rerender);
+  rerender();
+
+  return shellApi;
+}