@reqvire-org/ads 0.3.17 → 0.3.18

package/dist/atomic-composition.mjs

@@ -168,7 +168,7 @@ export function createAtomicCompositionReview(program, options) {
           if (parent.type === "atrule") conditions.unshift(`${parent.name} ${parent.params}`.trim().replace(/\s+/g, " "));
         }
         // Animation frames describe different instants, not combined classes.
-        if (conditions.some(condition => /^(?:-\w+-)?keyframes\b/.test(condition))) return;
+        if (conditions.some(condition => /^(?:(?:-\w+-)?keyframes|property)\b/.test(condition))) return;
         result.push({ property: decl.prop.toLowerCase(), value: decl.value, important: !!decl.important, selectors: JSON.stringify(selectors), conditions: JSON.stringify(conditions),
           file: path.relative(options.root, source.fileName).replaceAll("\\", "/"), line: position.line + decl.source.start.line, column: decl.source.start.column + (decl.source.start.line === 1 ? position.character : 0) });
       });

package/dist/check.mjs

@@ -24,6 +24,7 @@ import { createScenarioTrace } from "./scenario-trace.mjs";
 import { createScenarioSlots } from "./scenario-slots.mjs";
 import { createScenarioSelectors } from "./scenario-selectors.mjs";
 import { architectureEvidence, failure } from "./evidence.mjs";
+import { propertyRegistration } from "./property-registrations.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.`;
@@ -70,6 +71,30 @@ export function checkProject(directory, { trackingRoot } = {}) {
   inspectControllers(options, program, report, behaviors.contracts);
   // The foundation remains a fixed import-only entry, not an extra styling layer.
   const foundationEntry = path.join(dsRoot, config.stylesEntry);
+  const registeredProperties=new Map();
+  function checkRegistrations(file,css,offset={line:1}){
+    css.walkAtRules(/^property$/i,rule=>{
+      const line=offset.line+(rule.source?.start.line??1)-1;
+      try{
+        const registration=propertyRegistration(rule),relative=scoped.inventory.relative(path.relative(root,file));
+        const owner=scoped.inventory.owner(relative),foundation=isInside(path.join(dsRoot,config.tokenDir),file);
+        if(foundation){
+          let defined=false;css.walkDecls(registration.name,()=>{defined=true;});
+          if(!isSharedToken(registration.name)||!declaredTokens.has(registration.name)||!defined||["base.css","fonts.css"].includes(path.basename(file)))throw new Error("Shared @property registrations belong beside their real token definitions in foundation value sheets, not base.css or fonts.css.");
+        }else{
+          if(!owner||!/^(?:components|patterns)\//.test(owner))throw new Error("@property belongs to its runtime component/pattern or real token value sheet, never application, scenario, controller or shared reset styling.");
+          const violation=checkComponentVariable(registration.name,file,options);if(violation)throw new Error(violation.message);
+        }
+        for(const descriptor of rule.nodes??[])if(descriptor.type==="decl")for(const ref of references(descriptor.value)){
+          const tokenOwner=scopedTokenOwner(options,ref.name);
+          if(tokenOwner&&(tokenOwner.unit!==owner||!declaredTokens.has(ref.name))||!tokenOwner&&!/^(?:--ds-|--ux-|--showcase-)/.test(ref.name)&&(!isSharedToken(ref.name)||!declaredTokens.has(ref.name)&&!ref.fallback))throw new Error(`Invalid or cross-owner token reference ${ref.name} in registration metadata.`);
+        }
+        const previous=registeredProperties.get(registration.name);
+        if(previous&&(previous.owner!==owner||previous.signature!==registration.signature))throw new Error(`Conflicting @property registration for ${registration.name}; ${path.relative(root,previous.file)} already registers it. Keep one owner and identical descriptors across that owner's modules.`);
+        registeredProperties.set(registration.name,{...registration,owner,file});
+      }catch(error){report(file,"property-registration",`${error.message} See ads://guides/atomic-styles.`,line,rule.source?.start.column??1);diagnostics.at(-1).guidanceUri="ads://guides/atomic-styles";}
+    });
+  }
   try {
     const css = postcss.parse(readFileSync(foundationEntry, "utf8"), { from: foundationEntry });
     const imports = css.nodes.filter((node) => node.type !== "comment");
@@ -81,6 +106,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     let css;
     try { css = postcss.parse(text, { from: file }); }
     catch (error) { report(file, "css-syntax", error.reason ?? error.message, offset.line + (error.line ?? 1) - 1); return; }
+    checkRegistrations(file,css,offset);
     if (!foundation && (isDevelopmentFile(file, options) || !isInside(path.join(dsRoot, "components"), file) && !isInside(path.join(dsRoot, "patterns"), file) && file !== foundationEntry)) report(file, "style-ownership", "Visual CSS belongs to the local ADS's runtime components or patterns.");
     if (isDevelopmentFile(file, options) && css.nodes.some((node) => node.type !== "comment" && !(node.type === "atrule" && node.name === "import"))) report(file, "showcase-style", `Scenarios and fixtures define no styles. ${scenarioLayoutGuidance}`, offset.line);
     css.walkAtRules("import", (rule) => {
@@ -108,12 +134,13 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (rule.name === "font-face" && path.basename(file) !== "fonts.css") report(file, "foundation-role", "Font faces belong in the canonical fonts.css foundation sheet.", rule.source.start.line);
     });
     css.walkDecls((decl) => {
+      const propertyDescriptor=decl.parent.type==="atrule"&&decl.parent.name.toLowerCase()==="property";
       if (foundation && decl.prop.startsWith("--")) {
         if (path.basename(file) === "base.css") report(file, "foundation-role", "Shared token definitions belong in value sheets, not base.css.", decl.source.start.line, decl.source.start.column);
         return; // Definition names, values and aliases are validated by inspectTokens.
       }
       const fontDescriptor = foundation && path.basename(file) === "fonts.css" && decl.parent.type === "atrule" && decl.parent.name === "font-face";
-      if (foundation && !fontDescriptor && (path.basename(file) !== "base.css" || decl.parent.type !== "rule")) report(file, "foundation-role", "Token sheets contain shared definitions; native defaults belong in base.css, font descriptors in fonts.css, and UI styling in Linaria owners.", decl.source.start.line, decl.source.start.column);
+      if (foundation && !fontDescriptor && !propertyDescriptor && (path.basename(file) !== "base.css" || decl.parent.type !== "rule")) report(file, "foundation-role", "Token sheets contain shared definitions; native defaults belong in base.css, font descriptors in fonts.css, and UI styling in Linaria owners.", decl.source.start.line, decl.source.start.column);
       if (foundation && path.basename(file) === "base.css" && decl.parent.type === "rule") {
         const violation = foundationDeclaration(decl.parent, decl);
         if (violation) report(file, "foundation-role", violation, decl.source.start.line, decl.source.start.column);
@@ -131,7 +158,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
         if (!local && !isSharedToken(ref.name)) report(file, "token-name", `${ref.name} does not follow ADS's fixed token naming contract.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
         else if (!local && !declaredTokens.has(ref.name) && !ref.fallback) report(file, "token-reference", `Undefined shared token ${ref.name}.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
       }
-      if (fontDescriptor) return; // Font metadata defines source assets, not token-backed UI styles.
+      if (fontDescriptor || propertyDescriptor) return; // Font metadata defines source assets, not token-backed UI styles.
       const violations = new Set();
       valueParser(decl.value).walk((node) => {
         if (node.type === "function" && node.value === "url") return false;
@@ -146,7 +173,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     });
   }
   for (const file of files) {
-    if (scopedFiles.has(file)) continue; // Closed definition-only contract checked by inspectTokens.
+    if (scopedFiles.has(file)) { try{checkRegistrations(file,postcss.parse(readFileSync(file,"utf8"),{from:file}));}catch{/* Token inspection reports malformed sheets. */} continue; } // Closed definition-only contract checked by inspectTokens.
     if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) { checkCss(file, readFileSync(file, "utf8"), undefined, true); continue; }
     if (file.endsWith(".html")) { inspectHtml(readFileSync(file, "utf8"), (rule, message, line) => report(file, rule, message, line)); continue; }
     if (file.endsWith(".css")) {

package/dist/investigations.mjs

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
+import { compactAcceptance, compactRow, jsonBytes, resultBudgets, resultPage, resultRecord } from "./mcp/result-pages.mjs";
 
 export const INVESTIGATIONS_URI = "ads://project/investigations";
 const indexFile = root => path.join(root,".ds/investigations.json");
@@ -32,7 +33,7 @@ export function saveInvestigations(root, entries, registered) {
 }
 
 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}:{})}))};
