@reqvire-org/ads 0.3.18 → 0.3.21

package/dist/runtime-contracts.mjs

@@ -0,0 +1,225 @@
+import path from "node:path";
+import ts from "typescript";
+import selectorParser from "postcss-selector-parser";
+import { isDevelopmentFile, isReviewFile } from "./config.mjs";
+import { inspectUnitContracts, implementationIdentity, implementationNode } from "./unit-contracts.mjs";
+import { tokenContract } from "./token-policy.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+import { unwrap, createSourceValues, reference } from "./source-values.mjs";
+
+function fn(node) { return node && ts.isVariableDeclaration(node) ? unwrap(node.initializer) : node; }
+function all(node, predicate) { const result=[];function visit(item){if(predicate(item))result.push(item);ts.forEachChild(item,visit);}if(node)visit(node);return result; }
+
+export function inspectRuntimeContracts(options, program) {
+  if(options.runtimeContracts?.program===program)return options.runtimeContracts;
+  const checker=program.getTypeChecker(), declarations=inspectUnitContracts(options);
+  const result={program,diagnostics:[],bindings:[],parts:[],allowedStyles:new Set(),allowedStyleTypes:new Set()};
+  options.runtimeContracts=result;
+  const key=node=>`${node.getSourceFile().fileName}:${node.pos}`;
+  const values=createSourceValues(program,options,{strict:true});
+  const canonical=node=>{
+    if(!node)return null;
+    let symbol=checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node)?node.name:node);
+    if(symbol?.flags&ts.SymbolFlags.Alias)symbol=checker.getAliasedSymbol(symbol);
+    return symbol?.valueDeclaration;
+  };
+  const same=(node,reference)=>{const declaration=canonical(node);return declaration&&implementationIdentity(declaration,options.root)===reference.identity;};
+  function report(contract,message,code="runtime-contract") {result.diagnostics.push({file:contract.file,rule:code,line:1,column:1,message});}
+  function localCalls(node,seen=new Set()) {
+    if(!node||seen.has(node)||seen.size>32)return [];
+    seen=new Set([...seen,node]);const found=[node];
+    for(const call of all(node,ts.isCallExpression)) {
+      const target=canonical(call.expression);
+      if(target&&path.resolve(target.getSourceFile().fileName).startsWith(options.dsRoot+path.sep)&&(!isDevelopmentFile(target.getSourceFile().fileName,options)||isReviewFile(target.getSourceFile().fileName,options)))found.push(...localCalls(fn(target),seen));
+    }
+    return found;
+  }
+  for(const contract of declarations.contracts) {
+    for(const part of contract.declarativeParts??[]) {
+      const consumer=fn(implementationNode(program,part.consumer,options.root));
+      const bodies=localCalls(consumer),calls=bodies.flatMap(body=>all(body,ts.isCallExpression));
+      function childOrigins(expression,seen=new Set()) {
+        expression=unwrap(expression);if(!expression||seen.has(expression)||seen.size>40)return new Set();
+        seen=new Set([...seen,expression]);
+        const merge=sets=>new Set(sets.flatMap(set=>[...set]));
+        if(ts.isPropertyAccessExpression(expression)&&expression.name.text==="children") {
+          if(canonical(expression.expression)===consumer?.parameters?.[0])return new Set(["children-input"]);
+          if(ts.isPropertyAccessExpression(expression.expression)&&expression.expression.name.text==="props"&&childOrigins(expression.expression.expression,seen).size)return new Set([key(expression)]);
+        }
+        const declaration=canonical(expression);
+        if(declaration&&ts.isBindingElement(declaration)&&ts.isObjectBindingPattern(declaration.parent)&&declaration.parent.parent===consumer?.parameters?.[0]&&(declaration.propertyName??declaration.name).getText()==="children")return new Set(["children-input"]);
+        if(declaration&&ts.isVariableDeclaration(declaration)) {
+          if(declaration.initializer)return childOrigins(declaration.initializer,seen);
+          if(ts.isVariableDeclarationList(declaration.parent)&&ts.isForOfStatement(declaration.parent.parent)&&childOrigins(declaration.parent.parent.expression,seen).size)return new Set([key(declaration)]);
+        }
+        if(declaration&&ts.isParameter(declaration)) {
+          const callback=declaration.parent,index=callback.parameters.indexOf(declaration),origins=[];
+          for(const call of calls) {
+            if(fn(canonical(call.expression))===callback&&call.arguments[index])origins.push(childOrigins(call.arguments[index],seen));
+            const operation=uiOperation(call.expression,checker);
+            const childrenCall=["Children.map","Children.forEach"].includes(operation)&&call.arguments[1]&&(call.arguments[1]===callback||fn(canonical(call.arguments[1]))===callback);
+            const arrayCall=ts.isPropertyAccessExpression(call.expression)&&["map","forEach","flatMap"].includes(call.expression.name.text)&&call.arguments[0]&&(call.arguments[0]===callback||fn(canonical(call.arguments[0]))===callback);
+            if(index===0&&(childrenCall&&childOrigins(call.arguments[0],seen).size||arrayCall&&childOrigins(call.expression.expression,seen).size))origins.push(new Set([key(declaration)]));
+          }
+          return merge(origins);
+        }
+        if(ts.isCallExpression(expression)) {
+          if(["Children.toArray","toChildArray"].includes(uiOperation(expression.expression,checker)))return childOrigins(expression.arguments[0],seen);
+          if(ts.isPropertyAccessExpression(expression.expression)&&["filter","slice"].includes(expression.expression.name.text))return childOrigins(expression.expression.expression,seen);
+        }
+        return new Set();
+      }
+      const propOrigins=new Set(bodies.flatMap(body=>all(body,ts.isPropertyAccessExpression).filter(node=>node.name.text==="props").flatMap(node=>[...childOrigins(node.expression)])));
+      const readsProps=expression=>[...childOrigins(expression)].some(origin=>propOrigins.has(origin));
+      let consumed=false;
+      for(const body of bodies) {
+        for(const binary of all(body,ts.isBinaryExpression)) {
+          if(![ts.SyntaxKind.EqualsEqualsEqualsToken,ts.SyntaxKind.EqualsEqualsToken].includes(binary.operatorToken.kind))continue;
+          for(const [value,identity]of[[binary.left,binary.right],[binary.right,binary.left]])if(ts.isPropertyAccessExpression(value)&&value.name.text==="type"&&same(identity,part.api)&&readsProps(value.expression))consumed=true;
+        }
+        for(const call of all(body,ts.isCallExpression))for(const [index,arg]of call.arguments.entries())if(same(arg,part.api)) {
+          const helper=fn(canonical(call.expression)),parameter=helper?.parameters?.[index];
+          if(!parameter||!ts.isIdentifier(parameter.name))continue;
+          const parameterSymbol=checker.getSymbolAtLocation(parameter.name);
+          for(const binary of all(helper,ts.isBinaryExpression))if([ts.SyntaxKind.EqualsEqualsEqualsToken,ts.SyntaxKind.EqualsEqualsToken].includes(binary.operatorToken.kind))for(const [value,identity]of[[binary.left,binary.right],[binary.right,binary.left]]) {
+            if(!ts.isPropertyAccessExpression(value)||value.name.text!=="type"||checker.getSymbolAtLocation(identity)!==parameterSymbol)continue;
+            const childParameter=canonical(value.expression),childIndex=helper.parameters.indexOf(childParameter);
+            if(childIndex>=0&&readsProps(call.arguments[childIndex]))consumed=true;
+          }
+        }
+      }
+      if(!consumer||!consumed)report(contract,`${part.apiName}: cannot establish that ${part.consumer.symbol} identifies this declarative child from its children input by resolved symbol and reads that same child's props. A registration, decoy object, import or unused reference is not consumption.`,"declarative-consumer");
+      else result.parts.push({...part,unit:contract.unit,file:contract.file});
+    }
+    for(const [name,binding]of Object.entries(contract.bindings??{})) {
+      const producer=fn(implementationNode(program,binding.producer,options.root));
+      const [prefix,suffix]=binding.variable.split("${key}");
+      if(!(contract.paintInputs??[]).some(input=>input.api.identity===binding.input.api.identity&&input.property===`${binding.input.property}.*.${binding.valueFrom}`)) {report(contract,`${name}: register the actual config-entry value path as a constrained paint input. A producer does not authorize untyped config colours.`,"binding-input");continue;}
+      if([...tokenContract.naming.prefixes,"--ds-","--ux-","--showcase-"].some(value=>value.startsWith(prefix)||prefix.startsWith(value))||[...tokenContract.naming.names,...Object.keys(tokenContract.tokens)].some(value=>value.startsWith(prefix)&&value.endsWith(suffix))) {
+        report(contract,`${name}: runtime family ${binding.variable} overlaps the shared token vocabulary. Use a nonconflicting private runtime family; registration cannot grant shared-token overrides.`,"binding-collision");continue;
+      }
+      const other=result.bindings.find(entry=>entry.prefix.startsWith(prefix)||prefix.startsWith(entry.prefix));
+      if(other){report(contract,`${name}: runtime family overlaps ${other.unit}/${other.name}. Keep binding ownership unambiguous.`,"binding-collision");continue;}
+      let selector;
+      try {
+        const parsed=selectorParser().astSync(binding.scope.selector);
+        if(parsed.nodes.length!==1||parsed.first.nodes.length!==1||!["class","attribute"].includes(parsed.first.first.type))throw new Error();
+        selector=parsed.first.first;
+        if(selector.type==="attribute"&&(!selector.attribute.startsWith("data-")||selector.operator!=="="))throw new Error();
+      }catch{report(contract,`${name}: scope must name one actual owner-root class or exact data-* attribute, not a broad selector.`);continue;}
+      if(!producer?.parameters?.[0]||!ts.isIdentifier(producer.parameters[0].name)){report(contract,`${name}: producer requires an explicit config-map parameter.`);continue;}
+      const ownerFile=implementationNode(program,binding.producer,options.root).getSourceFile().fileName;
+      function builtInEntries(call, input) {
+        return ts.isCallExpression(call)&&call.arguments[0]&&ts.isPropertyAccessExpression(call.expression)&&call.expression.name.text==="entries"&&call.expression.expression.getText()==="Object"&&checker.getSymbolAtLocation(call.arguments[0])===input&&!checker.getSymbolAtLocation(call.expression.expression)?.declarations?.some(node=>node.getSourceFile().fileName.startsWith(options.root+path.sep)&&!node.getSourceFile().hasNoDefaultLib&&!node.getSourceFile().fileName.includes(`${path.sep}node_modules${path.sep}`));
+      }
+      function safeKey(body, keySymbol, before) {
+        return ts.isBlock(body)&&body.statements.some(statement=>{
+          if(!ts.isIfStatement(statement)||!ts.isPrefixUnaryExpression(statement.expression)||statement.expression.operator!==ts.SyntaxKind.ExclamationToken)return false;
+          const test=statement.expression.operand,stop=ts.isBlock(statement.thenStatement)?statement.thenStatement.statements[0]:statement.thenStatement;
+          return ts.isCallExpression(test)&&ts.isPropertyAccessExpression(test.expression)&&test.expression.name.text==="test"&&ts.isRegularExpressionLiteral(test.expression.expression)&&test.expression.expression.text==="/^[A-Za-z0-9_-]+$/"&&checker.getSymbolAtLocation(test.arguments[0])===keySymbol&&(ts.isThrowStatement(stop)||ts.isContinueStatement(stop))&&statement.end<=before;
+        });
+      }
+      function pairMatches(template,value,keySymbol,valueSymbol) {
+        template=unwrap(template);value=unwrap(value);
+        if(!template||!ts.isTemplateExpression(template)||template.templateSpans.length!==1||template.head.text!==prefix||template.templateSpans[0].literal.text!==suffix||checker.getSymbolAtLocation(template.templateSpans[0].expression)!==keySymbol)return false;
+        let valueRoot=value;const fields=[];while(ts.isPropertyAccessExpression(valueRoot)){fields.unshift(valueRoot.name.text);valueRoot=valueRoot.expression;}
+        return checker.getSymbolAtLocation(valueRoot)===valueSymbol&&fields.join(".")===binding.valueFrom;
+      }
+      function proveMap(body,seen=new Set()) {
+        if(!body?.parameters?.[0]||!ts.isIdentifier(body.parameters[0].name)||seen.has(body)||seen.size>8)return null;
+        seen=new Set([...seen,body]);const inputSymbol=checker.getSymbolAtLocation(body.parameters[0].name);
+        const returns=ts.isBlock(body.body)?all(body.body,ts.isReturnStatement).filter(node=>{for(let parent=node.parent;parent&&parent!==body;parent=parent.parent)if(ts.isFunctionLike(parent))return false;return true;}):[{expression:body.body}];
+        if(returns.length!==1)return null;
+        const returned=unwrap(returns[0].expression);
+        if(ts.isCallExpression(returned)) {
+          if(ts.isPropertyAccessExpression(returned.expression)&&returned.expression.expression.getText()==="Object"&&returned.expression.name.text==="fromEntries"&&!checker.getSymbolAtLocation(returned.expression.expression)?.declarations?.some(node=>node.getSourceFile().fileName.startsWith(options.root+path.sep)&&!node.getSourceFile().hasNoDefaultLib&&!node.getSourceFile().fileName.includes(`${path.sep}node_modules${path.sep}`))) {
+            const mapped=unwrap(returned.arguments[0]);
+            if(!mapped||!ts.isCallExpression(mapped)||!ts.isPropertyAccessExpression(mapped.expression)||mapped.expression.name.text!=="map"||!builtInEntries(unwrap(mapped.expression.expression),inputSymbol))return null;
+            const callback=unwrap(mapped.arguments[0]),tuple=callback?.parameters?.[0]?.name;
+            if(!callback||!ts.isArrowFunction(callback)||!tuple||!ts.isArrayBindingPattern(tuple)||tuple.elements.length!==2||!tuple.elements.every(ts.isBindingElement))return null;
+            const keySymbol=checker.getSymbolAtLocation(tuple.elements[0].name),valueSymbol=checker.getSymbolAtLocation(tuple.elements[1].name);
+            const outputs=ts.isBlock(callback.body)?all(callback.body,ts.isReturnStatement):[{expression:callback.body,pos:callback.body.pos}];
+            if(outputs.length!==1||!safeKey(callback.body,keySymbol,outputs[0].pos))return null;
+            const pair=unwrap(outputs[0].expression);
+            return pair&&ts.isArrayLiteralExpression(pair)&&pair.elements.length===2&&pairMatches(pair.elements[0],pair.elements[1],keySymbol,valueSymbol)?[body]:null;
+          }
+          const helper=canonical(returned.expression);
+          if(helper&&path.dirname(helper.getSourceFile().fileName)===path.dirname(ownerFile)&&checker.getSymbolAtLocation(returned.arguments[0])===inputSymbol){const proof=proveMap(fn(helper),seen);return proof?[body,...proof]:null;}
+          return null;
+        }
+        let mapSymbol;const writes=[];
+        for(const loop of all(body,ts.isForOfStatement)) {
+          if(!builtInEntries(unwrap(loop.expression),inputSymbol))continue;
+          const tuple=ts.isVariableDeclarationList(loop.initializer)&&loop.initializer.declarations[0]?.name;
+          if(!tuple||!ts.isArrayBindingPattern(tuple)||tuple.elements.length!==2||!tuple.elements.every(ts.isBindingElement))continue;
+          const keySymbol=checker.getSymbolAtLocation(tuple.elements[0].name),valueSymbol=checker.getSymbolAtLocation(tuple.elements[1].name);
+          for(const write of all(loop.statement,ts.isBinaryExpression))if(write.operatorToken.kind===ts.SyntaxKind.EqualsToken&&ts.isElementAccessExpression(write.left)&&pairMatches(write.left.argumentExpression,write.right,keySymbol,valueSymbol)&&safeKey(loop.statement,keySymbol,write.pos)) {
+            const target=canonical(write.left.expression);
+            if(!target||!ts.isVariableDeclaration(target)||!target.initializer||!ts.isObjectLiteralExpression(unwrap(target.initializer))||unwrap(target.initializer).properties.length)continue;
+            const actual=checker.getSymbolAtLocation(target.name);if(mapSymbol&&mapSymbol!==actual)continue;mapSymbol=actual;writes.push(write);
+          }
+        }
+        const escapes=mapSymbol&&all(body,ts.isIdentifier).some(node=>checker.getSymbolAtLocation(node)===mapSymbol&&!ts.isVariableDeclaration(node.parent)&&!ts.isReturnStatement(node.parent)&&!(ts.isElementAccessExpression(node.parent)&&writes.some(write=>write.left===node.parent)));
+        return mapSymbol&&!escapes&&checker.getSymbolAtLocation(returned)===mapSymbol?[body]:null;
+      }
+      const proof=proveMap(producer);
+      if(!proof){report(contract,`${name}: producer must return only the declared config-entry paint map. Use Object.entries with a loop or Object.fromEntries/map, guard keys with /^[A-Za-z0-9_-]+$/ before writing (throw or continue), and the exact computed family. Owner-local helper returns are supported; escaped maps, extra writes and unknown returns grant no permission.`,"binding-producer");continue;}
+      const scope=fn(implementationNode(program,binding.scope.api,options.root));
+      let attached=false;
+      const returnedElements=new Set();
+      function rendered(input,context=values.state()) {
+        const value=values.resolve(input,values.next(context));
+        context=value.context??context;
+        if(value.kind==="union"||value.kind==="array"){for(const item of value.values.slice(0,32))rendered(item,values.next(context));return;}
+        if(value.kind!=="node")return;
+        const node=value.node;
+        if(ts.isJsxExpression(node)){rendered(reference(node.expression,value.env,value.via),values.next(context));return;}
+        if(ts.isJsxFragment(node)){for(const child of node.children)rendered(reference(child,value.env,value.via),values.next(context));return;}
+        if(!ts.isJsxElement(node)&&!ts.isJsxSelfClosingElement(node))return;
+        const opening=ts.isJsxElement(node)?node.openingElement:node,children=ts.isJsxElement(node)?node.children:[];
+        const attributes=values.props(opening,value.env,value.via);
+        if(children.length)attributes.layers.push(new Map([["children",{kind:"array",values:children.map(child=>reference(child,value.env,value.via))}]]));
+        if(ts.isIdentifier(opening.tagName)&&/^[a-z]/.test(opening.tagName.text)) {returnedElements.add(opening);for(const child of children)rendered(reference(child,value.env,value.via),values.next(context));return;}
+        const component=values.resolve(reference(opening.tagName,value.env,value.via),values.next(context));
+        if(["provider","context"].includes(component.kind))for(const child of children)rendered(reference(child,value.env,value.via),values.next(context));
+        else if(component.kind==="node"&&component.node.body)for(const output of values.returns(component,[attributes],values.next(context),"component"))rendered(output,values.next(context));
+      }
+      const target=scope&&values.resolve(reference(scope),values.state());
+      if(target?.kind==="node")for(const output of values.returns(target,[{kind:"unknown"}],values.state(),"component"))rendered(output);
+      function inputMatches(expression) {
+        expression=unwrap(expression);if(!expression||!scope?.parameters?.[0])return false;
+        const fields=[];while(ts.isPropertyAccessExpression(expression)){fields.unshift(expression.name.text);expression=expression.expression;}
+        const parameter=scope.parameters[0].name;
+        if(ts.isIdentifier(parameter))return checker.getSymbolAtLocation(expression)===checker.getSymbolAtLocation(parameter)&&fields.join(".")===binding.input.property;
+        const [first,...rest]=binding.input.property.split(".");
+        const item=ts.isObjectBindingPattern(parameter)&&parameter.elements.find(item=>(item.propertyName??item.name).getText()===first);
+        return item&&ts.isIdentifier(item.name)&&checker.getSymbolAtLocation(expression)===checker.getSymbolAtLocation(item.name)&&fields.join(".")===rest.join(".");
+      }
+      function produced(expression,seen=new Set()) {
+        expression=unwrap(expression);if(!expression||seen.has(expression)||seen.size>20)return false;seen=new Set([...seen,expression]);
+        if(ts.isCallExpression(expression)&&same(expression.expression,binding.producer))return inputMatches(expression.arguments[0]);
+        if(ts.isCallExpression(expression)&&uiOperation(expression.expression,checker)==="useMemo") {
+          const callback=unwrap(expression.arguments[0]);
+          const returns=callback&&ts.isBlock(callback.body)?all(callback.body,ts.isReturnStatement):[];
+          return callback&&(ts.isArrowFunction(callback)||ts.isFunctionExpression(callback))&&(ts.isBlock(callback.body)?returns.length>0&&returns.every(node=>produced(node.expression,seen)):produced(callback.body,seen));
+        }
+        const declaration=canonical(expression);
+        return declaration&&ts.isVariableDeclaration(declaration)&&produced(declaration.initializer,seen);
+      }
+      for(const element of returnedElements) {
+        if(!ts.isIdentifier(element.tagName)||!/^[a-z]/.test(element.tagName.text))continue;
+        const attributes=element.attributes.properties.filter(ts.isJsxAttribute);
+        const target=attributes.find(attribute=>attribute.name.getText()===(selector.type==="class"?"className":selector.attribute));
+        const targetValue=target?.initializer&&(ts.isStringLiteralLike(target.initializer)?target.initializer.text:ts.isJsxExpression(target.initializer)&&ts.isStringLiteralLike(target.initializer.expression)?target.initializer.expression.text:null);
+        const matched=selector.type==="class"?targetValue?.split(/\s+/).includes(selector.value):targetValue===selector.value;
+        const style=attributes.find(attribute=>attribute.name.getText()==="style");
+        const overwritten=element.attributes.properties.some((attribute,index)=>ts.isJsxSpreadAttribute(attribute)&&index>Math.min(element.attributes.properties.indexOf(style),element.attributes.properties.indexOf(target)));
+        if(matched&&!overwritten&&style?.initializer&&ts.isJsxExpression(style.initializer)&&produced(style.initializer.expression)){attached=true;result.allowedStyles.add(key(style));}
+      }
+      if(!attached){report(contract,`${name}: cannot trace the producer's returned map onto its declared component root. Unused producers, unrelated elements and arbitrary inline styles do not establish a binding.`,"binding-scope");continue;}
+      for(const node of proof.flatMap(body=>all(body,ts.isTypeReferenceNode)))result.allowedStyleTypes.add(key(node));
+      result.bindings.push({...binding,name,prefix,suffix,unit:contract.unit,file:contract.file});
+    }
+  }
+  return result;
+}

