@starci/hfs 4.7.32 → 4.7.33

package/runtime/scripts/work/brand/brand-colour.mjs

@@ -0,0 +1,125 @@
+// brand-colour.mjs - the colour mathematics of the brand checks (brand.mjs): sRGB <-> linear <-> OKLab <-> oklch, colour
+// parsing and WCAG contrast. Pure: nothing here reads a file, so a brand is never proven by a dependency that may not be installed.
+
+const COLOUR_REGEX=Object.freeze({percent:new RegExp(['^[-+]?',String.raw`\d*`,String.raw`\.?`,String.raw`\d+%$`].join('')),number:new RegExp(['^[-+]?',String.raw`\d*`,String.raw`\.?`,String.raw`\d+`,String.raw`(?:e[-+]?\d+)?$`].join(''),'i'),important:new RegExp([String.raw`\s*`,'!important$'].join(''),'i'),call:new RegExp(['^(oklch|rgba?)',String.raw`\(`,String.raw`\s*`,'([^)]*)',String.raw`\)$`].join(''),'i')});
+
+/** A brand token matches its source within half a unit of the x100 OKLab distance: below perception, wide enough for hex/oklch rounding. */
+export const TOKEN_TOLERANCE=0.5;
+
+/** `value` without a trailing `!important`. */
+export const stripImportant=value=>value.replace(COLOUR_REGEX.important,'');
+
+// ---------------------------------------------------------------------------
+// Colour mathematics: sRGB <-> linear <-> OKLab <-> oklch, and WCAG contrast.
+// ---------------------------------------------------------------------------
+
+const clamp01=value=>{if(value<0){return 0;}if(value>1){return 1;}return value;};
+/** sRGB transfer function and its inverse; the piecewise form, not the 2.2 approximation. */
+const srgbToLinear=channel=>channel<=0.04045?channel/12.92:((channel+0.055)/1.055)**2.4;
+const linearToSrgb=channel=>channel<=0.0031308?channel*12.92:1.055*channel**(1/2.4)-0.055;
+
+/** Linear-light sRGB (0..1 each) to OKLab. */
+function linearRgbToOklab([red,green,blue]){
+  const long=Math.cbrt(0.4122214708*red+0.5363325363*green+0.0514459929*blue);
+  const medium=Math.cbrt(0.2119034982*red+0.6806995451*green+0.1073969566*blue);
+  const short=Math.cbrt(0.0883024619*red+0.2817188376*green+0.6299787005*blue);
+  return {L:0.2104542553*long+0.7936177850*medium-0.0040720468*short,
+    a:1.9779984951*long-2.4285922050*medium+0.4505937099*short,
+    b:0.0259040371*long+0.7827717662*medium-0.8086757660*short};
+}
+
+/** OKLab to linear-light sRGB (unclamped: a value outside 0..1 is outside the sRGB gamut). */
+function oklabToLinearRgb({L,a,b}){
+  const long=(L+0.3963377774*a+0.2158037573*b)**3;
+  const medium=(L-0.1055613458*a-0.0638541728*b)**3;
+  const short=(L-0.0894841775*a-1.2914855480*b)**3;
+  return [4.0767416621*long-3.3077115913*medium+0.2309699292*short,
+    -1.2684380046*long+2.6097574011*medium-0.3413193965*short,
+    -0.0041960863*long-0.7034186147*medium+1.7076147010*short];
+}
+
+export const rgbToOklab=([red,green,blue])=>linearRgbToOklab([srgbToLinear(red/255),srgbToLinear(green/255),srgbToLinear(blue/255)]);
+/** Out-of-gamut OKLab clips per channel; `clipped` says so rather than hiding it. */
+export function oklabToRgb(lab){
+  const linear=oklabToLinearRgb(lab);
+  const clipped=linear.some(channel=>channel<-1e-6||channel>1+1e-6);
+  return {rgb:linear.map(channel=>Math.round(clamp01(linearToSrgb(clamp01(channel)))*255)),clipped};
+}
+
+export function oklabToOklch({L,a,b}){
+  const chroma=Math.hypot(a,b);
+  const hue=chroma<1e-7?0:(Math.atan2(b,a)*180/Math.PI+360)%360;
+  return {L,C:chroma,h:hue};
+}
+export const oklchToOklab=({L,C,h})=>({L,a:C*Math.cos(h*Math.PI/180),b:C*Math.sin(h*Math.PI/180)});
+export const formatHex=rgb=>`#${rgb.map(channel=>Math.max(0,Math.min(255,Math.round(channel))).toString(16).padStart(2,'0')).join('')}`;
+
+const number=(text,{percentOf=1}={})=>{
+  const value=String(text).trim();
+  if(COLOUR_REGEX.percent.test(value))return Number.parseFloat(value)/100*percentOf;
+  if(COLOUR_REGEX.number.test(value))return Number.parseFloat(value);
+  if(/^none$/i.test(value))return 0;
+  return null;
+};
+
+/**
+ * Parses the colour notations a brand record and a stylesheet actually use: `#rgb`/`#rgba`/`#rrggbb`/
+ * `#rrggbbaa`, `oklch(L C H[/a])` and `rgb()/rgba()`. Alpha is read and reported but never compared:
+ * a token's identity is its colour. Anything else - a named colour, `var()`, `color-mix()`, `calc()` -
+ * returns null so the caller fails loudly instead of guessing a value.
+ */
+export function parseColor(input){
+  const value=String(input??'').trim().replace(COLOUR_REGEX.important,'');
+  if(!value)return null;
+  const hex=/^#([0-9a-f]{3,8})$/i.exec(value);
+  return hex?parseHexColor(hex[1],value):parseFunctionColor(value);
+}
+
+function parseHexColor(body,raw){
+  if(![3,4,6,8].includes(body.length))return null;
+  const pairs=body.length<=4?[...body].map(char=>char+char):body.match(/../g);
+  const [red,green,blue,alpha]=pairs.map(pair=>Number.parseInt(pair,16));
+  return color({notation:'hex',rgb:[red,green,blue],alpha:alpha===undefined?1:alpha/255,raw});
+}
+
+function parseFunctionColor(value){
+  const call=COLOUR_REGEX.call.exec(value);
+  if(!call)return null;
+  const kind=call[1].toLowerCase();
+  const [head,tail]=call[2].split('/');
+  const parts=head.trim().split(/[\s,]+/).filter(Boolean);
+  if(parts.length<3)return null;
+  const alpha=tail===undefined?1:number(tail,{percentOf:1});
+  return kind==='oklch'?parseOklchParts(parts,alpha,value):parseRgbParts(parts,alpha,value);
+}
+
+function parseOklchParts(parts,alpha,raw){
+  const lightness=number(parts[0],{percentOf:1});
+  const chroma=number(parts[1],{percentOf:0.4});
+  const hue=number(parts[2]==='none'?'0':String(parts[2]).replace(/deg$/i,''));
+  if([lightness,chroma,hue].includes(null))return null;
+  const lab=oklchToOklab({L:lightness,C:chroma,h:hue});
+  const {rgb,clipped}=oklabToRgb(lab);
+  return color({notation:'oklch',rgb,alpha:alpha??1,raw,lab,clipped});
+}
+
+function parseRgbParts(parts,alpha,raw){
+  const channels=parts.slice(0,3).map(part=>number(part,{percentOf:255}));
+  if(channels.includes(null))return null;
+  return color({notation:'rgb',rgb:channels.map(channel=>Math.round(channel)),alpha:alpha??1,raw});
+}
+
+function color({notation,rgb,alpha,raw,lab=null,clipped=false}){
+  const oklab=lab??rgbToOklab(rgb);
+  return {notation,raw,rgb,alpha,clipped,oklab,oklch:oklabToOklch(oklab),hex:formatHex(rgb)};
+}
+
+/** Euclidean OKLab distance on the x100 scale: black against white is 100. */
+export const deltaEOk=(first,second)=>100*Math.hypot(first.oklab.L-second.oklab.L,first.oklab.a-second.oklab.a,first.oklab.b-second.oklab.b);
+/** WCAG 2.x relative luminance of a parsed colour. */
+const relativeLuminance=({rgb:[red,green,blue]})=>0.2126*srgbToLinear(red/255)+0.7152*srgbToLinear(green/255)+0.0722*srgbToLinear(blue/255);
+/** WCAG 2.x contrast ratio: 21 for black against white, 1 for a colour against itself. */
+export function contrastRatio(first,second){
+  const one=relativeLuminance(first),two=relativeLuminance(second);
+  return (Math.max(one,two)+0.05)/(Math.min(one,two)+0.05);
+}

