@starci/hfs 4.7.47 → 4.9.0

package/runtime/scripts/machine/workflow-tree.mjs

@@ -1,122 +0,0 @@
-// workflow-tree.mjs - the host registry's view of a workflow's worktree (machine.sqlite worktrees, kind workflow) and the
-// base an op's gate measures against there. Read by the Kernel (scripts/kernel/workflow-worktree.mjs,
-// workflow-checkpoint.mjs) and by scripts/gates/gate.mjs, which finds its workflow from the directory it runs in.
-import fs from 'node:fs';
-import path from 'node:path';
-import { mergeBase } from '../api/git/merge-base.mjs';
-import { diffNames } from '../api/git/diff-names.mjs';
-import { log as gitLog } from '../api/git/log.mjs';
-import { revParse as gitRevParse } from '../api/git/rev-parse.mjs';
-import { withMachine } from '../../engine/db/machine.mjs';
-import { isInside } from '../lib/walk.mjs';
-import { requireWorktreeRecord } from '../lib/worktree-record.mjs';
-
-const SHA = /^[0-9a-f]{40,64}$/;
-const insidePath = (child, parent) => isInside(path.resolve(parent), path.resolve(child));
-const fail = ({ code }, message) => Object.assign(new Error(message), { code });
-const revParse = (cwd, ref) => { const sha = gitRevParse(cwd, ref); return sha && SHA.test(sha) ? sha : null; };
-const mainOf = (ctx) => ctx?.main ?? 'main';
-const envOf = (ctx) => ctx?.env ?? process.env;
-
-/** A registry row of a workflow worktree as a record: {workflowId, orcaWorktreeId, path, branch, checkpoint, repoRoot, ...}, or null. */
-export const workflowRecordOf = (row) => (row ? { workflowId: row.workflow_id, orcaWorktreeId: row.orca_id, path: path.resolve(row.path), branch: row.branch ?? null,
-  checkpoint: row.checkpoint_sha ?? null, repoRoot: row.repo_root, ledgerId: row.ledger_id ?? null, createdAt: row.created_at,
-  releasePending: row.release_pending_at != null } : null);
-
-/** The live workflow worktree of `workflowId`: {workflowId, orcaWorktreeId, path, branch, checkpoint, repoRoot}, or null. */
-export function workflowWorktreeOf(ctx, workflowId) {
-  const env = envOf(ctx);
-  try {
-    return workflowRecordOf(withMachine((m) => m.db.prepare("SELECT * FROM worktrees WHERE kind='workflow' AND workflow_id=? AND orca_id IS NOT NULL AND removed_at IS NULL ORDER BY created_at DESC LIMIT 1").get(workflowId), { env }));
-  } catch (cause) { throw Object.assign(new Error(`the workflow worktree registry is unavailable: ${cause.message}`, { cause }), { code: 'worktree-registry-unavailable' }); }
-}
-
-/**
- * The live workflow worktree whose directory is `dir` (or holds it), or null: how a tool run inside a worktree
- * (scripts/gates/gate.mjs) finds its workflow through the registry, never by parsing a branch or folder name.
- */
-export function workflowWorktreeAt(ctx, dir) {
-  const env = envOf(ctx);
-  const at = path.resolve(dir);
-  const key = (p) => { let r = path.resolve(p); try { r = fs.realpathSync.native(r); } catch { /* missing */ } return process.platform === 'win32' ? r.toLowerCase() : r; };
-  try {
-    const rows = withMachine((m) => m.db.prepare("SELECT * FROM worktrees WHERE kind='workflow' AND orca_id IS NOT NULL AND removed_at IS NULL ORDER BY created_at DESC").all(), { env });
-    const row = rows.find((r) => key(r.path) === key(at)) ?? rows.find((r) => insidePath(key(at), key(r.path)));
-    return workflowRecordOf(row ?? null);
-  } catch (cause) { throw Object.assign(new Error(`the workflow worktree registry is unavailable: ${cause.message}`, { cause }), { code: 'worktree-registry-unavailable' }); }
-}
-
-/** The registry functions a caller may replace (ctx.worktree in a spec, the functions above in the runtime). */
-const registryOf = (ctx) => ({ workflowWorktreeOf, workflowWorktreeAt, ...ctx?.worktree });
-
-/** The registry record of the workflow's worktree, its directory present: {workflowId, orcaWorktreeId, path, branch, checkpoint}. */
-function presentRecordOf(ctx, workflowId) {
-  return requireWorktreeRecord(registryOf(ctx).workflowWorktreeOf(ctx, workflowId), workflowId);
-}
-
-/**
- * The gate base of the workflow worktree that holds `dir` (part A's workflowWorktreeAt over the registry), or null when
- * `dir` is no workflow worktree: scripts/gates/gate.mjs measures an op there against its previous checkpoint.
- */
-export function gateBaseAt(ctx, dir) {
-  const rec = registryOf(ctx).workflowWorktreeAt(ctx, dir);
-  return rec ? gateBaseOf(ctx, rec.workflowId) : null;
-}
-
-/** The base an op's gate measures against: the previous checkpoint, else the merge-base of the workflow branch with main. */
-/**
- * The newest checkpoint commit of the workflow's own chain on the branch (subject `checkpoint <workflowId>: ...`, first-parent line from HEAD), or null. A registry
- * record that lost its checkpoint pointer (a tree put back by the custody repair) must not fall back to the merge-base with main: that would put the base of
- * every settled op's gate, and the target of a reset, behind the work those ops committed.
- */
-function chainCheckpointOf(rec) {
-  const r = gitLog(['--first-parent', '--format=%H%x09%s', '-n', '256', 'HEAD'], { cwd: rec.path, timeout: 30_000 });
-  if (r.status !== 0) return null;
-  const prefix = `checkpoint ${rec.workflowId}:`;
-  for (const line of String(r.stdout ?? '').split(/\r?\n/)) {
-    const [sha, subject] = line.split('\t');
-    if (SHA.test(sha ?? '') && subject?.startsWith(prefix)) return sha;
-  }
-  return null;
-}
-
-export function gateBaseOf(ctx, workflowId) {
-  const rec = presentRecordOf(ctx, workflowId);
-  const chained = rec.checkpoint ? null : chainCheckpointOf(rec);
-  if (chained) return chained;
-  if (rec.checkpoint) {
-    const sha = revParse(rec.path, rec.checkpoint);
-    if (!sha) throw fail({ code: 'workflow-gate-base-unknown' }, `the checkpoint ${rec.checkpoint} of workflow ${workflowId} is not a commit of ${rec.path}`);
-    return sha;
-  }
-  const base = mergeBase(rec.path, `refs/heads/${mainOf(ctx)}`, 'HEAD') ?? '';
-  if (!SHA.test(base)) throw fail({ code: 'workflow-gate-base-unknown' }, `workflow ${workflowId} has no checkpoint and ${rec.branch} has no merge-base with ${mainOf(ctx)}`);
-  return base;
-}
-
-const CHAIN_WALK_MAX = 64;
-/**
- * The bases an op's gate may have measured against, newest first (per side, WFWT2 2.2): the current checkpoint, then each
- * older checkpoint of the chain while the checkpoint stepped over changed none of `owned` (the op's owned paths, the
- * leases checkpointOp commits), stopping at the chain's start (the merge-base with main). A be checkpoint committed while
- * an fe op ran therefore never forces the fe op to re-run its gate: what differs between the bases is the other side's
- * committed, gated work, and the finish gates the whole branch again. An op that owns no path or owns '.' gets the current
- * checkpoint only.
- */
-export function gateBasesOf(ctx, workflowId, { owned = [] } = {}) {
-  const current = gateBaseOf(ctx, workflowId);
-  const paths = owned.map(String).filter(Boolean);
-  if (!paths.length || paths.some((p) => p === '.' || p === './')) return [current];
-  const rec = presentRecordOf(ctx, workflowId);
-  const root = mergeBase(rec.path, `refs/heads/${mainOf(ctx)}`, current);
-  const bases = [current];
-  for (let at = current; at !== root && bases.length < CHAIN_WALK_MAX;) {
-    const parent = revParse(rec.path, `${at}^`);
-    if (!parent) break;
-    const touched = diffNames(rec.path, parent, at, { paths: paths.map((p) => `:(literal)${p}`) });
-    if (touched === null || touched.length) break;
-    bases.push(parent);
-    at = parent;
-  }
-  return bases;
-}