package/dist/scenario-trace.mjs

@@ -1,11 +1,13 @@
 import path from "node:path";
 import ts from "typescript";
 import postcss from "postcss";
-import { isDevelopmentFile, isInside } from "./config.mjs";
-import { publicApi } from "./public-api.mjs";
+import { isDevelopmentFile, isInside, isReviewFile } from "./config.mjs";
+import { scenarioApi } from "./public-api.mjs";
 import { uiOperation } from "./ui-framework.mjs";
 import { inspectUnits } from "./units.mjs";
 import { createSourceValues, reference, union, isFunction } from "./source-values.mjs";
+import { inspectRuntimeContracts } from "./runtime-contracts.mjs";
+import { implementationNode } from "./unit-contracts.mjs";
 
 /** Source evidence only. No project modules execute, and unknown paths grant no
  * permission. Coverage uses intersections across unresolved render branches;
@@ -27,12 +29,16 @@ export function createScenarioTrace(program, options) {
   const isCx = expression => linaria(expression, "cx");
   const { state, next, at, resolve, get, arrays, returns, props } = createSourceValues(program, options, { preserveCall: expression => isCx(expression) || uiOperation(expression, checker) === "createElement", strict: true });
   const publicNodes = new Map(), helpers = new Map(), inventory = inspectUnits(options);
+  const parts = inspectRuntimeContracts(options, program).parts.map(part => ({ ...part,
+    apiNode: resolve(reference(implementationNode(program, part.api, options.root)?.name), state()).node,
+    consumerNode: resolve(reference(implementationNode(program, part.consumer, options.root)?.name), state()).node,
+  }));
   const locationKey = value => JSON.stringify([value.file, value.line, value.column]);
   function runtimeOwner(file) {
-    return ["components", "patterns"].some(folder => isInside(path.join(options.dsRoot, folder), file)) && !isDevelopmentFile(file, options)
+    return (isReviewFile(file, options) || ["components", "patterns"].some(folder => isInside(path.join(options.dsRoot, folder), file)) && !isDevelopmentFile(file, options))
       ? inventory.owner(inventory.relative(path.relative(options.root, file))) : null;
   }
-  for (const item of publicApi(program, options)) {
+  for (const item of scenarioApi(program, options)) {
     const value = resolve(reference(item.declaration.name ?? item.declaration), state());
     if (value.kind !== "node") continue;
     if (item.renderable) {
@@ -60,8 +66,20 @@ export function createScenarioTrace(program, options) {
     return null;
   }
 
-  function traceRenders(site) {
+  function traceRenders(site, { entry = false } = {}) {
     const limits = new Set();
+    function childParts(input, context) {
+      const value = resolve(input, next(context));
+      if (value.kind === "union") return common(value.values.slice(0, maxBranches).map(item => childParts(item, next(context))));
+      if (value.kind === "array") return combine(value.values.map(item => childParts(item, next(context))));
+      if (value.kind !== "node") return new Set();
+      if (ts.isJsxExpression(value.node)) return childParts(reference(value.node.expression, value.env, value.via), next(context));
+      if (ts.isJsxFragment(value.node)) return combine(value.node.children.map(item => childParts(reference(item, value.env, value.via), next(context))));
+      const view = element(value.node, value.env, value.via);
+      if (!view) return new Set();
+      const target = resolve(view.tag, next(context));
+      return new Set([...parts.filter(part => part.apiNode && part.apiNode === target.node).map(part => part.apiName), ...childParts(get(view.attributes, "children", next(context)), next(context))]);
+    }
     function render(input, context) {
       const value = resolve(input, next(context));
       context = value.context ?? input.context ?? context;
@@ -85,15 +103,19 @@ export function createScenarioTrace(program, options) {
         if (target.kind === "union") return target.values.length <= maxBranches ? common(target.values.map(component)) : new Set();
         if (target.kind !== "node") return new Set();
         const names = new Set(publicNodes.get(target.node) ?? []);
-        if (isFunction(target.node) && !isDevelopmentFile(target.node.getSourceFile().fileName, options)) {
+        for (const part of parts) if (target.node === part.consumerNode && childParts(get(view.attributes, "children", next(context)), next(context)).has(part.apiName)) names.add(`@consumed:${part.apiName}`);
+        if (isFunction(target.node) && (entry || !isDevelopmentFile(target.node.getSourceFile().fileName, options) || isReviewFile(target.node.getSourceFile().fileName, options))) {
           const outputs = returns(target, [view.attributes], next(context), "component");
           for (const name of render(union(outputs), next(context))) names.add(name);
         }
+        for (const part of parts) if (names.has(part.parentName) && names.has(`@consumed:${part.apiName}`)) names.add(`@exercised:${part.apiName}`);
         return names;
       }
       return component(view.tag);
     }
-    return { rendered: render(reference(site), state()), limits: [...limits].slice(0, 3) };
+    const target=entry&&resolve(reference(site),state());
+    const evidence = target?.kind==="node"&&isFunction(target.node) ? render(union(returns(target,[{kind:"object",layers:[]}],state(),"component")),state()) : render(reference(site), state());
+    return { rendered: new Set([...evidence].filter(name => !name.startsWith("@"))), declarative: new Set([...evidence].filter(name => name.startsWith("@exercised:")).map(name => name.slice(11))), limits: [...limits].slice(0, 3) };
   }
 
   function classValue(expression, property = false) {
@@ -122,7 +144,7 @@ export function createScenarioTrace(program, options) {
           const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text : template.head.text + template.templateSpans.map(span => `__ads_expression__${span.literal.text}`).join("");
           try { postcss.parse(text).walkDecls(declaration => { for(let parent=declaration.parent;parent;parent=parent.parent)if(parent.type==="atrule"&&/^(?:property|font-face|(?:-\w+-)?keyframes)$/i.test(parent.name))return; ++declarations; }); } catch { /* Source CSS guards own malformed templates. */ }
           if (owned(source, via) && declarations) return result(true, true);
