toolfactory 0.1.1 → 0.2.0

package/src/e2e.test.ts

@@ -163,7 +163,13 @@ describe.skipIf(!existsSync(repoNodeModules))(
       authorProse(fresh);
       commands.build(fresh);
 
-      expect(tree(walked)).toEqual(tree(fresh));
+      const walkedTree = tree(walked);
+      // Deselecting a region surface preserves its author-owned scaffold, including an empty
+      // Docker ignore file. All managed bytes still converge with the freshly generated tree.
+      expect(walkedTree[".dockerignore"]).toContain("# tf:dockerignore# /tf:dockerignore");
+      expect(walkedTree[".dockerignore"]).not.toContain("node_modules/");
+      delete walkedTree[".dockerignore"];
+      expect(walkedTree).toEqual(tree(fresh));
     });
   },
 );

package/src/hosts/openclaw.ts

@@ -62,8 +62,10 @@ function missing(scaffold: unknown, ours: unknown, path: string, skip: Set<strin
 
 function planned(files: PlannedFile[], path: string): string {
   const file = files.find((candidate) => candidate.path === `${HOST_DIR}/${path}`);
-  if (file?.kind !== "file") throw new Error(`the openclaw surface no longer plans ${path}`);
-  return file.content;
+  if (!file) throw new Error(`the openclaw surface no longer plans ${path}`);
+  if (file.kind === "file") return file.content;
+  if (file.kind === "merge" && file.format === "json") return JSON.stringify(file.patch, null, 2);
+  throw new Error(`the openclaw surface no longer plans ${path} as JSON`);
 }
 
 /** Human-readable drift lines; empty means the generator still mirrors upstream. */

package/src/hosts/vscode.ts

@@ -0,0 +1,79 @@
+/** Verify the extension scaffold against Microsoft's generator, without touching the checkout. */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { argv } from "node:process";
+import { fileURLToPath } from "node:url";
+import {
+  ESBUILD,
+  ESLINT,
+  GITIGNORE,
+  IGNORE,
+  LAUNCH,
+  TASKS,
+  VSCODE_GENERATOR,
+  VSCODE_SCAFFOLD,
+} from "../surfaces/vscode-scaffold.js";
+
+export function scaffoldDrift(): string[] {
+  const root = mkdtempSync(join(tmpdir(), "toolfactory-vscode-scaffold-"));
+  const target = join(root, "probe");
+  try {
+    execFileSync(
+      "npx",
+      [
+        "--yes",
+        "--package",
+        "yo",
+        "--package",
+        `generator-code@${VSCODE_GENERATOR}`,
+        "--",
+        "yo",
+        "code",
+        target,
+        "--extensionType",
+        "ts",
+        "--extensionDisplayName",
+        "ToolFactory Probe",
+        "--extensionId",
+        "tf-probe",
+        "--extensionDescription",
+        "ToolFactory scaffold probe",
+        "--pkgManager",
+        "npm",
+        "--bundler",
+        "esbuild",
+        "--gitInit",
+        "false",
+        "--skip-install",
+        "--skipOpen",
+        "--quick",
+      ],
+      { stdio: "pipe", cwd: root },
+    );
+    const pkg = JSON.parse(readFileSync(join(target, "package.json"), "utf8"));
+    const drift = Object.entries(VSCODE_SCAFFOLD)
+      .filter(([key, expected]) => JSON.stringify(pkg[key]) !== JSON.stringify(expected))
+      .map(([key]) => `package.json ${key}`);
+    for (const [path, expected] of [
+      ["esbuild.js", ESBUILD],
+      ["eslint.config.mjs", ESLINT],
+      [".vscodeignore", IGNORE],
+      [".gitignore", GITIGNORE],
+      [".vscode/launch.json", LAUNCH],
+      [".vscode/tasks.json", TASKS],
+    ]) {
+      if (readFileSync(join(target, path), "utf8") !== expected) drift.push(path);
+    }
+    return drift;
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+if (argv[1] === fileURLToPath(import.meta.url)) {
+  const drift = scaffoldDrift();
+  if (drift.length) throw new Error(`VS Code scaffold drifted: ${drift.join(", ")}`);
+  process.stdout.write("VS Code scaffold matches generator-code.\n");
+}

package/src/model.ts

@@ -7,6 +7,9 @@
  * rest is derived and written in-tree, tracked by a lock file.
  */
 import { z } from "zod";
+import { NATIVE_PACKAGE_IDS, nativePackageConfigSchema } from "./distribution/native.js";
+import { SYSTEM_PACKAGE_IDS, systemPackageConfigSchema } from "./distribution/system.js";
+import { vscodeConfigSchema } from "./surfaces/vscode-extension.js";
 
 export const CAPABILITIES = [
   "net",
@@ -48,6 +51,9 @@ export const SURFACE_IDS = [
   "gemini",
   "mcpb",
   "browser-extension",
+  "vscode-extension",
+  ...NATIVE_PACKAGE_IDS,
+  ...SYSTEM_PACKAGE_IDS,
 ] as const;
 export type SurfaceId = (typeof SURFACE_IDS)[number];
 
@@ -129,7 +135,17 @@ export const ToolConfigSchema = z
       .default({ examples: {} })
       .describe("Example arguments per operation, used by the generated surface-smoke tests."),
     npm: z.object({ scope: z.string().optional() }).optional(),
-    codex: z.object({ interface: jsonObject.optional() }).optional(),
+    codex: z
+      .object({
+        interface: jsonObject.optional(),
+        mcp: z
+          .boolean()
+          .default(true)
+          .describe(
+            "Whether the Codex plugin manifest eagerly configures the generated MCP server.",
+          ),
+      })
+      .optional(),
     browserExtension: z
       .object({
         endpoint: z
@@ -177,6 +193,9 @@ export const ToolConfigSchema = z
         "Privacy-policy URLs of the services this tool talks to; Anthropic's Connectors Directory submission requires them in the MCPB manifest.",
       ),
     hermes: z.object({ toolset: z.string().optional() }).optional(),
+    vscode: vscodeConfigSchema.optional(),
+    nativePackages: z.array(nativePackageConfigSchema).optional(),
+    systemPackages: z.array(systemPackageConfigSchema).optional(),
     openclaw: z
       .object({
         registers: z
@@ -304,10 +323,15 @@ export interface RegionFile {
 export interface MergeFile {
   kind: "merge";
   path: string;
-  format: "json" | "toml";
+  format: "json" | "toml" | "yaml";
   patch: Record<string, unknown>;
   /** Dotted paths inside `patch` whose object toolfactory owns whole: replaced, never merged. */
   owned?: string[];
+  /**
+   * Arrays whose entries are shared by a stable identifier. Toolfactory replaces only entries it
+   * previously wrote, preserves the author's other entries, and rejects an id collision.
+   */
+  keyedArrays?: Record<string, string>;
 }
 
 export type PlannedFile = FullFile | RegionFile | MergeFile;

package/src/project/apply.test.ts

@@ -279,9 +279,129 @@ describe("apply / check — merge files", () => {
     expect(text).toContain('dependencies = [ "zod" ]');
     expect(check(root, plan, "0.1.0")).toEqual([]);
   });
+
+  it("merges YAML and keeps authored keyed-array entries while removing stale generated ones", () => {
+    const root = tmp();
+    const plan = (commands: string[]): MergeFile[] => [
+      {
+        kind: "merge",
+        path: "extension.yaml",
+        format: "yaml",
+        patch: {
+          name: "hello",
+          commands: commands.map((command) => ({ command, title: command })),
+        },
+        keyedArrays: { commands: "command" },
+      },
+    ];
+    apply(root, plan(["hello.run", "hello.old"]), "0.1.0");
+    writeFileSync(
+      join(root, "extension.yaml"),
+      `${readFileSync(join(root, "extension.yaml"), "utf8")}commands:\n  - command: author.run\n    title: Author\n  - command: hello.run\n    title: hello.run\n  - command: hello.old\n    title: hello.old\n`,
+    );
+    // Recreate the document with a custom entry and the generated entries, as a hand-built host
+    // manifest would; the generated ids remain Toolfactory-owned from the lock.
+    writeFileSync(
+      join(root, "extension.yaml"),
+      "name: hello\ncommands:\n  - command: author.run\n    title: Author\n  - command: hello.run\n    title: hello.run\n  - command: hello.old\n    title: hello.old\n",
+    );
+    apply(root, plan(["hello.run", "hello.new"]), "0.1.0");
+    const text = readFileSync(join(root, "extension.yaml"), "utf8");
+    expect(text).toContain("author.run");
+    expect(text).toContain("hello.new");
+    expect(text).not.toContain("hello.old");
+    expect(check(root, plan(["hello.run", "hello.new"]), "0.1.0")).toEqual([]);
+    expect(() => apply(root, plan(["author.run"]), "0.1.0")).toThrow(/already has author entry/);
+  });
+
+  it("preserves unknown keyed-entry fields while removing stale projected leaves", () => {
+    const root = tmp();
+    const plan = (title: string, category?: string): MergeFile[] => [
+      {
+        kind: "merge",
+        path: "package.json",
+        format: "json",
+        patch: {
+          contributes: {
+            commands: [{ command: "hello.run", title, ...(category ? { category } : {}) }],
+          },
+        },
+        keyedArrays: { "contributes.commands": "command" },
+      },
+    ];
+    apply(root, plan("Run", "Toolfactory"), "0.1.0");
+    const path = join(root, "package.json");
+    const document = JSON.parse(readFileSync(path, "utf8"));
+    document.contributes.commands[0].icon = "$(rocket)";
+    writeFileSync(path, JSON.stringify(document));
+    // Native command details remain authored: they are not drift merely because Toolfactory
+    // owns the command's id and projected leaves.
+    expect(check(root, plan("Run", "Toolfactory"), "0.1.0")).toEqual([]);
+    apply(root, plan("Run tool"), "0.1.0");
+    expect(JSON.parse(readFileSync(path, "utf8")).contributes.commands).toEqual([
+      { command: "hello.run", title: "Run tool", icon: "$(rocket)" },
+    ]);
+    expect(check(root, plan("Run tool"), "0.1.0")).toEqual([]);
+  });
+
+  it("upgrades an untouched generated full file to a region but protects changed files", () => {
+    const root = tmp();
+    const old: PlannedFile[] = [{ kind: "file", path: "entry.ts", content: "old generated\n" }];
+    const region: RegionFile = {
+      kind: "region",
+      path: "entry.ts",
+      regions: [{ begin: "// tf:entry", end: "// /tf:entry", content: "new generated\n" }],
+      template: "// tf:entry\n// /tf:entry\n\n// author tail\n",
+    };
+    apply(root, old, "0.1.0");
+    apply(root, [region], "0.2.0");
+    expect(readFileSync(join(root, "entry.ts"), "utf8")).toContain("new generated");
+
+    const changed = tmp();
+    apply(changed, old, "0.1.0");
+    writeFileSync(join(changed, "entry.ts"), "author changed\n");
+    expect(() => apply(changed, [region], "0.2.0")).toThrow(/missing a toolfactory region marker/);
+  });
 });
 
 describe("apply / check — inverses and outputs", () => {
+  it("restores deleted keyed rows, leaves steady YAML bytes alone, and uninstalls keys and rows", () => {
+    const root = tmp();
+    const plan: MergeFile[] = [
+      {
+        kind: "merge",
+        path: "extension.yaml",
+        format: "yaml",
+        patch: {
+          generated: true,
+          commands: [{ command: "hello.run", title: "Run" }],
+        },
+        keyedArrays: { commands: "command" },
+      },
+    ];
+    apply(root, plan, "0.1.0");
+    writeFileSync(
+      join(root, "extension.yaml"),
+      "# author comment\nauthor: true\ngenerated: true\ncommands:\n  - command: author.run\n    title: Author\n",
+    );
+
+    // The prior lock owns hello.run, so removing it by hand does not turn it into an omission.
+    apply(root, plan, "0.1.0");
+    expect(readFileSync(join(root, "extension.yaml"), "utf8")).toContain("hello.run");
+
+    // Once current, no rewrite means YAML comments and formatting survive a rebuild.
+    const path = join(root, "extension.yaml");
+    writeFileSync(path, `# preserved comment\n${readFileSync(path, "utf8")}`);
+    const before = readFileSync(path, "utf8");
+    expect(apply(root, plan, "0.1.0").unchanged).toContain("extension.yaml");
+    expect(readFileSync(path, "utf8")).toBe(before);
+
+    apply(root, [], "0.1.0");
+    expect(readFileSync(path, "utf8")).toContain("author.run");
+    expect(readFileSync(path, "utf8")).not.toContain("hello.run");
+    expect(readFileSync(path, "utf8")).not.toContain("generated:");
+  });
+
   it("uninstalls the keys a patch stops writing, keeping every other key", () => {
     const root = tmp();
     mkdirSync(root, { recursive: true });

package/src/project/apply.ts

@@ -17,6 +17,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import type { MergeFile, PlannedFile, Region } from "../model.js";
 import { LOCK_PATH, type Lock, type Markers, readLock, serializeLock, sha256 } from "./lock.js";
 
@@ -114,17 +115,211 @@ export function pickPatch(
   return out;
 }
 
+function valueAt(document: Record<string, unknown>, path: string): unknown {
+  return path
+    .split(".")
+    .reduce<unknown>((value, part) => (isRecord(value) ? value[part] : undefined), document);
+}
+
+function setAt(document: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split(".");
+  let target = document;
+  for (const part of parts.slice(0, -1)) {
+    const next = target[part];
+    if (isRecord(next)) target = next;
+    else {
+      const created: Record<string, unknown> = {};
+      target[part] = created;
+      target = created;
+    }
+  }
+  target[parts.at(-1) as string] = value;
+}
+
+function omitKeyedArrays(
+  patch: Record<string, unknown>,
+  keyedArrays: Record<string, string>,
+  prefix = "",
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(patch)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (path in keyedArrays) continue;
+    out[key] = isRecord(value) ? omitKeyedArrays(value, keyedArrays, path) : value;
+  }
+  return out;
+}
+
+function keyedArrayEntries(value: unknown, id: string, path: string): Record<string, unknown>[] {
+  if (
+    !Array.isArray(value) ||
+    value.some((entry) => !isRecord(entry) || typeof entry[id] !== "string")
+  ) {
+    throw new Error(`${path} must be an array of objects with a string ${id} field.`);
+  }
+  return value as Record<string, unknown>[];
+}
+
+function keyedArrayState(
+  file: MergeFile,
+):
+  | Record<
+      string,
+      { id: string; values: string[]; entries: Record<string, Record<string, unknown>> }
+    >
+  | undefined {
+  if (!file.keyedArrays || Object.keys(file.keyedArrays).length === 0) return undefined;
+  return Object.fromEntries(
+    Object.entries(file.keyedArrays).map(([path, id]) => [
+      path,
+      {
+        id,
+        values: keyedArrayEntries(valueAt(file.patch, path), id, path).map(
+          (entry) => entry[id] as string,
+        ),
+        entries: Object.fromEntries(
+          keyedArrayEntries(valueAt(file.patch, path), id, path).map((entry) => [
+            entry[id] as string,
+            entry,
+          ]),
+        ),
+      },
+    ]),
+  );
+}
+
+function removeProjectedLeaves(
+  entry: Record<string, unknown>,
+  previous: Record<string, unknown>,
+  next: Record<string, unknown>,
+): Record<string, unknown> {
+  const out = { ...entry };
+  for (const [key, oldValue] of Object.entries(previous)) {
+    if (!(key in next)) delete out[key];
+    else if (isRecord(oldValue) && isRecord(next[key]) && isRecord(out[key]))
+      out[key] = removeProjectedLeaves(
+        out[key] as Record<string, unknown>,
+        oldValue,
+        next[key] as Record<string, unknown>,
+      );
+  }
+  return out;
+}
+
+function mergeKeyedArrays(
+  document: Record<string, unknown>,
+  file: MergeFile,
+  previous: Lock,
+): boolean {
+  let changed = false;
+  for (const [path, id] of Object.entries(file.keyedArrays ?? {})) {
+    const desired = keyedArrayEntries(valueAt(file.patch, path), id, path);
+    const previousIds = new Set(previous.files[file.path]?.keyedArrays?.[path]?.values ?? []);
+    const current = valueAt(document, path);
+    const entries = current === undefined ? [] : keyedArrayEntries(current, id, path);
+    const desiredById = new Map(desired.map((entry) => [entry[id] as string, entry]));
+    const retained: Record<string, unknown>[] = [];
+    const generated: Record<string, unknown>[] = [];
+    for (const entry of entries) {
+      const key = entry[id] as string;
+      const replacement = desiredById.get(key);
+      if (previousIds.has(key)) {
+        if (replacement) {
+          const previousEntry = previous.files[file.path]?.keyedArrays?.[path]?.entries?.[key];
+          generated.push(
+            deepMerge(
+              previousEntry ? removeProjectedLeaves(entry, previousEntry, replacement) : entry,
+              replacement,
+            ),
+          );
+        }
+        continue;
+      }
+      // Migration from a formerly whole generated file: an identical entry is ours already.
+      if (replacement && JSON.stringify(entry) === JSON.stringify(replacement)) {
+        generated.push(entry);
+        continue;
+      }
+      if (replacement)
+        throw new Error(`${file.path} ${path} already has author entry ${id}=${key}.`);
+      retained.push(entry);
+    }
+    const next = [
+      ...retained,
+      ...generated,
+      // A generated row may have been deleted by hand. It remains owned, so put its desired
+      // replacement back even when the previous lock knows its id already.
+      ...desired.filter((entry) => !generated.some((current) => current[id] === entry[id])),
+    ];
+    if (JSON.stringify(entries) !== JSON.stringify(next)) changed = true;
+    setAt(document, path, next);
+  }
+  return changed;
+}
+
+/** Select only generated leaves from an entry, leaving authored extension fields out of drift. */
+function pickProjectedEntry(
+  current: Record<string, unknown> | undefined,
+  projected: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  if (!current) return undefined;
+  const picked: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(projected)) {
+    const actual = current[key];
+    picked[key] = isRecord(value) && isRecord(actual) ? pickProjectedEntry(actual, value) : actual;
+  }
+  return picked;
+}
+
+function removeKeyedArrayEntries(
+  document: Record<string, unknown>,
+  keyedArrays: Record<string, { id: string; values: string[] }> | undefined,
+): boolean {
+  let changed = false;
+  for (const [path, state] of Object.entries(keyedArrays ?? {})) {
+    const current = valueAt(document, path);
+    if (!Array.isArray(current)) continue;
+    const next = current.filter(
+      (entry) => !isRecord(entry) || !state.values.includes(entry[state.id] as string),
+    );
+    if (next.length !== current.length) {
+      setAt(document, path, next);
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function pickMerge(document: Record<string, unknown>, file: MergeFile): Record<string, unknown> {
+  const picked = pickPatch(document, file.patch, file.owned);
+  for (const [path, id] of Object.entries(file.keyedArrays ?? {})) {
+    const desired = keyedArrayEntries(valueAt(file.patch, path), id, path);
+    const current = Array.isArray(valueAt(document, path))
+      ? (valueAt(document, path) as unknown[])
+      : [];
+    const byId = new Map(current.filter(isRecord).map((entry) => [entry[id] as string, entry]));
+    setAt(
+      picked,
+      path,
+      desired.map((entry) => pickProjectedEntry(byId.get(entry[id] as string), entry)),
+    );
+  }
+  return picked;
+}
+
 /** The dotted paths a patch writes: one per leaf value, and one per object it owns whole. */
 export function patchKeys(
   patch: Record<string, unknown>,
   owned: string[] = [],
+  keyedArrays: Record<string, string> = {},
   prefix = "",
 ): string[] {
   const keys: string[] = [];
   for (const [key, value] of Object.entries(patch)) {
     const path = prefix ? `${prefix}.${key}` : key;
+    if (path in keyedArrays) continue;
     if (isRecord(value) && !owned.includes(path) && Object.keys(value).length > 0) {
-      keys.push(...patchKeys(value, owned, path));
+      keys.push(...patchKeys(value, owned, keyedArrays, path));
     } else {
       keys.push(path);
     }
@@ -167,13 +362,15 @@ export function removeKeys(document: Record<string, unknown>, keys: readonly str
 }
 
 function parseDocument(text: string, format: MergeFile["format"]): Record<string, unknown> {
-  return (format === "toml" ? parseToml(text) : JSON.parse(text)) as Record<string, unknown>;
+  return (
+    format === "toml" ? parseToml(text) : format === "yaml" ? parseYaml(text) : JSON.parse(text)
+  ) as Record<string, unknown>;
 }
 
 function serializeDocument(document: Record<string, unknown>, format: MergeFile["format"]): string {
-  return format === "toml"
-    ? `${stringifyToml(document)}\n`
-    : `${JSON.stringify(document, null, 2)}\n`;
+  if (format === "toml") return `${stringifyToml(document)}\n`;
+  if (format === "yaml") return stringifyYaml(document);
+  return `${JSON.stringify(document, null, 2)}\n`;
 }
 
 /** The content toolfactory manages, as one string for hashing and comparison. */
@@ -199,12 +396,16 @@ function currentManagedContent(root: string, file: PlannedFile): string | undefi
   const text = readFileSync(path, "utf8");
   if (file.kind === "file") return text;
   if (file.kind === "region") return extractRegions(text, file)?.join(" ");
-  return JSON.stringify(pickPatch(parseDocument(text, file.format), file.patch, file.owned));
+  return JSON.stringify(pickMerge(parseDocument(text, file.format), file));
 }
 
 /** The two structured formats merge files use; the extension is the only discriminator needed. */
 function documentFormat(path: string): MergeFile["format"] {
-  return path.endsWith(".toml") ? "toml" : "json";
+  return path.endsWith(".toml")
+    ? "toml"
+    : path.endsWith(".yaml") || path.endsWith(".yml")
+      ? "yaml"
+      : "json";
 }
 
 /** The keys the lock recorded for a path that the current patch no longer writes. */
@@ -219,6 +420,22 @@ function stranded(root: string, path: string, keys: string[]): boolean {
   return keys.some((key) => hasKey(document, key));
 }
 
+function keyedEntriesRemain(
+  root: string,
+  path: string,
+  keyedArrays: Record<string, { id: string; values: string[] }> | undefined,
+): boolean {
+  if (!keyedArrays || !existsSync(join(root, path))) return false;
+  const document = parseDocument(readFileSync(join(root, path), "utf8"), documentFormat(path));
+  return Object.entries(keyedArrays).some(([arrayPath, state]) => {
+    const current = valueAt(document, arrayPath);
+    return (
+      Array.isArray(current) &&
+      current.some((entry) => isRecord(entry) && state.values.includes(entry[state.id] as string))
+    );
+  });
+}
+
 /** The marker pairs the lock recorded for a path that the current plan no longer writes. */
 function staleRegions(lock: Lock, path: string, current: readonly Markers[] = []): Markers[] {
   return (lock.files[path]?.regions ?? []).filter(
@@ -271,7 +488,12 @@ export function check(root: string, plan: PlannedFile[], toolfactoryVersion: str
     const entry = lock.files[path];
     if (planned.has(path) || entry?.state !== "generated" || !present(root, path)) continue;
     // A merge file toolfactory stops writing loses its keys, not its existence.
-    if (entry.keys && !stranded(root, path, entry.keys)) continue;
+    if (
+      (entry.keys || entry.keyedArrays) &&
+      !stranded(root, path, entry.keys ?? []) &&
+      !keyedEntriesRemain(root, path, entry.keyedArrays)
+    )
+      continue;
     // A region file likewise loses its regions: once they are empty, nothing of ours is stranded.
     if (entry.regions && !filled(root, path, entry.regions)) continue;
     drift.push({ path, kind: "orphan" });
@@ -290,6 +512,12 @@ function render(root: string, file: PlannedFile, previous: Lock): string {
       const stale = staleRegions(previous, file.path, file.regions);
       const replaced = replaceRegions(emptyRegions(text, stale) ?? text, file);
       if (replaced === undefined) {
+        const prior = previous.files[file.path];
+        // A generated full file can become a region file without forcing an author to recreate
+        // markers. Its lock hash proves every byte is still the old generator's, so replacing it
+        // cannot discard authored work. Manual or changed files still require `adopt`.
+        if (prior?.state === "generated" && sha256(text) === prior.sha256)
+          return replaceRegions(file.template, file) ?? file.template;
         throw new Error(
           `${file.path} exists but is missing a toolfactory region marker; restore the markers or run \`toolfactory adopt ${file.path}\`.`,
         );
@@ -298,23 +526,32 @@ function render(root: string, file: PlannedFile, previous: Lock): string {
     }
     return replaceRegions(file.template, file) ?? file.template;
   }
-  if (!existsSync(path)) return serializeDocument(deepMerge({}, file.patch), file.format);
+  if (!existsSync(path)) {
+    const document = deepMerge({}, omitKeyedArrays(file.patch, file.keyedArrays ?? {}), file.owned);
+    mergeKeyedArrays(document, file, previous);
+    return serializeDocument(document, file.format);
+  }
   const text = readFileSync(path, "utf8");
   const document = parseDocument(text, file.format);
   // The patch's inverse first: keys a previous patch wrote and this one dropped are uninstalled.
   const uninstalled = removeKeys(
     document,
-    staleKeys(previous, file.path, patchKeys(file.patch, file.owned)),
+    staleKeys(previous, file.path, patchKeys(file.patch, file.owned, file.keyedArrays)),
   );
+  const arraysChanged = mergeKeyedArrays(document, file, previous);
   // A document that already carries the patch is left byte-for-byte alone, so a rebuild never
   // reserializes the author's file (and, for TOML, never drops their comments).
   if (
     !uninstalled &&
-    JSON.stringify(pickPatch(document, file.patch, file.owned)) === JSON.stringify(file.patch)
+    !arraysChanged &&
+    JSON.stringify(pickMerge(document, file)) === JSON.stringify(file.patch)
   ) {
     return text;
   }
-  return serializeDocument(deepMerge(document, file.patch, file.owned), file.format);
+  return serializeDocument(
+    deepMerge(document, omitKeyedArrays(file.patch, file.keyedArrays ?? {}), file.owned),
+    file.format,
+  );
 }
 
 /** Write a plan to the tree and refresh the lock. */
@@ -336,7 +573,9 @@ export function apply(root: string, plan: PlannedFile[], toolfactoryVersion: str
       result.manual.push(file.path);
       continue;
     }
-    const keys = file.kind === "merge" ? patchKeys(file.patch, file.owned) : undefined;
+    const keys =
+      file.kind === "merge" ? patchKeys(file.patch, file.owned, file.keyedArrays) : undefined;
+    const keyedArrays = file.kind === "merge" ? keyedArrayState(file) : undefined;
     const regions =
       file.kind === "region" ? file.regions.map(({ begin, end }) => ({ begin, end })) : undefined;
     if (isLink(file)) {
@@ -363,6 +602,7 @@ export function apply(root: string, plan: PlannedFile[], toolfactoryVersion: str
       sha256: sha256(managedContent(file)),
       state: "generated",
       keys,
+      keyedArrays,
       regions,
     };
   }
@@ -373,11 +613,13 @@ export function apply(root: string, plan: PlannedFile[], toolfactoryVersion: str
       continue;
     }
     if (!present(root, path)) continue;
-    if (entry.keys) {
+    if (entry.keys || entry.keyedArrays) {
       // The inverse of a merge file is its keys: the author keeps the file and everything else in it.
       const format = documentFormat(path);
       const document = parseDocument(readFileSync(join(root, path), "utf8"), format);
-      if (removeKeys(document, entry.keys)) {
+      const removedKeys = removeKeys(document, entry.keys ?? []);
+      const removedEntries = removeKeyedArrayEntries(document, entry.keyedArrays);
+      if (removedKeys || removedEntries) {
         writeFileSync(join(root, path), serializeDocument(document, format));
         result.written.push(path);
       }