@reqvire-org/ads 0.3.12 → 0.3.14

package/dist/verification.mjs

@@ -19,13 +19,55 @@ const slash = file => file.replaceAll("\\", "/");
 const resultFile = root => path.join(root, ".ds/behavior-results.json");
 
 /** Follow real project imports; package/configuration changes also invalidate evidence. */
-function inputContext(options) { return { inventory: inspectUnits(options), scenarios: inspectScenarios(options).scenarios }; }
+function inputContext(options) {
+  const sources = new Map(), digests = new Map(), packages = new Map(), resolve = importResolver(options), resolutions = new Map();
+  return { inventory: inspectUnits(options), scenarios: inspectScenarios(options).scenarios,
+    seeds: [...configurationFiles(options)].map(file => path.join(options.root, file)).concat(sourceFiles(path.join(options.dsRoot, options.config.tokenDir)), path.join(options.dsRoot, options.config.stylesEntry)),
+    digest(file) { if (!digests.has(file)) digests.set(file, hash(readFileSync(file))); return digests.get(file); },
+    ast(file) { if (!sources.has(file)) sources.set(file, ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true)); return sources.get(file); },
+    resolve(specifier, file) { const key = `${file}\0${specifier}`; if (!resolutions.has(key)) resolutions.set(key, resolve(specifier, file)); return resolutions.get(key); },
+    hasSideEffects(file, record) {
+      let directory = path.dirname(file);
+      while (isInside(options.root, directory)) {
+        const manifest = path.join(directory, "package.json");
+        if (existsSync(manifest)) {
+          record(manifest);
+          if (!packages.has(manifest)) { try { packages.set(manifest, JSON.parse(readFileSync(manifest, "utf8")).sideEffects); } catch { packages.set(manifest, true); } }
+          const policy = packages.get(manifest), relative = slash(path.relative(directory, file));
+          if (policy === false) return false;
+          // Only the simple package sideEffects glob subset is narrowed. Unknown
+          // syntax and undeclared policies preserve the entire dependency graph.
+          if (!Array.isArray(policy) || policy.some(pattern => typeof pattern !== "string" || !/^[\w./*?-]+$/.test(pattern))) return true;
+          return policy.some(pattern => {
+            pattern = pattern.replace(/^\.\//, ""); if (!pattern.includes("/")) pattern = `**/${pattern}`;
+            const expression = pattern.match(/\*\*\/|\*\*|\*|\?|[^*?]+/g)?.map(part => part === "**/" ? "(?:.*/)?" : part === "**" ? ".*" : part === "*" ? "[^/]*" : part === "?" ? "[^/]" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("");
+            return new RegExp(`^${expression}$`).test(relative);
+          });
+        }
+        directory = path.dirname(directory);
+      }
+      return true;
+    },
+  };
+}
 
 export function behaviorInputs(options, contract, check, context = inputContext(options)) {
-  const files = new Set(), resolve = importResolver(options);
-  function visit(file) {
+  const files = new Set(), demands = new Map(), effectsVisited = new Set();
+  const resolve = context.resolve;
+  function effects(file) {
+    if (effectsVisited.has(file) || !isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    effectsVisited.add(file);
+    if (context.hasSideEffects(file, visit)) { visit(file); return; }
+    if (!/\.[cm]?[jt]sx?$/.test(file) || !lstatSync(file).isFile()) return;
+    if (lstatSync(file).isSymbolicLink() || realpathSync(file) !== file) throw new Error(`Behavior inputs cannot resolve through symlinks: ${file}`);
+    for (const statement of context.ast(file).statements) if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier)) for (const target of resolve(statement.moduleSpecifier.text, file)) effects(target);
+  }
+  function visit(file, names = null) {
     file = path.resolve(file);
-    if (files.has(file) || !isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    if (!isInside(options.root, file) || file.includes(`${path.sep}node_modules${path.sep}`) || !existsSync(file)) return;
+    const prior = demands.get(file);
+    if (demands.has(file) && (prior === null || names && names.every(name => prior.has(name)))) return;
+    demands.set(file, names === null ? null : new Set([...(prior ?? []), ...names]));
     if (lstatSync(file).isSymbolicLink() || realpathSync(file) !== file) throw new Error(`Behavior inputs cannot resolve through symlinks: ${file}`);
     if (!lstatSync(file).isFile()) return;
     files.add(file);
@@ -39,12 +81,31 @@ export function behaviorInputs(options, contract, check, context = inputContext(
       css.walk(node => { if (node.type === "decl" || node.type === "atrule") valueParser(node.type === "decl" ? node.value : node.params).walk(value => { if (value.type === "function" && value.value.toLowerCase() === "url") localAsset(value.nodes.filter(part => part.type !== "space").map(part => part.value).join("")); }); });
     }
     if (!/\.[cm]?[jt]sx?$/.test(file)) return;
-    const ast = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+    const ast = context.ast(file);
+    const barrel = names && ast.statements.every(statement => ts.isEmptyStatement(statement) || ts.isImportDeclaration(statement) && !statement.importClause || ts.isExportDeclaration(statement) && (!statement.exportClause || ts.isNamedExports(statement.exportClause)) && (!statement.exportClause || !statement.exportClause.elements.length || statement.moduleSpecifier));
+    if (barrel) {
+      for (const statement of ast.statements) {
+        if (!statement.moduleSpecifier || !ts.isStringLiteralLike(statement.moduleSpecifier)) continue;
+        for (const target of resolve(statement.moduleSpecifier.text, file)) {
+          if (ts.isImportDeclaration(statement) || !statement.exportClause) visit(target);
+          else {
+            const imported = statement.exportClause.elements.filter(entry => names.includes(entry.name.text)).map(entry => (entry.propertyName ?? entry.name).text);
+            if (imported.length) visit(target, imported);
+            effects(target);
+          }
+        }
+      }
+      return;
+    }
     function walk(node) {
       let specifier;
       if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) specifier = node.moduleSpecifier.text;
       if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require") && node.arguments[0] && ts.isStringLiteralLike(node.arguments[0])) specifier = node.arguments[0].text;
-      if (specifier) for (const target of resolve(specifier, file)) visit(target);
+      if (specifier) {
+        const clause = ts.isImportDeclaration(node) && node.importClause;
+        const names = clause && !clause.namedBindings ? clause.name ? ["default"] : null : clause?.namedBindings && ts.isNamedImports(clause.namedBindings) ? [...(clause.name ? ["default"] : []), ...clause.namedBindings.elements.map(entry => (entry.propertyName ?? entry.name).text)] : null;
+        for (const target of resolve(specifier, file)) visit(target, names);
+      }
       if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "URL" && node.arguments?.[0] && ts.isStringLiteralLike(node.arguments[0])) localAsset(node.arguments[0].text);
       if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && (!node.arguments[0] || !ts.isStringLiteralLike(node.arguments[0]))) {
         // Computed module selection cannot provide a precise dependency closure.
@@ -56,13 +117,11 @@ export function behaviorInputs(options, contract, check, context = inputContext(
     walk(ast);
   }
   for (const file of context.inventory.units.find(unit => unit.id === contract.unit)?.files ?? []) visit(path.join(options.root, file));
-  for (const file of configurationFiles(options)) visit(path.join(options.root, file));
-  for (const file of sourceFiles(path.join(options.dsRoot, options.config.tokenDir))) visit(file);
-  visit(path.join(options.dsRoot, options.config.stylesEntry));
+  for (const file of context.seeds) visit(file);
   const scenario = check.scenario && context.scenarios.find(item => item.id === check.scenario);
   if (scenario) visit(path.join(options.root, scenario.file));
-  const rows = [...files].sort().map(file => [slash(path.relative(options.root, file)), hash(readFileSync(file))]);
-  for (const file of ["package-lock.json", "bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock", "node_modules/.package-lock.json"]) rows.push([file, existsSync(path.join(options.root, file)) ? hash(readFileSync(path.join(options.root, file))) : null]);
+  const rows = [...files].sort().map(file => [slash(path.relative(options.root, file)), context.digest(file)]);
+  for (const file of ["package-lock.json", "bun.lock", "bun.lockb", "pnpm-lock.yaml", "yarn.lock", "node_modules/.package-lock.json"]) rows.push([file, existsSync(path.join(options.root, file)) ? context.digest(path.join(options.root, file)) : null]);
   rows.push(["profile", JSON.stringify(options.config.mcp.behaviorProfiles[check.profile])], ["node", process.version]);
   for (const file of ["./verification.mjs", "./verification/browser.mjs", "./verification/playwright-reporter.cjs"]) rows.push([`tool:${file}`, hash(readFileSync(new URL(file, import.meta.url)))]);
   return { revision: hash(JSON.stringify(rows)), files: rows.map(([file]) => file) };
@@ -104,9 +163,11 @@ export function affectedBehaviorUnits(options, changedFiles) {
   return contracts.filter(contract => Object.values(contract.checks).some(check => behaviorInputs(options, contract, check, context).files.some(file => changed.has(file)))).map(contract => contract.unit);
 }
 
-function execute(profile, args, root, env, signal) {
+export function executeDevelopmentCommand(profile, args, root, env, signal) {
   return new Promise((resolve, reject) => {
-    if (signal.aborted) { reject(new Error("Behavior verification cancelled.")); return; }
+    const label = profile.label ?? "Behavior verification";
+    if (signal.aborted) { reject(new Error(`${label} cancelled.`)); return; }
+    const startedAt = Date.now(), timeoutMs = profile.timeoutMs ?? 60000;
     let output = "", failure, child, guard, done = false;
     const kill = () => {
       if (!child?.pid) return;
@@ -121,28 +182,47 @@ function execute(profile, args, root, env, signal) {
       guard.once("error", error => { failure = error; kill(); });
       guard.once("exit", () => { if (!done) { failure ??= new Error("Verification ownership guard exited unexpectedly."); kill(); } });
     }
-    const abort = () => { failure = new Error("Behavior verification cancelled."); kill(); };
+    const abort = () => { failure = Object.assign(new Error(`${label} cancelled.`), { reason: "cancelled" }); kill(); };
     signal.addEventListener("abort", abort, { once: true });
-    const timeout = setTimeout(() => { failure = new Error("Behavior verification timed out. Inspect the registered runner and its browser/server cleanup."); kill(); }, profile.timeoutMs ?? 60000);
+    const timeout = setTimeout(() => { failure = Object.assign(new Error(`${label} timed out after ${timeoutMs} ms for the complete profile run, not each check.`), { reason: "timeout", timeoutMs }); kill(); }, timeoutMs);
     for (const stream of [child.stdout, child.stderr]) stream.on("data", chunk => { output = (output + chunk.toString()).slice(-12000); });
     child.once("error", error => { failure = error; });
     child.once("exit", kill);
     child.once("close", code => {
       done = true; kill(); guard?.stdin.end("disarm\n"); clearTimeout(timeout); signal.removeEventListener("abort", abort);
-      if (failure) reject(Object.assign(failure, { output }));
-      else resolve({ code, output });
+      const elapsedMs = Date.now() - startedAt;
+      if (failure) reject(Object.assign(failure, { output, elapsedMs }));
+      else resolve({ code, output, elapsedMs });
     });
   });
 }
 
+function readReport(file, runId) {
+  if (!existsSync(file) || realpathSync(file) !== file || !lstatSync(file).isFile() || lstatSync(file).size > 1024 * 1024) throw new Error("Runner produced no valid bounded verification report. A successful exit alone is not passing evidence.");
+  const value = JSON.parse(readFileSync(file, "utf8"));
+  if (value.schemaVersion !== 1 || value.runId !== runId || !Array.isArray(value.cases) || value.cases.length > 500 || value.active !== undefined && (!Array.isArray(value.active) || value.active.length > 100)) throw new Error("Runner report has the wrong run ID/schema or too many cases.");
+  return value;
+}
+
+function runProgress(group, report, startedAt, profile, timeoutMs) {
+  const selected = group.map(check => ({ unit: check.unit, check: check.id, id: check.case, file: slash(path.posix.join(path.posix.dirname(slash(check.contract.file)), check.file)) }));
+  const cases = selected.map(check => {
+    const matches = report?.cases.filter(item => item?.id === check.id && item.file === check.file) ?? [];
+    const running = report?.active?.find(item => item?.id === check.id && item.file === check.file);
+    return { unit: check.unit, check: check.check, state: running ? "running" : matches.length ? "completed" : Array.isArray(report?.active) ? "not_started" : "not_reported", ...(running ? { elapsedMs: Math.max(0, Date.now() - Date.parse(running.startedAt)) || 0, workerIndex: running.workerIndex } : {}), ...(matches.length ? { reportedStatus: matches.at(-1).status, durationMs: matches.reduce((sum, item) => sum + (Number.isFinite(item.durationMs) ? Math.max(0, item.durationMs) : 0), 0) } : {}) };
+  });
+  return { profile, elapsedMs: Date.now() - startedAt, timeoutMs, total: cases.length, completed: cases.filter(item => item.state === "completed").length, active: cases.filter(item => item.state === "running"), pending: cases.filter(item => ["not_started", "not_reported"].includes(item.state)).length, cases, ...(Number.isSafeInteger(report?.workers) ? { workers: report.workers } : {}) };
+}
+
 /** Registered development commands are trusted project code, never model-supplied commands. */
-export function createVerificationController(root) {
+export function createVerificationController(root, { reportRoot = root, onProgress } = {}) {
   root = path.resolve(root);
-  let active;
+  reportRoot = path.resolve(reportRoot);
+  let active, progress;
   return {
-    status: () => ({ running: !!active }),
+    status: () => ({ running: !!active, ...(active && progress ? { progress: { ...progress, elapsedMs: Date.now() - progress.startedAt } } : {}) }),
     async close() { active?.abort(); await active?.completion; },
-    async run({ unit, units, checks, persist = true } = {}, signal) {
+    async run({ unit, units, checks, persist = true } = {}, signal, notifyProgress) {
       if (active) return { ok: false, diagnostics: [{ rule: "behavior-busy", message: "A behavior verification is already running." }], results: [] };
       active = new AbortController();
       const controller = active;
@@ -162,7 +242,7 @@ export function createVerificationController(root) {
         for (const profileName of new Set(selection.map(check => check.profile))) {
           const profile = options.config.mcp.behaviorProfiles[profileName];
           const group = selection.filter(check => check.profile === profileName);
-          const directory = path.join(root, ".ds/verification", randomUUID());
+          const directory = path.join(reportRoot, ".ds/verification", randomUUID());
           mkdirSync(directory, { recursive: true });
           if (realpathSync(directory) !== directory) throw new Error("Verification output cannot resolve through a symlink.");
           const runId = randomUUID(), report = path.join(directory, "report.json"), request = path.join(directory, "request.json");
@@ -179,31 +259,60 @@ export function createVerificationController(root) {
           const requestContext = { schemaVersion: 1, runId, projectRoot: root, framework: options.config.framework, profile: profileName, mode: profile.mode ?? "unit", checks: group.map(({ contract: _contract, ...check }) => check), scenarios };
           writeFileSync(request, JSON.stringify(requestContext));
           const args = [...profile.args];
-          if (profile.runner === "playwright") args.push(...new Set(group.map(check => slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file))))), `--reporter=${fileURLToPath(new URL("./verification/playwright-reporter.cjs", import.meta.url))}`, `--output=${path.join(directory, "artifacts")}`);
+          if (profile.runner === "playwright") {
+            const tags = [...new Set(group.map(check => check.case))].map(id => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+            args.push(...new Set(group.map(check => slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file))))), `--grep=(?:^|\\s)@ads:(?:${tags.join("|")})(?=\\s|$)`, `--reporter=${fileURLToPath(new URL("./verification/playwright-reporter.cjs", import.meta.url))}`, `--output=${path.join(directory, "artifacts")}`);
+          }
           let run, reportValue, runnerError;
+          const startedAt = Date.now();
+          const update = value => {
+            progress = { ...runProgress(group, value, startedAt, profileName, profile.timeoutMs ?? 60000), startedAt };
+            onProgress?.(progress); notifyProgress?.(progress);
+          };
+          update();
+          let lastSnapshot = "", lastUpdate = Date.now();
+          const monitor = setInterval(() => {
+            let value;
+            try { value = readReport(report, runId); } catch { /* An absent/invalid intermediate snapshot cannot provide evidence. */ }
+            const snapshot = JSON.stringify(value);
+            if (snapshot !== lastSnapshot || Date.now() - lastUpdate >= 5000) { lastSnapshot = snapshot; lastUpdate = Date.now(); update(value); }
+          }, 250);
           try {
-            run = await execute(profile, args, root, { ADS_VERIFY_REQUEST: request, ADS_VERIFY_REPORT: report, ADS_VERIFY_MODE: requestContext.mode }, signal);
-            if (!existsSync(report) || realpathSync(report) !== report || lstatSync(report).size > 1024 * 1024) throw new Error("Runner produced no valid bounded verification report. A successful exit alone is not passing evidence.");
-            reportValue = JSON.parse(readFileSync(report, "utf8"));
-            if (reportValue.schemaVersion !== 1 || reportValue.runId !== runId || !Array.isArray(reportValue.cases) || reportValue.cases.length > 500) throw new Error("Runner report has the wrong run ID/schema or too many cases.");
-          } catch (error) { runnerError = error; reportValue = undefined; diagnostics.push({ rule: "behavior-runner", message: error.message, output: error.output?.slice(-4000), profile: profileName }); }
+            run = await executeDevelopmentCommand(profile, args, root, { ADS_VERIFY_REQUEST: request, ADS_VERIFY_REPORT: report, ADS_VERIFY_MODE: requestContext.mode }, signal);
+          } catch (error) { runnerError = error; }
+          finally { clearInterval(monitor); }
+          try { reportValue = readReport(report, runId); }
+          catch (error) { runnerError ??= error; }
+          update(reportValue);
+          if (runnerError) {
+            const detail = `${progress.completed}/${progress.total} checks completed; ${progress.pending} without a completed/active result. Active: ${progress.active.map(item => `${item.unit}#${item.check} (${Math.round(item.elapsedMs)} ms)`).join(", ") || "none reported"}.`;
+            diagnostics.push({ rule: "behavior-runner", message: `${runnerError.message} ${detail}`, reason: runnerError.reason, elapsedMs: runnerError.elapsedMs ?? Date.now() - startedAt, progress, output: runnerError.output?.slice(-4000), profile: profileName });
+          }
           const suiteErrors = Array.isArray(reportValue?.errors) ? reportValue.errors.slice(0, 5).map(error => String(error).slice(0, 1000)) : [];
-          const runnerFailure = run && (run.code !== 0 || suiteErrors.length) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : "reported a suite error"}. ${suiteErrors.join("; ") || reportValue?.cases.filter(item => item?.status === "failed").slice(0, 3).map(item => `${item.id}: ${item.message || "failed without a case diagnostic"}`).join("; ") || "Inspect the runner output and verification report."}`.slice(0, 3000) : undefined;
+          const incompleteReport = reportValue?.complete === false || progress.pending > 0 || progress.active.length > 0;
+          // Exit 1 is the normal test-failure exit. A complete report with actual
+          // assertion failures still contains independent, valid passing outcomes.
+          // Unexplained exits, suite errors and interrupted reports grant no pass.
+          const caseFailureExit = run?.code === 1 && !runnerError && !suiteErrors.length && !incompleteReport && reportValue?.cases.some(item => item?.status === "failed");
+          const runnerFailure = run && (run.code !== 0 || suiteErrors.length || incompleteReport) ? `Registered runner ${profileName} ${run.code !== 0 ? `exited with code ${run.code ?? "unknown"}` : incompleteReport ? "left an incomplete report" : "reported a suite error"}. ${suiteErrors.join("; ") || reportValue?.cases.filter(item => item?.status === "failed").slice(0, 3).map(item => `${item.id}: ${item.message || "failed without a case diagnostic"}`).join("; ") || "Inspect the runner output and verification report."}`.slice(0, 3000) : undefined;
           if (runnerFailure) diagnostics.push({ rule: "behavior-runner", message: runnerFailure, output: run.output?.slice(-4000), profile: profileName });
           const afterOptions = loadConfig(root), afterContext = inputContext(afterOptions);
           for (const check of group) {
             const file = slash(path.relative(root, path.resolve(root, path.dirname(check.contract.file), check.file)));
             const matches = reportValue?.cases.filter(item => item && item.id === check.case && item.file === file) ?? [];
             const reportedStatus = matches.length && matches.every(item => item.status === "passed") ? "passed" : matches.length && matches.every(item => item.status === "skipped") ? "skipped" : "failed";
-            let status = !run || runnerFailure ? "failed" : reportedStatus;
+            const blockedRun = !!runnerError || !!runnerFailure && !caseFailureExit;
+            let status = matches.some(item => item.status === "failed") ? "failed" : !matches.length || blockedRun ? reportValue ? "incomplete" : "failed" : reportedStatus;
             if (runnerError?.code === "ENOENT") status = "unavailable";
             const current = behaviorInputs(afterOptions, check.contract, check, afterContext).revision === check.inputRevision;
             if (!current) status = "stale";
             if (signal.aborted) status = "cancelled";
             results.push({ unit: check.unit, check: check.id, file: check.file, case: check.case, profile: profileName, status, current, revision: check.inputRevision, runId, completedAt: new Date().toISOString(),
               previewRevision: profile.mode === "browser" ? host?.previewRevision() ?? readPreviewManifest(options)?.revision ?? null : null,
-              ...(runnerFailure ? { reportedStatus, runnerExitCode: run.code } : {}),
-              message: runnerError?.message ?? (matches.filter(item => item.status !== "passed").map(item => String(item.message || `Case reported ${item.status} without a diagnostic.`).slice(0, 2000)).join("\n") || (!matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : runnerFailure ? `This case reported ${reportedStatus}, but the complete run did not pass. ${runnerFailure}` : "")), report: slash(path.relative(root, report)) });
+              ...(matches.length ? { reportedStatus, durationMs: matches.reduce((sum, item) => sum + (Number.isFinite(item.durationMs) ? Math.max(0, item.durationMs) : 0), 0) } : {}),
+              ...(runnerFailure ? { runnerExitCode: run.code } : {}),
+              execution: progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state,
+              message: [matches.filter(item => item.status !== "passed").map(item => String(item.message || `Case reported ${item.status} without a diagnostic.`).slice(0, 2000)).join("\n"), runnerError ? `${runnerError.message} This check ${matches.length ? `reported ${reportedStatus}` : `was ${progress.cases.find(item => item.unit === check.unit && item.check === check.id)?.state ?? "not reported"}`}; the complete run did not pass.` : !matches.length ? "The selected case did not execute/report. Missing and skipped cases do not pass." : runnerFailure ? `This case reported ${reportedStatus}, but the complete run did not pass. ${runnerFailure}` : ""].filter(Boolean).join("\n"), report: slash(path.relative(reportRoot, report)) });
           }
           if (signal.aborted) break;
         }
@@ -217,7 +326,7 @@ export function createVerificationController(root) {
         }
         return { ok: diagnostics.length === 0 && results.length > 0 && results.every(result => result.status === "passed" && result.current), diagnostics, results };
       } catch (error) { return { ok: false, diagnostics: [{ rule: "behavior-verification", message: error.message }], results }; }
-      finally { try { await host?.close(); } finally { if (active === controller) active = undefined; finish(); } }
+      finally { try { await host?.close(); } finally { if (active === controller) { active = undefined; progress = undefined; } finish(); } }
     },
   };
 }