-          reasons.add("The returned style must originate in runtime component/pattern Linaria through a public callable helper.");
+          reasons.add("The returned style must originate in component/pattern or review Linaria through its registered callable API.");
           return result(false);
         }
         if (ts.isCallExpression(node) && isCx(node.expression)) {
@@ -145,5 +167,11 @@ export function createScenarioTrace(program, options) {
     if (!ok && !reasons.size) reasons.add("Each nonempty return path needs owned Linaria styles; stable hooks alone are not styling evidence.");
     return { present: !property || value.kind !== "unknown", ok, reasons: [...reasons].slice(0, 3) };
   }
-  return { traceRenders, classValue };
+  function traceEntry(source) {
+    const module=checker.getSymbolAtLocation(source),symbol=module&&checker.getExportsOfModule(module).find(symbol=>symbol.name==="default");
+    const resolved=symbol?.flags&ts.SymbolFlags.Alias?checker.getAliasedSymbol(symbol):symbol;
+    const declaration=resolved?.valueDeclaration;
+    return traceRenders(declaration&&(ts.isExportAssignment(declaration)?declaration.expression:declaration.name??declaration),{entry:true});
+  }
+  return { traceRenders, traceEntry, classValue };
 }

package/dist/scenarios-vite.mjs

@@ -2,6 +2,7 @@ import path from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { loadConfig, isInside } from "./config.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
+import { configureReviewAlias } from "./preview-resources.mjs";
 export { createPreviewResources, previewEntriesPlugin } from "./preview-resources.mjs";
 
 /** Project-owned rendering; this plugin supplies only discoverable module entries. */
