@reqvire-org/ads 0.3.16 → 0.3.17

package/README.md

@@ -125,6 +125,9 @@ Private controllers stay beside their component; shared controllers have their o
 edit units. Optional behavior contracts connect guarantees to maintained checks.
 Demonstrations and passing execution evidence remain distinct. See
 [controllers and verification](docs/BEHAVIORS.md).
+Structured failure boundaries and compact investigation bundles help agents
+inspect the failing source, requests and available artifacts while preserving
+the intended design. Each result states what it established and left unverified.
 
 Experimental MCP Apps show an interactive token inspector and project-built
 token, component, pattern and composition scenarios. They use the same public implementations and fixtures

package/dist/check.mjs

@@ -22,6 +22,8 @@ import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
 import { createAtomicCompositionReview } from "./atomic-composition.mjs";
 import { createScenarioTrace } from "./scenario-trace.mjs";
 import { createScenarioSlots } from "./scenario-slots.mjs";
+import { createScenarioSelectors } from "./scenario-selectors.mjs";
+import { architectureEvidence, failure } from "./evidence.mjs";
 
 const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
 const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
@@ -38,7 +40,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
   for (const [field, file] of [["dsDir", dsRoot], ["publicEntry", path.join(dsRoot, config.publicEntry)], ["stylesEntry", path.join(dsRoot, config.stylesEntry)]]) {
     if (!existsSync(file) || (field === "dsDir" ? !statSync(file).isDirectory() : !statSync(file).isFile())) diagnostics.push({ rule: "project-structure", file: path.relative(root, file), line: 1, column: 1, message: `Missing or invalid ${field}. Bootstrap an empty ADS or configure its actual path.` });
   }
-  if (diagnostics.length) return { ok: false, diagnostics };
+  if (diagnostics.length) return architectureEvidence({ ok: false, diagnostics });
   const tokenInventory = inspectTokens(root);
   const declaredTokens = new Set(tokenInventory.tokens.map((token) => token.name));
   diagnostics.push(...tokenInventory.diagnostics);
@@ -55,7 +57,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const checker = program.getTypeChecker();
   const atomicCompositionReview = createAtomicCompositionReview(program, options);
   const scenarioTrace = createScenarioTrace(program, options);
-  let scenarioSlot;
+  let scenarioSlot, scenarioSelector;
   function report(file, rule, message, line = 1, column = 1) {
     diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
   }
@@ -162,17 +164,20 @@ export function checkProject(directory, { trackingRoot } = {}) {
     }
     const inlineAllowed = config.inlineStyleFiles.some((allowed) => path.resolve(root, allowed) === file);
     const showcase = isDevelopmentFile(file, options) && !isTestFile(file);