package/docs/ADS.md

@@ -107,6 +107,11 @@ framework/dependency gates and MCP execution contract.
 Flat owners may use `Button.scenario.tsx` and `Button.fixture.ts` instead.
 `Scenario.tsx` exports a default independently mountable view and literal metadata
 `export const scenario = { title: "Button states", covers: ["Button"] };`.
+Optional static `captureTargets` maps up to 20 names to CSS selectors scoped to
+that scenario's App. These support explicitly requested element screenshots; they
+do not grant coverage or styling exceptions. PNGs and current/candidate metadata
+are generated development evidence, outside source ownership and product bundles.
+See the portable [capture workflow](../skills/ads-designer/references/captures.md).
 Token entries under the configured token directory declare
 `export const scenario = { title: fixture.title, covers: ["TokenSamples"], samples: fixture.samples };`.
 `TokenSamples` is any project-owned public review pattern, not a required name.
@@ -159,7 +164,10 @@ or applies the right CSS property. Browser review still verifies the samples.
 
 Scenarios and fixture helpers are development-only wherever colocated. Runtime
 source and the public barrel cannot import or re-export them. Showcase/scenario
-code defines no CSS, custom classes or native controls; use public ADS APIs.
+code defines no CSS, custom classes or standalone native controls; use public ADS
+APIs. A single direct native child can supply semantics to a public runtime slot
+when source tracing proves that owner clones the exact child with its own props.
+An `asChild` flag alone is not evidence; scenario styling remains forbidden.
 Scenarios may consume public class helpers whose returned styles trace to owned
 Linaria. Stable hooks in that owner may accompany real styles; strings forwarded
 from scenarios, hook-only returns and untraceable outputs remain invalid.
