@reqvire-org/ads 0.3.17 → 0.3.20

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/linaria/preserve-values.cjs

@@ -8,6 +8,23 @@ module.exports = function preserveCustomProperties(Processor) {
   return class PreservedCustomProperties extends Processor {
     extractRules(valueCache, cssText, loc) {
       const source = postcss.parse(cssText);
+      const registrations = [];
+      const layerOrder=[];
+      // Moving a registration must not change which named layer was first seen.
+      source.walkAtRules("layer",rule=>{
+        if(!rule.nodes||!rule.params.trim())return;
+        let statement=postcss.atRule({name:"layer",params:rule.params});
+        for(let parent=rule.parent;parent&&parent.type!=="root";parent=parent.parent){if(parent.type!=="atrule")return;const wrapper=parent.clone({nodes:[]});wrapper.raws.semicolon=true;wrapper.append(statement);statement=wrapper;}
+        layerOrder.push(statement.toString()+(statement.nodes?"":";"));
+      });
+      source.walkAtRules(/^property$/i, rule => {
+        let extracted=rule.clone();
+        for(let parent=rule.parent;parent&&parent.type!=="root";parent=parent.parent){
+          if(parent.type!=="atrule")throw new Error("@property is document-global. Put it at the Linaria template's top level or inside conditional at-rules, not inside an element selector.");
+          const wrapper=parent.clone({nodes:[]});wrapper.append(extracted);extracted=wrapper;
+        }
+        registrations.push(extracted.toString());rule.remove();
+      });
       const values = new Map();
       source.walkDecls(declaration => {
         if (!declaration.prop.startsWith("--")) return;
@@ -17,9 +34,9 @@ module.exports = function preserveCustomProperties(Processor) {
         declaration.value = marker;
         delete declaration.raws.value;
       });
-      if (!values.size) return super.extractRules(valueCache, cssText, loc);
+      if (!values.size && !registrations.length) return super.extractRules(valueCache, cssText, loc);
       const rules = super.extractRules(valueCache, source.toString(), loc);
-      return Object.fromEntries(Object.entries(rules).map(([key, rule]) => {
+      const restoredRules=Object.fromEntries(Object.entries(rules).map(([key, rule]) => {
         const output = postcss.parse(rule.cssText);
         output.walkDecls(declaration => {
           if (declaration.prop.startsWith("--") && values.has(declaration.value)) declaration.value = values.get(declaration.value);
@@ -27,6 +44,8 @@ module.exports = function preserveCustomProperties(Processor) {
         const restored = output.toString();
         return [rule.atom ? restored : key, { ...rule, cssText: restored }];
       }));
+      const globalRule=cssText=>({cssText,start:loc?.start??null,className:this.className,displayName:this.displayName,atom:true});
+      return {...Object.fromEntries(registrations.length?layerOrder.map(css=>[css,globalRule(css)]):[]),...restoredRules,...Object.fromEntries(registrations.map(css=>[css,globalRule(css)]))};
     }
   };
 };

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/behavior-pages.mjs

@@ -0,0 +1,36 @@
+import { behaviorStatus } from "../verification.mjs";
+import { compactRow, resultPage } from "./result-pages.mjs";
+
+export const behaviorSections = ["owners", "checks", "guarantees", "subjects", "demonstrations", "profiles"];
+const checkResult = (unit, id, result) => {
+  const {status,current,revision,runId,profile,case:caseId,durationMs,completedAt,failure}=result;
+  return {status,current,revision,runId,profile,case:caseId,durationMs,completedAt,...(failure?{failure}:{}),
+    ...(runId?{investigation:{unit,check:id,runId}}:{})};
+};
+
+/** Discovery never embeds stored runner reports or investigation bodies. */
+export function behaviorPage(options, {unit,api,query="",section=unit?"checks":"owners",cursor,limit} = {}) {
+  if(!behaviorSections.includes(section)||section!=="owners"&&!unit)throw new Error("Select an exact unit before paging behavioral details.");
+  const inventory=behaviorStatus(options);
+  const matches=inventory.contracts.filter(contract=>(!unit||contract.unit===unit)&&(!api||Object.values(contract.subjects).some(subject=>subject.api===api))&&JSON.stringify([contract.unit,contract.subjects,contract.guarantees.map(({id,description})=>({id,description}))]).toLowerCase().includes(query.toLowerCase()));
+  let rows;
+  if(section==="owners") rows=matches.map(contract=>({unit:contract.unit,file:contract.file,
+    apis:Object.values(contract.subjects).filter(subject=>subject.api).map(subject=>subject.api).slice(0,10),
+    apiCount:Object.values(contract.subjects).filter(subject=>subject.api).length,
+    checkCount:Object.keys(contract.checks).length,guaranteeCount:contract.guarantees.length,
+    guarantees:contract.guarantees.slice(0,3).map(({id,result})=>({id,result})),guaranteesTruncated:contract.guarantees.length>3,
+    sections:{checks:Object.keys(contract.checks).length,guarantees:contract.guarantees.length,subjects:Object.keys(contract.subjects).length,demonstrations:Object.keys(contract.demonstrations).length},
+    next:{tool:"ads_behaviors",arguments:{unit:contract.unit,section:"checks"}}}));
+  else {
+    const contract=matches[0];
+    if(!contract)throw new Error("No behavior contract matches this unit/filter.");
+    if(section==="checks")rows=Object.entries(contract.checks).map(([id,{result,...check}])=>({id,...check,result:checkResult(contract.unit,id,result)}));
+    if(section==="guarantees")rows=contract.guarantees;
+    if(section==="subjects")rows=Object.entries(contract.subjects).map(([id,subject])=>({id,...subject}));
+    if(section==="demonstrations")rows=Object.entries(contract.demonstrations).map(([subject,scenarios])=>({subject,scenarios}));
+    if(section==="profiles")rows=[...new Set(Object.values(contract.checks).map(check=>check.profile))].map(id=>({id,...options.config.mcp.behaviorProfiles[id]}));
+  }
+  const revision=matches.map(contract=>[contract.unit,contract.file,Object.entries(contract.checks).map(([id,check])=>[id,check.result.revision,check.result.status,check.result.runId])]);
+  return resultPage(rows,{cursor,limit,identity:["behaviors",section,unit,api,query,revision,rows],key:section==="owners"?"contracts":"items",
+    header:{section,...(unit?{unit,sourceFile:matches[0]?.file}:{}),diagnosticCount:inventory.diagnostics.length,diagnostics:inventory.diagnostics.slice(0,2).map(row=>compactRow(row,384)),resourceUri:"ads://project/behaviors"}});
+}

package/dist/mcp/context.mjs

@@ -5,7 +5,7 @@ import { projectGuideFiles } from "../project-documents.mjs";
 
 export const GUIDE_URI = "ads://project/guide";
 // Put the task triggers and entry path first: some hosts shorten server guidance.
-export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner; use ads_apply_transaction only for coupled owner patches. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For requested visual evidence, use ads_capture or screenshot-enabled patch dry runs; read ads://guides/captures for named targets, image resources and the current/candidate lifecycle. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. For a failed check or rejected patch, inspect its structured failure boundary and acceptance scope; ads_investigate reads retained per-check evidence without rerunning tests (ads://guides/evidence). Preserve valid APIs when source tracing is inconclusive. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
+export const serverInstructions = "Use ADS for UI work: components, patterns, controllers, hooks, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner; use ads_apply_transaction only for coupled owner patches. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. For requested visual evidence, use ads_capture or screenshot-enabled patch dry runs; read ads://guides/captures for named targets, image resources and the current/candidate lifecycle. For behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. Execution replies are bounded summaries. Read only needed sections with ads_results(resultId, section, status, cursor); follow nextCursor without rerunning. For a failure, inspect its boundary and acceptance, then ads_investigate with the outcome's exact unit/check/runId; detail sections and artifacts load separately (ads://guides/evidence). Preserve valid APIs when source tracing is inconclusive. Use the configured project framework and declared dependencies; MCP hosts supply no ad hoc APIs. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
 
 function manager(root, pkg) {
   if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
@@ -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,8 +57,10 @@ 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 guarded owners, aliases and migration. 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.
+
 7. After edits, inspect ads_status.build or ads://project/build explicitly. Running/unreported/old output is not a current successful preview. Fix diagnostics in owned source, wait for rebuilding and invoke the preview tool again. Notifications may not start an agent turn.
 
 Project guide resources: ${context.guides.map((guide) => `${guide.file}: ${guide.uri}`).join("; ") || "none discovered"}.

package/dist/mcp/edit-preparation.mjs

@@ -30,9 +30,9 @@ export function prepareUnitPatch(options, {unit, action = "create", draft}) {
     const owner = inventory.units.find(entry => entry.id === unit);
     const files = [...new Set([...(owner?.files ?? []), ...(owner?.companionFiles ?? []).map(entry => entry.path),
       ...(!owner ? ["ds.config.json"] : []),
-      ...(/^(?:components|patterns|controllers)\//.test(unit) ? [path.relative(options.root,path.join(options.dsRoot,options.config.publicEntry)).replaceAll("\\","/")] : [])])];
-    if (!owner && !/^(?:components|patterns|controllers|composition)\/.+/.test(unit)) throw new Error("Discover an existing unit or choose a new unoccupied component/pattern/controller/composition owner.");
-    if (/^(?:components|patterns|controllers|composition)\//.test(unit)) for (let directory=unit;directory!==".";directory=path.posix.dirname(directory)) {
+      ...(/^(?:components|patterns|controllers|review)\//.test(unit) ? [path.relative(options.root,path.join(options.dsRoot,unit.startsWith("review/")?options.config.reviewEntry:options.config.publicEntry)).replaceAll("\\","/")] : [])])];
+    if (!owner && !/^(?:components|patterns|controllers|composition|review)\/.+/.test(unit)) throw new Error("Discover an existing unit or choose a new unoccupied component/pattern/controller/composition/review owner.");
+    if (/^(?:components|patterns|controllers|composition|review)\//.test(unit)) for (let directory=unit;directory!==".";directory=path.posix.dirname(directory)) {
       const marker=path.join(options.dsRoot,directory,".gitkeep");
       if (existsSync(marker) && realpathSync(marker)===marker && lstatSync(marker).isFile() && lstatSync(marker).size===0) {
         const relative=path.relative(options.root,marker).replaceAll("\\","/");

package/dist/mcp/execution-results.mjs

@@ -0,0 +1,146 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { compactAcceptance, compactRow, jsonBytes, resultBudgets, resultPage, resultRecord } from "./result-pages.mjs";
+
+export const RESULTS_URI = "ads://project/results";
+export const resultSections = ["outcomes", "checks", "diagnostics", "advisories", "warnings", "changes", "captures", "acceptance", "investigation", "selection"];
+const kinds = ["verification", "mutation"];
+const maxStoredBytes = 8 * 1024 * 1024;
+const uuid = value => typeof value === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value);
+const resultUri = id => `ads://results/${id}`;
+const count = items => {
+  const statuses = {};
+  for (const item of items) { const status = item.status ?? (item.skipped ? "skipped" : item.passed === true ? "passed" : item.passed === false ? "failed" : "unknown"); statuses[status] = (statuses[status] ?? 0) + 1; }
+  return { total: items.length, ...statuses };
+};
+
+function outcome(item) {
+  const { current, investigation, ...detail } = item;
+  return { ...detail, inputsCurrentAtCompletion:current,
+    investigation: { unit:item.unit, check:item.check, runId:item.runId, resourceUri:investigation?.resourceUri } };
+}
+
+function snapshot(kind, raw) {
+  const outcomes = raw.results ?? raw.behavior?.results ?? (raw.checks ?? []).flatMap(check => check.results ?? []);
+  const sections = {
+    outcomes: outcomes.map(outcome),
+    checks: (raw.checks ?? []).map(({ results, ...check }) => ({ ...check, ...(results ? { outcomeCount: results.length } : {}) })),
+    diagnostics: raw.diagnostics ?? [], advisories: raw.advisories ?? [], warnings: raw.warnings ?? [], changes: raw.changes ?? [],
+    captures: raw.screenshots?.captures ?? [], selection: [{unit:raw.unit,units:raw.units,transaction:raw.transaction}],
+    acceptance: raw.acceptance ? [raw.acceptance] : [], investigation: raw.investigation ? [raw.investigation] : [],
+  };
+  const resultId = randomUUID();
+  return { schemaVersion: 1, resultId, kind, createdAt: new Date().toISOString(), ok: !!raw.ok,
+    ...(raw.applied !== undefined ? { applied: raw.applied } : {}), ...(raw.unit ? { unit: raw.unit } : {}),
+    ...(raw.units ? { units: raw.units } : {}), ...(raw.transaction ? { transaction: true } : {}),
+    acceptance: raw.acceptance, investigation: raw.investigation,
+    sections: Object.fromEntries(Object.entries(sections).map(([key, rows]) => [key, rows.map((row, recordIndex) => ({ recordIndex, ...(row && typeof row === "object" ? row : {message:row}) }))])),
+    counts: { outcomes: count(outcomes), checks: count(sections.checks), diagnostics: sections.diagnostics.length,
+      advisories: sections.advisories.length, warnings: sections.warnings.length, changes: sections.changes.length, captures: sections.captures.length },
+    resourceUri: resultUri(resultId) };
+}
+
+function summary(value, storageWarning) {
+  const { ok, resultId, kind, applied, unit, units, transaction, createdAt, counts, resourceUri } = value;
+  const failedOutcomes = value.sections.outcomes.filter(item => item.status !== "passed");
+  const failureRows = failedOutcomes.length ? failedOutcomes : value.sections.diagnostics;
+  const section = failedOutcomes.length ? "outcomes" : value.sections.diagnostics.length ? "diagnostics" : value.sections.captures.length ? "captures" : value.sections.outcomes.length ? "outcomes" : "checks";
+  const result = { ok, resultId, kind, ...(applied !== undefined ? { applied } : {}), ...(unit ? { unit } : {}),
+    ...(units ? { units } : {}), ...(transaction ? { transaction } : {}), createdAt, counts, freshness:"recorded-at-completion",
+    acceptance: compactAcceptance(value.acceptance), failures: value.failurePreview ?? failureRows.slice(0, 3).map(item => compactRow({recordIndex:item.recordIndex,unit:item.unit,check:item.check,status:item.status,rule:item.rule,file:item.file,failure:item.failure,message:item.message},640)),
+    failureCount: value.failureCount ?? failureRows.length, resourceUri,
+    next: value.detailsUnavailable ? null : { tool: "ads_results", arguments: { resultId, section, ...(section === "outcomes" && failedOutcomes.length ? { status: "not_passed" } : {}) } },
+    ...((storageWarning ?? value.storageWarning) ? { storageWarning: storageWarning ?? value.storageWarning } : {}), byteLimit: resultBudgets.summary };
+  if (jsonBytes(result) > resultBudgets.summary) {
+    result.failures = failureRows.slice(0, 3).map(item => compactRow(item, 384));
+    result.detailTruncated = true;
+  }
+  if (jsonBytes(result) > resultBudgets.summary) {
+    result.failures = []; result.detailTruncated = true;
+    result.acceptance = { scope: value.acceptance?.scope, status: value.acceptance?.status, detailTruncated: true };
+  }
+  if (jsonBytes(result) > resultBudgets.summary) {
+    delete result.unit; delete result.units;
+    result.acceptance = { status: value.acceptance?.status, detailTruncated: true };
+  }
+  return result;
+}
+
+/** One immutable, replaceable snapshot per execution kind. No result history. */
+export function createExecutionResults(root) {
+  root = path.resolve(root);
+  const folder = path.join(root, ".ds/tool-results"), memory = new Map();
+  function file(kind) { return path.join(folder, `${kind}.json`); }
+  function read(kind) {
+    const temporary = memory.get(kind);
+    if (temporary?.memoryOnly) return temporary.value;
+    const target = file(kind);
+    try {
+      if (realpathSync(target) !== target || !lstatSync(target).isFile() || lstatSync(target).nlink !== 1 || lstatSync(target).size > maxStoredBytes) return undefined;
+      const value = JSON.parse(readFileSync(target, "utf8"));
+      return value.schemaVersion === 1 && value.kind === kind && uuid(value.resultId) && resultSections.every(section => Array.isArray(value.sections?.[section])) ? value : undefined;
+    } catch { return undefined; }
+  }
+  function find(resultId) {
+    if (!uuid(resultId)) throw new Error("Use an exact resultId returned by an execution summary.");
+    const value = kinds.map(read).find(value => value?.resultId === resultId);
+    if (!value) throw new Error("Result is unavailable or superseded. Only the latest completed result of each kind is retained; discover its ID with ads_status.");
+    return value;
+  }
+  return {
+    save(kind, raw) {
+      if (!kinds.includes(kind)) throw new Error("Unknown execution kind.");
+      const value = snapshot(kind, raw);
+      let content = JSON.stringify(value);
+      if (Buffer.byteLength(content) > maxStoredBytes) {
+        const preview=summary(value);
+        value.failurePreview=preview.failures;value.failureCount=preview.failureCount;
+        value.sections=Object.fromEntries(resultSections.map(section=>[section,[]]));
+        value.acceptance=preview.acceptance;delete value.investigation;
+        value.detailsUnavailable=true;
+        value.storageWarning="Result details exceeded the 8 MiB retention limit. Only this summary is retained; execution and applied state above are unchanged.";
+        content=JSON.stringify(value);
+      }
+      let storageWarning;
+      try {
+        let ancestor=folder;
+        while(true){try{lstatSync(ancestor);break;}catch(error){if(error.code!=="ENOENT")throw error;ancestor=path.dirname(ancestor);}}
+        if(realpathSync(ancestor)!==ancestor)throw new Error("Result output cannot resolve through a symlink.");
+        mkdirSync(folder, { recursive: true });
+        if (realpathSync(folder) !== folder) throw new Error("Result output cannot resolve through a symlink.");
+        const staged = `${file(kind)}.${randomUUID()}.tmp`;
+        try { writeFileSync(staged, content); renameSync(staged, file(kind)); } finally { rmSync(staged, { force: true }); }
+        memory.set(kind, { value, memoryOnly: false });
+      } catch {
+        memory.set(kind, { value: JSON.parse(content), memoryOnly: true });
+        storageWarning = "Result details are available in this server's memory only; storage failed. Execution and applied state above are unchanged.";
+      }
+      return summary(value, storageWarning);
+    },
+    latest(kind) { const value = read(kind); return value ? summary(value, memory.get(kind)?.memoryOnly ? "Result details are in server memory only." : undefined) : null; },
+    index() { return { retention: "latest-per-kind", results: kinds.map(kind => this.latest(kind)).filter(Boolean).map(({resultId,kind,ok,applied,createdAt,counts,resourceUri})=>({resultId,kind,ok,applied,createdAt,counts,resourceUri})) }; },
+    fingerprint() { return kinds.map(kind=>{if(memory.get(kind)?.memoryOnly)return memory.get(kind).value.resultId;try{const stat=lstatSync(file(kind));return `${kind}:${stat.mtimeMs}:${stat.size}`;}catch{return `${kind}:missing`;}}).join("\n"); },
+    page({ resultId, section = "outcomes", status = "all", cursor, limit, recordIndex, offset, chars } = {}) {
+      const value = find(resultId);
+      if(value.detailsUnavailable)throw new Error("This result exceeded the 8 MiB retention limit; only its summary is available.");
+      if (!resultSections.includes(section) || !["all", "passed", "not_passed"].includes(status) || status !== "all" && section !== "outcomes") throw new Error("Select a registered result section; status filters apply only to outcomes.");
+      if (recordIndex !== undefined) {
+        if (cursor !== undefined || status !== "all") throw new Error("Read record ranges without a cursor or status filter.");
+        return resultRecord(value.sections[section],{recordIndex,offset,chars,header:{resultId,section}});
+      }
+      if(offset!==undefined||chars!==undefined)throw new Error("Select a recordIndex before reading text ranges.");
+      const rows = value.sections[section].filter(row => status === "all" || (status === "passed" ? row.status === "passed" : row.status !== "passed"));
+      return resultPage(rows, { cursor, limit, identity: [resultId, section, status], header: { resultId, kind: value.kind, section, status, freshness:"recorded-at-completion" } });
+    },
+    readResource(uri) {
+      if (uri === RESULTS_URI) return { uri, mimeType: "application/json", text: JSON.stringify(this.index()) };
+      const url = new URL(uri);
+      if (url.protocol !== "ads:" || url.hostname !== "results" || [...url.searchParams.keys()].some(key => !["section", "status", "cursor", "limit", "recordIndex", "offset", "chars"].includes(key))) throw new Error("Invalid execution result resource URI.");
+      const id = url.pathname.slice(1);
+      const value = url.search ? this.page({ resultId: id, section: url.searchParams.get("section") ?? "outcomes", status: url.searchParams.get("status") ?? "all", cursor: url.searchParams.get("cursor") ?? undefined,
+        ...Object.fromEntries(["limit","recordIndex","offset","chars"].filter(key=>url.searchParams.has(key)).map(key=>[key,Number(url.searchParams.get(key))])) }) : summary(find(id));
+      return { uri, mimeType: "application/json", text: JSON.stringify(value) };
+    },
+  };
+}