@reqvire-org/ads 0.3.20 → 0.3.21

package/dist/mcp/server.mjs

@@ -126,6 +126,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       { uri: "ads://guides/atomic-styles", name: "Atomic styles: composition conflicts and custom-property extraction", mimeType: "text/markdown" },
       { uri: "ads://guides/scenarios", name: "Scenario coverage and public class-helper contracts", mimeType: "text/markdown" },
       { uri: "ads://guides/layers", name: "Component capabilities, pattern composition and dependency ownership", mimeType: "text/markdown" },
+      { uri: "ads://guides/contracts", name: "Static owner contracts, typed paints and guarded migration", mimeType: "text/markdown" },
       { uri: "ads://guides/review", name: "Development-only review UI, token renderers and migration", mimeType: "text/markdown" },
       { uri: "ads://guides/captures", name: "On-demand captures and candidate visual review", mimeType: "text/markdown" },
       { uri: `${PROJECT_URI}/status`, name: "ADS project status", mimeType: "application/json" },
@@ -173,6 +174,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     if (uri === "ads://guides/atomic-styles") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/atomic-styles.md", import.meta.url), "utf8") }] };
     if (uri === "ads://guides/scenarios") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/scenarios.md", import.meta.url), "utf8") }] };
     if (uri === "ads://guides/layers") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/layers.md", import.meta.url), "utf8") }] };
+    if (uri === "ads://guides/contracts") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/contracts.md", import.meta.url), "utf8") }] };
     if (uri === "ads://guides/review") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/review.md", import.meta.url), "utf8") }] };
     if (uri === "ads://guides/captures") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/captures.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
@@ -318,7 +320,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         return json({ total: matches.length, units: matches.slice(0, limit).map(item => ({ id: item.id, kind: item.kind, fileCount: item.files.length, ...(unit ? { files: item.files.slice(0, 200), filesTruncated: item.files.length > 200, ...(item.companionFiles ? { companionFiles: item.companionFiles } : {}), ...(item.filePolicy ? { filePolicy: item.filePolicy } : {}) } : {}) })) });
       } },
       { name: "ads_read_file", description: "Read a bounded range of ADS or registered configuration/extension source. Returns unit, full-file digest, startLine and nextOffset; default/max is 12000 UTF-16 characters. Binary assets return byte count/digest and no encoded content. Paths come from ads_units or discovery. Missing new paths return digest null. Read only relevant context before preparing a Git patch.", schema: z.object({ path: z.string().min(1).max(500), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(mutationLimits.readChars).default(mutationLimits.readChars) }).strict(), call: ({ path: file, ...range }) => json(edits.read(file, range)) },