@@ -378,7 +386,7 @@ The checks enforce the architecture's ownership boundaries:
 | Public API and dependencies | Consumers use public ADS imports; ADS implementations and showcase do not import application source; runtime code does not import showcase fixtures |
 | Interaction policy | Primitive state variables stay inside components; non-state customization hooks require explicit registration |
 | Renderer exceptions | Inline styles and imperative writes require used, narrow configured boundaries; stale entries fail; public props omit inherited style and reject open-ended visual strings |
-| Preview ownership | Scenarios define no CSS, custom classes, or native controls; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
+| Preview ownership | Scenarios define no CSS, custom classes, or standalone native controls; native slot children require public runtime cloning evidence; all declared tokens and public renderable UI have reachable registered scenarios; token references must exist; legacy catalogue pages are checked when present |
 | Assets | Source/public collisions and configured generated artifacts in source are rejected |
 
 Pointer capture without locally visible capture-loss cleanup produces a

package/docs/ARCHITECTURE.md

@@ -303,6 +303,10 @@ Opaque conditional branches do not grant speculative coverage. Scenarios may
 consume deliberate public class helpers when their returned styles retain
 runtime-owned Linaria provenance; stable owner-authored hooks may accompany real
 styles. This preserves ownership rather than granting scenario styling freedom.