@@ -10,13 +11,13 @@ export function scenarioRegistryPlugin(directory = process.cwd()) {
   const virtual = "virtual:ads-scenarios";
   const resolved = "\0virtual:ads-scenarios";
   function registry() {
-    const value = inspectScenarios(options);
+    const value = inspectScenarios(loadConfig(directory));
     if (value.diagnostics.length) throw new Error(value.diagnostics.map((item) => `${item.file}: ${item.message}`).join("\n"));
     mkdirSync(path.join(options.root, ".ds/scenarios"), { recursive: true });
     writeFileSync(path.join(options.root, ".ds/scenarios/manifest.json"), JSON.stringify({ schemaVersion: 1, scenarios: value.scenarios }, null, 2) + "\n");
     return `export const scenarios = [${value.scenarios.map((item) => `{...${JSON.stringify(item)}, load: () => import(${JSON.stringify(path.join(options.root, item.file).replaceAll("\\", "/"))})}`).join(",\n")}];`;
   }
-  return { name: "ads-scenario-registry", resolveId(id) { if (id === virtual) return resolved; },
+  return { name: "ads-scenario-registry", config(config) { configureReviewAlias(config, options); }, resolveId(id) { if (id === virtual) return resolved; },
     load(id) { if (id === resolved) return registry(); },
     handleHotUpdate({ file, server }) {
       if (!isInside(options.dsRoot, file)) return;

package/dist/scenarios.mjs

@@ -1,15 +1,18 @@
 import path from "node:path";
 import { existsSync } from "node:fs";
 import ts from "typescript";
-import { publicApi } from "./public-api.mjs";
+import { publicApi, scenarioApi } from "./public-api.mjs";
 import { uiOperation } from "./ui-framework.mjs";
-import { isDevelopmentFile, isInside, isScenarioFile, sourceFiles } from "./config.mjs";
+import { isDevelopmentFile, isInside, isScenarioFile, scenarioIdentity, sourceFiles } from "./config.mjs";
 import { projectCompilerOptions } from "./boundaries.mjs";
 import { inspectTokens } from "./tokens.mjs";
 import { isSharedToken } from "./token-policy.mjs";
 import { validTokenSamples } from "./token-samples.mjs";
 import { scopedTokens } from "./scoped-tokens.mjs";
 import { createScenarioTrace } from "./scenario-trace.mjs";
+import { inspectRuntimeContracts } from "./runtime-contracts.mjs";
+import { inspectUnitContracts } from "./unit-contracts.mjs";
+import { inspectPaintContracts } from "./paint-contracts.mjs";
 
 export const scenarioArtifact = (root, id) => path.join(root, ".ds/scenarios", id, "index.html");
 
@@ -37,39 +40,53 @@ export function publicUi(program, options) {
 export function inspectScenarios(options, suppliedProgram) {
   const { root, dsRoot } = options;
   const files = sourceFiles(dsRoot).filter(isScenarioFile);
-  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], { ...projectCompilerOptions(options), allowJs: true });
-  const known = new Map(publicUi(program, options).map((item) => [item.name, item]));
+  const program = suppliedProgram ?? inspectUnitContracts(options).program ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), path.join(dsRoot, options.config.reviewEntry), ...files], { ...projectCompilerOptions(options), allowJs: true });
+  const apis = scenarioApi(program, options);
+  const duplicate = apis.find((item, index) => apis.some((other, otherIndex) => index !== otherIndex && item.name === other.name));
+  const known = new Map(apis.filter(item => item.kind !== "controllers").map((item) => [item.name, item]));
   const checker = program.getTypeChecker();
+  const declarativeParts = inspectRuntimeContracts(options, program).parts;
+  const contractDeclarations=inspectUnitContracts(options).contracts;
+  const bindingTrace = contractDeclarations.some(contract=>contract.paintInputs?.length) ? createScenarioTrace(program, options) : null;
   const behaviorApis = new Map(publicApi(program, options).filter(item => !item.renderable && item.behavioral).map(item => [item.name, item]));
-  const tokenInventory = inspectTokens(root);
+  const tokenInventory = inspectTokens(root, options);
   const tokenNames = new Set(tokenInventory.tokens.map(token => token.name));
   const scoped = scopedTokens(options);
   const scenarios = [];
-  const diagnostics = [];
+  const diagnostics = [...inspectUnitContracts(options).diagnostics,...inspectRuntimeContracts(options,program).diagnostics,...inspectPaintContracts(options).diagnostics];
   const ids = new Set();
-  function report(file, message) { diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "scenario-contract", line: 1, column: 1, message }); }
+  function report(file, message, node, detail = {}) {
+    const position = node?.getSourceFile().getLineAndCharacterOfPosition(node.getStart());
+    diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "scenario-contract", line: (position?.line ?? 0) + 1, column: (position?.character ?? 0) + 1, message, ...detail });
+  }
+  if (duplicate) report(path.join(dsRoot, options.config.reviewEntry), `Review export ${duplicate.name} collides with the production API. Use a distinct development export so scenario coverage is unambiguous.`);
   for (const file of files) {
     const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
     let kind = isInside(path.join(dsRoot, options.config.tokenDir), file) ? "tokens" : relative.split("/")[0];
     if (!["tokens", "components", "patterns", "composition"].includes(kind)) { report(file, "Scenarios live beside tokens/components/patterns or under composition/, not inside showcase pages."); continue; }
-    const id = relative.replace(/(?:\/Scenario|\.scenario)\.[^.]+$/, "");
-    if (id.length > 256) { report(file, "Scenario paths must fit within 256 characters."); continue; }
-    if (ids.has(id)) { report(file, `Duplicate scenario id ${id}. Use one entrypoint per identity.`); continue; }
-    ids.add(id);
+    let id = scenarioIdentity(file, dsRoot);
     const source = program.getSourceFile(file);
     if (!source) { report(file, "Cannot inspect scenario source."); continue; }
-    let metadata;
+    let metadata, metadataExpression;
     let entry = false;
     for (const node of source.statements) {
       if (ts.isExportAssignment(node) || node.modifiers?.some((item) => item.kind === ts.SyntaxKind.DefaultKeyword)) entry = true;
       if (ts.isVariableStatement(node) && node.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)) {
-        for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === "scenario") metadata = literal(declaration.initializer, checker);
+        for (const declaration of node.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === "scenario") { metadataExpression = declaration.initializer; metadata = literal(metadataExpression, checker); }
       }
     }