-      ...(mutations ? [{ name: "ads_prepare_patch", description: "Prepare a Git patch without a separate project mirror. Create copies only one owner plus its declared companions into a local draft; edit that directory with local file tools. Diff checks baseline/source freshness and owner paths, then writes a patchFile under .ds/patches. Discard removes the draft. Live source is never changed; ads_apply_patch still validates all gates. Remote clients can continue sending inline Git diffs instead.", schema:z.object({unit:z.string().min(1).max(256),action:z.enum(["create","diff","discard"]).default("create"),draft:z.string().max(100).optional()}).strict(), call:args=>json(prepareUnitPatch(options,args)) },
+      ...(mutations ? [{ name: "ads_prepare_patch", description: "Prepare a Git patch without a separate project mirror. Create copies only one owner plus its declared companions into a local draft; edit that directory with local file tools. Diff checks baseline/source freshness and owner paths, then writes a patchFile under .ds/patches. Migrate prepares mechanical .ads. role names and legacy contracts in that draft, retaining unresolved sections for review. Discard removes the draft. Live source is never changed; ads_apply_patch still validates all gates. Remote clients can continue sending inline Git diffs instead.", schema:z.object({unit:z.string().min(1).max(256),action:z.enum(["create","migrate","diff","discard"]).default("create"),draft:z.string().max(100).optional()}).strict(), call:args=>json(prepareUnitPatch(options,args)) },
       {name:"ads_prepare_token_samples",description:"Reconcile a token scenario's consumed literal fixture samples. Removes undeclared tokens, preserves existing project bindings, and accepts explicit real-token/property/probe bindings. Reports unresolved token names; never guesses CSS meaning from token names. Returns an owner patchFile without changing source. Apply it through ads_apply_patch and review the real preview.",schema:z.object({id:z.string().min(1).max(256),bindings:z.array(z.object({token:z.string().max(256),property:z.string().max(100),probe:z.string().max(1000)}).passthrough()).max(1000).optional()}).strict(),call:args=>{
         const {patch,...result}=reconcileTokenSamples(options,args);
         return json({...result,removed:result.removed.slice(0,50),unresolved:result.unresolved.slice(0,50),unresolvedCount:result.unresolved.length,...storePreparedPatch(options,patch)});

package/dist/paint-contracts.mjs

@@ -0,0 +1,124 @@
+import path from "node:path";
+import ts from "typescript";
+import valueParser from "postcss-value-parser";
+import { isContractFile, isInside } from "./config.mjs";
+import { inspectUnitContracts, implementationIdentity, runtimeBindingOwner } from "./unit-contracts.mjs";
+import { createSourceValues, reference } from "./source-values.mjs";
+
+export function paintReference(text) {
+  if (typeof text !== "string" || text.length > 1000) return null;
+  text=text.trim();
+  if (["none", "currentColor"].includes(text)) return {kind:"keyword",value:text};
+  const nodes = valueParser(text).nodes.filter(node => !["space","comment"].includes(node.type));
+  if (nodes.length !== 1 || nodes[0].type !== "function" || nodes[0].unclosed) return null;
+  const node=nodes[0], children=node.nodes.filter(item => !["space","comment"].includes(item.type));
+  if (node.value === "var" && children.length === 1 && children[0].type === "word" && /^--[\w-]+$/.test(children[0].value)) return {kind:"variable",name:children[0].value};
+  if (node.value === "url" && children.length === 1 && ["word","string"].includes(children[0].type) && /^#[^\s"'()#\\\p{Cc}]+$/u.test(children[0].value)) return {kind:"resource",id:children[0].value.slice(1)};
+  return null;
+}
+
+function supportedType(type, seen = new Set()) {
+  if (!type || seen.has(type)) return false;
+  seen=new Set([...seen,type]);
+  if (type.flags & ts.TypeFlags.Undefined) return true;
+  if (type.flags & ts.TypeFlags.StringLiteral) return !!paintReference(type.value);
+  if (type.isUnion()) return type.types.every(item=>supportedType(item,seen));
+  if (type.flags & ts.TypeFlags.TemplateLiteral) return type.texts.length===2 && (type.texts[0]==="var(--"||type.texts[0]==="url(#") && type.texts[1]===")" && type.types.every(item=>!!(item.flags & (ts.TypeFlags.String|ts.TypeFlags.StringLiteral)));
+  return false;
+}
+
+export function inspectPaintContracts(options) {
+  if(options.paintContracts)return options.paintContracts;
+  const declarations=inspectUnitContracts(options), result={allowedProperties:new Set(),diagnostics:[],contracts:declarations.contracts};
+  options.paintContracts=result;
+  if(!declarations.program)return result;
+  // TypeScript source identities use absolute paths, independently of process cwd.
+  for(const contract of declarations.contracts)for(const input of contract.paintInputs??[]) {
+    const checker=declarations.program.getTypeChecker();
+    const source=declarations.program.getSourceFile(path.resolve(options.root,input.api.source));
+    let declaration;
+    function find(node){if(node.pos===input.api.position&&(ts.isFunctionDeclaration(node)||ts.isVariableDeclaration(node)||ts.isClassDeclaration(node)))declaration=node;else ts.forEachChild(node,find);}
+    if(source)find(source);
+    const signature=declaration&&checker.getTypeAtLocation(declaration.name).getCallSignatures()[0];
+    let values=signature?.parameters[0]?[{type:checker.getTypeOfSymbolAtLocation(signature.parameters[0],declaration)}]:[];
+    for(const segment of input.property.split(".")) {
+      const next=[];
+      for(const item of values)for(const type of item.type.isUnion()?item.type.types:[item.type]){
+        if(type.flags & (ts.TypeFlags.Undefined|ts.TypeFlags.Null))continue;
+        if(segment==="*") {
+          const indexed=type.getStringIndexType()??type.getNumberIndexType();
+          if(indexed)next.push({type:indexed});else for(const prop of type.getProperties())next.push({type:checker.getTypeOfSymbolAtLocation(prop,prop.valueDeclaration??declaration),symbol:prop});
+        }else {const prop=type.getProperty(segment);if(prop)next.push({type:checker.getTypeOfSymbolAtLocation(prop,prop.valueDeclaration??declaration),symbol:prop});}
+      }
+      values=next;
+    }
+    if(!values.length||values.some(value=>!supportedType(value.type)))result.diagnostics.push({file:contract.file,rule:"paint-contract",line:1,column:1,message:`${input.apiName}.${input.property} must resolve to constrained token/local-resource paint references, not string, any or unknown. A declared role does not waive the actual type contract.`});
+    else for(const value of values)for(const node of value.symbol?.declarations??[])result.allowedProperties.add(`${node.getSourceFile().fileName}:${node.pos}`);
+  }
+  return result;
+}
+
+const paintProp=/^(?:background(?:Color)?|color|fill|stroke|stopColor|stop-color|floodColor|flood-color|(?:\w+)?ColorToken)$/i;
+
+/** Check resolved values at the consuming source, so exports cannot launder privacy. */
+export function inspectTokenValueFlows(program, options, inventory, scoped, report) {
+  if(!scoped.definitions.length && !inspectUnitContracts(options).contracts.some(contract=>contract.paintInputs?.length))return;
+  const values=createSourceValues(program,options), checker=program.getTypeChecker();
+  const declarations=inspectUnitContracts(options).contracts;
+  function strings(input, context=values.state()) {
+    const value=values.resolve(input,context);
+    if(value.kind==="literal")return typeof value.value==="string"?[value.value]:[];
+    if(value.kind==="union")return value.values.slice(0,32).flatMap(item=>strings(item,values.next(context)));
+    if(value.kind==="node"&&ts.isTemplateExpression(value.node)) {
+      let result=[value.node.head.text];
+      for(const span of value.node.templateSpans) {const parts=strings(reference(span.expression,value.env,value.via),values.next(context));result=result.flatMap(prefix=>parts.map(part=>prefix+part+span.literal.text)).slice(0,32);}
+      return result;
+    }
+    if(value.kind==="node"&&ts.isBinaryExpression(value.node)&&value.node.operatorToken.kind===ts.SyntaxKind.PlusToken) {
+      const left=strings(reference(value.node.left,value.env,value.via),values.next(context)),right=strings(reference(value.node.right,value.env,value.via),values.next(context));
+      return left.flatMap(first=>right.map(second=>first+second)).slice(0,32);
+    }
+    return [];
+  }
+  for(const source of program.getSourceFiles()) {
+    if(!isInside(options.root,source.fileName)||source.fileName.includes(`${path.sep}node_modules${path.sep}`)||isContractFile(source.fileName))continue;
+    const owner=scoped.inventory.owner(scoped.inventory.relative(path.relative(options.root,source.fileName)));
+    const emitted=new Set();
+    function check(node,text,bare=false,requirePaint=false,allowedBindings=null) {
+      const names=bare&&/^--[\w-]+$/.test(text)?[text]:valueParser(text).nodes.flatMap(function walk(value){return value.type==="function"&&value.value==="var"?[value.nodes.find(item=>item.type==="word")?.value]:value.nodes?value.nodes.flatMap(walk):[];}).filter(Boolean);
+      for(const name of names) {
+        const tokenOwner=scoped.definitions.find(entry=>name.startsWith(entry.namespace));
+        const binding=runtimeBindingOwner(options,name);
+        const issue=tokenOwner&&tokenOwner.unit!==owner?`${name} is private to ${tokenOwner.unit}; ${owner??"application source"} cannot consume it through props, aliases or helpers. Promote a cross-owner design value to shared tokens.`:binding&&(binding.unit!==owner||allowedBindings&&!allowedBindings.includes(binding.id))?`${name} is an instance binding private to ${binding.unit} and is not permitted by this consuming paint input.`:requirePaint&&!inventory.tokens.some(token=>token.name===name)&&!binding?`Undefined paint reference ${name}. Declare a real accessible token or a scoped runtime binding.`:null;
+        if(issue&&!emitted.has(`${node.pos}:${name}`)) {emitted.add(`${node.pos}:${name}`);const p=source.getLineAndCharacterOfPosition(node.getStart());report(source.fileName,"token-reference",issue,p.line+1,p.character+1);}
+      }
+      if(requirePaint&&!paintReference(text)) {const p=source.getLineAndCharacterOfPosition(node.getStart());report(source.fileName,"paint-reference",`Invalid paint reference ${JSON.stringify(text)}. Use an accessible token, declared scoped binding, local SVG paint resource, none or currentColor.`,p.line+1,p.character+1);}
+    }
+    function visit(node) {
+      if(ts.isCallExpression(node)&&ts.isPropertyAccessExpression(node.expression)&&["getPropertyValue","setProperty","removeProperty"].includes(node.expression.name.text)) {
+        for(const text of strings(reference(node.arguments[0])))check(node,text,true);
+        if(node.expression.name.text==="setProperty")for(const text of strings(reference(node.arguments[1])))check(node,text);
+      }
+      if(ts.isBinaryExpression(node)&&node.operatorToken.kind===ts.SyntaxKind.EqualsToken&&ts.isPropertyAccessExpression(node.left)&&ts.isPropertyAccessExpression(node.left.expression)&&node.left.expression.name.text==="style")for(const text of strings(reference(node.right)))check(node,text);
+      if(ts.isJsxOpeningElement(node)||ts.isJsxSelfClosingElement(node)) {
+        const attributes=values.props(node,new Map(),[]);
+        for(const property of values.keys(attributes,values.state())) {
+          if(paintProp.test(property))for(const text of strings(values.get(attributes,property,values.state())))check(node,text);
+          if(property==="style") {
+            const styles=values.get(attributes,"style",values.state());
+            for(const property of values.keys(styles,values.state()))for(const text of strings(values.get(styles,property,values.state())))check(node,text);
+          }
+        }
+        let symbol=checker.getSymbolAtLocation(node.tagName);if(symbol?.flags&ts.SymbolFlags.Alias)symbol=checker.getAliasedSymbol(symbol);
+        const declaration=symbol?.valueDeclaration;
+        if(declaration)for(const contract of declarations)for(const input of contract.paintInputs??[])if(input.api.identity===implementationIdentity(declaration,options.root)) {
+          let current=[values.props(node,new Map(),[])];
+          for(const segment of input.property.split("."))current=current.flatMap(value=>segment==="*"?values.arrays(value,values.state())??(values.keys(value,values.state())??[]).map(key=>values.get(value,key,values.state())):[values.get(value,segment,values.state())]);
+          for(const value of current)for(const text of strings(value))check(node,text,false,true,input.bindings??[]);
+        }
+      }
+      ts.forEachChild(node,visit);
+    }
+    visit(source);
+  }
+}

package/dist/preview-resources.mjs

@@ -125,7 +125,7 @@ export function createPreviewResources(output, options, entries) {
   const scenarios = entries.map((entry, index) => {
     const chunk = bundle.find(item => item.type === "chunk" && item.facadeModuleId === `\0ads-preview-entry:${index}`);
     if (!chunk) throw new Error(`Missing compiled scenario entry: ${entry.id}`);
-    return { id: entry.id, title: entry.title, kind: entry.kind, ...(entry.samples ? { samples: entry.samples } : {}), module: uris.get(chunk.fileName) };
+    return { id: entry.id, title: entry.title, kind: entry.kind, ...(entry.samples ? { samples: entry.samples } : {}), ...(entry.paintBindings?.length ? {paintBindings:entry.paintBindings} : {}), ...(entry.paintAudit?{paintAudit:true}:{}), module: uris.get(chunk.fileName) };
   });
   const graph = { schemaVersion: 1, framework: options.config.framework, assets: records, scenarios };
   const revision = hash(JSON.stringify(graph));

package/dist/public-props.mjs

@@ -18,7 +18,7 @@ function stringKeys(node, checker, seen = new Set()) {
 
 // Inspect locally declared exported *Props APIs without loading React at runtime.
 // Follow local aliases and inheritance, and distinguish Omit/Pick's actual keys.
-export function inspectPublicProps(source, checker, report) {
+export function inspectPublicProps(source, checker, report, allowedPaintProperties = new Set()) {
   function inspect(node, excluded = new Set(), seen = new Set()) {
     if (!node || seen.has(node)) return;
     seen = new Set([...seen, node]);
@@ -26,7 +26,7 @@ export function inspectPublicProps(source, checker, report) {
       const name = propertyName(node.name);
       if (excluded.has(name)) return;
       if (name === "style") report(node, "public-style-prop", "Public ADS props must omit style. Use semantic props and documented token hooks.");
-      if (visualName.test(name ?? "") && arbitraryString(node.type, new Set())) report(node, "visual-prop", "Public visual props must use semantic variants or a finite token union, not arbitrary strings.");
+      if (visualName.test(name ?? "") && arbitraryString(node.type, new Set()) && !allowedPaintProperties.has(`${node.getSourceFile().fileName}:${node.pos}`)) report(node, "visual-prop", "Public visual props must use semantic variants, a finite token union or an owner-registered constrained paint-reference contract, not arbitrary strings.");
       return;
     }
     if (ts.isTypeReferenceNode(node) || ts.isExpressionWithTypeArguments(node)) {

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

@@ -6,6 +6,8 @@ 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,6 +29,10 @@ 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 (isReviewFile(file, options) || ["components", "patterns"].some(folder => isInside(path.join(options.dsRoot, folder), file)) && !isDevelopmentFile(file, options))
@@ -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) || isReviewFile(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) {
@@ -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

@@ -11,7 +11,7 @@ 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");