+A native element may provide semantics as the single direct child of a public
+runtime slot when source tracing proves it is cloned with that owner's props.
+This preserves polymorphic composition without allowing standalone scenario
+controls, scenario styling or name-based exceptions.
 The skill-local [scenario guide](../skills/ads-designer/references/scenarios.md)
 explains evidence, limits and diagnostics.
 
@@ -336,6 +340,39 @@ The MCP server serves compiled bytes without evaluating project TSX. Compiler
 adapters normalize each entry to mount/unmount, retaining native React or Preact
 semantics; choosing a framework does not install one into the tooling host.
 
+## On-demand visual evidence
+
+The capture unit is a registered, independently mountable scenario or one of its
+project-declared `captureTargets`. Components, patterns, compositions and token
+previews use the same real MCP App, fixtures and adapter as interactive review.
+Shared controllers/hooks need a visible demonstration. Capture introduces no
+tool-owned component templates, styling or fixture inference.
+
+ADS owns isolated preview hosting, App readiness and an owned Playwright process;
+the receiving project supplies Playwright and its installed browser. The capture
+host is the existing minimal MCP client/bridge with navigation hidden, giving the
+sandboxed App the requested viewport. Project runtime, fonts and styles remain
+inside the App resource graph. The image excludes showcase chrome.
+
+Captures exist only when requested. `ads_capture` replaces current and removes any
+candidate for that scenario/target. Guarded patch/transaction dry runs can opt into
+`screenshot:true` with explicit selected captures: after the normal gates, ADS
+renders current and candidate under matching settings without changing live source.
+A new scenario has no fabricated baseline. Final freshness/conflict checks precede
+image publication. Matching accepted source promotes candidate to current.
+
+There are at most two slots per target: current and candidate. Revisions/settings
+are metadata, not new resource identities. There is no previous slot, accumulating
+history or TTL. Stale source is identified explicitly; deleted targets are collected.
+PNG/pixel/store limits and explicit clearing bound generated storage. These images
+are visual evidence for one state, not passing behavioral guarantees.
+
+One MCP capture index and a PNG resource template expose stable image slots.
+Subscriptions receive resource updates when images change or disappear. The pair
+is published as one atomic generated record under `.ds/captures/` and stays outside
+source ownership and product bundles. Detailed usage lives in each portable skill's
+[capture reference](../skills/ads-designer/references/captures.md).
+
 ## Build checks keep the architecture in place
 
 The project build runs ADS checks before producing application or showcase
