@reqvire-org/ads 0.3.18 → 0.3.21

package/dist/contract-migration.mjs

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { adsFileRole, isBehaviorFile, isScenarioFile, loadConfig, scenarioIdentity } from "./config.mjs";
+import { inspectUnitContracts } from "./unit-contracts.mjs";
+import { publicApi } from "./public-api.mjs";
+import { projectCompilerOptions } from "./boundaries.mjs";
+
+const slash=value=>value.replaceAll("\\","/");
+
+/** Mechanical edits in an ordinary owner draft. Never writes live source. */
+export function migrateContractDraft(options, prepared) {
+  const base=prepared.directory, name=path.posix.basename(prepared.unit), renames=new Map(), notes=[];
+  const relative=file=>slash(path.relative(base,file));
+  const resolve=file=>path.join(base,file);
+  const files=prepared.files.filter(file=>!file.endsWith("ds.config.json")&&file.startsWith(options.config.dsDir+"/"));
+  const owned=files.filter(file=>!file.endsWith("/"+options.config.publicEntry)&&!file.endsWith("/"+options.config.reviewEntry));
+  for(const file of owned) {
+    if(adsFileRole(file)||!/\.[cm]?[jt]sx?$/.test(file))continue;
+    let next;
+    if(isScenarioFile(file))next=path.basename(file).startsWith("Scenario.")?path.join(path.dirname(file),`${name}.ads.scenario${path.extname(file)}`):file.replace(/\.scenario\./,".ads.scenario.");
+    else if(/(?:^|\/)fixture\.[cm]?[jt]sx?$/.test(file))next=path.join(path.dirname(file),`${name}.ads.fixture${path.extname(file)}`);
+    else if(/\.(?:fixture|fixtures|test|spec)\.[cm]?[jt]sx?$/.test(file))next=file.replace(/\.(behavior\.spec|fixture|fixtures|test|spec)(\.[^.]+)$/,".ads.$1$2");
+    else if(/\.scenario-adapter\.[cm]?[jt]sx?$/.test(file))next=file.replace(/\.scenario-adapter\./,".ads.helpers.");
+    if(next&&next!==file) {
+      next=slash(next);
+      if(isScenarioFile(file)&&scenarioIdentity(path.join(options.root,file),options.dsRoot)===prepared.unit&&scenarioIdentity(path.join(options.root,next),options.dsRoot)!==prepared.unit){notes.push(`Kept ${file}: a default-directory rename would change this flat owner's identity. Review a deliberate owner migration separately.`);continue;}
+      if([...renames.values()].includes(next)&&isScenarioFile(file))next=next.replace(".ads.scenario.",".named.ads.scenario.");
+      if(existsSync(resolve(next)))throw new Error(`Migration would overwrite ${next}; resolve the naming conflict in this draft.`);
+      renames.set(file,next);
+    }
+  }
+  for(const file of owned.filter(isScenarioFile)) {
+    const fixtureBase=path.basename(file).startsWith("Scenario.")?path.join(path.dirname(file),"fixture"):file.replace(/\.scenario\.[^.]+$/,".fixture");
+    const fixture=owned.find(candidate=>candidate.startsWith(fixtureBase+".")&&/\.(?:[cm]?[jt]sx?|json)$/.test(candidate));
+    if(!fixture)continue;
+    const scenario=renames.get(file);
+    if(scenario)renames.set(fixture,scenario.replace(/\.scenario\.[^.]+$/,".fixture")+path.extname(fixture));
+    else renames.delete(fixture);
+  }
+  if(new Set(renames.values()).size!==renames.size)throw new Error("Migration has colliding development filenames; resolve the owner draft deliberately.");
+  const jsonFiles=owned.filter(file=>isBehaviorFile(file)||/(?:^|\/)tokens\.json$|\.tokens\.json$/.test(file));
+  for(const [from,to]of renames)if(isScenarioFile(from)&&scenarioIdentity(path.join(options.root,from),options.dsRoot)!==scenarioIdentity(path.join(options.root,to),options.dsRoot)) {
+    const text=readFileSync(resolve(from),"utf8"),source=ts.createSourceFile(from,text,ts.ScriptTarget.Latest,true,ts.ScriptKind.TSX);
+    const declaration=source.statements.filter(ts.isVariableStatement).flatMap(statement=>statement.declarationList.declarations).find(declaration=>ts.isIdentifier(declaration.name)&&declaration.name.text==="scenario");
+    let expression=declaration?.initializer;while(expression&&(ts.isAsExpression(expression)||ts.isSatisfiesExpression(expression)||ts.isParenthesizedExpression(expression)))expression=expression.expression;
+    if(expression&&ts.isObjectLiteralExpression(expression)) {
+      if(!expression.properties.some(property=>property.name?.getText()==="id")){const at=expression.getStart()+1;writeFileSync(resolve(from),text.slice(0,at)+`id:${JSON.stringify(scenarioIdentity(path.join(options.root,from),options.dsRoot))},`+text.slice(at));}
+    }else {renames.delete(from);notes.push(`Kept ${from}: its indirect metadata needs an explicit stable id before this rename.`);}
+  }
+  const runtime=owned.find(file=>!adsFileRole(file)&&!isScenarioFile(file)&&new RegExp(`(?:^|/)${name.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}\\.[cm]?[jt]sx?$`).test(file));
+  const directory=runtime?path.dirname(runtime):path.dirname(owned[0]??path.join(options.config.dsDir,prepared.unit,"entry.ts"));
+  const contractFile=slash(path.join(directory,`${name}.ads.contract.ts`));
+  const contract={schemaVersion:1},imports=[],references=new Map();
+  const compiler=ts.createProgram(files.filter(file=>/\.[cm]?[jt]sx?$/.test(file)).map(file=>path.resolve(options.root,file)),{...projectCompilerOptions(options),allowJs:true});
+  const checker=compiler.getTypeChecker(),apis=publicApi(compiler,options);
+  function importReference(file,symbol) {
+    const source=compiler.getSourceFile(path.resolve(options.root,file));
+    const module=source&&checker.getSymbolAtLocation(source);
+    const exported=module&&checker.getExportsOfModule(module).find(item=>item.name===symbol);
+    if(!exported)throw new Error(`${file}#${symbol} is not an importable internal export; keep the legacy section until its owner deliberately exposes a local contract reference.`);
+    const key=`${file}#${symbol}`;
+    if(!references.has(key)) {
+      const alias=`subject${references.size}`;references.set(key,alias);
+      let specifier=slash(path.relative(path.dirname(contractFile),file)).replace(/\.[cm]?[jt]sx?$/,"");if(!specifier.startsWith("."))specifier="./"+specifier;
+      imports.push(`import { ${symbol} as ${alias} } from ${JSON.stringify(specifier)};`);
+    }
+    return `__ads_reference_${references.get(key)}__`;
+  }
+  const remove=[];
+  if(!existsSync(resolve(contractFile)))for(const file of jsonFiles) {
+    const value=JSON.parse(readFileSync(resolve(file),"utf8"));
+    if(isBehaviorFile(file)) {
+      try {
+        const subjects={};
+        for(const [id,subject]of Object.entries(value.subjects??{})) {
+          if(subject.api) {const api=apis.find(api=>api.name===subject.api);if(!api)throw new Error(`Unknown API ${subject.api}`);subjects[id]={api:importReference(slash(path.relative(options.root,api.file)),api.declaration.name?.text??subject.api)};}
+          else if(subject.symbol)subjects[id]={implementation:importReference(slash(path.normalize(path.join(path.dirname(file),subject.source))),subject.symbol)};
+          else throw new Error(`Subject ${id} names a whole file. Select an actual implementation symbol before migrating this behavior section.`);
+        }
+        const {schemaVersion:_version,...behavior}=value;contract.behavior={...behavior,subjects};remove.push(file);
+      }catch(error){notes.push(error.message);}
+    }else {contract.tokens={namespace:value.namespace,stylesheet:"./"+slash(path.relative(path.dirname(contractFile),file.replace(/\.json$/,".css")))};remove.push(file);}
+  }
+  for(const file of files) {
+    if(!/\.[cm]?[jt]sx?$|\.json$|\.md$/.test(file)||remove.includes(file))continue;
+    const original=readFileSync(resolve(file),"utf8");let text=original;
+    for(const [before,after]of renames) {
+      let from=slash(path.relative(path.dirname(file),before)),to=slash(path.relative(path.dirname(renames.get(file)??file),after));
+      if(!from.startsWith("."))from="./"+from;if(!to.startsWith("."))to="./"+to;
+      for(const [left,right]of [[before,after],[from,to],[from.replace(/\.[cm]?[jt]sx?$/,""),to.replace(/\.[cm]?[jt]sx?$/,"")]]) {
+        for(const quote of ['"',"'","`"] )text=text.replaceAll(quote+left+quote,quote+right+quote);
+        if(file.endsWith(".md"))text=text.replaceAll(`](${left})`,`](${right})`);
+      }
+    }
+    if(text!==original)writeFileSync(resolve(file),text);
+  }
+  if(remove.length) {
+    if(contract.behavior)for(const check of Object.values(contract.behavior.checks)) {
+      const old=slash(path.normalize(path.join(directory,check.file))),next=renames.get(old);
+      if(next)check.file="./"+slash(path.relative(directory,next));
+    }
+    let text=JSON.stringify(contract,null,2);
+    for(const alias of references.values())text=text.replaceAll(JSON.stringify(`__ads_reference_${alias}__`),alias);
+    writeFileSync(resolve(contractFile),`import type { UnitContract } from "@reqvire-org/ads/contracts";\n${imports.filter(line=>[...references.values()].some(alias=>line.includes(` as ${alias} `)&&new RegExp(`\\b${alias}\\b`).test(text))).join("\n")}\nexport default ${text} satisfies UnitContract;\n`);
+    for(const file of remove) {const fsPath=resolve(file);renameSync(fsPath,path.join(base,"..",`migrated-${path.basename(file)}`));}
+  }else if(inspectUnitContracts(loadConfig(options.root)).contracts.some(contract=>contract.unit===prepared.unit))notes.push("Existing TypeScript contract retained. Only legacy file roles/references were renamed.");
+  for(const [from,to]of renames)renameSync(resolve(from),resolve(to));
+  return {...prepared,migration:{renamed:[...renames].map(([from,to])=>({from,to})),converted:remove,contractFile:remove.length?relative(resolve(contractFile)):null,notes},next:"Review the migrated draft and its references, then use action: diff and ads_apply_patch dryRun: true. Live source is unchanged; unresolved sections retain their legacy registration. Migrate one passing owner at a time."};
+}

