@reqvire-org/ads 0.3.3 → 0.3.6

package/dist/mcp/build-status.mjs

@@ -4,13 +4,15 @@ import path from "node:path";
 import { z } from "zod";
 import { isInside, projectPath } from "../config.mjs";
 import { readPreviewManifest } from "../preview-resources.mjs";
+import { previewArtifactPath, withPreviewSession } from "../preview-scope.mjs";
 
 export const BUILD_URI = "ads://project/build";
 export const buildStatusFile = (root) => path.join(root, ".ds/build-status.json");
 const maxBytes = 256 * 1024;
 const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional(), code: z.string().max(100).optional() }).strict();
 const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
-const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
+const progressSchema = z.object({ phase: z.enum(["queued", "validation", "compilation", "validation-and-compilation", "publication", "idle"]), startedAt: z.string().datetime(), updatedAt: z.string().datetime() }).strict();
+const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), progress: progressSchema.optional(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
 export const artifactDigest = (file) => {
   if (realpathSync(file) !== file) throw new Error("Preview output cannot resolve through a symlink.");
   if (statSync(file).size > 2 * 1024 * 1024) throw new Error("Preview exceeds 2 MiB.");
@@ -37,8 +39,9 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   const entries = new Map(apps.map((app) => [app.id, { id: app.id, state: "idle", revision: 0, lastSuccessfulRevision: null, artifactDigest: null, diagnostics: [] }]));
   let sequence = 0;
   let diagnostics = [];
+  let progress;
   function save() {
-    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()], ...(diagnostics.length ? { diagnostics } : {}) };
+    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()], ...(progress ? { progress } : {}), ...(diagnostics.length ? { diagnostics } : {}) };
     let text = JSON.stringify(snapshot.parse(value));
     // A shared graph failure applies to every scenario. Store repeated details
     // once only when necessary; ordinary reports retain inline diagnostics.