+    if(metadata?.id!==undefined) {
+      const owner=scoped.inventory.owner(relative);
+      if(typeof metadata.id!=="string"||metadata.id.length>256||!/^[\w-]+(?:[/.][\w-]+)*$/.test(metadata.id)||!owner||!(metadata.id===owner||metadata.id.startsWith(owner+"/")||metadata.id.startsWith(owner+".")))report(file,"Scenario id must be a safe stable identity inside this owner; it cannot capture another layer/owner.",metadataExpression,{entry:"id"});
+      else id=metadata.id;
+    }
+    if (id.length > 256) { report(file, "Scenario paths must fit within 256 characters."); continue; }
+    if (ids.has(id)) { report(file, `Duplicate scenario id ${id}. Use one entrypoint per identity.`); continue; }
+    ids.add(id);
     if (metadata?.kind !== undefined) {
       const owner = scoped.inventory.owner(relative);
-      if (metadata.kind !== "tokens" || !scoped.definitions.some(entry => entry.unit === owner)) { report(file, "Only an owner with registered local tokens may set kind: tokens for a colocated token preview."); continue; }
-      kind = "tokens";
+      if (metadata.kind !== "tokens" || !scoped.definitions.some(entry => entry.unit === owner)) report(file, "Only an owner with registered local tokens may set kind: tokens for a colocated token preview.",entryNode("kind"),{entry:"kind"});
+      else kind = "tokens";
     }
     if (!entry) report(file, "Export a default independently mountable scenario entrypoint.");
     const module = checker.getSymbolAtLocation(source);