-    function nodeReport(node, rule, message) {
+    function nodeReport(node, rule, message, detail) {
       const position = source.getLineAndCharacterOfPosition(node.getStart(source));
       report(file, rule, message, position.line + 1, position.character + 1);
+      if (detail) Object.assign(diagnostics.at(-1), detail);
     }
     function scenarioClass(node, expression, property = false) {
       const proof = scenarioTrace.classValue(expression, property);
       if (proof.present && !proof.ok) nodeReport(node, "showcase-class", `Scenarios define no custom class names. A public class helper must return runtime-owned Linaria styles; stable hooks authored in that owner may accompany real styles. Arbitrary strings, private styles and forwarded consumer classes do not qualify.${proof.reasons.length ? ` ${proof.reasons.join(" ")}` : ""} ${scenarioLayoutGuidance} See ads://guides/scenarios.`);
     }
-    function scenarioControl(node) {
+    function scenarioControl(node, native) {
       const proof = (scenarioSlot ??= createScenarioSlots(program, options))(node);
-      if (!proof.ok) nodeReport(node, "showcase-control", `Scenario controls must render public ADS components for actual interaction. A native direct child may provide semantics only when source tracing proves its public runtime parent clones that child with owned props; an asChild prop alone grants no permission.${proof.reasons.length ? ` ${proof.reasons.join(" ")}` : ""} ${scenarioLayoutGuidance} See ads://guides/scenarios.`);
+      if (proof.ok) return;
+      const selector = native ? (scenarioSelector ??= createScenarioSelectors(program, options))(node) : { ok: false, reasons: ["A selector cannot establish custom widget behavior or keyboard semantics."] };
+      if (!selector.ok) nodeReport(node, "showcase-control", `Scenario controls must compose public ADS runtime UI. Native semantics require source evidence of owned cloning props or an attached runtime Linaria selector addressing that native tag or a verified runtime-owned part in that position. A prop name, broad selector or scenario-authored marker grants no permission. ${selector.reasons.join(" ")} Preserve valid APIs when tracing is inconclusive; report the limitation instead of changing the API to satisfy coverage. ${scenarioLayoutGuidance} See ads://guides/scenarios.`, { failure: failure("architecture", "source-ownership", "ownership-not-proven", { certainty: "inconclusive" }) });
     }
     if (!showcase && (isInside(path.join(dsRoot, "components"), file) || isInside(path.join(dsRoot, "patterns"), file))) inspectPublicProps(source, checker, nodeReport);
     function isLinariaTag(tag) {
@@ -231,7 +236,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
         if (showcase) for (const property of properties) if (ts.isSpreadAssignment(property)) scenarioClass(property, property.expression, true);
         if (showcase && tag && ts.isStringLiteralLike(tag)) {
           const role = properties.find(property => ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) && property.name.text === "role")?.initializer;
-          if (showcaseControls.has(tag.text) || role && ts.isStringLiteralLike(role) && widgetRoles.has(role.text)) scenarioControl(node);
+          if (showcaseControls.has(tag.text) || role && ts.isStringLiteralLike(role) && widgetRoles.has(role.text)) scenarioControl(node, showcaseControls.has(tag.text));
         }
       }
       if (isInside(dsRoot, file) && (ts.isIdentifier(node) && ["fetch", "XMLHttpRequest", "WebSocket", "EventSource"].includes(node.text) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node))) {
@@ -242,7 +247,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (showcase && (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && ts.isIdentifier(node.tagName) && /^[a-z]/.test(node.tagName.text)) {
         const role = node.attributes.properties.find((attr) => ts.isJsxAttribute(attr) && attr.name.text === "role")?.initializer;
         const roleValue = role && ts.isStringLiteralLike(role) ? role.text : role && ts.isJsxExpression(role) && role.expression && ts.isStringLiteralLike(role.expression) ? role.expression.text : null;
-        if (showcaseControls.has(node.tagName.text) || widgetRoles.has(roleValue)) scenarioControl(node);
+        if (showcaseControls.has(node.tagName.text) || widgetRoles.has(roleValue)) scenarioControl(node, showcaseControls.has(node.tagName.text));
       }
       if (showcase && ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className") scenarioClass(node, node.initializer && ts.isJsxExpression(node.initializer) ? node.initializer.expression : node.initializer);
       if (showcase && ts.isJsxSpreadAttribute(node)) scenarioClass(node, node.expression, true);
@@ -279,5 +284,5 @@ export function checkProject(directory, { trackingRoot } = {}) {
   }
   // Bounded clients should see actionable warnings before source-analysis limits.
   advisories.sort((first, second) => Number(first.severity === "info") - Number(second.severity === "info"));
-  return { ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) };
+  return architectureEvidence({ ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) });
 }

package/dist/evidence.mjs