@@ -369,8 +406,12 @@ context, or the shared token foundation. ADS resolves file ownership, reconstruc
 candidate files locally and validates a temporary project copy with architecture
 checks, registered lint rules and project validation scripts. Affected registered
 behavior checks, including consumers of a changed shared controller, also run in
-the isolated candidate project. Passing checks describe
-their registered assertions, not every natural-language claim. This keeps edits
+the isolated candidate project. The project owns its test code and runner policy;
+ADS owns affected-check selection, candidate hosting, progress, evidence freshness
+and process cleanup. One profile timeout bounds its entire runner process. Parallel
+workers can share that candidate host with independent App state. Partial outcomes
+remain diagnostic when execution is interrupted; they cannot approve a mutation.
+Passing checks describe their registered assertions, not every natural-language claim. This keeps edits
 focused without requiring entire file bodies in model context. Peer units and
 unrelated owners remain outside the selected unit's edit boundary. Shared foundation,
 branding and guides have their own units. Shared credits and text license notices

package/docs/BEHAVIORS.md

@@ -139,17 +139,57 @@ configuration must discover colocated spec files. Configure browser installation
 and any required test setup in that project. The ADS tooling host gains no
 framework or browser dependency from a profile.
 
-The Playwright adapter appends selected file paths, its reporter and a generated
-artifact directory.
-
-Runner failures remain blocking even when some selected cases reported passed.
-Those results retain `reportedStatus` and `runnerExitCode`, and explain the suite
-failure rather than returning an empty message. Suite-level browser errors and
+The Playwright adapter appends selected file paths and case-tag filtering, its
+reporter and a generated artifact directory. Unselected cases in the same spec
+do not run. It preserves the project's worker configuration.
+
+`timeoutMs` bounds the complete runner process for one profile, including runner
+startup, hooks, retries and all selected cases. It is not a per-test timeout.
+Playwright's own test/hook timeouts remain separate project settings. Set the
+profile budget from measured suite durations with headroom; increasing it does
+not repair a stalled assertion or cleanup.
+
+Independent specs can use multiple Playwright workers against the same managed
+candidate host. Each check needs its own page/context and state; avoid fixed ports,
+shared mutable fixtures and test-order dependencies. Start with a small worker
+count and measure on the target machine. Files normally run in parallel; tests
+within one file normally remain sequential. ADS does not force parallelism or
+change verification policy. See [Playwright parallelism](https://playwright.dev/docs/test-parallel).
+Prefer readiness/assertion polling over arbitrary sleeps. Timer-only guarantees
+may use [Playwright's clock](https://playwright.dev/docs/clock); retain real time
+when browser motion, pointer gestures or layout timing are what the check verifies.
+
+An ordinary test-failure exit (code 1) with a complete report and actual failing
+cases preserves independent case outcomes: passing checks stay `passed`, failed
+checks stay `failed`, and overall verification still blocks the mutation. The
+report must account for every selected check, with no active cases or suite errors.
+The same rule supports older custom reports without an explicit `complete` field
+after normal process completion. An unexplained nonzero exit cannot certify a
+pass, even if all reported cases claim success. Results retain `reportedStatus`
+and `runnerExitCode` and explain the overall failure. Suite-level browser errors and
 bounded runner output appear in diagnostics. `openBehaviorScenario` includes the
 scenario ID and failed browser requests in startup failures; App resource errors
 identify the resource URI. Failed assertions and startup errors are not retried
 automatically. Fix or investigate the failure before explicitly verifying again.
 
+The reporter atomically publishes partial snapshots at test start/end. While a
+run is active, `ads_status.behaviors.progress` exposes the profile, runner budget,
+elapsed time, completed/active/pending counts, worker count when available and
+case identities/timings. Candidate mutation verification exposes the same data at
+`ads_status.mutations.progress`. Clients requesting MCP progress receive updates
+and a heartbeat during the runner phase; client-side request timeouts still apply.
+`durationMs` records completed case execution, including attempts, separately from
+the suite's wall time. Parallel case durations can sum to more than wall time.
+
+After a deadline, valid completed outcomes remain visible through `reportedStatus`
+and durations, alongside active and unstarted case identities. A passed case from
+an interrupted run has blocking status `incomplete`; real assertion failures retain
+their own messages. No incomplete run can accept a mutation or certify a guarantee.
+Reports and artifacts stay under the live project's `.ds/verification/` even after
+the candidate copy is removed. This is diagnostic output, not passing live-source
+evidence. Old/custom runners without incremental progress use `not_reported` for
+cases whose execution state cannot be established.
+
 Use native test tags for stable case identity:
 
 ```ts
@@ -210,7 +250,13 @@ selected `checks` and optional `scenarios` URLs. Write a bounded JSON report:
 }
 ```
 
-Case statuses are `passed`, `failed` or `skipped`, with optional `message`.
+Case statuses are `passed`, `failed` or `skipped`, with optional `message` and
+`durationMs`. Protocol runners may atomically publish intermediate reports with
+`complete:false` and an `active` list of `{id,file,startedAt,workerIndex?}`, then
+publish `complete:true` at completion. Older final reports without `complete`
+remain supported after normal process completion. An explicitly incomplete report
+cannot pass even with exit code zero. Partial reports retain the same schema/run
+identity and size limits as final reports.
 `file` is project-relative. Nonzero process exit, missing cases, skipped cases,
 wrong run IDs and unavailable reports do not pass. Test commands are trusted
 project code; an adapter cannot prove the quality or honesty of their assertions.
@@ -245,10 +291,23 @@ Computed module selection conservatively includes all ADS owners. Environment,
 network and other unregistered external inputs remain the runner's responsibility;
 an evidence record is not a proof about arbitrary external state.
 
+For named imports through simple re-export barrels, ADS follows selected bindings
+and retains dependencies with declared side effects. This narrowing requires a
+package `sideEffects:false` or a supported simple `sideEffects` glob array; preserve
+CSS/global effects in that policy. Unknown policies/patterns, wildcard exports and
+computed imports remain conservative. Barrel source changes still invalidate
+dependents. ADS caches source parsing, resolution and digests within an inspection
+only; later runs read current source again.
+
 Guarded mutations execute affected registered behavior contracts after core,
 Oxlint and configured project checks, before writing source. Imported shared
 controller changes also select dependent contracts conservatively. Rejected and
 dry-run patches publish no source changes. Verification output stays under `.ds/`.
+To check a prepared draft, request its diff and pass the returned `patchFile` to
+`ads_apply_patch` with `dryRun:true`. This checks the isolated candidate, including
+affected behavior contracts and its configured browser preview. Candidate evidence
+is not persisted as passing evidence for live source. `ads_verify` selects checks
+for current source and has no draft argument.
 
 ## Packaging and performance
 

package/docs/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.3.14
+
+- Preserve independent passing behavior outcomes in complete runs with failed
+  assertions while keeping overall verification and mutations blocked. Retain
+  incomplete status for missing results, suite errors and unexplained exits.
+- Recognize native scenario children through source-verified public runtime slot
+  composition, including React/Preact cloning and local prop mergers. Keep
+  standalone controls, custom scenario styling and unproven slot paths rejected;
+  update diagnostics, architecture and portable skill guidance generically.
+
+## 0.3.13
+
+- Add on-demand scenario/named-element PNG captures and screenshot-enabled guarded
+  dry runs. Expose stable current/candidate resources, freshness and notifications;
+  standalone captures clear earlier candidates, matching applies promote them, and
+  bounded storage keeps no previous/history/TTL. Document architecture and portable
+  skill usage without introducing project-specific renderers or fixtures.
+- Report behavior progress, worker activity and per-case durations, preserving
+  partial outcomes and candidate artifacts on timeout while blocking incomplete
+  runs. Send requested MCP progress updates and expose candidate progress in status.
+- Filter selected Playwright case tags, preserve project worker configuration and
+  verify concurrent Apps against one candidate host. Narrow named barrel dependencies
+  under declared side-effect policies and reuse parsing/digests within an inspection.
+- Explain draft behavior verification through diff preparation and candidate
+  dry runs in all five portable skills. Distinguish candidate checks from
+  selected live-source verification through `ads_verify`.
+
 ## 0.3.12
 
 - Let the documentation unit create shared credits, conventional root license

package/docs/GUIDE.md

@@ -5,7 +5,54 @@ contains a Node CLI, shared token contract, static checks, an Oxlint plugin, and
 empty foundation scaffolding. It includes no component or pattern catalogue,
 fonts, mock screens, or UI runtime dependency.
 
-
+## Use ADS through MCP
+
+Connect your coding agent using the [MCP client setup](MCP.md#connect-codex-or-claude).
+The client launches `ads mcp` in your project; add `--mutations` to enable guarded
+source editing. Initialization also supplies `ads-mcp` and `ads-read-mcp` launch
+scripts. The server starts its showcase and configured preview compiler, so use
+the returned showcase URL rather than starting a separate preview application.
+
+An agent uses the MCP tools to inspect, edit and review the project:
+
+1. Call `ads_status` to identify the connected project, available commands,
+   mutation mode, showcase URL and build freshness.
+2. Find public UI/behavior APIs with `ads_catalog`, inspect relevant definitions
+   with `ads_tokens`, and discover preview IDs with `ads_scenarios`. Read one
+   relevant workflow through `ads_skills` and `ads_read_skill` before editing.
+3. Open a discovered preview with `ads_show_scenario` or `ads_show_tokens`. These
+   render the project's actual scenario, fixtures and adapter through MCP Apps.
+   Use the returned showcase link when the client cannot render Apps.
+4. When editing is enabled, discover ownership with `ads_units`, read relevant
+   source through `ads_read_file`, and submit an owner Git patch through
+   `ads_apply_patch`. Use `ads_apply_transaction` for genuinely coupled owners.
+   Prepare/diff a local draft with `ads_prepare_patch` when useful. Dry-run first;
+   ADS checks an isolated candidate before any live source is written.
+5. Review diagnostics, registered behavior evidence and the rendered result.
+   `ads_behaviors` discovers guarantees; `ads_verify` executes selected registered
+   checks. Recheck `ads_status.build` after changes; notifications alone do not
+   establish current output.
+
+For an on-demand screenshot, call `ads_capture` with a discovered scenario ID and
+optionally a named `captureTargets` element, theme and viewport. To compare a
+proposed change before applying it, add `screenshot:true` and an explicit
+`captures:[{scenario:"<discovered ID>"}]` selection to the patch/transaction dry run.
+Normal patches and dry runs create no screenshots. Capture uses project-installed
+Playwright and its browser; ADS installs neither.
+
+Read `ads://project/captures` and the returned PNG image URIs through MCP
+`resources/read`. Each target keeps only current and candidate: a successful
+standalone screenshot replaces current and clears candidate; a screenshot-enabled
+dry run replaces the pair; applying matching source promotes candidate. Source
+changes mark images stale. There is no previous slot, history or TTL.
+`ads_capture_clear` discards candidate or clears both images. Subscribe to resource
+updates when supported, and explicitly reread otherwise. Screenshots provide visual
+evidence for one state; they do not replace behavior checks.
+
+The [MCP guide](MCP.md) details tool/resource schemas, prompts, skills and
+notifications. The portable [capture guide](../skills/ads-designer/references/captures.md)
+explains screenshot setup, named targets, limits and comparison usage; MCP serves
+the same guide at `ads://guides/captures`.
 
 ## Implementation support