+  return {retention:"latest-per-check",entries:Object.values(saved(root)).map(({unit,check,status,runId,target,completedAt,inputRevision,resourceUri,failure})=>({unit,check,status,runId,target,completedAt,inputRevision,resourceUri,...(failure?{failure}:{})}))};
 }
 
 export function readInvestigation(root,{unit,check}) {
@@ -41,6 +42,35 @@ export function readInvestigation(root,{unit,check}) {
   return {...bundle,artifacts:(bundle.artifacts??[]).map(artifact=>({...artifact,available:!!artifactPath(root,artifact.path)}))};
 }
 
+export const investigationSections=["summary","details","requests","browserErrors","artifacts"];
+export function investigationPage(root,{unit,check,runId,section="summary",cursor,limit,recordIndex,offset,chars}={}) {
+  if(check===undefined){
+    if(runId!==undefined||section!=="summary"||recordIndex!==undefined||offset!==undefined||chars!==undefined)throw new Error("Select an exact unit/check before reading investigation details.");
+    const entries=investigationIndex(root).entries.filter(entry=>!unit||entry.unit===unit);
+    return resultPage(entries,{cursor,limit,identity:["investigations",unit,entries],key:"entries",header:{retention:"latest-per-check"}});
+  }
+  if(!unit||!investigationSections.includes(section))throw new Error("Select an exact unit/check and a known investigation section.");
+  const bundle=readInvestigation(root,{unit,check});
+  if(runId!==undefined&&bundle.runId!==runId)throw new Error("Investigation was superseded by a different run. Do not mix it with the earlier result.");
+  const details={source:bundle.source,failingStep:bundle.failingStep,viewport:bundle.viewport,viewportSource:bundle.viewportSource,failure:bundle.failure};
+  if(section!=="summary"){
+    const rows=(section==="details"?[details]:bundle[section]??[]).map((row,recordIndex)=>({recordIndex,...(row&&typeof row==="object"?row:{value:row})})),header={unit,check,runId:bundle.runId,section};
+    if(recordIndex!==undefined){if(cursor!==undefined||!runId)throw new Error("Read investigation record ranges with the exact runId and without a cursor.");return resultRecord(rows,{recordIndex,offset,chars,header});}
+    if(offset!==undefined||chars!==undefined)throw new Error("Select a recordIndex before reading text ranges.");
+    return resultPage(rows,{cursor,limit,identity:["investigation",unit,check,bundle.runId,bundle.inputRevision,section,rows],header});
+  }
+  if(recordIndex!==undefined||offset!==undefined||chars!==undefined)throw new Error("Select an investigation detail section before reading record ranges.");
+  if(cursor!==undefined)throw new Error("The investigation summary has no continuation; select a detail section.");
+  const result={unit,check,runId:bundle.runId,status:bundle.status,target:bundle.target,inputRevision:bundle.inputRevision,inputsCurrentAtCompletion:bundle.inputsCurrentAtCompletion,
+    framework:bundle.framework,profile:bundle.profile,mode:bundle.mode,scenario:bundle.scenario,observedPreviewRevision:bundle.observedPreviewRevision,
+    details:compactRow(details,1536),
+    acceptance:compactAcceptance(bundle.acceptance),counts:Object.fromEntries(investigationSections.slice(2).map(key=>[key,bundle[key]?.length??0])),resourceUri:bundle.resourceUri,byteLimit:resultBudgets.summary};
+  if(jsonBytes(result)>resultBudgets.summary){delete result.resourceUri;result.resourceUriOmitted=true;result.details=compactRow(result.details,512);}
+  if(jsonBytes(result)>resultBudgets.summary){result.acceptance={status:bundle.acceptance?.status,detailTruncated:true};delete result.scenario;delete result.observedPreviewRevision;result.detailTruncated=true;}
+  if(jsonBytes(result)>resultBudgets.summary)throw new Error("Investigation identity exceeds the summary budget.");
+  return result;
+}
+
 export function investigationArtifacts(root,report,attachments=[]) {
   return attachments.slice(0,5).flatMap(attachment=>{
     if(typeof attachment?.path!=="string")return [];
@@ -57,9 +87,10 @@ export function investigationArtifacts(root,report,attachments=[]) {
 /** 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);
+    const url=new URL(uri),parts=url.pathname.slice(1).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]}))};
+    if([...url.searchParams.keys()].some(key=>!["section","runId","cursor","limit","recordIndex","offset","chars"].includes(key)))throw new Error("Unknown investigation resource query.");
+    return {uri,mimeType:"application/json",text:JSON.stringify(investigationPage(root,{unit:parts[0],check:parts[1],section:url.searchParams.get("section")??"summary",runId:url.searchParams.get("runId")??undefined,cursor:url.searchParams.get("cursor")??undefined,...Object.fromEntries(["limit","recordIndex","offset","chars"].filter(key=>url.searchParams.has(key)).map(key=>[key,Number(url.searchParams.get(key))]))}))};
   }
   const artifact=Object.values(saved(root)).flatMap(bundle=>bundle.artifacts??[]).find(artifact=>artifact.resourceUri===uri);
   const file=artifact&&artifactPath(root,artifact.path);

package/dist/linaria/preserve-values.cjs

@@ -8,6 +8,23 @@ module.exports = function preserveCustomProperties(Processor) {
   return class PreservedCustomProperties extends Processor {
     extractRules(valueCache, cssText, loc) {
       const source = postcss.parse(cssText);
+      const registrations = [];
+      const layerOrder=[];
+      // Moving a registration must not change which named layer was first seen.
+      source.walkAtRules("layer",rule=>{
+        if(!rule.nodes||!rule.params.trim())return;
+        let statement=postcss.atRule({name:"layer",params:rule.params});
+        for(let parent=rule.parent;parent&&parent.type!=="root";parent=parent.parent){if(parent.type!=="atrule")return;const wrapper=parent.clone({nodes:[]});wrapper.raws.semicolon=true;wrapper.append(statement);statement=wrapper;}
+        layerOrder.push(statement.toString()+(statement.nodes?"":";"));
+      });
+      source.walkAtRules(/^property$/i, rule => {
+        let extracted=rule.clone();
+        for(let parent=rule.parent;parent&&parent.type!=="root";parent=parent.parent){
+          if(parent.type!=="atrule")throw new Error("@property is document-global. Put it at the Linaria template's top level or inside conditional at-rules, not inside an element selector.");
+          const wrapper=parent.clone({nodes:[]});wrapper.append(extracted);extracted=wrapper;
+        }
+        registrations.push(extracted.toString());rule.remove();
+      });
       const values = new Map();
       source.walkDecls(declaration => {
         if (!declaration.prop.startsWith("--")) return;
@@ -17,9 +34,9 @@ module.exports = function preserveCustomProperties(Processor) {
         declaration.value = marker;
         delete declaration.raws.value;
       });
-      if (!values.size) return super.extractRules(valueCache, cssText, loc);
+      if (!values.size && !registrations.length) return super.extractRules(valueCache, cssText, loc);
       const rules = super.extractRules(valueCache, source.toString(), loc);
-      return Object.fromEntries(Object.entries(rules).map(([key, rule]) => {
+      const restoredRules=Object.fromEntries(Object.entries(rules).map(([key, rule]) => {
         const output = postcss.parse(rule.cssText);
         output.walkDecls(declaration => {
           if (declaration.prop.startsWith("--") && values.has(declaration.value)) declaration.value = values.get(declaration.value);
@@ -27,6 +44,8 @@ module.exports = function preserveCustomProperties(Processor) {
         const restored = output.toString();
         return [rule.atom ? restored : key, { ...rule, cssText: restored }];
       }));
+      const globalRule=cssText=>({cssText,start:loc?.start??null,className:this.className,displayName:this.displayName,atom:true});
+      return {...Object.fromEntries(registrations.length?layerOrder.map(css=>[css,globalRule(css)]):[]),...restoredRules,...Object.fromEntries(registrations.map(css=>[css,globalRule(css)]))};
     }
   };
 };

package/dist/mcp/behavior-pages.mjs

@@ -0,0 +1,36 @@
+import { behaviorStatus } from "../verification.mjs";
+import { compactRow, resultPage } from "./result-pages.mjs";
+
+export const behaviorSections = ["owners", "checks", "guarantees", "subjects", "demonstrations", "profiles"];
+const checkResult = (unit, id, result) => {
+  const {status,current,revision,runId,profile,case:caseId,durationMs,completedAt,failure}=result;
+  return {status,current,revision,runId,profile,case:caseId,durationMs,completedAt,...(failure?{failure}:{}),
+    ...(runId?{investigation:{unit,check:id,runId}}:{})};
+};
+
+/** Discovery never embeds stored runner reports or investigation bodies. */
+export function behaviorPage(options, {unit,api,query="",section=unit?"checks":"owners",cursor,limit} = {}) {
+  if(!behaviorSections.includes(section)||section!=="owners"&&!unit)throw new Error("Select an exact unit before paging behavioral details.");
+  const inventory=behaviorStatus(options);
+  const matches=inventory.contracts.filter(contract=>(!unit||contract.unit===unit)&&(!api||Object.values(contract.subjects).some(subject=>subject.api===api))&&JSON.stringify([contract.unit,contract.subjects,contract.guarantees.map(({id,description})=>({id,description}))]).toLowerCase().includes(query.toLowerCase()));
+  let rows;
+  if(section==="owners") rows=matches.map(contract=>({unit:contract.unit,file:contract.file,
+    apis:Object.values(contract.subjects).filter(subject=>subject.api).map(subject=>subject.api).slice(0,10),
+    apiCount:Object.values(contract.subjects).filter(subject=>subject.api).length,
+    checkCount:Object.keys(contract.checks).length,guaranteeCount:contract.guarantees.length,
+    guarantees:contract.guarantees.slice(0,3).map(({id,result})=>({id,result})),guaranteesTruncated:contract.guarantees.length>3,
+    sections:{checks:Object.keys(contract.checks).length,guarantees:contract.guarantees.length,subjects:Object.keys(contract.subjects).length,demonstrations:Object.keys(contract.demonstrations).length},
+    next:{tool:"ads_behaviors",arguments:{unit:contract.unit,section:"checks"}}}));
+  else {
+    const contract=matches[0];
+    if(!contract)throw new Error("No behavior contract matches this unit/filter.");
+    if(section==="checks")rows=Object.entries(contract.checks).map(([id,{result,...check}])=>({id,...check,result:checkResult(contract.unit,id,result)}));
+    if(section==="guarantees")rows=contract.guarantees;
+    if(section==="subjects")rows=Object.entries(contract.subjects).map(([id,subject])=>({id,...subject}));
+    if(section==="demonstrations")rows=Object.entries(contract.demonstrations).map(([subject,scenarios])=>({subject,scenarios}));
+    if(section==="profiles")rows=[...new Set(Object.values(contract.checks).map(check=>check.profile))].map(id=>({id,...options.config.mcp.behaviorProfiles[id]}));
+  }
+  const revision=matches.map(contract=>[contract.unit,contract.file,Object.entries(contract.checks).map(([id,check])=>[id,check.result.revision,check.result.status,check.result.runId])]);
+  return resultPage(rows,{cursor,limit,identity:["behaviors",section,unit,api,query,revision,rows],key:section==="owners"?"contracts":"items",
+    header:{section,...(unit?{unit,sourceFile:matches[0]?.file}:{}),diagnosticCount:inventory.diagnostics.length,diagnostics:inventory.diagnostics.slice(0,2).map(row=>compactRow(row,384)),resourceUri:"ads://project/behaviors"}});
+}

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. 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.";
+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. Execution replies are bounded summaries. Read only needed sections with ads_results(resultId, section, status, cursor); follow nextCursor without rerunning. For a failure, inspect its boundary and acceptance, then ads_investigate with the outcome's exact unit/check/runId; detail sections and artifacts load separately (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];
@@ -58,6 +58,8 @@ Use this server for UI components/patterns, tokens/themes/branding, layout, inte
    Inspection connects a public export to its owning source, available guides, token values and discovered preview IDs. Bounded tools keep discovery focused; explicit resource reads supply detail. Source metadata does not prove layout, interaction or motion. A scenario renders the real public implementation and its fixture context in either review surface.
 5. Check ads_status.mutations. When enabled, discover one owner with ads_units, read relevant source ranges with ads_read_file and submit only a Git unified diff through ads_apply_patch({unit, patch, dryRun}). Include that owner's scenarios, fixtures and required public re-exports, never peer units. tokens is the foundation unit; its manifest lists companionFiles for required canonical foundation imports when token files are created/deleted in the same patch. Preserve unrelated imports/comments and public-entry statements; a real selected-owner re-export can remove its redundant export {};. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit; use ads_apply_transaction for coupled owners instead of bypassing rejection with direct writes. ads_prepare_patch creates a local owner draft/diff; ads_prepare_token_samples reconciles explicit project bindings without guessing visual meaning. Intentional project setup, registered guard/compiler code and exceptions use configuration; shared globals use foundation, guides documentation and assets their discovered assets/* unit. Keep mandatory ADS gates. Binary/large Git diffs may use patchFile under .ds/patches/ to avoid model-context bytes. In read-only mode, source edits use the client editor/filesystem tools. Reuse the local public API (${context.publicEntry}). Edit presentation in its ADS owner; keep application data/services/routing in application code and development fixtures beside their scenario; larger scenarios live in composition/. Linaria extracts owned styling. Inspect relevant tokens with ads_tokens and source/owning guides before edits.
 6. ${route.validation} Registered commands: ${context.commands.map((command) => command.args?.join(" ") ?? `choose the project package manager for ${command.script}`).join("; ") || "none discovered; inspect the project's build setup"}. Run them from ${context.projectRoot}.
+Execution replies from ads_verify and guarded edits contain counts, acceptance and resultId, not full reports. Read only needed outcomes/diagnostics/captures with ads_results, following nextCursor with identical filters. A truncated row has recordIndex for bounded text ranges. For one failure, use ads_investigate with its unit/check/runId; read request/error/artifact sections only when needed. Only the latest verification and mutation results, and latest investigation per check, are available. Notifications do not establish freshness.
+
 7. After edits, inspect ads_status.build or ads://project/build explicitly. Running/unreported/old output is not a current successful preview. Fix diagnostics in owned source, wait for rebuilding and invoke the preview tool again. Notifications may not start an agent turn.
 
 Project guide resources: ${context.guides.map((guide) => `${guide.file}: ${guide.uri}`).join("; ") || "none discovered"}.

package/dist/mcp/execution-results.mjs

@@ -0,0 +1,146 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { compactAcceptance, compactRow, jsonBytes, resultBudgets, resultPage, resultRecord } from "./result-pages.mjs";
+
+export const RESULTS_URI = "ads://project/results";
+export const resultSections = ["outcomes", "checks", "diagnostics", "advisories", "warnings", "changes", "captures", "acceptance", "investigation", "selection"];
+const kinds = ["verification", "mutation"];
+const maxStoredBytes = 8 * 1024 * 1024;
+const uuid = value => typeof value === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value);
+const resultUri = id => `ads://results/${id}`;
+const count = items => {
+  const statuses = {};
+  for (const item of items) { const status = item.status ?? (item.skipped ? "skipped" : item.passed === true ? "passed" : item.passed === false ? "failed" : "unknown"); statuses[status] = (statuses[status] ?? 0) + 1; }
+  return { total: items.length, ...statuses };
+};
+
+function outcome(item) {
+  const { current, investigation, ...detail } = item;
+  return { ...detail, inputsCurrentAtCompletion:current,
+    investigation: { unit:item.unit, check:item.check, runId:item.runId, resourceUri:investigation?.resourceUri } };
+}
+
+function snapshot(kind, raw) {
+  const outcomes = raw.results ?? raw.behavior?.results ?? (raw.checks ?? []).flatMap(check => check.results ?? []);
+  const sections = {
+    outcomes: outcomes.map(outcome),
+    checks: (raw.checks ?? []).map(({ results, ...check }) => ({ ...check, ...(results ? { outcomeCount: results.length } : {}) })),
+    diagnostics: raw.diagnostics ?? [], advisories: raw.advisories ?? [], warnings: raw.warnings ?? [], changes: raw.changes ?? [],
+    captures: raw.screenshots?.captures ?? [], selection: [{unit:raw.unit,units:raw.units,transaction:raw.transaction}],
+    acceptance: raw.acceptance ? [raw.acceptance] : [], investigation: raw.investigation ? [raw.investigation] : [],
+  };
+  const resultId = randomUUID();
+  return { schemaVersion: 1, resultId, kind, createdAt: new Date().toISOString(), ok: !!raw.ok,
+    ...(raw.applied !== undefined ? { applied: raw.applied } : {}), ...(raw.unit ? { unit: raw.unit } : {}),
+    ...(raw.units ? { units: raw.units } : {}), ...(raw.transaction ? { transaction: true } : {}),
+    acceptance: raw.acceptance, investigation: raw.investigation,
+    sections: Object.fromEntries(Object.entries(sections).map(([key, rows]) => [key, rows.map((row, recordIndex) => ({ recordIndex, ...(row && typeof row === "object" ? row : {message:row}) }))])),
+    counts: { outcomes: count(outcomes), checks: count(sections.checks), diagnostics: sections.diagnostics.length,
+      advisories: sections.advisories.length, warnings: sections.warnings.length, changes: sections.changes.length, captures: sections.captures.length },
+    resourceUri: resultUri(resultId) };
+}
+
+function summary(value, storageWarning) {
+  const { ok, resultId, kind, applied, unit, units, transaction, createdAt, counts, resourceUri } = value;
+  const failedOutcomes = value.sections.outcomes.filter(item => item.status !== "passed");
+  const failureRows = failedOutcomes.length ? failedOutcomes : value.sections.diagnostics;
+  const section = failedOutcomes.length ? "outcomes" : value.sections.diagnostics.length ? "diagnostics" : value.sections.captures.length ? "captures" : value.sections.outcomes.length ? "outcomes" : "checks";
+  const result = { ok, resultId, kind, ...(applied !== undefined ? { applied } : {}), ...(unit ? { unit } : {}),
+    ...(units ? { units } : {}), ...(transaction ? { transaction } : {}), createdAt, counts, freshness:"recorded-at-completion",
+    acceptance: compactAcceptance(value.acceptance), failures: value.failurePreview ?? failureRows.slice(0, 3).map(item => compactRow({recordIndex:item.recordIndex,unit:item.unit,check:item.check,status:item.status,rule:item.rule,file:item.file,failure:item.failure,message:item.message},640)),
+    failureCount: value.failureCount ?? failureRows.length, resourceUri,
+    next: value.detailsUnavailable ? null : { tool: "ads_results", arguments: { resultId, section, ...(section === "outcomes" && failedOutcomes.length ? { status: "not_passed" } : {}) } },
+    ...((storageWarning ?? value.storageWarning) ? { storageWarning: storageWarning ?? value.storageWarning } : {}), byteLimit: resultBudgets.summary };
+  if (jsonBytes(result) > resultBudgets.summary) {
+    result.failures = failureRows.slice(0, 3).map(item => compactRow(item, 384));
+    result.detailTruncated = true;
+  }
+  if (jsonBytes(result) > resultBudgets.summary) {
+    result.failures = []; result.detailTruncated = true;
+    result.acceptance = { scope: value.acceptance?.scope, status: value.acceptance?.status, detailTruncated: true };
+  }
+  if (jsonBytes(result) > resultBudgets.summary) {
+    delete result.unit; delete result.units;
+    result.acceptance = { status: value.acceptance?.status, detailTruncated: true };
+  }
+  return result;
+}
+
+/** One immutable, replaceable snapshot per execution kind. No result history. */
+export function createExecutionResults(root) {
+  root = path.resolve(root);
+  const folder = path.join(root, ".ds/tool-results"), memory = new Map();
+  function file(kind) { return path.join(folder, `${kind}.json`); }
+  function read(kind) {
+    const temporary = memory.get(kind);
+    if (temporary?.memoryOnly) return temporary.value;
+    const target = file(kind);
+    try {
+      if (realpathSync(target) !== target || !lstatSync(target).isFile() || lstatSync(target).nlink !== 1 || lstatSync(target).size > maxStoredBytes) return undefined;
+      const value = JSON.parse(readFileSync(target, "utf8"));
+      return value.schemaVersion === 1 && value.kind === kind && uuid(value.resultId) && resultSections.every(section => Array.isArray(value.sections?.[section])) ? value : undefined;
+    } catch { return undefined; }
+  }
+  function find(resultId) {
+    if (!uuid(resultId)) throw new Error("Use an exact resultId returned by an execution summary.");
+    const value = kinds.map(read).find(value => value?.resultId === resultId);
+    if (!value) throw new Error("Result is unavailable or superseded. Only the latest completed result of each kind is retained; discover its ID with ads_status.");
+    return value;
+  }
+  return {
+    save(kind, raw) {
+      if (!kinds.includes(kind)) throw new Error("Unknown execution kind.");
+      const value = snapshot(kind, raw);
+      let content = JSON.stringify(value);
+      if (Buffer.byteLength(content) > maxStoredBytes) {
+        const preview=summary(value);
+        value.failurePreview=preview.failures;value.failureCount=preview.failureCount;
+        value.sections=Object.fromEntries(resultSections.map(section=>[section,[]]));
+        value.acceptance=preview.acceptance;delete value.investigation;
+        value.detailsUnavailable=true;
+        value.storageWarning="Result details exceeded the 8 MiB retention limit. Only this summary is retained; execution and applied state above are unchanged.";
+        content=JSON.stringify(value);
+      }
+      let storageWarning;
+      try {
+        let ancestor=folder;
+        while(true){try{lstatSync(ancestor);break;}catch(error){if(error.code!=="ENOENT")throw error;ancestor=path.dirname(ancestor);}}
+        if(realpathSync(ancestor)!==ancestor)throw new Error("Result output cannot resolve through a symlink.");
+        mkdirSync(folder, { recursive: true });
+        if (realpathSync(folder) !== folder) throw new Error("Result output cannot resolve through a symlink.");
+        const staged = `${file(kind)}.${randomUUID()}.tmp`;
+        try { writeFileSync(staged, content); renameSync(staged, file(kind)); } finally { rmSync(staged, { force: true }); }
+        memory.set(kind, { value, memoryOnly: false });
+      } catch {
+        memory.set(kind, { value: JSON.parse(content), memoryOnly: true });
+        storageWarning = "Result details are available in this server's memory only; storage failed. Execution and applied state above are unchanged.";
+      }
+      return summary(value, storageWarning);
+    },
+    latest(kind) { const value = read(kind); return value ? summary(value, memory.get(kind)?.memoryOnly ? "Result details are in server memory only." : undefined) : null; },
+    index() { return { retention: "latest-per-kind", results: kinds.map(kind => this.latest(kind)).filter(Boolean).map(({resultId,kind,ok,applied,createdAt,counts,resourceUri})=>({resultId,kind,ok,applied,createdAt,counts,resourceUri})) }; },
+    fingerprint() { return kinds.map(kind=>{if(memory.get(kind)?.memoryOnly)return memory.get(kind).value.resultId;try{const stat=lstatSync(file(kind));return `${kind}:${stat.mtimeMs}:${stat.size}`;}catch{return `${kind}:missing`;}}).join("\n"); },
+    page({ resultId, section = "outcomes", status = "all", cursor, limit, recordIndex, offset, chars } = {}) {
+      const value = find(resultId);
+      if(value.detailsUnavailable)throw new Error("This result exceeded the 8 MiB retention limit; only its summary is available.");
+      if (!resultSections.includes(section) || !["all", "passed", "not_passed"].includes(status) || status !== "all" && section !== "outcomes") throw new Error("Select a registered result section; status filters apply only to outcomes.");
+      if (recordIndex !== undefined) {
+        if (cursor !== undefined || status !== "all") throw new Error("Read record ranges without a cursor or status filter.");
+        return resultRecord(value.sections[section],{recordIndex,offset,chars,header:{resultId,section}});
+      }
+      if(offset!==undefined||chars!==undefined)throw new Error("Select a recordIndex before reading text ranges.");
+      const rows = value.sections[section].filter(row => status === "all" || (status === "passed" ? row.status === "passed" : row.status !== "passed"));
+      return resultPage(rows, { cursor, limit, identity: [resultId, section, status], header: { resultId, kind: value.kind, section, status, freshness:"recorded-at-completion" } });
+    },
+    readResource(uri) {
+      if (uri === RESULTS_URI) return { uri, mimeType: "application/json", text: JSON.stringify(this.index()) };
+      const url = new URL(uri);
+      if (url.protocol !== "ads:" || url.hostname !== "results" || [...url.searchParams.keys()].some(key => !["section", "status", "cursor", "limit", "recordIndex", "offset", "chars"].includes(key))) throw new Error("Invalid execution result resource URI.");
+      const id = url.pathname.slice(1);
+      const value = url.search ? this.page({ resultId: id, section: url.searchParams.get("section") ?? "outcomes", status: url.searchParams.get("status") ?? "all", cursor: url.searchParams.get("cursor") ?? undefined,
+        ...Object.fromEntries(["limit","recordIndex","offset","chars"].filter(key=>url.searchParams.has(key)).map(key=>[key,Number(url.searchParams.get(key))])) }) : summary(find(id));
+      return { uri, mimeType: "application/json", text: JSON.stringify(value) };
+    },
+  };
+}

package/dist/mcp/mutations.mjs

@@ -279,7 +279,7 @@ export function createMutationController(directory, { captures = createCaptureCo
         const expected = snapshot(candidateOptions);
         candidateRevision=digest(Buffer.from(expected));
         const result = checkProject(candidate, { trackingRoot: root });
-        if (!result.ok) return lastResult = mutationEvidence({ ok: false, applied: false, diagnostics: result.diagnostics.slice(0, 50), total: result.diagnostics.length, checks: verified },candidateRevision);
+        if (!result.ok) return lastResult = mutationEvidence({ ok: false, applied: false, diagnostics: result.diagnostics, 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"));
@@ -305,7 +305,7 @@ export function createMutationController(directory, { captures = createCaptureCo
           let evidence;
           try { evidence = await verification.run({ units: behaviorUnits, persist: false }, signal); }
           finally { await verification.close(); }
-          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);
+          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], checks: verified, behavior: evidence },candidateRevision);
           verified.push({ name: "registered behavior checks", passed: true, results: evidence.results });
         }
         let screenshots;
@@ -353,7 +353,7 @@ 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 = 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 } : {}),
+        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, 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." },candidateRevision);
       } catch (error) {

package/dist/mcp/result-pages.mjs

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+
+export const resultBudgets = { summary: 4096, page: 8192, row: 2048, defaultLimit: 10, maxLimit: 20 };
+export const jsonBytes = value => Buffer.byteLength(JSON.stringify(value));
+
+/** Projection is only for delivery; validation always uses the complete result. */
+export function compactValue(input, { string = 500, array = 8, keys = 24, depth = 5 } = {}) {
+  let truncated = false;
+  function visit(value, level) {
+    if (typeof value === "string") {
+      if (value.length <= string) return value;
+      truncated = true; return `${value.slice(0, string)}…`;
+    }
+    if (value === null || typeof value === "number" || typeof value === "boolean" || value === undefined) return value;
+    if (level >= depth) { truncated = true; return "[omitted]"; }
+    if (Array.isArray(value)) { if (value.length > array) truncated = true; return value.slice(0, array).map(item => visit(item, level + 1)); }
+    const entries = Object.entries(value);
+    if (entries.length > keys) truncated = true;
+    return Object.fromEntries(entries.slice(0, keys).map(([key, item]) => [key, visit(item, level + 1)]));
+  }
+  const value = visit(input, 0);
+  return { value, truncated };
+}
+
+export function compactRow(input, bytes = resultBudgets.row) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) input = { value: input };
+  for (const limits of [{}, { string: 160, array: 3, keys: 18 }, { string: 60, array: 1, keys: 12, depth: 3 }]) {
+    const { value, truncated } = compactValue(input, limits);
+    const row = { ...value, ...(truncated ? { detailTruncated: true } : {}) };
+    if (jsonBytes(row) <= bytes) return row;
+  }
+  const row = Object.fromEntries(["recordIndex", "id", "unit", "check", "status", "passed", "rule", "file", "path", "name"].filter(key => input[key] !== undefined).slice(0, 4).map(key => [key, typeof input[key] === "string" ? input[key].slice(0, 20) : input[key]]));
+  const result = { ...row, detailTruncated: true };
+  return jsonBytes(result) <= bytes ? result : { detailTruncated: true };
+}
+
+export function compactAcceptance(value) {
+  if (!value) return undefined;
+  const establishedCount=value.establishedCount??value.established?.length??0,unverifiedCount=value.unverifiedCount??value.unverified?.length??0;
+  return { scope: value.scope, status: value.status, establishedCount, unverifiedCount,
+    established: (value.established ?? []).slice(0, 3).map(item => String(item).slice(0, 100)),
+    unverified: (value.unverified ?? []).slice(0, 12).map(item => String(item).slice(0, 100)),
+    ...(value.detailTruncated || establishedCount > 3 || unverifiedCount > 12 ? { detailTruncated: true } : {}) };
+}
+
+/** The cursor binds the immutable result/query, not just an array offset. */
+export function resultPage(items, { cursor, limit = resultBudgets.defaultLimit, identity, header = {}, key = "items" } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > resultBudgets.maxLimit) throw new Error("Use a page limit from 1 to 20.");
+  const stamp = createHash("sha256").update(JSON.stringify(identity)).digest("hex").slice(0, 24);
+  let offset = 0;
+  if (cursor !== undefined) {
+    if (typeof cursor !== "string" || cursor.length > 300) throw new Error("Invalid result cursor.");
+    const match = /^([a-f0-9]{24}):(\d+)$/.exec(cursor);
+    offset = match && match[1] === stamp ? Number(match[2]) : -1;
+    if (!Number.isSafeInteger(offset) || offset <= 0 || offset >= items.length) throw new Error("Invalid or stale result cursor; restart this listing.");
+  }
+  const selected = [];
+  const envelope = () => ({ ...header, total: items.length, returned: selected.length, byteLimit: resultBudgets.page, [key]: selected,
+    ...(offset + selected.length < items.length ? { nextCursor: `${stamp}:${offset + selected.length}` } : {}) });
+  for (const item of items.slice(offset, offset + limit)) {
+    selected.push(compactRow(item));
+    if (jsonBytes(envelope()) > resultBudgets.page) { selected.pop(); break; }
+  }
+  if (offset < items.length && !selected.length) throw new Error("The page envelope exceeds the response budget.");
+  const result = envelope();
+  if (jsonBytes(result) > resultBudgets.page) throw new Error("The page exceeds its response budget.");
+  return result;
+}
+
+export function compactProgress(value) {
+  if (!value) return undefined;
+  const { stage, profile, elapsedMs, timeoutMs, total, completed, pending, workers } = value;
+  return { stage, profile, elapsedMs, timeoutMs, total, completed, pending, workers, activeCount: value.active?.length ?? 0,
+    active: (value.active ?? []).slice(0, 3).map(item => compactRow(item, 512)) };
+}
+
+/** Exact JSON ranges complement lossy row previews without unbounded replies. */
+export function resultRecord(rows, { recordIndex, offset = 0, chars = 2000, header = {} } = {}) {
+  if (!Number.isInteger(recordIndex) || recordIndex < 0 || recordIndex >= rows.length || !Number.isInteger(offset) || offset < 0 || !Number.isInteger(chars) || chars < 1 || chars > 2000) throw new Error("Read a valid recordIndex with an offset and 1–2000 characters.");
+  const source=JSON.stringify(rows[recordIndex]);
+  if(offset>source.length)throw new Error("Offset exceeds the selected record.");
+  let end=Math.min(source.length,offset+chars);
+  const result=()=>({...header,recordIndex,offset,totalChars:source.length,text:source.slice(offset,end),nextOffset:end<source.length?end:null,byteLimit:resultBudgets.page});
+  while(jsonBytes(result())>resultBudgets.page&&end>offset)end=offset+Math.floor((end-offset)*0.8);
+  if(jsonBytes(result())>resultBudgets.page||end===offset&&offset<source.length)throw new Error("Record identity exceeds the response budget.");
+  return result();
+}