@@ -0,0 +1,18 @@
+/** Categories describe the failing boundary, never an inferred root cause. */
+export const failureCategories = new Set(["architecture", "build", "transport", "runner", "assertion"]);
+
+export function failure(category, phase, code, detail = {}) {
+  if (!failureCategories.has(category)) throw new Error("Unknown ADS evidence category.");
+  return { category, phase, code, ...detail };
+}
+
+export function acceptance(scope, passed, established, unverified) {
+  return { scope, status: passed ? "passed" : "not_established", established, unverified };
+}
+
+export function architectureEvidence(result) {
+  return { ...result,
+    diagnostics: result.diagnostics.map(diagnostic => ({ ...diagnostic, failure: diagnostic.failure ?? failure("architecture", "source-analysis", diagnostic.rule) })),
+    acceptance: acceptance("core-architecture", result.ok, result.ok ? ["core-source-guards"] : [], ["project-checks", "compiled-preview", "browser-behavior", "visual-parity", "accessibility-audit"]),
+  };
+}

package/dist/investigations.mjs

@@ -0,0 +1,70 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+
+export const INVESTIGATIONS_URI = "ads://project/investigations";
+const indexFile = root => path.join(root,".ds/investigations.json");
+const identity = entry => `${entry.unit}#${entry.check}`;
+export const investigationUri = entry => `ads://investigations/${encodeURIComponent(entry.unit)}/${encodeURIComponent(entry.check)}`;
+const ordinary = file => { try { return realpathSync(file)===path.resolve(file)&&lstatSync(file).isFile()&&lstatSync(file).nlink===1; } catch { return false; } };
+const digest = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+function saved(root) {
+  const file=indexFile(root);
+  if(!ordinary(file)||lstatSync(file).size>2*1024*1024)return {};
+  try {const value=JSON.parse(readFileSync(file,"utf8"));return value.schemaVersion===1&&value.bundles&&typeof value.bundles==="object"&&!Array.isArray(value.bundles)?value.bundles:{};}catch{return {};}
+}
+function artifactPath(root, relative) {
+  if(typeof relative!=="string"||!/^\.ds\/verification\/[a-f0-9-]{36}\/artifacts\//.test(relative)||relative.includes("\\")||relative.split("/").some(part=>[".","..",""].includes(part)))return null;
+  const file=path.resolve(root,relative);
+  return ordinary(file)&&lstatSync(file).size<=20*1024*1024?file:null;
+}
+
+/** One latest bundle per registered check, including isolated candidate runs. */
+export function saveInvestigations(root, entries, registered) {
+  const valid=new Set(registered),bundles=Object.fromEntries(Object.entries(saved(root)).filter(([key])=>valid.has(key)));
+  for(const entry of entries)bundles[identity(entry)]={...entry,resourceUri:investigationUri(entry)};
+  const content=JSON.stringify({schemaVersion:1,bundles});
+  if(Buffer.byteLength(content)>2*1024*1024)throw new Error("Latest investigation metadata exceeds 2 MiB.");
+  const file=indexFile(root),temporary=`${file}.${randomUUID()}.tmp`;
+  mkdirSync(path.dirname(file),{recursive:true});
+  if(realpathSync(path.dirname(file))!==path.dirname(file))throw new Error("Investigation output cannot resolve through a symlink.");
+  try {writeFileSync(temporary,content);renameSync(temporary,file);}finally{rmSync(temporary,{force:true});}
+}
+
+export function investigationIndex(root) {
+  return {retention:"latest-per-check",entries:Object.values(saved(root)).map(({unit,check,status,completedAt,inputRevision,resourceUri,failure})=>({unit,check,status,completedAt,inputRevision,resourceUri,...(failure?{failure}:{})}))};
+}
+
+export function readInvestigation(root,{unit,check}) {
+  const bundle=saved(root)[identity({unit,check})];
+  if(!bundle)throw new Error("No investigation exists for this check. Run ads_verify or a guarded candidate first.");
+  return {...bundle,artifacts:(bundle.artifacts??[]).map(artifact=>({...artifact,available:!!artifactPath(root,artifact.path)}))};
+}
+
+export function investigationArtifacts(root,report,attachments=[]) {
+  return attachments.slice(0,5).flatMap(attachment=>{
+    if(typeof attachment?.path!=="string")return [];
+    const target=path.resolve(path.dirname(report),attachment.path);
+    if(!target.startsWith(path.join(path.dirname(report),"artifacts")+path.sep))return [];
+    const relative=path.relative(root,target).replaceAll("\\","/");
+    const file=artifactPath(root,relative);
+    if(!file)return [];
+    const bytes=readFileSync(file);
+    return [{name:String(attachment.name).slice(0,100),mimeType:String(attachment.mimeType).slice(0,100),path:relative,bytes:bytes.length,digest:digest(bytes),resourceUri:`ads://verification-artifacts/${relative.split("/").map(encodeURIComponent).join("/")}`}];
+  });
+}
+
+/** Only files explicitly registered by the latest bundles are resource-readable. */
+export function readInvestigationResource(root,uri) {
+  if(uri.startsWith("ads://investigations/")) {
+    const parts=uri.slice("ads://investigations/".length).split("/").map(decodeURIComponent);
+    if(parts.length!==2)throw new Error("Invalid investigation URI.");
+    return {uri,mimeType:"application/json",text:JSON.stringify(readInvestigation(root,{unit:parts[0],check:parts[1]}))};
+  }
+  const artifact=Object.values(saved(root)).flatMap(bundle=>bundle.artifacts??[]).find(artifact=>artifact.resourceUri===uri);
+  const file=artifact&&artifactPath(root,artifact.path);
+  if(!file||!existsSync(file))throw new Error("Investigation artifact is unavailable or has been superseded.");
+  const bytes=readFileSync(file);
+  if(bytes.length!==artifact.bytes||digest(bytes)!==artifact.digest)throw new Error("Investigation artifact changed after verification.");
+  return ["text/plain","text/markdown","application/json"].includes(artifact.mimeType)?{uri,mimeType:artifact.mimeType,text:bytes.toString("utf8")}:{uri,mimeType:artifact.mimeType,blob:bytes.toString("base64")};
+}

package/dist/mcp/context.mjs

@@ -5,7 +5,7 @@ import { projectGuideFiles } from "../project-documents.mjs";
 
 export const GUIDE_URI = "ads://project/guide";
 // Put the task triggers and entry path first: some hosts shorten server guidance.
-export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner; use ads_apply_transaction only for coupled owner patches. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For requested visual evidence, use ads_capture or screenshot-enabled patch dry runs; read ads://guides/captures for named targets, image resources and the current/candidate lifecycle. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
+export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner; use ads_apply_transaction only for coupled owner patches. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For requested visual evidence, use ads_capture or screenshot-enabled patch dry runs; read ads://guides/captures for named targets, image resources and the current/candidate lifecycle. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. For a failed check or rejected patch, inspect its structured failure boundary and acceptance scope; ads_investigate reads retained per-check evidence without rerunning tests (ads://guides/evidence). Preserve valid APIs when source tracing is inconclusive. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
 
 function manager(root, pkg) {
   if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];

package/dist/mcp/mutations.mjs

@@ -15,6 +15,7 @@ import { createCaptureController, captureSelections } from "../capture.mjs";
 import { previewSourceRevision } from "../preview-inputs.mjs";
 import { inspectScenarios } from "../scenarios.mjs";
 import { checkUnitCandidate, checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
+import { acceptance, failure as evidenceFailure } from "../evidence.mjs";
 
 export const mutationLimits = { units: 8, files: 32, patchBytes: 256 * 1024, patchFileBytes: 16 * 1024 * 1024, fileBytes: 16 * 1024 * 1024, readChars: 12000, snapshotFiles: 20000, snapshotBytes: 128 * 1024 * 1024 };
 const digest = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
@@ -22,8 +23,8 @@ const ignored = new Set([".git", ".ds", "node_modules", ".vite", "coverage", ".p
 const textFile = file => /\.(?:[cm]?[jt]sx?|css|html|jsonc?|md|txt|svg)$/.test(file);
 const setupDotfile = file => /^\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?$/.test(file);
 
-function fail(rule, message, file) {
-  return Object.assign(new Error(message), { diagnostic: { rule, message, ...(file ? { file } : {}) } });
+function fail(rule, message, file, boundary = evidenceFailure("architecture","mutation-policy",rule)) {
+  return Object.assign(new Error(message), { diagnostic: { rule, message, failure:boundary, ...(file ? { file } : {}) } });
 }
 
 function address(options, file) {
@@ -108,12 +109,13 @@ function snapshot(options, destination) {
   return JSON.stringify(entries);
 }
 
-function checkCommand(command, args, cwd, signal, input) {
+function checkCommand(command, args, cwd, signal, input, gate = {category:"architecture",phase:"patch-preparation"}) {
   return new Promise((resolve, reject) => {
-    if (signal?.aborted) { reject(fail("mutation-cancelled", "Mutation cancelled before validation.")); return; }
+    if (signal?.aborted) { reject(fail("mutation-cancelled", "Mutation cancelled before validation.",undefined,evidenceFailure("runner","mutation-execution","ADS_CANCELLED"))); return; }
     const child = spawn(command, args, { cwd, shell: false, detached: process.platform !== "win32", windowsHide: true, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
       env: { ...process.env, PATH: [path.join(cwd, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) } });
     let output = "", failure;
+    const startedAt=Date.now();
     if (input !== undefined) { child.stdin.on("error", () => {}); child.stdin.end(input); }
     function kill() {
       if (!child.pid) return;
@@ -130,13 +132,23 @@ function checkCommand(command, args, cwd, signal, input) {
     child.once("exit", kill); // Also clean up descendants of a finished launcher.
     child.once("close", code => {
       clearTimeout(timer); signal?.removeEventListener("abort", abort);
-      if (failure) reject(failure);
-      else if (code !== 0) reject(fail("mutation-check", `${path.basename(command)} ${args.join(" ")} failed (${code}).\n${output}`));
-      else resolve({ command: path.basename(command), args, passed: true });
+      const detail={command:path.basename(command),args,elapsedMs:Date.now()-startedAt,exitCode:code};
+      if (failure || code !== 0) {
+        const error=failure??fail("mutation-check", `${path.basename(command)} ${args.join(" ")} failed (${code}).\n${output}`);
+        error.diagnostic={...(error.diagnostic??{rule:"mutation-check",message:error.message}),...detail,output:output.slice(-4000),failure:evidenceFailure(failure?"runner":gate.category,gate.phase,failure?.code??(failure?"ADS_COMMAND_INTERRUPTED":"ADS_COMMAND_EXIT"),{certainty:"observed-boundary"})};
+        reject(error);
+      } else resolve({ ...detail,phase:gate.phase, passed: true });
     });
   });
 }
 
+function mutationEvidence(result, candidateRevision) {
+  const diagnostics=(result.diagnostics??[]).map(diagnostic=>({...diagnostic,failure:diagnostic.failure??evidenceFailure("architecture","mutation-policy",diagnostic.rule)}));
+  const failed=diagnostics[0];
+  const accepted=acceptance("candidate-validation",result.ok,(result.checks??[]).filter(check=>check.passed&&!check.skipped).map(check=>check.name??[check.command,...(check.args??[])].join(" ")),["unregistered-checks","unselected-behavior-checks","post-application-preview-freshness","visual-parity","accessibility-audit"]);
+  return {...result,...(result.diagnostics?{diagnostics}:{}),acceptance:accepted,investigation:{target:"candidate",candidateRevision:candidateRevision??null,...(failed?{failure:failed.failure,failingStep:failed.failure.phase,source:failed.file?{file:failed.file,line:failed.line,column:failed.column}:null,...(failed.command?{command:failed.command,args:failed.args,exitCode:failed.exitCode,output:failed.output}:{}),message:failed.message}:{}),acceptance:accepted}};
+}
+
 function checks(options) {
   const context = projectContext(options);
   const pkg = JSON.parse(readFileSync(path.join(options.root, "package.json"), "utf8"));
@@ -175,11 +187,12 @@ export function createMutationController(directory, { captures = createCaptureCo
         startLine: source.content.slice(0, offset).split("\n").length };
     },
     async apply({ unit, patch, patchFile, patches, dryRun = false, screenshot = false, captures: selections }, signal, notifyProgress) {
-      if (busy) return { ok: false, applied: false, diagnostics: [{ rule: "mutation-busy", message: "Another mutation is validating; retry after it finishes." }] };
+      if (busy) return mutationEvidence({ ok: false, applied: false, diagnostics: [{ rule: "mutation-busy", message: "Another mutation is validating; retry after it finishes.",failure:evidenceFailure("runner","mutation-execution","ADS_MUTATION_BUSY") }] });
       busy = true;
       active = new AbortController();
       signal = signal ? AbortSignal.any([signal, active.signal]) : active.signal;
-      let temporary;
+      let temporary, candidateRevision;
+      let boundary=evidenceFailure("runner","mutation-execution","ADS_MUTATION_EXCEPTION",{certainty:"unclassified"});
       const verified = [];
       try {
         const options = loadConfig(root);
@@ -264,8 +277,9 @@ export function createMutationController(directory, { captures = createCaptureCo
         const candidateOptions = loadConfig(candidate);
         const extraChecks = checks(candidateOptions);
         const expected = snapshot(candidateOptions);
+        candidateRevision=digest(Buffer.from(expected));
         const result = checkProject(candidate, { trackingRoot: root });
-        if (!result.ok) return lastResult = { ok: false, applied: false, diagnostics: result.diagnostics.slice(0, 50), total: result.diagnostics.length, checks: verified };
+        if (!result.ok) return lastResult = mutationEvidence({ ok: false, applied: false, diagnostics: result.diagnostics.slice(0, 50), total: result.diagnostics.length, checks: verified },candidateRevision);
         verified.push({ name: "ads check", passed: true });
         const lintConfig = generateLintConfig(candidate).file;
         const require = createRequire(path.join(candidate, "package.json"));
@@ -276,30 +290,33 @@ export function createMutationController(directory, { captures = createCaptureCo
         if (configuration) for (const file of inspectUnits(candidateOptions).units.find(item => item.id === "configuration").files) {
           if (/\.[cm]?[jt]sx?$/.test(file) && !lintPaths.some(directory => isInside(path.resolve(candidate, directory), path.resolve(candidate, file)))) lintPaths.push(file);
         }
-        await checkCommand(process.execPath, [executable, "--deny-warnings", "--config", lintConfig, ...lintPaths], candidate, signal);
+        await checkCommand(process.execPath, [executable, "--deny-warnings", "--config", lintConfig, ...lintPaths], candidate, signal, undefined, {category:"architecture",phase:"registered-oxlint"});
         verified.push({ name: "registered Oxlint rules", passed: true });
         if (assets || configuration) {
+          boundary=evidenceFailure("build","brand-assets","ADS_ASSET_BUILD");
           const brand = await generateBrandAssets(candidate);
           verified.push({ name: "brand assets", passed: true, skipped: !!brand.skipped });
         }
-        for (const check of extraChecks) verified.push(await checkCommand(check.command, check.args, candidate, signal));
+        for (const check of extraChecks) verified.push(await checkCommand(check.command, check.args, candidate, signal, undefined, {category:"build",phase:`project-check:${check.args[1]}`}));
+        boundary=evidenceFailure("runner","behavior-verification","ADS_BEHAVIOR_SETUP");
         const behaviorUnits = affectedBehaviorUnits(candidateOptions, changes.map(change => change.path));
         if (behaviorUnits.length) {
           const verification = createVerificationController(candidate, { reportRoot: root, onProgress: value => { progress = { stage: "behavior", ...value }; notifyProgress?.(progress); } });
           let evidence;
           try { evidence = await verification.run({ units: behaviorUnits, persist: false }, signal); }
           finally { await verification.close(); }
-          if (!evidence.ok) return lastResult = { ok: false, applied: false, diagnostics: [...evidence.diagnostics, ...evidence.results.filter(item => item.status !== "passed").map(item => ({ rule: "behavior-check", message: `${item.unit}#${item.check}: ${item.status}. ${item.message}` }))].slice(0, 50), checks: verified, behavior: evidence };
+          if (!evidence.ok) return lastResult = mutationEvidence({ ok: false, applied: false, diagnostics: [...evidence.results.filter(item => item.status !== "passed").map(item => ({ rule: "behavior-check", failure:item.failure, message: `${item.unit}#${item.check}: ${item.status}. ${item.message}` })),...evidence.diagnostics].slice(0, 50), checks: verified, behavior: evidence },candidateRevision);
           verified.push({ name: "registered behavior checks", passed: true, results: evidence.results });
         }
         let screenshots;
         if (screenshot) {
+          boundary=evidenceFailure("runner","capture","ADS_CAPTURE_FAILED");
           progress = { stage: "capture", total: selections.length, completed: 0, active: [], profile: "screenshots", elapsedMs: 0 };
           notifyProgress?.(progress);
           const proposal = digest(Buffer.from(JSON.stringify(changes.map(change => [change.path, change.content === null ? null : digest(Buffer.from(change.content))]))));
           screenshots = await captures.run({ captures: selections, candidateRoot: candidate, proposal, publish: false }, signal, value => { progress = value; notifyProgress?.(value); });
         }
-        if (signal?.aborted) throw fail("mutation-cancelled", "Mutation cancelled before application.");
+        if (signal?.aborted) throw fail("mutation-cancelled", "Mutation cancelled before application.",undefined,evidenceFailure("runner","mutation-execution","ADS_CANCELLED"));
         if (snapshot(candidateOptions) !== expected) throw fail("mutation-check", "A validation command changed source files. Use checks without source-writing side effects.");
         if (snapshot(loadConfig(root)) !== before) throw fail("mutation-conflict", "Project inputs changed during validation; no changes were applied. Read current source and retry.");
         for (const change of changes) address(options, change.path);
@@ -336,11 +353,11 @@ export function createMutationController(directory, { captures = createCaptureCo
         const warnings = [];
         if (!dryRun && (assets || configuration)) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
         if (!dryRun && captures.store.fingerprint()) { try { captures.store.promote(previewSourceRevision(loadConfig(root)), inspectScenarios(loadConfig(root)).scenarios); } catch (error) { warnings.push({ rule: "mutation-capture", message: `Source was applied; capture promotion needs recovery: ${error.message}` }); } }
-        return lastResult = { ok: true, ...(patches ? {units,transaction:true} : {unit}), applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
+        return lastResult = mutationEvidence({ ok: true, ...(patches ? {units,transaction:true} : {unit}), applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
           ...(screenshots ? { screenshots } : {}),
-          preview: "Source validation passed. Inspect the managed preview build and rendered scenario after applying; validation is not visual verification." };
+          preview: "Source validation passed. Inspect the managed preview build and rendered scenario after applying; validation is not visual verification." },candidateRevision);
       } catch (error) {
-        return lastResult = { ok: false, applied: false, diagnostics: [error.diagnostic ?? { rule: "mutation-error", message: error.message }], checks: verified };
+        return lastResult = mutationEvidence({ ok: false, applied: false, diagnostics: [error.diagnostic ?? { rule: "mutation-error", message: error.message,failure:error.failure??boundary }], checks: verified },candidateRevision);
       } finally { try { if (temporary) rmSync(temporary, { recursive: true, force: true }); } finally { busy = false; active = undefined; progress = undefined; } }
     },
   };