package/dist/contracts.d.mts

@@ -0,0 +1,22 @@
+/** Development-only declaration types. ADS reads the contract AST without execution. */
+export type Implementation = ((...args: never[]) => unknown) | (abstract new (...args: never[]) => unknown);
+export interface BehaviorCheck { file: string; case: string; scenario?: string; profile: string; }
+export interface UnitContract {
+  schemaVersion: 1;
+  tokens?: { namespace: string; stylesheet: string };
+  paintInputs?: readonly { api: Implementation; property: string; kind: "paint-reference"; bindings?: readonly string[] }[];
+  bindings?: Readonly<Record<string, {
+    input: { api: Implementation; property: string };
+    producer: Implementation;
+    valueFrom: string;
+    variable: string;
+    scope: { api: Implementation; selector: string };
+    checks: readonly string[];
+  }>>;
+  declarativeParts?: readonly { api: Implementation; parent: Implementation; consumer: Implementation; checks: readonly string[] }[];
+  behavior?: {
+    subjects: Readonly<Record<string, { api: Implementation } | { implementation: Implementation }>>;
+    guarantees: readonly { id: string; description: string; subjects: readonly string[]; checks: readonly string[] }[];
+    checks: Readonly<Record<string, BehaviorCheck>>;
+  };
+}

package/dist/evidence.mjs