package/runtime/scripts/work/brand/brand-tokens.mjs

@@ -0,0 +1,167 @@
+// brand-tokens.mjs - reading the real tokens out of the real source for the brand checks (brand.mjs): css custom
+// properties by scope, JSON/YAML token files, and the lookup that follows a `var(--other)` through the declared sources.
+import fs from 'node:fs';
+import path from 'node:path';
+import {parseYaml} from '../../../engine/yaml.mjs';
+import {grammarDistRefusal} from '../../gates/grammar-dist.mjs';
+import {slash} from '../../lib/path-key.mjs';
+import {stripImportant} from './brand-colour.mjs';
+
+const SOURCE_BYTES_LIMIT=4*1024*1024;
+const REGEX=Object.freeze({declaration:new RegExp(['^(--[A-Za-z0-9_-]+)',String.raw`\s*:\s*`,String.raw`([\s\S]+)$`].join('')),semicolons:new RegExp([';+','$'].join(''))});
+
+// ---------------------------------------------------------------------------
+// Reading the real tokens out of the real source.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every `--name: value` declaration of a stylesheet, with the selector that carries it. Declarations are
+ * split by scope because a brand's `color.tokens[].value` is the default (light) value: a dark override is
+ * reported as context, never accepted as a match for it.
+ */
+export function parseCssCustomProperties(text){
+  const source=String(text??'').replace(/\/\*[\s\S]*?\*\//g,' ');
+  const base=new Map(),dark=new Map(),all=[];
+  const stack=[];
+  let buffer='';
+  const flush=()=>{
+    const declaration=buffer.trim();
+    buffer='';
+    const match=REGEX.declaration.exec(declaration);
+    if(!match)return;
+    const selector=stack.filter(Boolean).join(' ');
+    const value=stripImportant(match[2].trim()).replace(REGEX.semicolons,'').trim();
+    // `:root:not([data-theme="light"])` inside a dark media query is a dark scope: a negated light theme is not a light one.
+    const asserted=selector.replace(/:not\([^)]*\)/g,' ');
+    const isDark=/dark/i.test(selector)&&!/data-theme\s*=\s*["']?light/i.test(asserted);
+    const entry={name:match[1],value,selector,scope:isDark?'dark':'base'};
+    all.push(entry);
+    const target=isDark?dark:base;
+    if(!target.has(entry.name))target.set(entry.name,entry);
+  };
+  for(const character of source){
+    if(character==='{'){stack.push(buffer.trim());buffer='';continue;}
+    if(character==='}'){flush();stack.pop();continue;}
+    if(character===';'){flush();continue;}
+    buffer+=character;
+  }
+  flush();
+  return {base,dark,all};
+}
+
+/**
+ * A JSON/YAML token file, flattened by key. Three authored shapes are accepted: a `tokens: [{name,value}]`
+ * list (the shape the grammar DNA uses), flat `--token: value` keys, and a nested object whose key path
+ * spells the token (`starci.core.primary` is `--starci-core-primary`).
+ */
+export function parseTokenData(data){
+  const maps={exact:new Map(),derived:new Map()};
+  walkTokens(data,[],maps);
+  return maps;
+}
+
+const putToken=(map,name,value)=>{if(typeof name==='string'&&name&&!map.has(name))map.set(name,String(value));};
+const isTokenLeaf=value=>typeof value==='string'||typeof value==='number';
+
+function walkTokens(node,trail,maps){
+  if(Array.isArray(node)){
+    for(const item of node){
+      if(item&&typeof item==='object')walkTokenItem(item,trail,maps);
+    }
+    return;
+  }
+  if(node&&typeof node==='object')walkTokenEntries(node,trail,maps);
+}
+
+function walkTokenEntries(node,trail,maps){
+  for(const [key,value] of Object.entries(node)){
+    const next=[...trail,key];
+    if(!isTokenLeaf(value)){walkTokens(value,key.startsWith('--')?trail:next,maps);continue;}
+    if(key.startsWith('--'))putToken(maps.exact,key,value);
+    else {putToken(maps.derived,key,value);putToken(maps.derived,`--${next.join('-')}`,value);}
+  }
+}
+
+/** One object of a `tokens: [{name,value}]` list: a named leaf, else a nested structure. */
+function walkTokenItem(item,trail,maps){
+  if(!isTokenLeaf(item.value)){walkTokens(item,trail,maps);return;}
+  const name=item.name??item.token;
+  if(typeof name==='string')putToken(name.startsWith('--')?maps.exact:maps.derived,name,item.value);
+}
+
+export const readText=file=>{
+  const stat=fs.lstatSync(file);
+  if(stat.isSymbolicLink()||!stat.isFile()||stat.size>SOURCE_BYTES_LIMIT)throw new Error('A brand source must be a bounded real file.');
+  return fs.readFileSync(file,'utf8');
+};
+
+const PATH_ESCAPES='the declared path escapes its repository root';
+/** Why a declared source path cannot be read inside `sourceRoot`, or null. */
+function sourcePathError(sourceRoot,declared){
+  if(!declared||path.isAbsolute(declared)||declared.split('/').includes('..'))return PATH_ESCAPES;
+  const file=path.resolve(sourceRoot,declared);
+  if(path.relative(path.resolve(sourceRoot),file).startsWith('..'))return PATH_ESCAPES;
+  return fs.existsSync(file)?null:'this repository does not carry the declared file';
+}
+
+/** The token lookup of a read source file: css custom properties, or a JSON/YAML token file. */
+function parseSourceText(file,source,text,entry){
+  if(source.kind==='css'||path.extname(file).toLowerCase()==='.css'){
+    const parsed=parseCssCustomProperties(text);
+    return {...entry,found:true,declarations:parsed.all.length,lookup:{css:parsed}};
+  }
+  try{
+    const data=path.extname(file).toLowerCase()==='.json'?JSON.parse(text):parseYaml(text);
+    const parsed=parseTokenData(data);
+    return {...entry,found:true,declarations:parsed.exact.size+parsed.derived.size,lookup:{tokens:parsed}};
+  }catch(error){return {...entry,found:true,error:`unreadable token file: ${String(error.message??error)}`};}
+}
+
+/** One declared source file, read into a token lookup. Never throws: an unreadable source is reported. */
+export function readSourceTokens(sourceRoot,source){
+  const declared=slash(source?.path??'');
+  const entry={repository:source?.repository??null,path:declared,kind:source?.kind??null,found:false,declarations:0,scope:null};
+  const pathError=sourcePathError(sourceRoot,declared);
+  if(pathError)return {...entry,error:pathError};
+  const file=path.resolve(sourceRoot,declared);
+  // A source inside a built @starci/grammar dist is read only when that dist is the build of its source:
+  // a stale dist would bind the brand to tokens the package no longer ships.
+  const refusal=grammarDistRefusal(file);
+  if(refusal)return {...entry,found:true,error:refusal.message,staleGrammarDist:{state:refusal.state,root:refusal.root,fix:refusal.fix}};
+  let text;
+  try{text=readText(file);}catch(error){return {...entry,found:true,error:String(error.message??error)};}
+  return parseSourceText(file,source,text,entry);
+}
+
+/** The first declaration of this token across the declared sources, preferring the default scope. */
+export function lookupToken(sources,token,seen=new Set()){
+  if(seen.has(token))return null;
+  const nextSeen=new Set(seen).add(token);
+  for(const scope of ['base','dark']){
+    for(const source of sources){
+      const hit=lookupInSource(sources,source,token,scope,nextSeen);
+      if(hit)return hit;
+    }
+  }
+  return null;
+}
+
+/** A css declaration of the token in `scope`, its `var(--other)` followed through the declared sources. */
+function resolveCssDeclaration(sources,source,found,scope,seen){
+  const reference=/^var\(\s*(--[A-Za-z0-9_-]+)\s*\)$/.exec(String(found.value).trim())?.[1]??null;
+  if(reference){
+    const resolved=lookupToken(sources,reference,seen);
+    if(resolved)return {...resolved,file:source.path,selector:found.selector,scope,declaredValue:found.value,resolvedFrom:reference};
+  }
+  return {value:found.value,file:source.path,selector:found.selector,scope};
+}
+
+/** The token as one source declares it in `scope` (a token file only answers the base scope), or null. */
+function lookupInSource(sources,source,token,scope,seen){
+  const found=source.lookup?.css?.[scope].get(token);
+  if(found)return resolveCssDeclaration(sources,source,found,scope,seen);
+  const tokens=scope==='base'?source.lookup?.tokens:null;
+  if(!tokens)return null;
+  const value=tokens.exact.get(token)??tokens.derived.get(token)??tokens.derived.get(token.replace(/^--/,''));
+  return value===undefined?null:{value,file:source.path,selector:null,scope:'base'};
+}

package/runtime/scripts/work/brand/brand-value-source.mjs

@@ -0,0 +1,106 @@
+// brand-value-source.mjs - how a colour token the app has not written yet is traced (brand.mjs tokens-match-source). Two forms:
+//   {path, value, token?, line?, sha256?}  the reference render the value was read from: the file is read, never written.
+//   {ruling, token, value}                 the answered ask that ruled the value, read from the ledger's recorded answer; the
+//                                          declaration the app still has to make is owed to interface.implement.
+// Both pass at the decide stage and are refused at the verify stage while the app source lacks the token (planned-source-missing).
+import fs from 'node:fs';
+import path from 'node:path';
+import {sha256 as digest} from '../../../engine/digest.mjs';
+import {slash} from '../../lib/path-key.mjs';
+import {parseColor,deltaEOk,TOKEN_TOLERANCE} from './brand-colour.mjs';
+import {readSourceTokens,lookupToken} from './brand-tokens.mjs';
+
+const round=(value,places=4)=>Number.parseFloat(Number(value).toFixed(places));
+const collapse=value=>String(value??'').trim().replace(/\s+/g,' ').toLowerCase();
+const CUSTOM_PROPERTY=/^--[A-Za-z0-9_-]+$/;
+const COLOUR_IN_TEXT=/#[0-9a-f]{3,8}\b|(?:oklch|rgba?)\([^)]*\)/gi;
+/** The answerers whose recorded answer is a ruling: the owner, the owner's standing autopilot ruling, and the config's auto-accept of the recommended option. */
+const RULING_ANSWERERS=Object.freeze(['owner','autopilot','auto-recommended']);
+/** The op that writes the app theme, so the one that owes the declaration of a planned token. */
+export const OWED_TO='interface.implement';
+
+const invalid=why=>({status:'value-source-invalid',why});
+
+/** The first recorded answer of `ruling` given by one of RULING_ANSWERERS, or the first refusal. */
+function rulingAnswer({ruling,brandDir,findReceipt}){
+  if(typeof findReceipt!=='function')return {ok:false,why:'no ledger was given to read the ruling from'};
+  const attempts=RULING_ANSWERERS.map(answerer=>findReceipt({acceptedBy:ruling,brandDir,answerer}));
+  return attempts.find(attempt=>attempt.ok)??attempts[0];
+}
+
+/** Whether the answer's own words (the chosen option, the note, the picks) carry `value`, as the same text or as a colour equal to it. */
+function answerCarries(answer,value){
+  const wanted=parseColor(value);
+  const texts=[answer.option,answer.note,...Object.values(answer.picks??{})].filter(text=>typeof text==='string');
+  const sameColour=text=>[...text.matchAll(COLOUR_IN_TEXT)].some(found=>{const colour=parseColor(found[0]);return Boolean(colour&&wanted&&deltaEOk(colour,wanted)<=TOKEN_TOLERANCE);});
+  return texts.some(text=>collapse(text).includes(collapse(value))||sameColour(text));
+}
+
+/** The shape of a ruling reference, or the refusal naming what is wrong with it. */
+function rulingShapeProblem(reference){
+  if(typeof reference.ruling!=='string'||!reference.ruling.trim())return 'valueSource.ruling must be the dispatch id of the answered ask that ruled this value';
+  if(typeof reference.token!=='string'||!CUSTOM_PROPERTY.test(reference.token))return 'valueSource.token must be the custom property the app has to declare';
+  if(typeof reference.value!=='string'||!reference.value.trim())return 'valueSource.value must be the exact value the ruling carries';
+  if(['path','sha256','line'].some(key=>Object.hasOwn(reference,key)))return 'a ruling valueSource is {ruling, token, value}; a file reference names path and has no ruling';
+  return null;
+}
+
+/** A token traced to the ledger's recorded answer: the answer exists, was given by a ruling answerer, carries the value, and the value is the brand value. */
+function checkRulingSource({token,reference,brandDir,findReceipt}){
+  const problem=rulingShapeProblem(reference);
+  if(problem)return invalid(problem);
+  if(reference.token!==token.token)return invalid(`valueSource.token ${reference.token} must be this brand token, ${token.token}: the app declares it under its brand token name`);
+  const evidence={ruling:reference.ruling,token:reference.token,value:reference.value,owedTo:OWED_TO};
+  const answer=rulingAnswer({ruling:reference.ruling,brandDir,findReceipt});
+  if(!answer.ok)return {...evidence,status:'ruling-unrecorded',why:answer.why};
+  const given={answeredBy:answer.answeredBy,provisional:answer.provisional,answeredAt:answer.at,receipt:answer.file};
+  if(!answerCarries(answer,reference.value))return {...evidence,...given,status:'ruling-differs',why:`the answer to ${reference.ruling} does not carry ${reference.value}`};
+  const expected=parseColor(token.value),ruled=parseColor(reference.value);
+  if(!expected||!ruled)return {...evidence,...given,status:'unparseable-reference-value',why:'the brand value or the ruled value is not a colour this runtime can parse'};
+  const delta=round(deltaEOk(expected,ruled),3);
+  if(delta>TOKEN_TOLERANCE)return {...evidence,...given,deltaE:delta,status:'ruling-differs',why:`the brand value ${token.value} is not the ruled value ${reference.value}`};
+  return {...evidence,...given,deltaE:delta,status:'planned-from-ruling'};
+}
+
+/**
+ * A token the app has not written yet may name the external render it was read from:
+ * `valueSource: {path, value, token?, line?, sha256?}`. `path` is relative to the same --source root as
+ * `sources[]` (for example `acme-fe/src/app/globals.css`) and is only ever read; `token` is the
+ * name the reference declares (default: the brand token's own name); `value` is the exact value it declares
+ * there. The reference passes when that declaration exists in the default (light) scope with exactly that
+ * text, its colour is the brand value, and a declared sha256 still names the file's bytes.
+ */
+function checkFileSource({sourceRoot,token,reference}){
+  if(typeof reference.path!=='string'||!reference.path.trim())return invalid('valueSource.path must name the reference file, relative to the --source root');
+  if(typeof reference.value!=='string'||!reference.value.trim())return invalid('valueSource.value must be the exact value the reference declares');
+  const name=reference.token??token.token;
+  if(typeof name!=='string'||!CUSTOM_PROPERTY.test(name))return invalid('valueSource.token must be the custom property the reference declares');
+  const evidence={path:slash(reference.path),token:name,value:reference.value,line:reference.line??null,declaredSha256:reference.sha256??null};
+  const extension=path.extname(reference.path).toLowerCase();
+  const read=readSourceTokens(sourceRoot,{path:reference.path,kind:extension==='.css'?'css':'tokens'});
+  if(read.error)return {...evidence,status:'reference-unreadable',why:read.error};
+  if(reference.sha256!==undefined&&reference.sha256!==null){
+    const computed=digest(fs.readFileSync(path.resolve(sourceRoot,reference.path)));
+    if(String(reference.sha256).toLowerCase()!==computed)
+      return {...evidence,computedSha256:computed,status:'reference-digest-mismatch',why:'the reference file is no longer the bytes the brand read'};
+  }
+  const found=lookupToken([read],name);
+  if(!found)return {...evidence,status:'reference-absent',why:`the reference does not declare ${name}`};
+  if(found.scope==='dark')return {...evidence,actual:found.value,selector:found.selector,status:'reference-only-in-dark-scope',why:`the reference declares ${name} only in a dark scope`};
+  const declared=[found.value,found.declaredValue].filter(value=>value!==undefined).map(collapse);
+  if(!declared.includes(collapse(reference.value)))
+    return {...evidence,actual:found.declaredValue??found.value,selector:found.selector,status:'reference-differs',why:`the reference declares ${name}: ${found.declaredValue??found.value}, not ${reference.value}`};
+  const expected=parseColor(token.value),planned=parseColor(reference.value);
+  if(!expected||!planned)return {...evidence,status:'unparseable-reference-value',why:'the brand value or the reference value is not a colour this runtime can parse'};
+  const delta=round(deltaEOk(expected,planned),3);
+  if(delta>TOKEN_TOLERANCE)return {...evidence,deltaE:delta,status:'reference-differs',why:`the brand value ${token.value} is not the reference value ${reference.value}`};
+  return {...evidence,selector:found.selector,deltaE:delta,status:'planned-from-reference'};
+}
+
+/** One planned token's trace: its reference file or its ruling. `findReceipt` reads an answered ask from the ledger (brand.mjs findOwnerReceipt). */
+export function checkValueSource({sourceRoot,token,brandDir=null,findReceipt=null}){
+  const reference=token?.valueSource;
+  if(!reference||typeof reference!=='object'||Array.isArray(reference))return invalid('valueSource must be an object {path, value, token?, line?, sha256?} or {ruling, token, value}');
+  if(Object.hasOwn(reference,'ruling'))return checkRulingSource({token,reference,brandDir,findReceipt});
+  return checkFileSource({sourceRoot,token,reference});
+}