package/runtime/scripts/reconciler/checklist-items.mjs

@@ -1,7 +0,0 @@
-// The checklist row builders of `start` (scripts/reconciler/start.mjs) and of the row modules split out of it.
-
-/** One checklist row. status green|red|warn; required rows decide the exit code, warn never does; a green row with `idle: true` is an agent seat that is not running because nothing needs it yet. */
-const item = (group, id, name, status, detail = '', { fix = null, required = true, idle = false } = {}) => ({ group, id, name, status, required: required && status !== 'warn', detail, ...(fix && status !== 'green' ? { fix } : {}), ...(idle && status === 'green' ? { idle: true } : {}) });
-export const green = (group, id, name, detail, opts) => item(group, id, name, 'green', detail, opts);
-export const red = (group, id, name, detail, fix, opts) => item(group, id, name, 'red', detail, { fix, ...opts });
-export const warn = (group, id, name, detail, fix) => item(group, id, name, 'warn', detail, { fix, required: false });

package/runtime/scripts/reconciler/guard-row.mjs

@@ -1,25 +0,0 @@
-// guard-row.mjs — the host checklist row of the command guard hook: the exact hook command launch trust registers is run
-// the way a seat's shell runs it (scripts/api/process/probe-guard-command.mjs), because a hook that does not resolve is a
-// non-blocking error and leaves every guarded command unguarded. Required: red names each failing shell.
-import { probeGuardCommand } from '../api/process/probe-guard-command.mjs';
-import { toolGuardCommand } from '../lib/guard-command.mjs';
-import { green, red } from './checklist-items.mjs';
-
-const NAME = 'command guard resolvable';
-const FIX = 'starci runtime link, then launch again to refresh the registered Node and linked runtime CLI paths';
-
-/** The row of one probe of `toolGuardCommand()`; never throws. Seam: `probe`. */
-export function guardCommandRow({ home, probe = probeGuardCommand } = {}) {
-  let command;
-  let result;
-  try {
-    command = toolGuardCommand({ home });
-    result = probe({ command, home });
-  }
-  catch (error) { return red('preflight', 'guard-command', NAME, `${command ?? 'linked runtime guard'}: ${String(error?.message ?? error).slice(0, 200)}`, FIX); }
-  if (!result.ok) return red('preflight', 'guard-command', NAME, `${command} does not run: ${result.reason}`.slice(0, 400), FIX);
-  const ran = result.shells.filter((entry) => !entry.skipped).map((entry) => entry.shell).join(', ');
-  const skipped = result.shells.filter((entry) => entry.skipped).map((entry) => entry.skipped);
-  const note = skipped.length ? ` (skipped: ${skipped.join('; ')})` : '';
-  return green('preflight', 'guard-command', NAME, `${command} runs through ${ran}${note}`);
-}

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

@@ -1,125 +0,0 @@
-// 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

@@ -1,167 +0,0 @@
-// 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

@@ -1,106 +0,0 @@
-// 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});
-}