@@ -67,6 +70,11 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   save();
   return {
     session,
+    progress(phase) {
+      const now = new Date().toISOString();
+      progress = { phase, startedAt: !progress || progress.phase === "idle" ? now : progress.startedAt, updatedAt: now };
+      save();
+    },
     failure(error) {
       diagnostics = (Array.isArray(error) ? error : [error]).slice(0, 20).map(error => normalizeDiagnostic(root, error));
       for (const value of entries.values()) { value.state = "error"; ++value.revision; value.diagnostics = []; }
@@ -116,7 +124,8 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
 }
 
 /** Read durable build events; a running process alone never means a fresh build. */
-export function inspectBuildStatus(root, config, { session, processState, file = buildStatusFile(root) } = {}) {
+export function inspectBuildStatus(root, config, { session, previewSession, processState, file = buildStatusFile(root) } = {}) {
+  const options = withPreviewSession({ root, config: { mcp: config } }, previewSession);
   let report;
   let reportError;
   try {
@@ -130,7 +139,7 @@ export function inspectBuildStatus(root, config, { session, processState, file =
   let graphError;
   if (config.previewManifest && report?.previews.some(entry => entry.state === "ready")) {
     try {
-      if (!readPreviewManifest({ root, config: { mcp: config } }, { verify: true })) throw new Error("Preview resource manifest is missing.");
+      if (!readPreviewManifest(options, { verify: true })) throw new Error("Preview resource manifest is missing.");
     } catch (error) { graphError = `Invalid preview resource graph: ${error.message}`; }
   }
   const previews = config.apps.map((app) => {
@@ -138,12 +147,13 @@ export function inspectBuildStatus(root, config, { session, processState, file =
     let state = value?.state ?? "unreported";
     let diagnostics = value?.diagnosticSet !== undefined ? report.diagnosticSets[value.diagnosticSet] : value?.diagnostics ?? [];
     if (report?.diagnostics?.length) { state = "error"; diagnostics = [...report.diagnostics, ...diagnostics].slice(0, 20); }
-    const available = existsSync(path.resolve(root, app.file));
+    const artifact = path.resolve(root, previewArtifactPath(options, app.file));
+    const available = existsSync(artifact);
     if (reportError) { state = "error"; diagnostics = [{ message: reportError }]; }
     if (graphError && app.id.includes("/")) { state = "error"; diagnostics = [{ message: graphError }]; }
     if (state === "ready") {
       try {
-        if (value.lastSuccessfulRevision !== value.revision || artifactDigest(path.resolve(root, app.file)) !== value.artifactDigest) throw new Error("Preview output does not match its successful build. Rebuild before reviewing it.");
+        if (value.lastSuccessfulRevision !== value.revision || artifactDigest(artifact) !== value.artifactDigest) throw new Error("Preview output does not match its successful build. Rebuild before reviewing it.");
       } catch (error) { state = "error"; diagnostics = [{ message: error.message }]; }
     }
     if (processState?.state === "failed") { state = "error"; diagnostics = [{ message: processState.error ?? "Preview watcher exited." }, ...diagnostics].slice(0, 20); }
@@ -153,7 +163,7 @@ export function inspectBuildStatus(root, config, { session, processState, file =
       current, stale: state === "unreported" ? null : !current, available, diagnostics };
   });
   const state = reportError || report?.diagnostics?.length || previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
-  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };
+  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, ...(report?.progress ? { progress: report.progress } : {}), previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };
 }
 
 export class PreviewBuildError extends Error {

package/dist/mcp/catalog.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 import ts from "typescript";
 import { isInside, sourceFiles } from "../config.mjs";
 import { projectCompilerOptions } from "../boundaries.mjs";
-import { publicUi } from "../scenarios.mjs";
+import { publicApi } from "../public-api.mjs";
 import { projectGuideFiles } from "../project-documents.mjs";
 
 export const PROJECT_URI = "ads://project";
@@ -24,7 +24,7 @@ export function projectDocuments(options) {
   for (const name of projectGuideFiles(root)) files.push(path.join(root, name));
   return [...new Set(files)].filter((file) => isInside(root, realpathSync(file))).sort().map((file) => {
     const relative = path.relative(root, file).replaceAll("\\", "/");
-    return { uri: sourceUri(relative), name: relative, mimeType: file.endsWith(".md") ? "text/markdown" : "text/plain", file };
+    return { uri: sourceUri(relative), name: relative, mimeType: file.endsWith(".md") ? "text/markdown" : file.endsWith(".json") ? "application/json" : "text/plain", file };
   });
 }
 
@@ -32,27 +32,30 @@ 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));
+  const program = ts.createProgram([entry], { ...projectCompilerOptions(options), allowJs: true });
   const checker = program.getTypeChecker();
   const source = program.getSourceFile(entry);
   const module = source && checker.getSymbolAtLocation(source);
   if (!module) return [];
   const documents = projectDocuments(options);
   const items = [];
-  const renderable = new Set(publicUi(program, options).filter(item => item.renderable).map(item => item.name));
+  const api = new Map(publicApi(program, options).map(item => [item.name, item]));
   for (const exported of checker.getExportsOfModule(module)) {
     let symbol = exported;
     if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
     const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
-    if (!(symbol.flags & ts.SymbolFlags.Value) || !declaration || !renderable.has(exported.name)) continue;
+    if (!(symbol.flags & ts.SymbolFlags.Value) || !declaration || !api.has(exported.name)) continue;
     const file = declaration.getSourceFile().fileName;
-    const kind = isInside(path.join(dsRoot, "components"), file) ? "components" : isInside(path.join(dsRoot, "patterns"), file) ? "patterns" : null;
+    const kind = api.get(exported.name).kind;
+    const ui = api.get(exported.name).renderable;
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+    if (!ui && !type.getCallSignatures().length && !type.getConstructSignatures().length) continue;
     if (!kind) continue;
     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, importFrom: config.publicAlias, file: relative, line, sourceUri: sourceUri(relative), guides,
-      previews: scenarios.filter(item => item.covers.includes(exported.name)).map(item => item.id) });
+    items.push({ name: exported.name, kind, apiKind: ui ? "ui" : "behavior", importFrom: config.publicAlias, file: relative, line, sourceUri: sourceUri(relative), guides,
+      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

@@ -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, 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 at a time. 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. 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 behavior work, read ads://guides/behaviors and use ads_behaviors/ads_verify: scenario exercises are demonstrations, and registered guarantees need current passing execution evidence. 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];
@@ -35,7 +35,7 @@ export function workflow(previews) {
     next: "Find the requested public UI with ads_catalog (query + kind + small limit), then read its source/guide and one selected ADS skill. For a broad UI request, inspect the public barrel and targeted application entry files in sourceRoot.",
     skills: [
       { task: "Build, refine or debug UI using the project ADS", name: "ads-designer" },
-      { task: "Adapt a component-library reference", name: "ads-assimilate" },
+      { task: "Adapt a component-library reference", name: "ads-migrate" },
       { task: "Import from another project's design-system", name: "ads-import" },
       { task: "Implement or review motion", name: "ads-motion" },
       { task: "Stress-test layout, states and interactions", name: "ads-break-ui" },
@@ -56,7 +56,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, including export {};. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit; report unsupported coupled changes instead of bypassing rejection with direct writes. 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/. 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}.
 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.
 

package/dist/mcp/edit-preparation.mjs

@@ -0,0 +1,111 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isInside } from "../config.mjs";
+import { checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
+import { textDiff } from "./text-diff.mjs";
+
+const hash = value => createHash("sha256").update(value).digest("hex");
+const binary = bytes => bytes?.includes(0) || bytes && !Buffer.from(bytes.toString("utf8")).equals(bytes);
+function generated(options, relative) {
+  const target = path.join(options.root, ".ds", relative);
+  mkdirSync(path.dirname(target), {recursive:true});
+  if (realpathSync(path.dirname(target)) !== path.dirname(target)) throw new Error("Patch preparation output cannot resolve through symlinks.");
+  return target;
+}
+export function storePreparedPatch(options, patch) {
+  if (Buffer.byteLength(patch) > 16 * 1024 * 1024) throw new Error("Prepared Git patch exceeds 16 MiB.");
+  if (!patch) return {patch:null,patchFile:null};
+  const file = `.ds/patches/${randomUUID()}.patch`;
+  writeFileSync(generated(options,file.slice(4)),patch);
+  return {patchFile:file,bytes:Buffer.byteLength(patch)};
+}
+
+/** A temporary copy of just one owner and its declared companions, not a project mirror. */
+export function prepareUnitPatch(options, {unit, action = "create", draft}) {
+  validateUnitId(unit);
+  const inventory = inspectUnits(options);
+  if (action === "create") {
+    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)) {
+      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("\\","/");
+        if (!files.includes(relative)) files.push(relative);
+      }
+    }
+    draft = randomUUID();
+    const base = generated(options,`patch-drafts/${draft}/manifest.json`), folder = path.join(path.dirname(base),"work");
+    const entries = [];
+    let bytes = 0;
+    for (const file of files) {
+      const absolute = path.resolve(options.root,file);
+      if (!isInside(options.root,absolute) || realpathSync(absolute) !== absolute || !lstatSync(absolute).isFile()) throw new Error("Draft inputs must be ordinary project source files.");
+      if (lstatSync(absolute).size > 16 * 1024 * 1024) throw new Error("Draft input exceeds 16 MiB.");
+      const content = readFileSync(absolute);
+      bytes += content.length;
+      if (entries.length >= 256 || bytes > 32 * 1024 * 1024) throw new Error("Owner draft exceeds 256 files/32 MiB. Prepare a targeted Git patch instead.");
+      for (const name of ["work","base"]) {
+        const target = path.join(path.dirname(base),name,file);
+        mkdirSync(path.dirname(target),{recursive:true}); writeFileSync(target,content);
+      }
+      entries.push({file,digest:hash(content)});
+    }
+    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."};
+  }
+  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);
+  if (realpathSync(base) !== base) throw new Error("Draft paths cannot resolve through symlinks.");
+  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.");
+  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.");
+    for (const entry of readdirSync(directory,{withFileTypes:true})) {
+      const file = path.join(directory,entry.name);
+      if (entry.isDirectory()) walk(file);
+      else if (!entry.isFile() || lstatSync(file).nlink !== 1) throw new Error("Drafts contain ordinary unlinked source files only.");
+      else files.add(path.relative(path.join(base,"work"),file).replaceAll("\\","/"));
+      if (files.size > 256) throw new Error("Draft exceeds 256 files.");
+    }
+  }
+  walk(path.join(base,"work"));
+  const changes = [];
+  let patch = "", bytes = 0;
+  for (const file of files) {
+    if (!file || path.isAbsolute(file) || file.includes("\\") || file.split("/").some(part => !part || part === "." || part === ".." || part.startsWith(".") && part !== ".gitkeep" && !/^\.(?:oxlintrc|linariarc|babelrc)(?:\.json)?$/.test(part))) throw new Error("Drafts use ordinary project-relative source paths.");
+    const original = path.join(base,"base",file), next = path.join(base,"work",file), live = path.join(options.root,file);
+    const read = file => {
+      if (!existsSync(file)) return null;
+      const stat = lstatSync(file);
+      if (realpathSync(file) !== file || !stat.isFile() || stat.nlink !== 1 || stat.size > 16 * 1024 * 1024) throw new Error("Draft inputs must be ordinary unlinked files no larger than 16 MiB.");
+      return readFileSync(file);
+    };
+    const expected = metadata.entries.find(entry => entry.file === file)?.digest ?? null;
+    const left = read(original), right = read(next), source = read(live);
+    if ((left && hash(left)) !== expected || (source && hash(source)) !== expected) throw new Error(`Source/baseline changed for ${file}; create a fresh owner draft.`);
+    if (left !== null && right !== null && left.equals(right) || left === null && right === null) continue;
+    bytes += (left?.length ?? 0) + (right?.length ?? 0);
+    if (bytes > 32 * 1024 * 1024) throw new Error("Draft changes exceed 32 MiB.");
+    const change = {path:file,originalContent:left === null ? null : binary(left) ? left : left.toString(),content:right === null ? null : binary(right) ? right : right.toString()};
+    changes.push(change);
+    if (!binary(left) && !binary(right)) patch += textDiff(file,change.originalContent,change.content);
+    else {
+      let diff;
+      try { diff = execFileSync("git",["diff","--no-index","--binary","--no-ext-diff","--no-textconv","--",left === null ? "/dev/null" : original,right === null ? "/dev/null" : next],{encoding:"utf8",maxBuffer:16*1024*1024}); }
+      catch (error) { if (error.status !== 1) throw error; diff=error.stdout; }
+      patch += diff.replace(/^diff --git .+$/m,`diff --git a/${file} b/${file}`);
+    }
+  }
+  if (changes.length) checkUnitFiles(options,unit,changes,inventory,true);
+  return {unit,draft,changes:changes.map(entry=>entry.path),...storePreparedPatch(options,patch),next:"Apply with ads_apply_patch using this unit and patchFile. Preparation is not validation or publication."};
+}

package/dist/mcp/mutations.mjs

@@ -5,6 +5,7 @@ import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, re
 import path from "node:path";
 import ts from "typescript";
 import { isInside, loadConfig } from "../config.mjs";
+import { affectedBehaviorUnits, createVerificationController } from "../verification.mjs";
 import { checkProject } from "../check.mjs";
 import { generateLintConfig } from "../lint-config.mjs";
 import { generateBrandAssets } from "../brand-assets.mjs";
@@ -12,7 +13,7 @@ import { projectContext } from "./context.mjs";
 import { applyFilePatch, parseUnifiedPatch } from "./patch.mjs";
 import { checkUnitCandidate, checkUnitFiles, inspectUnits, validateUnitId } from "../units.mjs";
 
-export const mutationLimits = { files: 32, patchBytes: 256 * 1024, patchFileBytes: 16 * 1024 * 1024, fileBytes: 16 * 1024 * 1024, readChars: 12000, snapshotFiles: 20000, snapshotBytes: 128 * 1024 * 1024 };
+export const mutationLimits = { units: 8, files: 32, patchBytes: 256 * 1024, patchFileBytes: 16 * 1024 * 1024, fileBytes: 16 * 1024 * 1024, readChars: 12000, snapshotFiles: 20000, snapshotBytes: 128 * 1024 * 1024 };
 const digest = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 const ignored = new Set([".git", ".ds", "node_modules", ".vite", "coverage", ".playwright-cli", "test-results", "output"]);
 const textFile = file => /\.(?:[cm]?[jt]sx?|css|html|jsonc?|md|txt|svg)$/.test(file);
@@ -28,7 +29,7 @@ function address(options, file) {
   if (!isInside(options.root, target) || target === options.root) throw fail("mutation-path", "Mutation paths must stay inside the project.", file);
   for (let current = options.root; ; ) {
     const relative = path.relative(current, target).split(path.sep);
-    if (relative.some(part => ignored.has(part) || part.startsWith(".") && !setupDotfile(part))) throw fail("mutation-path", "Hidden, dependency and generated paths are not editable.", file);
+    if (relative.some(part => ignored.has(part) || part.startsWith(".") && !setupDotfile(part) && !(part === ".gitkeep" && path.basename(target) === part && isInside(options.dsRoot, target)))) throw fail("mutation-path", "Hidden, dependency and generated paths are not editable.", file);
     current = path.join(current, relative[0]);
     const stat = lstatSync(current, { throwIfNoEntry: false });
     if (stat?.isSymbolicLink() || stat && current !== target && !stat.isDirectory() || stat && current === target && (!stat.isFile() || stat.nlink !== 1)) throw fail("mutation-path", "Mutation paths must contain ordinary directories and unlinked regular files.", file);
@@ -153,7 +154,7 @@ export function createMutationController(directory) {
       let commands = [], diagnostics = [];
       try { commands = checks(options).map(check => [check.command, ...check.args].join(" ")); }
       catch (error) { diagnostics = [error.diagnostic ?? { rule: "mutation-check", message: error.message }]; }
-      return { enabled: true, scope: "one-ds-unit", format: "git-unified-diff", dsDir: options.config.dsDir, limits: mutationLimits, checks: ["ads check", "registered Oxlint rules", ...commands], diagnostics, busy, lastResult };
+      return { enabled: true, scope: "one-ds-unit", format: "git-unified-diff", transactions:{tool:"ads_apply_transaction",maxUnits:mutationLimits.units,finalCandidateChecks:true}, preparation:{owner:"ads_prepare_patch",tokenSamples:"ads_prepare_token_samples"}, dsDir: options.config.dsDir, limits: mutationLimits, checks: ["ads check", "registered Oxlint rules", ...commands], diagnostics, busy, lastResult };
     },
     cancel() { active?.abort(); },
     units() { return inspectUnits(loadConfig(root)).units; },
@@ -169,7 +170,7 @@ export function createMutationController(directory) {
       return { ...source, unit, content, offset, nextOffset: end < source.content.length ? end : null, totalChars: source.content.length,
         startLine: source.content.slice(0, offset).split("\n").length };
     },
-    async apply({ unit, patch, patchFile, dryRun = false }, signal) {
+    async apply({ unit, patch, patchFile, patches, dryRun = false }, signal) {
       if (busy) return { ok: false, applied: false, diagnostics: [{ rule: "mutation-busy", message: "Another mutation is validating; retry after it finishes." }] };
       busy = true;
       active = new AbortController();
@@ -178,26 +179,22 @@ export function createMutationController(directory) {
       const verified = [];
       try {
         const options = loadConfig(root);
-        validateUnitId(unit);
-        if ((typeof patch === "string") === (typeof patchFile === "string")) throw fail("mutation-patch", "Provide exactly one of patch or patchFile.");
-        const maxPatch = patchFile === undefined ? mutationLimits.patchBytes : mutationLimits.patchFileBytes;
-        if (patchFile !== undefined) patch = readPatchFile(options, patchFile);
-        if (typeof patch !== "string" || patch.includes("\0") || Buffer.from(patch).toString("utf8") !== patch || Buffer.byteLength(patch) > maxPatch) throw fail("mutation-patch", "Patch exceeds its UTF-8 Git diff size limit.");
-        const entries = parseUnifiedPatch(patch, mutationLimits.files), changes = [];
-        const originals = entries.map(entry => {
-          const change = { path: entry.path };
-          const target = address(options, change.path);
-          const before = read(options, change.path);
-          if (!entry.binary && before.binary) throw fail("mutation-patch", "Binary assets require a git diff --binary patch.", change.path);
-          change.content = entry.binary ? entry.operation === "delete" ? null : before.content ?? Buffer.alloc(0) : applyFilePatch(entry, before.content);
-          if (entry.binary) change.binaryPatch = entry.patch;
-          change.expectedDigest = before.digest;
-          change.originalContent = before.content;
-          if (!entry.binary) validateContent(change, unit);
-          changes.push(change);
-          return { ...before, mode: before.exists ? lstatSync(target).mode : undefined };
+        if (patches !== undefined && (unit !== undefined || patch !== undefined || patchFile !== undefined || !Array.isArray(patches) || patches.length < 2 || patches.length > mutationLimits.units)) throw fail("mutation-batch", "A transaction requires 2–8 distinct owner patches, without a top-level unit/patch.");
+        const groups = patches ?? [{unit,patch,patchFile}];
+        if (new Set(groups.map(group => group.unit)).size !== groups.length) throw fail("mutation-batch", "Use one patch per distinct unit in a transaction.");
+        let patchBytes = 0;
+        const plans = groups.map(group => {
+          validateUnitId(group.unit);
+          if ((typeof group.patch === "string") === (typeof group.patchFile === "string")) throw fail("mutation-patch", "Provide exactly one of patch or patchFile for each owner.");
+          const value = group.patchFile === undefined ? group.patch : readPatchFile(options,group.patchFile);
+          const maxPatch = group.patchFile === undefined ? mutationLimits.patchBytes : mutationLimits.patchFileBytes;
+          patchBytes += Buffer.byteLength(value ?? "");
+          if (typeof value !== "string" || value.includes("\0") || Buffer.from(value).toString("utf8") !== value || Buffer.byteLength(value) > maxPatch || patchBytes > mutationLimits.patchFileBytes) throw fail("mutation-patch", "Patch exceeds its UTF-8 Git diff size limit.");
+          return {unit:group.unit,entries:parseUnifiedPatch(value,mutationLimits.files)};
         });
-        const inventory = checkUnitFiles(options, unit, changes, inspectUnits(options), true);
+        const units = groups.map(group => group.unit), configuration = units.includes("configuration"), assets = units.some(unit => unit.startsWith("assets"));
+        for (const plan of plans) for (const entry of plan.entries) address(options,entry.path);
+        const changes = [], originals = [], byPath = new Map();
         const cache = path.join(root, ".ds");
         mkdirSync(cache, { recursive: true });
         if (realpathSync(cache) !== path.join(realpathSync(root), ".ds")) throw fail("mutation-path", "The .ds directory cannot resolve through a symlink.");
@@ -205,7 +202,6 @@ export function createMutationController(directory) {
         const candidate = path.join(temporary, "project");
         mkdirSync(candidate);
         const before = snapshot(options, candidate);
-        for (const original of originals) if (read(options, original.path).digest !== original.digest) throw fail("mutation-conflict", "Source changed while preparing the validation copy. Read the affected range and regenerate the patch.", original.path);
         const dependencies = path.join(root, "node_modules");
         if (!existsSync(dependencies)) throw fail("mutation-check", "Install project dependencies before using guarded mutations.");
         symlinkSync(realpathSync(dependencies), path.join(candidate, "node_modules"), process.platform === "win32" ? "junction" : "dir");
@@ -221,24 +217,45 @@ export function createMutationController(directory) {
             return true;
           } });
         }
+        const entries = plans.flatMap(plan => plan.entries);
         if (entries.some(entry => entry.binary)) {
           const formats = new Set(entries.filter(entry=>entry.binary).map(entry=>entry.objectFormat));
           if (formats.size !== 1) throw fail("mutation-patch", "Binary blocks in one Git diff must use the same object format.");
           await checkCommand("git", ["init", "--quiet", `--object-format=${[...formats][0]}`, candidate], root, signal);
         }
-        for (const change of changes) {
-          const file = path.join(candidate, change.path);
-          if (change.binaryPatch) {
-            for (const match of change.binaryPatch.matchAll(/^(?:literal|delta) (\d+)$/gm)) if (Number(match[1]) > mutationLimits.fileBytes) throw fail("mutation-content", "Binary patch blocks exceed 16 MiB.", change.path);
-            await checkCommand("git", ["apply", "--binary", "--whitespace=nowarn", "-"], candidate, signal, change.binaryPatch);
-            change.content = existsSync(file) ? readFileSync(file) : null;
-            validateContent(change, unit);
+        for (const plan of plans) {
+          const current = loadConfig(candidate), selected = plan.entries.map(entry => {
+            address(options,entry.path);
+            const before = read(current,entry.path);
+            if (!entry.binary && before.binary) throw fail("mutation-patch", "Binary assets require a git diff --binary patch.", entry.path);
+            const change = {path:entry.path, originalContent:before.content, content:entry.binary ? entry.operation === "delete" ? null : before.content ?? Buffer.alloc(0) : applyFilePatch(entry,before.content), ...(entry.binary ? {binaryPatch:entry.patch} : {})};
+            if (!entry.binary) validateContent(change,plan.unit);
+            if (!byPath.has(entry.path)) {
+              const original = read(options,entry.path);
+              // The candidate copy and live inputs must agree before any changes.
+              if (original.digest !== before.digest) throw fail("mutation-conflict", "Source changed while preparing validation; regenerate the patch.", entry.path);
+              originals.push({...original,mode:original.exists ? lstatSync(address(options,entry.path)).mode : undefined});
+              byPath.set(entry.path,changes.length);
+              changes.push({...change,expectedDigest:original.digest});
+              if (changes.length > mutationLimits.files) throw fail("mutation-batch", "A transaction may change at most 32 distinct files.");
+            }
+            return change;
+          });
+          const inventory = checkUnitFiles(current,plan.unit,selected,inspectUnits(current),true);
+          for (const change of selected) {
+            const file = path.join(candidate,change.path);
+            if (change.binaryPatch) {
+              for (const match of change.binaryPatch.matchAll(/^(?:literal|delta) (\d+)$/gm)) if (Number(match[1]) > mutationLimits.fileBytes) throw fail("mutation-content", "Binary patch blocks exceed 16 MiB.", change.path);
+              await checkCommand("git",["apply","--binary","--whitespace=nowarn","-"],candidate,signal,change.binaryPatch);
+              change.content = existsSync(file) ? readFileSync(file) : null;
+              validateContent(change,plan.unit);
+            } else if (change.content === null) rmSync(file);
+            else {mkdirSync(path.dirname(file),{recursive:true});writeFileSync(file,change.content);}
+            changes[byPath.get(change.path)].content = change.content;
           }
-          else if (change.content === null) rmSync(file);
-          else { mkdirSync(path.dirname(file), { recursive: true }); writeFileSync(file, change.content); }
+          checkUnitCandidate(loadConfig(candidate),plan.unit,selected,inventory);
         }
         const candidateOptions = loadConfig(candidate);
-        checkUnitCandidate(candidateOptions, unit, changes, inventory);
         const extraChecks = checks(candidateOptions);
         const expected = snapshot(candidateOptions);
         const result = checkProject(candidate, { trackingRoot: root });
@@ -250,16 +267,25 @@ export function createMutationController(directory) {
         const bin = JSON.parse(readFileSync(oxlintPackage, "utf8")).bin;
         const executable = path.resolve(path.dirname(oxlintPackage), typeof bin === "string" ? bin : bin.oxlint);
         const lintPaths = [candidateOptions.config.sourceDir, candidateOptions.config.dsDir].filter(file => existsSync(path.join(candidate, file)));
-        if (unit === "configuration") for (const file of inspectUnits(candidateOptions).units.find(item => item.id === "configuration").files) {
+        if (configuration) for (const file of inspectUnits(candidateOptions).units.find(item => item.id === "configuration").files) {
           if (/\.[cm]?[jt]sx?$/.test(file) && !lintPaths.some(directory => isInside(path.resolve(candidate, directory), path.resolve(candidate, file)))) lintPaths.push(file);
         }
         await checkCommand(process.execPath, [executable, "--deny-warnings", "--config", lintConfig, ...lintPaths], candidate, signal);
         verified.push({ name: "registered Oxlint rules", passed: true });
-        if (unit.startsWith("assets") || unit === "configuration") {
+        if (assets || configuration) {
           const brand = await generateBrandAssets(candidate);
           verified.push({ name: "brand assets", passed: true, skipped: !!brand.skipped });
         }
         for (const check of extraChecks) verified.push(await checkCommand(check.command, check.args, candidate, signal));
+        const behaviorUnits = affectedBehaviorUnits(candidateOptions, changes.map(change => change.path));
+        if (behaviorUnits.length) {
+          const verification = createVerificationController(candidate);
+          let evidence;
+          try { evidence = await verification.run({ units: behaviorUnits, persist: false }, signal); }
+          finally { await verification.close(); }
+          if (!evidence.ok) return lastResult = { ok: false, applied: false, diagnostics: [...evidence.diagnostics, ...evidence.results.filter(item => item.status !== "passed").map(item => ({ rule: "behavior-check", message: `${item.unit}#${item.check}: ${item.status}. ${item.message}` }))].slice(0, 50), checks: verified, behavior: evidence };
+          verified.push({ name: "registered behavior checks", passed: true, results: evidence.results });
+        }
         if (signal?.aborted) throw fail("mutation-cancelled", "Mutation cancelled before application.");
         if (snapshot(candidateOptions) !== expected) throw fail("mutation-check", "A validation command changed source files. Use checks without source-writing side effects.");
         if (snapshot(loadConfig(root)) !== before) throw fail("mutation-conflict", "Project inputs changed during validation; no changes were applied. Read current source and retry.");
@@ -290,8 +316,8 @@ export function createMutationController(directory) {
           }
         }
         const warnings = [];
-        if (!dryRun && (unit.startsWith("assets") || unit === "configuration")) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
-        return lastResult = { ok: true, unit, applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
+        if (!dryRun && (assets || configuration)) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
+        return lastResult = { ok: true, ...(patches ? {units,transaction:true} : {unit}), applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
           preview: "Source validation passed. Inspect the managed preview build and rendered scenario after applying; validation is not visual verification." };
       } catch (error) {
         return lastResult = { ok: false, applied: false, diagnostics: [error.diagnostic ?? { rule: "mutation-error", message: error.message }], checks: verified };

package/dist/mcp/preview-owner-guard.mjs

@@ -0,0 +1,29 @@
+import { spawn } from "node:child_process";
+
+// The only stdin writer is the MCP owner. EOF also arrives after SIGKILL or a
+// client launcher crash, when the owner's JavaScript cleanup cannot execute.
+const pid = Number(process.argv[2]);
+if (!Number.isSafeInteger(pid) || pid <= 1 || pid === process.pid) throw new Error("Invalid owned preview process group");
+let released = false, stopping = false, timer, input = "";
+function stop() {
+  if (released || stopping) return;
+  stopping = true;
+  if (process.platform === "win32") {
+    const terminator = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    terminator.on("error", () => { process.exitCode = 1; });
+    return;
+  }
+  try { process.kill(-pid, "SIGTERM"); }
+  catch (error) { if (error.code !== "ESRCH") process.exitCode = 1; return; }
+  timer = setTimeout(() => {
+    try { process.kill(-pid, "SIGKILL"); }
+    catch (error) { if (error.code !== "ESRCH") process.exitCode = 1; }
+  }, 1500);
+}
+process.stdin.on("data", bytes => {
+  input = (input + bytes).slice(-32);
+  if (input === "disarm\n") { released = true; clearTimeout(timer); }
+});
+for (const event of ["end", "close", "error"]) process.stdin.once(event, stop);
+for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, stop);
+process.stdin.resume();