@@ -87,12 +104,45 @@ export function inspectScenarios(options, suppliedProgram) {
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     const fixture = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].map(extension => fixtureBase + extension).find(existsSync);
     if (!fixture) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
-    if (!metadata || Object.keys(metadata).some((key) => !["title", "kind", "covers", "exercises", "tokens", "samples", "captureTargets"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
-      || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
-      || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => known.get(name)?.kind === "patterns"))
-      || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
-      report(file, "Export static metadata with nonempty covers naming rendered public UI. Optional exercises names public behavioral APIs, not rendered UI. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
+    function entryNode(field, index) {
+      let value = metadataExpression;
+      const seen = new Set();
+      while (value && !seen.has(value)) {
+        seen.add(value);
+        if (ts.isSatisfiesExpression(value) || ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
+        else if (ts.isIdentifier(value)) { let symbol = checker.getSymbolAtLocation(value); if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol); value = symbol?.valueDeclaration?.initializer; }
+        else break;
+      }
+      const property = value && ts.isObjectLiteralExpression(value) && value.properties.find(item => ts.isPropertyAssignment(item) && (ts.isIdentifier(item.name) || ts.isStringLiteralLike(item.name)) && item.name.text === field);
+      return index !== undefined && property && ts.isArrayLiteralExpression(property.initializer) ? property.initializer.elements[index] : property?.initializer ?? metadataExpression;
+    }
+    if (!metadata) {
+      report(file, "Scenario metadata is not statically readable. Render coverage is not established until this prerequisite is repaired.", metadataExpression, {coverage:"not-established",owner:scoped.inventory.owner(relative)});
+      continue;
+    }
+    for(const field of Object.keys(metadata))if(!["id","title","kind","covers","exercises","tokens","samples","captureTargets"].includes(field))report(file,`Unknown scenario field ${field}.`,entryNode(field),{entry:field});
+    if(typeof metadata.title!=="string"||!metadata.title.trim()) {
+      report(file,"Scenario title must be a nonempty static string; independent render evidence is retained.",entryNode("title"),{entry:"title"});
+      metadata.title=id;
+    }
+    if(!Array.isArray(metadata.covers)||!metadata.covers.length) {
+      report(file,"Scenario covers must be a nonempty static array naming rendered public UI. Coverage is not established until repaired.",entryNode("covers"),{entry:"covers",coverage:"not-established",owner:scoped.inventory.owner(relative)});
+      metadata.covers=[];
+    }
+    if(Object.hasOwn(metadata,"tokens")&&(!Array.isArray(metadata.tokens)||metadata.tokens.some(name=>typeof name!=="string"||!name.startsWith("--")))) {
+      report(file,"Scenario tokens must be a static list of real token names.",entryNode("tokens"),{entry:"tokens"});metadata.tokens=[];
+    }
+    if(kind==="tokens"&&Object.hasOwn(metadata,"tokens")||kind==="tokens"&&!validTokenSamples(metadata.samples)||Object.hasOwn(metadata,"samples")&&!validTokenSamples(metadata.samples)) {
+      report(file,"Token scenarios need samples: fixture.samples, a literal list of { token, property, probe } real CSS bindings. Printing values or covers: [] is incomplete.",entryNode("samples"),{entry:"samples"});delete metadata.samples;
+    }
+    const covers = [];
+    for (const [index, name] of metadata.covers.entries()) {
+      const api = typeof name === "string" && known.get(name);
+      if (!api?.renderable || declarativeParts.some(part=>part.apiName===name)) report(file, `Scenario covers[${index}] ${JSON.stringify(name) ?? "(unresolved)"} ${api ? "is not independently rendered UI. Use exercises for a behavioral or registered declarative API." : "does not name a known public UI export."} Independent valid render evidence is retained.`, entryNode("covers", index), { entry: `covers[${index}]`, ...(typeof name === "string" ? { api: name } : {}), reason: api ? "wrong-api-role" : "unknown-api" });
+      else covers.push(name);
     }
+    metadata = { ...metadata, covers };
+    if (kind === "tokens" && !covers.some(name => ["patterns", "review"].includes(known.get(name)?.kind))) report(file, "Token covers must name the real development review renderer or product pattern consuming samples.", entryNode("covers"));
     // A bad behavioral entry must fail validation without erasing independent
     // render evidence and manufacturing missing-coverage errors for real UI.
     const exercises = [];
@@ -104,8 +154,8 @@ export function inspectScenarios(options, suppliedProgram) {
     if (Object.hasOwn(metadata, "exercises")) {
       if (!Array.isArray(metadata.exercises)) report(file, "Scenario exercises must be a static array naming public behavioral APIs.");
       else for (const [index, name] of metadata.exercises.entries()) {
-        if (typeof name !== "string") report(file, `Scenario exercises[${index}] must name a public behavioral API, not ${JSON.stringify(name) ?? "an unresolved value"}.`);
-        else if (!behaviorApis.has(name)) report(file, `Scenario exercises[${index}] ${JSON.stringify(name)} is not a recognized public behavioral API. Use a public callable function, hook or controller; rendered UI belongs in covers. Discover the project's exports before declaring exercises.`);
+        if (typeof name !== "string") report(file, `Scenario exercises[${index}] must name a public behavioral API, not ${JSON.stringify(name) ?? "an unresolved value"}.`, entryNode("exercises", index), { entry: `exercises[${index}]` });
+        else if (!behaviorApis.has(name) && !declarativeParts.some(part=>part.apiName===name)) report(file, `Scenario exercises[${index}] ${JSON.stringify(name)} is not a recognized public behavioral API. Use a public callable function, hook or controller; rendered UI belongs in covers. Discover the project's exports before declaring exercises.`, entryNode("exercises", index), { entry: `exercises[${index}]`, api: name });
         else exercises.push(name);
       }
     }
@@ -117,16 +167,22 @@ export function inspectScenarios(options, suppliedProgram) {
       for (const name of tokens) if (tokenInventory.tokens.find(token => token.name === name)?.owner !== owner) report(file, `Token ${name} needs a preview beside its defining owner. Shared tokens belong under the configured token directory; local tokens stay with their component/pattern.`);
     }
     const stylesheets = kind === "tokens" ? scoped.definitions.filter(entry => entry.unit === scoped.inventory.owner(relative)).map(entry => entry.file) : [];
-    scenarios.push({ id, kind, title: metadata.title, ...(fixture ? { fixture: path.relative(root, fixture).replaceAll("\\", "/") } : {}), covers: [...new Set(metadata.covers)], ...(captureTargets ? { captureTargets } : {}), ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), ...(stylesheets.length ? { stylesheets } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    const reachable = new Set(metadata.covers);
+    function findBindings(node) { if(ts.isJsxElement(node)||ts.isJsxSelfClosingElement(node))for(const name of bindingTrace.traceRenders(node).rendered)reachable.add(name);ts.forEachChild(node,findBindings); }
+    if(bindingTrace) findBindings(source);
+    const paintBindings = inspectRuntimeContracts(options,program).bindings.filter(binding=>reachable.has(binding.scope.apiName)).map(binding=>({owner:binding.unit,name:binding.name,scope:binding.scope.selector,prefix:binding.prefix,suffix:binding.suffix,tokens:tokenInventory.tokens.filter(token=>!token.owner||token.owner==="tokens"||token.owner===binding.unit).map(token=>token.name)}));
+    const paintAudit=contractDeclarations.some(contract=>contract.paintInputs?.some(input=>reachable.has(input.apiName)));
+    scenarios.push({ id, kind, title: metadata.title, ...(fixture ? { fixture: path.relative(root, fixture).replaceAll("\\", "/") } : {}), covers: [...new Set(metadata.covers)], ...(captureTargets ? { captureTargets } : {}), ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), ...(stylesheets.length ? { stylesheets } : {}), ...(paintBindings.length?{paintBindings}:{}), ...(paintAudit?{paintAudit:true}:{}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
 
 export function inspectScenarioCoverage(options, program, report, advise = () => {}, trace = createScenarioTrace(program, options)) {
   const registry = inspectScenarios(options, program);
-  for (const item of registry.diagnostics) report(path.join(options.root, item.file), item.rule, item.message, item.line, item.column);
+  for (const {file,rule,message,line,column,...detail} of registry.diagnostics) report(path.join(options.root, file), rule, message, line, column, detail);
   const checker = program.getTypeChecker();
   const ui = publicUi(program, options);
+  const parts = inspectRuntimeContracts(options, program).parts;
   function symbolOf(expression) {
     while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isNonNullExpression(expression))) expression = expression.expression;
     if (!expression) return null;
@@ -156,7 +212,7 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
     return symbol.declarations?.length ? symbol : null;
   }
   const identities = new Map(), behaviorIdentities = new Set();
-  for (const item of publicApi(program, options)) {
+  for (const item of scenarioApi(program, options)) {
     if (!identities.has(item.declaration)) identities.set(item.declaration, new Set());
     identities.get(item.declaration).add(item.name);
     if (item.behavioral && !item.renderable) behaviorIdentities.add(item.declaration);
@@ -164,12 +220,12 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
 
   const covered = new Set();
   const coveredTokens = new Set();
-  const tokenInventory = inspectTokens(options.root);
+  const tokenInventory = inspectTokens(options.root, options);
   const declaredTokens = new Set(tokenInventory.tokens.map(token => token.name));
   for (const scenario of registry.scenarios) {
     const source = program.getSourceFile(path.join(options.root, scenario.file));
     const rendered = new Set();
-    const exercised = new Set(), referencedApis = new Set();
+    const exercised = new Set(), referencedApis = new Set(), declarative = new Set();
     const referencedTokens = new Set();
     let samplesPassed = false;
     const renderLimits = new Set();
@@ -226,22 +282,25 @@ export function inspectScenarioCoverage(options, program, report, advise = () =>
       ts.forEachChild(node, child => visit(child, reached && (ts.isExportAssignment(node) || ts.isVariableDeclaration(node))));
     }
     for (const node of source.statements) if (ts.isExportAssignment(node) || node.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) visit(node, true);
+    if(parts.some(part=>scenario.exercises?.includes(part.apiName)))for(const name of trace.traceEntry(source).declarative)declarative.add(name);
     for (const name of scenario.covers) {
       if (!rendered.has(name)) report(source.fileName, "scenario-render", `${name} is declared in covers but has no reachable public render reference. Render it directly or through a traced parent with fixture props/defaults selecting that child. Imports, unused JSX and unknown conditional paths do not establish coverage.${renderLimits.size ? ` Source tracing could not establish: ${[...renderLimits].slice(0, 2).join(" ")}` : ""} Review the real scenario in a browser; do not hide a valid public part just to avoid coverage. See ads://guides/scenarios.`);
       else covered.add(name);
     }
     for (const name of scenario.exercises ?? []) {
-      if (!exercised.has(name) && !referencedApis.has(name)) report(source.fileName, "scenario-exercise", `${name} is declared in exercises but has no reachable behavioral use. Imports and unused adapters do not count.`);
+      if (parts.some(part=>part.apiName===name) && !declarative.has(name)) report(source.fileName, "scenario-exercise", `${name} is a registered declarative API, but its child does not reach the declared consumer through a rendered parent. Imports, unused children and unrelated parent renders do not establish consumption.`);
+      else if (!exercised.has(name) && !referencedApis.has(name)) report(source.fileName, "scenario-exercise", `${name} is declared in exercises but has no reachable behavioral use. Imports and unused adapters do not count.`);
       else if (!exercised.has(name)) advise(source.fileName, "scenario-exercise-review", `${name} is referenced dynamically. Verify its invocation in the registered browser/behavior checks; a reference alone does not prove execution.`);
     }
     for (const name of referencedTokens) if (!declaredTokens.has(name)) report(source.fileName, "token-scenario-reference", `Reachable scenario input references undeclared token ${name}.`);
-    if (scenario.kind === "tokens" && !samplesPassed) report(source.fileName, "token-scenario-render", "Pass the declared fixture.samples into a rendered public review pattern's samples prop. Printing token names or reading unused fixtures is not sample coverage.");
+    if (scenario.kind === "tokens" && !samplesPassed) report(source.fileName, "token-scenario-render", "Pass the declared fixture.samples into a rendered review renderer's samples prop. Printing token names or reading unused fixtures is not sample coverage.");
     for (const name of scenario.tokens) {
       if (!referencedTokens.has(name)) report(source.fileName, "token-scenario-render", `${name} is declared in tokens but has no reachable reference from the default scenario entry. Consume the real token fixture; metadata alone does not count.`);
       else if (scenario.kind === "tokens" && samplesPassed && declaredTokens.has(name)) coveredTokens.add(name);
     }
   }
-  for (const item of ui.filter((item) => item.renderable && !covered.has(item.name))) report(item.file, "scenario-coverage", `Public UI ${item.name} needs a colocated, registered scenario render reference. Related parts may share a scenario.`);
+  const blockedOwners=new Set(registry.diagnostics.filter(item=>item.coverage==="not-established").map(item=>item.owner));
+  for (const item of ui.filter((item) => item.renderable && !covered.has(item.name) && !blockedOwners.has(scopedTokens(options).inventory.owner(scopedTokens(options).inventory.relative(path.relative(options.root,item.file)))))) report(item.file, "scenario-coverage", `Public UI ${item.name} needs a colocated, registered scenario render reference. Related parts may share a scenario.`);
   for (const token of tokenInventory.tokens.filter(token => !coveredTokens.has(token.name))) {
     const definition = token.definitions[0];
     report(path.join(options.root, definition.file), "token-scenario-coverage", `Token ${token.name} needs a registered scenario with a reachable token fixture reference.`, definition.line, definition.column);