@reqvire-org/ads 0.3.20 → 0.3.21

package/README.md

@@ -31,6 +31,8 @@ uses Preact. See [implementation support](docs/GUIDE.md#implementation-support).
   proposed candidates, exposed as MCP image resources.
 - **Verify behavior** through project-owned guarantees and registered tests,
   with progress, timings and evidence tied to current source.
+- **Keep contracts explicit** for typed paint inputs, scoped data bindings and
+  declarative APIs, without adding ADS to production components.
 - **Guide agents** with prompts and portable skills for building, importing,
   migrating, motion and UI stress testing.
 

package/dist/behaviors.mjs

@@ -9,6 +9,7 @@ import { inspectUnits } from "./units.mjs";
 import { scenarioApi } from "./public-api.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
 import { uiOperation } from "./ui-framework.mjs";
+import { inspectUnitContracts } from "./unit-contracts.mjs";
 
 const id = z.string().regex(/^[a-zA-Z0-9][\w.-]{0,99}$/);
 const reference = z.string().min(1).max(500);
@@ -27,20 +28,22 @@ export const behaviorSchema = z.object({
 export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
   const { root, dsRoot, config } = options;
   const inventory = inspectUnits(options);
-  const files = sourceFiles(dsRoot).filter(isBehaviorFile);
+  const declarations = inspectUnitContracts(options);
+  const typed = declarations.contracts.filter(entry => entry.behavior);
+  const files = [...sourceFiles(dsRoot).filter(isBehaviorFile), ...typed.map(entry => path.resolve(root, entry.file))];
   if (!files.length) return { contracts: [], diagnostics: [] };
-  const program = suppliedProgram ?? ts.createProgram(sourceFiles(dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
+  const program = suppliedProgram ?? declarations.program ?? ts.createProgram(sourceFiles(dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
   const checker = program.getTypeChecker();
   const apis = new Map(scenarioApi(program, options).map(item => [item.name, item]));
   const scenarios = (suppliedRegistry ?? inspectScenarios(options, program)).scenarios;
-  const diagnostics = [], contracts = [], owners = new Set();
+  const diagnostics = [...declarations.diagnostics], contracts = [], owners = new Set();
   const relative = file => path.relative(root, file).replaceAll("\\", "/");
   for (const file of files) {
     const report = message => diagnostics.push({ file: relative(file), rule: "behavior-contract", line: 1, column: 1, message });
     let value;
     try {
       if (statSync(file).size > 128 * 1024 || realpathSync(file) !== file) throw new Error("Behavior contracts must be regular files of at most 128 KiB.");
-      const parsed = behaviorSchema.safeParse(JSON.parse(readFileSync(file, "utf8")));
+      const parsed = behaviorSchema.safeParse(typed.find(entry => path.resolve(root, entry.file) === file)?.behavior ?? JSON.parse(readFileSync(file, "utf8")));
       if (!parsed.success) throw new Error(parsed.error.issues.slice(0, 5).map(issue => `${issue.path.join(".")}: ${issue.message}`).join("; "));
       value = parsed.data;
     } catch (error) { report(error.message); continue; }
@@ -85,6 +88,13 @@ export function inspectBehaviors(options, suppliedProgram, suppliedRegistry) {
       if (cases.has(identity)) report(`Duplicate execution identity for check ${name}. Use one check ID and reference it from several guarantees.`);
       cases.add(identity);
     }
+    const declaration=typed.find(entry=>entry.unit===unit);
+    for(const entry of [...Object.values(declaration?.bindings??{}),...(declaration?.declarativeParts??[])])for(const name of entry.checks) {
+      const check=value.checks[name],scenario=check&&scenarios.find(scenario=>scenario.id===check.scenario);
+      const parent=entry.parentName??entry.scope.apiName;
+      if(!check||config.mcp.behaviorProfiles[check.profile]?.mode!=="browser"||!scenario?.covers.includes(parent)||entry.parentName&&!scenario.exercises?.includes(entry.apiName))report(`Required contract check ${name} must use a browser profile and a scenario covering ${parent}${entry.parentName?` and exercising ${entry.apiName}`:""}. Source registration does not establish rendered behavior.`);
+      if(!value.guarantees.some(guarantee=>guarantee.checks.includes(name)))report(`Required contract check ${name} must back a named guarantee, not remain an unclaimed execution.`);
+    }
     contracts.push({ ...value, unit, file: relative(file), demonstrations: Object.fromEntries(Object.entries(value.subjects).filter(([, item]) => item.api).map(([name, item]) => [name, scenarios.filter(scenario => scenario.exercises?.includes(item.api)).map(scenario => scenario.id)])) });
   }
   return { contracts, diagnostics };

package/dist/bootstrap-ds/README.md

@@ -56,7 +56,7 @@ Its MCP client discovers entries, invokes preview tools and follows notification
 There are no required TokensPage/ComponentsPage/PatternsPage/CompositionPage
 files, and no separate project browser app to implement or rebuild.
 
-The existing `tokens/Foundation.scenario.tsx` and colocated fixture visually demonstrate all
+The existing `tokens/Foundation.ads.scenario.tsx` and colocated fixture visually demonstrate all
 starter token values. The fixture owns `{ token, property, probe }` bindings;
 the public `TokenPreview` pattern owns their presentation and applies the real CSS
 variables. Add/remove samples alongside token definitions. `ads check` rejects

package/dist/bootstrap-ds/design-system/tokens/{Foundation.scenario.tsx → Foundation.ads.scenario.tsx}

@@ -1,4 +1,4 @@
 import { TokenPreview } from "@ds/review";
-import { fixture } from "./Foundation.fixture";
+import { fixture } from "./Foundation.ads.fixture";
 export const scenario = { title: fixture.title, covers: ["TokenPreview"], samples: fixture.samples };
 export default function Scenario() { return <TokenPreview {...fixture} />; }

package/dist/bootstrap-ds/tsconfig.build.json

@@ -7,6 +7,13 @@
     "rootDir": "design-system",
     "outDir": "dist"
   },
-  "include": ["design-system/**/*.ts", "design-system/**/*.tsx"],
-  "exclude": ["design-system/showcase"]
+  "include": [
+    "design-system/index.ts"
+  ],
+  "exclude": [
+    "design-system/showcase",
+    "design-system/review",
+    "design-system/composition",
+    "**/*.ads.*"
+  ]
 }

package/dist/boundaries.mjs

@@ -4,6 +4,7 @@ import { importedUiName } from "./ui-framework.mjs";
 import { isInside, isStateVariable, isTestFile, isDevelopmentFile } from "./config.mjs";
 import { isSharedToken } from "./token-policy.mjs";
 import { scopedTokenOwner } from "./scoped-tokens.mjs";
+import { runtimeBindingOwner } from "./unit-contracts.mjs";
 
 export function projectCompilerOptions({ root, config, dsRoot }) {
   const file = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
@@ -64,6 +65,7 @@ export function checkComponentVariable(name, filename, options) {
   const showcase = development;
   const owned = scopedTokenOwner(options, name);
   if (owned) return path.resolve(options.root, owned.file) === filename ? null : { rule: "token-ownership", message: `Define ${name} only in ${owned.file}, owned by ${owned.unit}. Consume it with var(); runtime geometry remains a separate styleWrites boundary.` };
+  if (runtimeBindingOwner(options, name)) return { rule: "binding-ownership", message: `${name} belongs to a declared runtime producer. Do not redefine instance bindings in CSS or arbitrary style objects.` };
   if (isSharedToken(name)) return tokens ? null : { rule: "token-ownership", message: `Define ${name} in ADS tokens, not component, pattern, showcase, or app styles.` };
   if (name.startsWith("--ux-")) return patterns || showcase ? null : { rule: "variable-ownership", message: "--ux-* variables belong to ADS patterns and showcase composition." };
   if (name.startsWith("--showcase-")) return showcase ? null : { rule: "variable-ownership", message: "--showcase-* variables belong to the ADS showcase." };

package/dist/check.mjs

@@ -9,6 +9,10 @@ import { foundationFiles, foundationImportTarget, isSharedToken } from "./token-
 import { inspectAssets } from "./assets.mjs";
 import { appImportViolation, showcaseImportViolation, checkComponentVariable, importResolver, projectCompilerOptions, isUiCssProperties, styleWriteViolation } from "./boundaries.mjs";
 import { inspectPublicProps } from "./public-props.mjs";
+import { adsFileRole } from "./config.mjs";
+import { inspectPaintContracts, inspectTokenValueFlows } from "./paint-contracts.mjs";
+import { runtimeBindingOwner } from "./unit-contracts.mjs";
+import { inspectRuntimeContracts } from "./runtime-contracts.mjs";
 import { inspectHtml, isMountCss } from "./html.mjs";
 import { inspectShowcasePages } from "./showcase.mjs";
 import { inspectShowcaseCoverage } from "./showcase-coverage.mjs";
@@ -43,7 +47,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     if (!existsSync(file) || (field === "dsDir" ? !statSync(file).isDirectory() : !statSync(file).isFile())) diagnostics.push({ rule: "project-structure", file: path.relative(root, file), line: 1, column: 1, message: `Missing or invalid ${field}. Bootstrap an empty ADS or configure its actual path.` });
   }
   if (diagnostics.length) return architectureEvidence({ ok: false, diagnostics });
-  const tokenInventory = inspectTokens(root);
+  const tokenInventory = inspectTokens(root, options);
   const declaredTokens = new Set(tokenInventory.tokens.map((token) => token.name));
   diagnostics.push(...tokenInventory.diagnostics);
   diagnostics.push(...inspectAssets(options));
@@ -57,6 +61,11 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const compiler = projectCompilerOptions(options);
   const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
   const checker = program.getTypeChecker();
+  const paintContracts = inspectPaintContracts(options);
+  diagnostics.push(...paintContracts.diagnostics);
+  const runtimeContracts = inspectRuntimeContracts(options, program);
+  diagnostics.push(...runtimeContracts.diagnostics);
+  for (const binding of runtimeContracts.bindings) if (scoped.definitions.some(entry=>entry.namespace.startsWith(binding.prefix)||binding.prefix.startsWith(entry.namespace))) diagnostics.push({file:binding.file,rule:"binding-collision",line:1,column:1,message:`Runtime family ${binding.variable} overlaps an owner-local design-token namespace. Keep instance bindings separate from token definitions.`});
   const atomicCompositionReview = createAtomicCompositionReview(program, options);
   const scenarioTrace = createScenarioTrace(program, options);
   let scenarioSlot, scenarioSelector;
@@ -65,6 +74,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
   }
   const layers = createLayerBoundaries(program, options, report), layerStyles = [];
   layers.inspectDependencies();
+  inspectTokenValueFlows(program, options, tokenInventory, scoped, report);
   for (const file of layers.runtimeHelpers()) if (!files.includes(file)) files.push(file);
   inspectStyleBoundaries(options, program, report);
   inspectShowcasePages(options, program, resolveImport, report);
@@ -154,6 +164,11 @@ export function checkProject(directory, { trackingRoot } = {}) {
       const variable = checkComponentVariable(decl.prop, file, options);
       if (variable) report(file, variable.rule, variable.message, offset.line + decl.source.start.line - 1, decl.source.start.column);
       for (const ref of references(decl.value)) {
+        const binding = runtimeBindingOwner(options, ref.name);
+        if (binding) {
+          if (scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== binding.unit) report(file, "binding-ownership", `${ref.name} is an instance binding owned by ${binding.unit}, not a shared design token.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
+          continue;
+        }
         const owned = scopedTokenOwner(options, ref.name);
         if (owned) {
           if (scoped.inventory.owner(scoped.inventory.relative(path.relative(root, file))) !== owned.unit || !declaredTokens.has(ref.name)) report(file, "token-reference", `${ref.name} belongs to ${owned.unit}. Use shared tokens across owners; owner-local tokens must be defined and consumed by their owner.`, offset.line + decl.source.start.line - 1, decl.source.start.column);
@@ -179,6 +194,9 @@ export function checkProject(directory, { trackingRoot } = {}) {
     });
   }
   for (const file of files) {
+    const role = adsFileRole(file);
+    const roleExtension=role==="contract"?/\.[cm]?ts$/.test(file):["fixture","fixtures"].includes(role)?/\.(?:[cm]?[jt]sx?|json)$/.test(file):/\.[cm]?[jt]sx?$/.test(file);
+    if (role && (!["contract", "scenario", "fixture", "fixtures", "helpers", "test", "spec", "behavior.spec"].includes(role)||!roleExtension)) report(file, "development-role", `Unknown .ads. role or unsupported extension: ${role}. Use a TypeScript contract, a script scenario/fixture/helpers/test/behavior.spec, or JSON fixture; marking development code does not grant styling or mutation permissions.`);
     if (scopedFiles.has(file)) { try{checkRegistrations(file,postcss.parse(readFileSync(file,"utf8"),{from:file}));}catch{/* Token inspection reports malformed sheets. */} continue; } // Closed definition-only contract checked by inspectTokens.
     if (file.endsWith(".css") && isInside(path.join(dsRoot, config.tokenDir), file) && !isDevelopmentFile(file, options)) { checkCss(file, readFileSync(file, "utf8"), undefined, true); continue; }
     if (file.endsWith(".html")) { inspectHtml(readFileSync(file, "utf8"), (rule, message, line) => report(file, rule, message, line)); continue; }
@@ -212,7 +230,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
       const selector = native ? (scenarioSelector ??= createScenarioSelectors(program, options))(node) : { ok: false, reasons: ["A selector cannot establish custom widget behavior or keyboard semantics."] };
       if (!selector.ok) nodeReport(node, "showcase-control", `Scenario controls must compose public ADS runtime UI. Native semantics require source evidence of owned cloning props or an attached runtime Linaria selector addressing that native tag or a verified runtime-owned part in that position. A prop name, broad selector or scenario-authored marker grants no permission. ${selector.reasons.join(" ")} Preserve valid APIs when tracing is inconclusive; report the limitation instead of changing the API to satisfy coverage. ${scenarioLayoutGuidance} See ads://guides/scenarios.`, { failure: failure("architecture", "source-ownership", "ownership-not-proven", { certainty: "inconclusive" }) });
     }
-    if (!showcase && (isInside(path.join(dsRoot, "components"), file) || isInside(path.join(dsRoot, "patterns"), file))) inspectPublicProps(source, checker, nodeReport);
+    if (!showcase && (isInside(path.join(dsRoot, "components"), file) || isInside(path.join(dsRoot, "patterns"), file))) inspectPublicProps(source, checker, nodeReport, paintContracts.allowedProperties);
     function isLinariaTag(tag) {
       if (ts.isCallExpression(tag)) tag = tag.expression;
       let symbolNode = tag;
@@ -295,13 +313,14 @@ export function checkProject(directory, { trackingRoot } = {}) {
       if (specifier && resolveImport(specifier, file).some((target) => (specifier.startsWith(".") || existsSync(target)) && target.endsWith(".css") && isInside(root, target) && !isInside(dsRoot, target) && target !== path.join(sourceRoot, "app-mount.css") && !isInside(path.join(root, "node_modules"), target))) nodeReport(node, "style-ownership", "Imported project CSS belongs to ADS components, patterns, or the foundation. Only structural app-mount.css is allowed outside the ADS.");
       if (specifier && appImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "no-app-import", "ADS implementations and showcase fixtures must not import app code. Use public ADS APIs with local fixture data; keep application integration harnesses in application tests.");
       if (specifier && showcaseImportViolation(specifier, file, options, resolveImport)) nodeReport(node, "showcase-import", "Showcase code and styles are development fixtures; runtime code must not import them.");
-      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase)) nodeReport(node, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
+      const boundStyle = runtimeContracts.allowedStyles.has(`${file}:${node.pos}`);
+      if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && (!inlineAllowed || showcase) && !boundStyle) nodeReport(node, "no-inline-style", showcase ? `Scenarios define no inline styles. ${scenarioLayoutGuidance}` : inlineStyleGuidance);
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "style" && node.initializer) {
         inspectProperty(node.initializer);
       }
       const mutation = styleWriteViolation(node, file, options);
       if (mutation) nodeReport(node, "style-mutation", mutation);
-      if (!inlineAllowed && isUiCssProperties(node, checker)) nodeReport(node, "css-properties", "Keep CSSProperties out of the public API. Use deliberate component contracts or a documented measured-geometry renderer boundary; demo layout belongs in a development-only review/ helper.");
+      if (!inlineAllowed && isUiCssProperties(node, checker) && !runtimeContracts.allowedStyleTypes.has(`${file}:${node.pos}`)) nodeReport(node, "css-properties", "Keep CSSProperties out of the public API. Use deliberate component contracts or a documented measured-geometry renderer boundary; demo layout belongs in a development-only review/ helper.");
       if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && node.name.text === "className" && node.initializer) {
         inspectClass(node.initializer);
       }
@@ -318,5 +337,6 @@ export function checkProject(directory, { trackingRoot } = {}) {
   // Bounded clients should see actionable warnings before source-analysis limits.
   for (const { file, css, offset } of layerStyles) layers.inspectStyles(file, css, offset);
   advisories.sort((first, second) => Number(first.severity === "info") - Number(second.severity === "info"));
-  return architectureEvidence({ ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) });
+  const uniqueDiagnostics=[...new Map(diagnostics.map(diagnostic=>[JSON.stringify([diagnostic.file,diagnostic.rule,diagnostic.line,diagnostic.column,diagnostic.message]),diagnostic])).values()];
+  return architectureEvidence({ ok: uniqueDiagnostics.length === 0, diagnostics:uniqueDiagnostics, ...(advisories.length ? { advisories } : {}) });
 }

package/dist/config.mjs

@@ -163,10 +163,27 @@ export function isTokenManifestFile(file) {
   return /(?:^|[\\/])tokens\.json$|\.tokens\.json$/.test(file);
 }
 
+/** A visible development boundary, independent of whether its role is supported. */
+export function adsFileRole(file) {
+  const match = path.basename(file).match(/\.ads\.(.+)\.[^.]+$/);
+  return match ? match[1] : null;
+}
+
+export function isContractFile(file) {
+  return /\.ads\.contract\.[cm]?ts$/.test(file);
+}
+
+/** Filenames may change without changing the identity used by clients/checks. */
+export function scenarioIdentity(file, dsRoot) {
+  let id = path.relative(dsRoot, file).replaceAll("\\", "/").replace(/\.ads(?=\.)/, "").replace(/(?:\/Scenario|\.scenario)\.[^.]+$/, "");
+  if (adsFileRole(file) === "scenario" && path.posix.basename(id) === path.posix.basename(path.posix.dirname(id))) id = path.posix.dirname(id);
+  return id;
+}
+
 export function isDevelopmentFile(file, { dsRoot }) {
-  if (!isInside(dsRoot, file)) return isTestFile(file);
+  if (!isInside(dsRoot, file)) return isTestFile(file) || adsFileRole(file) !== null;
   const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
-  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file) || isTokenManifestFile(file)
+  return adsFileRole(file) !== null || isTestFile(file) || isScenarioFile(file) || isFixtureFile(file) || isBehaviorFile(file) || isTokenManifestFile(file)
     || /^(?:showcase|composition|review)\//.test(relative)
     || /(?:^|\/)(?:scenario|fixtures)(?:\/|$)/.test(relative)
     || /\.scenario(?:-adapter)?\.[cm]?[jt]sx?$/.test(relative);
@@ -174,7 +191,7 @@ export function isDevelopmentFile(file, { dsRoot }) {
 
 /** Review implementations may own demo presentation; scenarios/fixtures may not. */
 export function isReviewFile(file, { dsRoot }) {
-  return isInside(path.join(dsRoot, "review"), file) && !isTestFile(file) && !isScenarioFile(file) && !isFixtureFile(file) && !isBehaviorFile(file) && !isTokenManifestFile(file);
+  return isInside(path.join(dsRoot, "review"), file) && adsFileRole(file) === null && !isTestFile(file) && !isScenarioFile(file) && !isFixtureFile(file) && !isBehaviorFile(file) && !isTokenManifestFile(file);
 }
 
 const ignored = new Set(["node_modules", "dist", "dist-showcase", "dist-kit", ".git", ".vite", ".ds", "coverage"]);
@@ -194,7 +211,7 @@ export function sourceFiles(root) {
 export function importViolation(specifier, filename, options, resolve) {
   const { root, dsRoot, config } = options;
   // ADS implementation code needs its private imports; the showcase is a consumer.
-  if (isInside(dsRoot, filename) && !isDevelopmentFile(filename, options)) return false;
+  if (isInside(dsRoot, filename) && (!isDevelopmentFile(filename, options) || isContractFile(filename))) return false; // Contract symbol ownership is checked without executing imports.
   if (specifier === `${config.publicAlias}/review`) return !isDevelopmentFile(filename, options) && !isTestFile(filename);
   if (specifier.startsWith(`${config.publicAlias}/`)) return true;
   if (specifier === config.publicAlias) return false;

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,7 +152,7 @@ export function initProject(directory = process.cwd(), { toolPackage, packageMan
     return file;
   });
   if (!existingTokens.length) {
-    for (const name of ["Foundation.scenario.tsx", "Foundation.fixture.ts"]) {
+    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);
     }

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

@@ -57,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/. 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 guarded owners, aliases and migration. 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.
 

package/dist/mcp/edit-preparation.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 import { isInside } from "../config.mjs";
 import { checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
 import { textDiff } from "./text-diff.mjs";
+import { migrateContractDraft } from "../contract-migration.mjs";
 
 const hash = value => createHash("sha256").update(value).digest("hex");
 const binary = bytes => bytes?.includes(0) || bytes && !Buffer.from(bytes.toString("utf8")).equals(bytes);
@@ -26,8 +27,9 @@ export function storePreparedPatch(options, patch) {
 export function prepareUnitPatch(options, {unit, action = "create", draft}) {
   validateUnitId(unit);
   const inventory = inspectUnits(options);
-  if (action === "create") {
+  if (action === "create" || action === "migrate") {
     const owner = inventory.units.find(entry => entry.id === unit);
+    if(action==="migrate"&&!owner)throw new Error("Discover an existing owner before preparing its contract migration.");
     const files = [...new Set([...(owner?.files ?? []), ...(owner?.companionFiles ?? []).map(entry => entry.path),
       ...(!owner ? ["ds.config.json"] : []),
       ...(/^(?:components|patterns|controllers|review)\//.test(unit) ? [path.relative(options.root,path.join(options.dsRoot,unit.startsWith("review/")?options.config.reviewEntry:options.config.publicEntry)).replaceAll("\\","/")] : [])])];
@@ -58,7 +60,8 @@ export function prepareUnitPatch(options, {unit, action = "create", draft}) {
     }
     mkdirSync(folder,{recursive:true});
     writeFileSync(base,JSON.stringify({schemaVersion:1,unit,entries}));
-    return {draft,unit,directory:folder,files, next:"Edit only this draft, then call ads_prepare_patch with action: diff and this draft ID. Live source is unchanged; the resulting Git patch still requires ads_apply_patch and all its gates."};
+    const prepared={draft,unit,directory:folder,files, next:"Edit only this draft, then call ads_prepare_patch with action: diff and this draft ID. Live source is unchanged; the resulting Git patch still requires ads_apply_patch and all its gates."};
+    return action === "migrate" ? migrateContractDraft(options,prepared) : prepared;
   }
   if (!/^[a-f0-9-]{36}$/.test(draft ?? "")) throw new Error("Use the draft ID returned by ads_prepare_patch.");
   const base = path.join(options.root,".ds/patch-drafts",draft);
@@ -66,7 +69,7 @@ export function prepareUnitPatch(options, {unit, action = "create", draft}) {
   const metadata = JSON.parse(readFileSync(path.join(base,"manifest.json"),"utf8"));
   if (metadata.schemaVersion !== 1 || metadata.unit !== unit) throw new Error("Draft and selected unit do not match.");
   if (action === "discard") {rmSync(base,{recursive:true});return {discarded:true,draft,unit};}
-  if (action !== "diff") throw new Error("Choose create, diff or discard.");
+  if (action !== "diff") throw new Error("Choose create, migrate, diff or discard.");
   const files = new Set(metadata.entries.map(entry => entry.file));
   function walk(directory) {
     if (realpathSync(directory) !== directory) throw new Error("Draft directories cannot resolve through symlinks.");