@@ -12,7 +12,7 @@ export function acceptance(scope, passed, established, unverified) {
 
 export function architectureEvidence(result) {
   return { ...result,
-    diagnostics: result.diagnostics.map(diagnostic => ({ ...diagnostic, failure: diagnostic.failure ?? failure("architecture", "source-analysis", diagnostic.rule) })),
+    diagnostics: result.diagnostics.map(diagnostic => ({ ...diagnostic, ...(/^(?:unit-contract|paint-.+|binding-.+|declarative-.+|development-role)$/.test(diagnostic.rule)&&!diagnostic.guidanceUri?{guidanceUri:"ads://guides/contracts"}:{}), failure: diagnostic.failure ?? failure("architecture", "source-analysis", diagnostic.rule) })),
     acceptance: acceptance("core-architecture", result.ok, result.ok ? ["core-source-guards"] : [], ["project-checks", "compiled-preview", "browser-behavior", "visual-parity", "accessibility-audit"]),
   };
 }

package/dist/index.mjs

@@ -1,6 +1,7 @@
 export { initProject } from "./init.mjs";
 export { checkProject } from "./check.mjs";
 export { inspectTokens, tokenContract } from "./tokens.mjs";
+export { inspectTokenOrigins } from "./token-origins.mjs";
 export { generateLintConfig } from "./lint-config.mjs";
 export { generateBrandAssets } from "./brand-assets.mjs";
 // Node-only helpers for registered project lint extensions. They reuse the

package/dist/init.mjs

@@ -152,16 +152,16 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
     return file;
   });
   if (!existingTokens.length) {
-    for (const name of ["Foundation.scenario.tsx", "Foundation.fixture.ts"]) {
-      const content = readFileSync(path.join(starter, "design-system/tokens", name), "utf8").replaceAll('"@ds"', JSON.stringify(config.publicAlias));
+    for (const name of ["Foundation.ads.scenario.tsx", "Foundation.ads.fixture.ts"]) {
+      const content = readFileSync(path.join(starter, "design-system/tokens", name), "utf8").replaceAll('"@ds/review"', JSON.stringify(`${config.publicAlias}/review`)).replaceAll('"@ds"', JSON.stringify(config.publicAlias));
       addMissing(path.join(tokenRoot, name), content);
     }
-    for (const name of ["TokenPreview.tsx", "Scenario.tsx", "fixture.ts"]) {
-      let content = readFileSync(path.join(starter, "design-system/patterns/token-preview", name), "utf8");
+    for (const name of ["TokenPreview.tsx"]) {
+      let content = readFileSync(path.join(starter, "design-system/review/token-preview", name), "utf8");
       if (selectedFramework === "preact") content = content.replace('from "react"', 'from "preact/hooks"');
-      addMissing(path.join(dsRoot, "patterns/token-preview", name), content.replaceAll('"@ds"', JSON.stringify(config.publicAlias)));
+      addMissing(path.join(dsRoot, "review/token-preview", name), content.replaceAll('"@ds"', JSON.stringify(config.publicAlias)));
     }
-    const reviewFile = path.relative(root, path.join(dsRoot, "patterns/token-preview/TokenPreview.tsx")).replaceAll("\\", "/");
+    const reviewFile = path.relative(root, path.join(dsRoot, "review/token-preview/TokenPreview.tsx")).replaceAll("\\", "/");
     if (!config.boundaries.styleWrites.some(item => item.file === reviewFile)) config.boundaries.styleWrites.push({ file: reviewFile, properties: ["--ux-token-preview-value"] });
   }
   tokenFiles.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
@@ -172,16 +172,19 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
   };
   addMissing(stylesFile, tokenFiles.map((file) => `@import ${JSON.stringify(relativeImport(stylesFile, file))};`).join("\n") + "\n");
   const entryFile = path.join(dsRoot, config.publicEntry);
-  const reviewExport = !existingTokens.length ? `export { TokenPreview } from ${JSON.stringify(relativeImport(entryFile, path.join(dsRoot, "patterns/token-preview/TokenPreview")))};\n` : "";
-  addMissing(entryFile, `// Export your project's public components and types here.\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\n${reviewExport}`);
-  if (reviewExport && existsSync(entryFile) && !readFileSync(entryFile, "utf8").includes("patterns/token-preview/TokenPreview")) {
-    let current = readFileSync(entryFile, "utf8");
-    if (/\bTokenPreview\b/.test(current)) throw new Error("TokenPreview is already owned by this project. Add a token review scenario using its public API before initializing the foundation.");
-    const ast = ts.createSourceFile(entryFile, current, ts.ScriptTarget.Latest, true);
-    for (const statement of [...ast.statements].reverse()) if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.exportClause.elements.length) {
-      current = current.slice(0, statement.getStart(ast)) + current.slice(statement.end);
+  addMissing(entryFile, `// Export your project's public components and types here.\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\n`);
+  if (!existingTokens.length) {
+    const reviewEntry = path.join(dsRoot, config.reviewEntry);
+    const reviewExport = `export { TokenPreview } from ${JSON.stringify(relativeImport(reviewEntry, path.join(dsRoot, "review/token-preview/TokenPreview")))};\n`;
+    addMissing(reviewEntry, reviewExport);
+    if (existsSync(reviewEntry) && !readFileSync(reviewEntry, "utf8").includes("token-preview/TokenPreview")) throw new Error("The project owns an existing review entry. Add the new token renderer through that development API before initializing the foundation.");
+    if (existsSync(entryFile)) {
+      let current = readFileSync(entryFile, "utf8");
+      const ast = ts.createSourceFile(entryFile, current, ts.ScriptTarget.Latest, true);
+      for (const statement of [...ast.statements].reverse()) if (ts.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts.isNamedExports(statement.exportClause) && !statement.exportClause.elements.length) current = current.slice(0, statement.getStart(ast)) + current.slice(statement.end);
+      if (!ast.statements.some(statement => ts.isImportDeclaration(statement) || statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword))) current += `\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\n`;
+      if (current !== readFileSync(entryFile, "utf8")) updates.set(entryFile, current);
     }
-    updates.set(entryFile, current + "\n" + reviewExport);
   }
   for (const section of ["components", "patterns", "controllers", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
   addMissing(path.join(dsRoot, "assets/brand/README.md"), readFileSync(path.join(starter, "design-system/assets/brand/README.md")));

package/dist/layers.mjs

@@ -0,0 +1,288 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import ts from "typescript";
+import selectorParser from "postcss-selector-parser";
+import valueParser from "postcss-value-parser";
+import { isDevelopmentFile, isInside, isStateVariable, isTestFile, isReviewFile } from "./config.mjs";
+import { importResolver, styleAccessProperty } from "./boundaries.mjs";
+
+const guidance = "See ads://guides/layers. A component provides one cohesive UI capability; a pattern arranges capabilities into a reusable structure or workflow. Component count does not decide the layer.";
+
+/** Include statically addressed local helpers outside the configured source roots.
+ * Dependency packages remain external; no project module is imported/executed. */
+export function layerSourceFiles(initial, options) {
+  const files = new Set(initial), resolve = importResolver(options);
+  for (const file of files) {
+    const source = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+    function include(literal) {
+      if (!literal || !ts.isStringLiteralLike(literal)) return;
+      for (const dependency of resolve(literal.text, file)) {
+        if (isInside(options.root, dependency) && !dependency.split(path.sep).includes("node_modules") && /\.[cm]?[jt]sx?$/.test(dependency) && existsSync(dependency)) files.add(dependency);
+      }
+    }
+    function visit(node) {
+      if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) include(node.moduleSpecifier);
+      if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) include(node.moduleReference.expression);
+      if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) include(node.argument.literal);
+      if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require")) include(node.arguments[0]);
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+  return [...files];
+}
+
+/** Source-only dependency and private-style evidence; never evaluates project code. */
+export function createLayerBoundaries(program, options, report) {
+  const { root, dsRoot, sourceRoot, config } = options;
+  const checker = program.getTypeChecker(), resolve = importResolver(options);
+  const sources = program.getSourceFiles().filter(source => isInside(root, source.fileName) && !source.isDeclarationFile && !source.fileName.split(path.sep).includes("node_modules"));
+  const runtime = file => !isTestFile(file) && !isDevelopmentFile(file, options);
+  const layer = file => ["components", "patterns", "controllers", "composition", "review"].find(name => isInside(path.join(dsRoot, name), file)) ?? (isInside(sourceRoot, file) && !isInside(dsRoot, file) ? "application" : "shared");
+  const unalias = symbol => symbol?.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+  const entry = program.getSourceFile(path.join(dsRoot, config.publicEntry));
+  const module = entry && checker.getSymbolAtLocation(entry);
+  const publicSymbols = new Set((module ? checker.getExportsOfModule(module) : []).map(unalias));
+  const publicFiles = new Set([...publicSymbols].filter(symbol => symbol?.flags & ts.SymbolFlags.Value).flatMap(symbol => symbol.declarations?.map(node => node.getSourceFile().fileName) ?? []));
+  const edges = new Map(), emitted = new Set(), classOwners = new Map(), attributeOwners = new Map(), componentVariables = new Set(), patternVariables = new Set(), publicHooks = new Set();
+
+  function emit(node, rule, message) {
+    const source = node.getSourceFile(), position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    const key = `${source.fileName}:${node.pos}:${rule}:${message}`;
+    if (emitted.has(key)) return;
+    emitted.add(key);
+    report(source.fileName, rule, `${message} ${guidance}`, position.line + 1, position.character + 1, { guidanceUri: "ads://guides/layers" });
+  }
+  function target(specifier, source) {
+    return resolve(specifier, source.fileName).find(file => program.getSourceFile(file));
+  }
+  function exportsOf(file) {
+    const source = file && program.getSourceFile(file), symbol = source && checker.getSymbolAtLocation(source);
+    return symbol ? checker.getExportsOfModule(symbol) : [];
+  }
+  function origins(symbol) {
+    symbol = unalias(symbol);
+    return [...new Set(symbol?.declarations?.map(node => node.getSourceFile().fileName) ?? [])].filter(file => isInside(root, file) && !file.split(path.sep).includes("node_modules")).map(file => ({ file, symbol }));
+  }
+  function bindings(pattern) {
+    return ts.isObjectBindingPattern(pattern) ? pattern.elements.filter(node => !node.dotDotDotToken).map(node => (node.propertyName ?? node.name).text).filter(Boolean) : null;
+  }
+  function members(identifier, source) {
+    const symbol = checker.getSymbolAtLocation(identifier), names = new Set();
+    let opaque = false;
+    function visit(node) {
+      if (ts.isIdentifier(node) && node !== identifier && checker.getSymbolAtLocation(node) === symbol) {
+        const parent = node.parent;
+        if (ts.isPropertyAccessExpression(parent) && parent.expression === node) names.add(parent.name.text);
+        else if (ts.isElementAccessExpression(parent) && parent.expression === node && ts.isStringLiteralLike(parent.argumentExpression)) names.add(parent.argumentExpression.text);
+        else if (ts.isVariableDeclaration(parent) && parent.initializer === node && bindings(parent.name)) for (const name of bindings(parent.name)) names.add(name);
+        else opaque = true;
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return opaque ? null : [...names];
+  }
+  function selectedImport(call, source) {
+    let expression = call;
+    while (ts.isAwaitExpression(expression.parent) || ts.isParenthesizedExpression(expression.parent)) expression = expression.parent;
+    const parent = expression.parent;
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === expression && parent.name.text !== "then") return [parent.name.text];
+    if (ts.isElementAccessExpression(parent) && parent.expression === expression && ts.isStringLiteralLike(parent.argumentExpression)) return [parent.argumentExpression.text];
+    if (ts.isVariableDeclaration(parent)) return bindings(parent.name) ?? (ts.isIdentifier(parent.name) ? members(parent.name, source) : null);
+    if (ts.isPropertyAccessExpression(parent) && parent.name.text === "then" && ts.isCallExpression(parent.parent)) {
+      const callback = parent.parent.arguments[0];
+      if (callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)) && callback.parameters[0]) {
+        const parameter = callback.parameters[0].name;
+        return bindings(parameter) ?? (ts.isIdentifier(parameter) ? members(parameter, source) : null);
+      }
+    }
+    return null;
+  }
+  function add(source, node, dependency, typeOnly = false) {
+    if (!dependency?.file || !isInside(root, dependency.file) || dependency.file.split(path.sep).includes("node_modules")) return;
+    const list = edges.get(source.fileName) ?? [];
+    list.push({ ...dependency, node, typeOnly });
+    edges.set(source.fileName, list);
+  }
+  function addSymbol(source, node, symbol, typeOnly = false) {
+    for (const origin of origins(symbol)) add(source, node, origin, typeOnly);
+  }
+  function addModule(source, node, file, names, typeOnly = false) {
+    if (!file) return;
+    const values = exportsOf(file).filter(symbol => names === null || names.includes(symbol.name));
+    for (const symbol of values) if (typeOnly || unalias(symbol)?.flags & ts.SymbolFlags.Value) addSymbol(source, node, symbol, typeOnly);
+    if (!values.length || layer(file) === "composition" || isDevelopmentFile(file, options)) add(source, node, { file }, typeOnly);
+    // Explicit side effects in a forwarding barrel still run for a selected export.
+    if (!typeOnly) for (const statement of program.getSourceFile(file)?.statements ?? []) {
+      if (ts.isImportDeclaration(statement) && !statement.importClause && ts.isStringLiteralLike(statement.moduleSpecifier)) {
+        const sideEffect = target(statement.moduleSpecifier.text, statement.getSourceFile());
+        if (sideEffect) add(source, node, { file: sideEffect });
+      }
+    }
+  }
+  for (const source of sources) {
+    function visit(node) {
+      if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier)) {
+        const file = target(node.moduleSpecifier.text, source), clause = node.importClause;
+        if (!clause) add(source, node, { file: file ?? resolve(node.moduleSpecifier.text, source.fileName)[0] });
+        else {
+          if (clause.name) addSymbol(source, node, checker.getSymbolAtLocation(clause.name), !!clause.isTypeOnly);
+          const named = clause.namedBindings;
+          if (named && ts.isNamedImports(named)) for (const item of named.elements) addSymbol(source, item, checker.getSymbolAtLocation(item.name), !!(clause.isTypeOnly || item.isTypeOnly));
+          if (named && ts.isNamespaceImport(named)) addModule(source, node, file, members(named.name, source), !!clause.isTypeOnly);
+        }
+      }
+      if (ts.isExportDeclaration(node)) {
+        if (node.exportClause && ts.isNamedExports(node.exportClause)) for (const item of node.exportClause.elements) addSymbol(source, item, checker.getSymbolAtLocation(item.name), !!(node.isTypeOnly || item.isTypeOnly));
+        else if (node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) addModule(source, node, target(node.moduleSpecifier.text, source), null, !!node.isTypeOnly);
+      }
+      if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && node.moduleReference.expression && ts.isStringLiteralLike(node.moduleReference.expression)) {
+        addModule(source, node, target(node.moduleReference.expression.text, source), members(node.name, source), !!node.isTypeOnly);
+      }
+      if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal)) addModule(source, node, target(node.argument.literal.text, source), null, true);
+      const requireSymbol = ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require" ? checker.getSymbolAtLocation(node.expression) : null;
+      if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require" && (!requireSymbol || requireSymbol.declarations?.every(declaration => declaration.getSourceFile().isDeclarationFile))) && ts.isStringLiteralLike(node.arguments[0])) {
+        addModule(source, node, target(node.arguments[0].text, source), selectedImport(node, source));
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+
+  function runtimeHelpers() {
+    const found = new Set(sources.filter(source => isReviewFile(source.fileName, options) || runtime(source.fileName) && ["components", "patterns", "controllers"].includes(layer(source.fileName))).map(source => source.fileName));
+    for (const file of found) for (const edge of edges.get(file) ?? []) if (!edge.typeOnly && runtime(edge.file) && program.getSourceFile(edge.file)) found.add(edge.file);
+    return [...found];
+  }
+
+  function inspectDependencies() {
+    for (const source of sources.filter(source => runtime(source.fileName) || isReviewFile(source.fileName, options))) {
+      const ownLayer = layer(source.fileName);
+      // Check resolved declaration ownership too: a barrel cannot launder fixtures/app code.
+      if (isInside(dsRoot, source.fileName) || ownLayer === "application") for (const edge of edges.get(source.fileName) ?? []) {
+        if (runtime(source.fileName) && layer(edge.file) === "review") emit(edge.node, "review-import", "Production code and its public entry cannot depend on review implementations or their types, including through aliases and re-exports. Use the development review entry only from scenarios, fixtures and tests.");
+        if (edge.typeOnly) continue;
+        if (runtime(source.fileName) && !runtime(edge.file)) emit(edge.node, "showcase-import", "Runtime code cannot depend on review helpers, scenarios, fixtures or checks, including through re-exports. Keep demonstrations beside their owner and integration harnesses in tests.");
+        if (isInside(dsRoot, source.fileName) && layer(edge.file) === "application") emit(edge.node, "no-app-import", "ADS runtime cannot import application stores, routing or services, including through forwarding modules. Receive data and navigation callbacks through public APIs.");
+      }
+      if (!["components", "patterns", "review"].includes(ownLayer)) continue;
+      for (const initial of edges.get(source.fileName) ?? []) {
+        if (initial.typeOnly && ownLayer === "components") continue;
+        const queue = [{ edge: initial, trail: [source.fileName] }], seen = new Set();
+        while (queue.length) {
+          const { edge, trail } = queue.shift();
+          const key = `${edge.file}:${edge.symbol?.name ?? ""}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          const dependencyLayer = layer(edge.file), chain = [...trail, edge.file];
+          const via = chain.map(file => path.relative(root, file).replaceAll("\\", "/")).join(" → ");
+          if (ownLayer === "components" && ["patterns", "composition"].includes(dependencyLayer)) {
+            emit(initial.node, "component-dependency", `Component runtime depends on ${dependencyLayer}: ${via}. Move the arrangement to a pattern or extract a lower-level component/controller; do not change a valid API just to satisfy classification.`);
+            break;
+          }
+          if (["patterns", "review"].includes(ownLayer) && dependencyLayer === "components") {
+            if (edge.symbol ? !publicSymbols.has(edge.symbol) : !publicFiles.has(edge.file)) emit(initial.node, "component-contract", `Pattern accesses private component ${edge.symbol?.name ?? "module"}: ${via}. Export an intentional public contract or keep the helper/state/style inside its component; importing a module directly is allowed when the selected symbol is public.`);
+            continue; // Public component implementations may use their own private files.
+          }
+          if (ownLayer === "review" && ["patterns", "controllers"].includes(dependencyLayer)) {
+            if (edge.symbol ? !publicSymbols.has(edge.symbol) : !publicFiles.has(edge.file)) emit(initial.node, "review-contract", `Review accesses private ${dependencyLayer} ${edge.symbol?.name ?? "module"}: ${via}. Demonstrate the production API instead of depending on private implementation details.`);
+            continue;
+          }
+          if (dependencyLayer === "application" || !runtime(edge.file)) continue;
+          if (["patterns", "review"].includes(ownLayer) && dependencyLayer !== "shared") continue;
+          for (const next of edges.get(edge.file) ?? []) if (!next.typeOnly) queue.push({ edge: next, trail: chain });
+        }
+      }
+    }
+  }
+
+  function strings(node, seen = new Set()) {
+    if (!node || seen.has(node)) return [];
+    seen.add(node);
+    if (ts.isStringLiteralLike(node)) return [node.text];
+    if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {
+      const symbol = unalias(checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node));
+      return (symbol?.declarations ?? []).flatMap(declaration => ts.isVariableDeclaration(declaration) || ts.isPropertyAssignment(declaration) ? strings(declaration.initializer, seen) : []);
+    }
+    if (ts.isTaggedTemplateExpression(node)) return [];
+    const found = [];
+    ts.forEachChild(node, child => { found.push(...strings(child, seen)); });
+    return found;
+  }
+  function own(map, key, file) {
+    if (!map.has(key)) map.set(key, new Set());
+    map.get(key).add(file);
+  }
+  for (const symbol of publicSymbols) for (const node of symbol?.declarations ?? []) if (ts.isVariableDeclaration(node)) for (const value of strings(node.initializer)) publicHooks.add(value);
+  for (const source of sources.filter(source => runtime(source.fileName))) {
+    function visit(node) {
+      let name, value;
+      if (["components", "patterns"].includes(layer(source.fileName))) {
+        const write = styleAccessProperty(node);
+        if (typeof write === "string" && write.startsWith("--")) (layer(source.fileName) === "components" ? componentVariables : patternVariables).add(write);
+      }
+      if (ts.isJsxAttribute(node)) { name = node.name.getText(); value = node.initializer; }
+      if (ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name))) { name = node.name.text; value = node.initializer; }
+      if (name === "className" || name === "class") for (const text of strings(value)) for (const token of text.split(/\s+/).filter(Boolean)) own(classOwners, token, source.fileName);
+      if (name?.startsWith("data-")) for (const text of strings(value)) own(attributeOwners, `${name}=${text}`, source.fileName);
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  }
+  function privateHook(map, key, kinds = ["components"]) {
+    const owners = map.get(key);
+    return !publicHooks.has(key) && owners?.size && (map !== attributeOwners || owners.size === 1) && [...owners].every(file => kinds.includes(layer(file)));
+  }
+  // Called first for all component styles, then for patterns by checkProject.
+  function collectComponentStyles(file, css) {
+    if (runtime(file) && ["components", "patterns"].includes(layer(file))) css.walkDecls(declaration => {
+      if (declaration.prop.startsWith("--")) (layer(file) === "components" ? componentVariables : patternVariables).add(declaration.prop);
+    });
+  }
+  function inspectStyles(file, css, offset = { line: 1 }) {
+    if (!runtime(file) && !isReviewFile(file, options)) return;
+    const ownLayer = layer(file);
+    css.walkAtRules("import", rule => {
+      const first = valueParser(rule.params).nodes.find(node => node.type !== "space" && node.type !== "comment");
+      const specifier = first?.type === "string" ? first.value : first?.type === "function" && first.value === "url" ? first.nodes[0]?.value : null;
+      if (!specifier || /^(?:[a-z]+:|\/\/)/i.test(specifier)) return;
+      for (const dependency of resolve(specifier, file)) {
+        const dependencyLayer = layer(dependency);
+        const boundary = ownLayer === "components" && ["patterns", "composition"].includes(dependencyLayer) ? "component-dependency"
+          : ["patterns", "review"].includes(ownLayer) && dependencyLayer === "components" ? "component-contract" : null;
+        if (boundary) report(file, boundary, `Stylesheet import crosses the ${ownLayer} → ${dependencyLayer} boundary: ${specifier}. Consume public component contracts instead of importing private styles. ${guidance}`, offset.line + (rule.source?.start.line ?? 1) - 1, rule.source?.start.column ?? 1, { guidanceUri: "ads://guides/layers" });
+      }
+    });
+    if (!["patterns", "review"].includes(ownLayer)) return;
+    const failures = new Set();
+    const styleReport = (node, message) => {
+      const line = offset.line + (node.source?.start.line ?? 1) - 1;
+      const key = `${line}:${message}`;
+      if (failures.has(key)) return;
+      failures.add(key);
+      report(file, "component-style", `${message} Use component props, public class helpers or registered non-state customization variables; patterns own arrangement and spacing. ${guidance}`, line, node.source?.start.column ?? 1, { guidanceUri: "ads://guides/layers" });
+    };
+    css.walkRules(rule => {
+      try {
+        selectorParser(selectors => {
+          function subject(selector) {
+            const nodes = selector.nodes ?? [], lastCombinator = nodes.findLastIndex(node => node.type === "combinator");
+            for (const node of nodes.slice(lastCombinator + 1)) {
+              if (node.type === "class" && privateHook(classOwners, node.value, ownLayer === "review" ? ["components", "patterns"] : undefined)) styleReport(rule, `${ownLayer === "review" ? "Review selector targets private product" : "Pattern selector targets private component"} class .${node.value}.`);
+              if (node.type === "attribute" && node.operator === "=" && privateHook(attributeOwners, `${node.attribute}=${node.value}`, ownLayer === "review" ? ["components", "patterns"] : undefined) && !publicHooks.has(node.value)) styleReport(rule, `${ownLayer === "review" ? "Review selector targets private product" : "Pattern selector targets private component"} marker [${node.attribute}="${node.value}"].`);
+              if (node.type === "pseudo" && [":is", ":where"].includes(node.value)) for (const branch of node.nodes ?? []) subject(branch);
+            }
+          }
+          for (const selector of selectors.nodes) subject(selector);
+        }).processSync(rule.selector);
+      } catch { /* CSS syntax diagnostics are owned by the existing parser/build. */ }
+    });
+    css.walkDecls(declaration => valueParser(declaration.value).walk(node => {
+      if (node.type !== "function" || node.value !== "var") return;
+      const name = node.nodes.find(child => child.type === "word")?.value;
+      if ((componentVariables.has(name) || ownLayer === "review" && patternVariables.has(name) && !publicHooks.has(name)) && (isStateVariable(name) || !config.boundaries.componentVariables.includes(name))) styleReport(declaration, `${ownLayer === "review" ? "Review reads private product" : "Pattern reads private component"} variable ${name}.`);
+    }));
+  }
+  return { inspectDependencies, runtimeHelpers, collectComponentStyles, inspectStyles };
+}

package/dist/lint-config.mjs

@@ -13,7 +13,7 @@ export function createLintConfig({ root, config }) {
     if (!existsSync(specifier)) throw new Error(`Project plugin not found: ${plugin.path}`);
     return { name: plugin.name, specifier };
   });
-  const options = { projectRoot: root, sourceDir: config.sourceDir, dsDir: config.dsDir, publicAlias: config.publicAlias, stylesEntry: config.stylesEntry, inlineStyleFiles: config.inlineStyleFiles,
+  const options = { projectRoot: root, sourceDir: config.sourceDir, dsDir: config.dsDir, publicAlias: config.publicAlias, publicEntry: config.publicEntry, reviewEntry: config.reviewEntry, stylesEntry: config.stylesEntry, inlineStyleFiles: config.inlineStyleFiles,
     configurationFiles: [...configurationFiles({ root, config, sourceRoot: path.resolve(root,config.sourceDir), dsRoot: path.resolve(root,config.dsDir) })].sort() };
   return {
     jsPlugins: [{ name: "ads", specifier: fileURLToPath(new URL("./oxlint.mjs", import.meta.url)) }, ...projectPlugins],

package/dist/mcp/catalog.mjs

@@ -5,6 +5,7 @@ import { isInside, sourceFiles } from "../config.mjs";
 import { projectCompilerOptions } from "../boundaries.mjs";
 import { publicApi } from "../public-api.mjs";
 import { projectDocumentFiles } from "../project-documents.mjs";
+import { inspectUnitContracts } from "../unit-contracts.mjs";
 
 export const PROJECT_URI = "ads://project";
 export const sourceUri = (file) => `${PROJECT_URI}/files/${file.split("/").map(encodeURIComponent).join("/")}`;
@@ -32,7 +33,7 @@ export function inspectCatalog(options, scenarios = []) {
   const { root, dsRoot, config } = options;
   const entry = path.join(dsRoot, config.publicEntry);
   if (!existsSync(entry)) return [];
-  const program = ts.createProgram([entry], { ...projectCompilerOptions(options), allowJs: true });
+  const program = inspectUnitContracts(options).program ?? ts.createProgram([entry], { ...projectCompilerOptions(options), allowJs: true });
   const checker = program.getTypeChecker();
   const source = program.getSourceFile(entry);
   const module = source && checker.getSymbolAtLocation(source);
@@ -40,6 +41,7 @@ export function inspectCatalog(options, scenarios = []) {
   const documents = projectDocuments(options);
   const items = [];
   const api = new Map(publicApi(program, options).map(item => [item.name, item]));
+  const contracts = inspectUnitContracts(options).contracts;
   for (const exported of checker.getExportsOfModule(module)) {
     let symbol = exported;
     if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
@@ -54,7 +56,12 @@ export function inspectCatalog(options, scenarios = []) {
     const relative = path.relative(root, file).replaceAll("\\", "/");
     const line = declaration.getSourceFile().getLineAndCharacterOfPosition(declaration.getStart()).line + 1;
     const guides = documents.filter((doc) => doc.file.endsWith(".md") && path.dirname(doc.file) === path.dirname(file)).map((doc) => doc.uri);
-    items.push({ name: exported.name, kind, apiKind: ui ? "ui" : "behavior", importFrom: config.publicAlias, file: relative, line, sourceUri: sourceUri(relative), guides,
+    const contract=contracts.find(contract=>[...(contract.paintInputs??[]),...(contract.declarativeParts??[])].some(input=>input.apiName===exported.name)||Object.values(contract.bindings??{}).some(binding=>binding.apiName===exported.name));
+    const declarative=contract?.declarativeParts?.find(part=>part.apiName===exported.name);
+    const bindings=Object.entries(contract?.bindings??{}).filter(([,binding])=>binding.apiName===exported.name);
+    items.push({ name: exported.name, kind, apiKind: declarative ? "declarative" : ui ? "ui" : "behavior", importFrom: config.publicAlias, file: relative, line, sourceUri: sourceUri(relative), guides,
+      ...(contract?{contractUri:sourceUri(contract.file),paintInputCount:contract.paintInputs?.filter(input=>input.apiName===exported.name).length??0,paintInputs:contract.paintInputs?.filter(input=>input.apiName===exported.name).slice(0,8).map(input=>({property:input.property,kind:input.kind,bindings:input.bindings??[]})),...(declarative?{consumer:{parent:declarative.parentName,sourceUri:sourceUri(declarative.consumer.source),symbol:declarative.consumer.symbol,checks:declarative.checks.slice(0,8),checkCount:declarative.checks.length},evidence:"registered relationship; source and browser verification are separate"}:{})}:{}),
+      ...(bindings.length?{bindingCount:bindings.length,bindings:bindings.slice(0,4).map(([id,binding])=>({id,variable:binding.variable,scope:binding.scope.selector,producer:{sourceUri:sourceUri(binding.producer.source),symbol:binding.producer.symbol},checks:binding.checks.slice(0,8),checkCount:binding.checks.length})),bindingEvidence:"registered; verify source diagnostics and current browser checks"}:{}),
       previews: scenarios.filter(item => item.covers.includes(exported.name) || item.exercises?.includes(exported.name)).map(item => item.id) });
   }
   return items.sort((a, b) => a.name.localeCompare(b.name));

package/dist/mcp/context.mjs

@@ -24,6 +24,7 @@ export function projectContext(options) {
   const guides = [...projectGuideFiles(root), path.join(config.dsDir, "README.md"), path.join(config.dsDir, "readme.md"), path.join(config.dsDir, "SKILL.md")].filter((file) => existsSync(path.join(root, file))).map((file) => ({ file: file.replaceAll("\\", "/"), uri: sourceUri(file.replaceAll("\\", "/")) }));
   return { name: pkg.name ?? path.basename(root), projectRoot: root, dsRoot, sourceRoot, framework: config.framework,
     publicEntry: path.join(dsRoot, config.publicEntry), publicEntryUri: existsSync(path.join(dsRoot, config.publicEntry)) ? sourceUri(path.relative(root, path.join(dsRoot, config.publicEntry)).replaceAll("\\", "/")) : null,
+    review: { importFrom: `${config.publicAlias}/review`, entry: path.join(dsRoot, config.reviewEntry), sourceUri: existsSync(path.join(dsRoot, config.reviewEntry)) ? sourceUri(path.relative(root, path.join(dsRoot, config.reviewEntry)).replaceAll("\\", "/")) : null, developmentOnly: true },
     stylesEntry: path.join(dsRoot, config.stylesEntry), packageManager, commands, guides,
     showcase: { client: "tool-owned-mcp", url: config.mcp.showcaseUrl, title: config.mcp.showcaseTitle ?? `${pkg.name ?? path.basename(root)} · Design System` },
     runtime: { node: process.execPath, nodeBinDir: path.dirname(process.execPath), nodeVersion: process.version,
@@ -56,7 +57,7 @@ Use this server for UI components/patterns, tokens/themes/branding, layout, inte
 3. Select one workflow with ads_skills, then ads_read_skill. ${route.skills.map((skill) => `${skill.task}: ${skill.name}`).join("; ")}. Native skill activation is host-controlled. Relative skill references resolve from its SKILL.md URI. Read support files only when relevant.
 4. ${route.preview} Token samples: ads_scenarios(kind: tokens), then ads_show_scenario or ads_show_tokens(category: id). Token source inspection: ads_tokens with a focused query. Registered previews: ${previews.map((preview) => `${preview.id}: ${preview.tool ?? "ads_show_scenario"}`).join(", ") || "none"}. Showcase URL: ${context.showcase.url ?? "not configured; use the project's showcase command"}.
    Inspection connects a public export to its owning source, available guides, token values and discovered preview IDs. Bounded tools keep discovery focused; explicit resource reads supply detail. Source metadata does not prove layout, interaction or motion. A scenario renders the real public implementation and its fixture context in either review surface.
-5. Check ads_status.mutations. When enabled, discover one owner with ads_units, read relevant source ranges with ads_read_file and submit only a Git unified diff through ads_apply_patch({unit, patch, dryRun}). Include that owner's scenarios, fixtures and required public re-exports, never peer units. tokens is the foundation unit; its manifest lists companionFiles for required canonical foundation imports when token files are created/deleted in the same patch. Preserve unrelated imports/comments and public-entry statements; a real selected-owner re-export can remove its redundant export {};. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit; use ads_apply_transaction for coupled owners instead of bypassing rejection with direct writes. ads_prepare_patch creates a local owner draft/diff; ads_prepare_token_samples reconciles explicit project bindings without guessing visual meaning. Intentional project setup, registered guard/compiler code and exceptions use configuration; shared globals use foundation, guides documentation and assets their discovered assets/* unit. Keep mandatory ADS gates. Binary/large Git diffs may use patchFile under .ds/patches/ to avoid model-context bytes. In read-only mode, source edits use the client editor/filesystem tools. Reuse the local public API (${context.publicEntry}). Edit presentation in its ADS owner; keep application data/services/routing in application code and development fixtures beside their scenario; larger scenarios live in composition/. Linaria extracts owned styling. Inspect relevant tokens with ads_tokens and source/owning guides before edits.
+5. Check ads_status.mutations. When enabled, discover one owner with ads_units, read relevant source ranges with ads_read_file and submit only a Git unified diff through ads_apply_patch({unit, patch, dryRun}). Include that owner's scenarios, fixtures and required public re-exports, never peer units. tokens is the foundation unit; its manifest lists companionFiles for required canonical foundation imports when token files are created/deleted in the same patch. Preserve unrelated imports/comments and public-entry statements; a real selected-owner re-export can remove its redundant export {};. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit; use ads_apply_transaction for coupled owners instead of bypassing rejection with direct writes. ads_prepare_patch creates a local owner draft/diff; ads_prepare_token_samples reconciles explicit project bindings without guessing visual meaning. Intentional project setup, registered guard/compiler code and exceptions use configuration; shared globals use foundation, guides documentation and assets their discovered assets/* unit. Keep mandatory ADS gates. Binary/large Git diffs may use patchFile under .ds/patches/ to avoid model-context bytes. In read-only mode, source edits use the client editor/filesystem tools. Reuse the local public API (${context.publicEntry}). Edit presentation in its ADS owner; keep application data/services/routing in application code and development fixtures beside their scenario; larger scenarios live in composition/. Demo framing and token renderers live in development-only review/, imported through ${context.review.importFrom}; never export them from the production barrel or import them into application runtime. Read ads://guides/review for review owners/aliases and ads://guides/contracts when editing static owner declarations, .ads. development roles, constrained paints/bindings or declarative APIs. Contract registration, source evidence and browser verification remain separate. Use ads_prepare_patch action: migrate for a reviewable owner draft, then normal diff and guarded application. Linaria extracts owned styling. Inspect relevant tokens with ads_tokens and source/owning guides before edits.
 6. ${route.validation} Registered commands: ${context.commands.map((command) => command.args?.join(" ") ?? `choose the project package manager for ${command.script}`).join("; ") || "none discovered; inspect the project's build setup"}. Run them from ${context.projectRoot}.
 Execution replies from ads_verify and guarded edits contain counts, acceptance and resultId, not full reports. Read only needed outcomes/diagnostics/captures with ads_results, following nextCursor with identical filters. A truncated row has recordIndex for bounded text ranges. For one failure, use ads_investigate with its unit/check/runId; read request/error/artifact sections only when needed. Only the latest verification and mutation results, and latest investigation per check, are available. Notifications do not establish freshness.