@metaobjectsdev/codegen-ts 0.7.0-rc.8 → 0.7.0

package/src/generators/docs-file.ts

@@ -0,0 +1,87 @@
+// docsFile() — emits `<Entity>.md` next to each generated entity module.
+//
+// rc.12+: structured around a shared Mustache template at
+// `templates/docs/entity-page.md.mustache` + a data builder at
+// `docs-data-builder.ts`. Adopters can override the framework template by
+// dropping their own `templates/docs/entity-page.md.mustache` into the
+// project root (resolved via the project-then-framework provider chain).
+//
+// docsFile() calls `render()` directly rather than wrapping
+// `templateGenerator()` because the per-entity output path depends on
+// `GenContext.config.outputLayout`, which the generic templateGenerator
+// `walk(root)` signature doesn't expose. Other future docs-style adopters
+// with ctx-free walks (single-file aggregators, etc.) compose
+// `templateGenerator()` directly.
+//
+// The conformance fixture (`fixtures/conformance/docs-file-basic`) gates
+// byte-identity — the codegen output must match the hand-coded rc.11
+// byte-for-byte. If you're hacking on this and the conformance test
+// breaks, the refactor is the bug, not the fixture.
+
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { render } from "@metaobjectsdev/render";
+import type { Generator, GeneratorFactory } from "../generator.js";
+import { entityOutputPath } from "../import-path.js";
+import { projectProvider } from "../render-engine/framework-provider.js";
+import { buildEntityDocData } from "./docs-data-builder.js";
+
+export interface DocsFileOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/** The names of the generators that may emit sibling files for an entity.
+ *  We always list them in the "Generated code" section — adopters cross-
+ *  reference their own metaobjects.config.ts to confirm which are wired in.
+ *  Matches the rc.11 behavior. */
+const KNOWN_SIBLING_GENERATORS = new Set([
+  "queries-file",
+  "routes-file",
+  "routes-file-hono",
+]);
+
+const TEMPLATE_REF = "docs/entity-page.md";
+
+export const docsFile = function docsFile(opts?: DocsFileOpts): Generator {
+  const generator: Generator = {
+    name: "docs-file",
+    async generate(ctx) {
+      if (!ctx.renderContext) {
+        throw new Error("docs-file: renderContext is required (provided by runGen)");
+      }
+      const rc = ctx.renderContext;
+      const provider = projectProvider(ctx.projectRoot ?? process.cwd());
+      const layout = ctx.config.outputLayout ?? "flat";
+      return ctx.loadedRoot.objects().filter(ctx.matches).map((entity: MetaObject) => {
+        const path = entityOutputPath(layout, entity.package, `${entity.name}.md`);
+        const payload = buildEntityDocData(entity, {
+          dialect: rc.dialect,
+          ...(rc.columnNamingStrategy !== undefined && {
+            columnNamingStrategy: rc.columnNamingStrategy,
+          }),
+          loadedRoot: rc.loadedRoot,
+          generatorNames: KNOWN_SIBLING_GENERATORS,
+        });
+        let content: string;
+        try {
+          content = render({
+            ref: TEMPLATE_REF,
+            payload,
+            provider,
+            format: "markdown",
+          });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new Error(
+            `docs-file: failed rendering '${TEMPLATE_REF}' for '${path}': ${msg}`,
+            { cause: err instanceof Error ? err : undefined },
+          );
+        }
+        return { path, content };
+      });
+    },
+  };
+  if (opts?.filter) generator.filter = opts.filter;
+  if (opts?.target) generator.target = opts.target;
+  return generator;
+} as GeneratorFactory<DocsFileOpts>;

package/src/generators/index.ts

@@ -1,7 +1,24 @@
 export { entityFile, type EntityFileOpts } from "./entity-file.js";
 export { queriesFile, type QueriesFileOpts } from "./queries-file.js";
 export { routesFile, type RoutesFileOpts } from "./routes-file.js";
+export { routesFileHono, type RoutesFileHonoOpts } from "./routes-file-hono.js";
 export { barrel, type BarrelOpts } from "./barrel.js";
 export { mermaidErDiagram, type MermaidErOptions } from "./mermaid-er.js";
 export { promptRender, type PromptRenderOpts } from "./prompt-render-file.js";
 export { outputParser, type OutputParserOpts } from "./output-parser-file.js";
+export { docsFile, type DocsFileOpts } from "./docs-file.js";
+export {
+  templateGenerator,
+  type TemplateGeneratorOpts,
+  type TemplateWalkResult,
+  type TemplateFormat,
+} from "./template-generator.js";
+export type {
+  EntityDocData,
+  StorageFieldDoc,
+  IdentityDoc,
+  RelationshipDoc,
+  UsedByDoc,
+  GeneratedFileDoc,
+} from "./docs-data.js";
+export { buildEntityDocData } from "./docs-data-builder.js";

package/src/generators/routes-file-hono.ts

@@ -0,0 +1,48 @@
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { perEntity, type Generator, type GeneratorFactory } from "../generator.js";
+import { renderRoutesFileHono } from "../templates/routes-file-hono.js";
+import { formatTs } from "../format.js";
+import { entityOutputPath } from "../import-path.js";
+
+export interface RoutesFileHonoOpts {
+  filter?: (entity: MetaObject) => boolean;
+  target?: string;
+}
+
+/**
+ * Hono variant of routesFile() — emits `<Entity>.routes.hono.ts` mounting
+ * the same five CRUD verbs (GET list / GET :id / POST / PATCH+PUT / DELETE)
+ * against `@metaobjectsdev/runtime-ts/hono` rather than `…/drizzle-fastify`.
+ *
+ * Same cross-port wire contract (envelope shape, status codes, filter +
+ * sort + withCount semantics) as the Fastify flavor. Workers / Bun / Node
+ * consumers running Hono can replace hand-written route registration with
+ * this generator output one entity at a time.
+ *
+ * Per-entity opt-out via `@emitRoutes: false` is honored. If the user
+ * supplies their own filter, both must pass (AND).
+ */
+export const routesFileHono = function routesFileHono(opts?: RoutesFileHonoOpts): Generator {
+  const userFilter = opts?.filter ?? (() => true);
+  const generator: Generator = {
+    name: "routes-file-hono",
+    filter: (e: MetaObject) => e.ownAttr("emitRoutes") !== false && userFilter(e),
+    generate: perEntity(async (entity, ctx) => {
+      if (!ctx.renderContext) {
+        throw new Error("routes-file-hono: renderContext is required (provided by runGen)");
+      }
+      return {
+        path: entityOutputPath(
+          ctx.config.outputLayout ?? "flat",
+          entity.package,
+          `${entity.name}.routes.hono.ts`,
+        ),
+        content: await formatTs(renderRoutesFileHono(entity, ctx.renderContext)),
+      };
+    }),
+  };
+  if (opts?.target) {
+    generator.target = opts.target;
+  }
+  return generator;
+} as GeneratorFactory<RoutesFileHonoOpts>;

package/src/generators/template-generator.ts

@@ -0,0 +1,106 @@
+// templateGenerator() — the missing primitive identified by the
+// template-driven-codegen design (2026-05-28). Walks the loaded MetaRoot
+// → renders shared Mustache templates via @metaobjectsdev/render → emits
+// EmittedFile[]. Same Generator interface as the per-port hand-coded
+// generators; just adds the "Mustache template" + "walk that yields a
+// data dict per output" primitives.
+//
+// Design line we adopted (from the design doc):
+//   Code → hand-coded generators (ts-poet, idiomatic per-port).
+//   Documents → templateGenerator (shared Mustache templates).
+//
+// docsFile() is the first templateGenerator instance (rc.12). OpenAPI specs,
+// Mermaid diagrams, HTML doc sites, etc. follow as templates + a walk
+// function each.
+
+import type { MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import { render, type Provider, type RenderFormat } from "@metaobjectsdev/render";
+import type { Generator, GenContext, EmittedFile, GeneratorFactory } from "../generator.js";
+import { projectProvider } from "../render-engine/framework-provider.js";
+
+export type TemplateFormat = RenderFormat;
+
+export interface TemplateWalkResult {
+  /** The data dict to render against. Templates reference its keys; the
+   *  shape is the public-API contract template authors consume. */
+  data: object;
+  /** Output path RELATIVE to the generator's target outDir. */
+  outputPath: string;
+}
+
+export interface TemplateGeneratorOpts {
+  /** kebab-case identifier; surfaces in diagnostics and the overwrite-policy
+   *  per-file snapshot key. */
+  name: string;
+  /** Walk the loaded metadata tree and produce `{ data, outputPath }` tuples
+   *  — one per emitted file. Pattern A (per-entity), pattern B (single
+   *  aggregator), pattern C (mixed), pattern D (filter inline) all fit. */
+  walk: (root: MetaRoot) => TemplateWalkResult[] | Promise<TemplateWalkResult[]>;
+  /** Template reference. Resolved by the configured Provider chain — by
+   *  default the project's `templates/<ref>.mustache` first, then the
+   *  framework defaults at `codegen-ts/templates/<ref>.mustache`. */
+  template: string;
+  /** Drives the render engine's escaper. Defaults to "text". */
+  format?: TemplateFormat;
+  /** Optional per-entity filter for adopters who want to scope a generator
+   *  via the standard `Generator.filter` plumbing. Not consulted by the
+   *  default `walk` — adopters apply filters inside their walk function. */
+  filter?: (entity: MetaObject) => boolean;
+  /** Override the Provider used for template resolution. When omitted the
+   *  generator resolves via `projectProvider(ctx.projectRoot)`, which layers
+   *  the project's `templates/` over the framework defaults. (The project
+   *  root is the directory holding `.metaobjects/config.json`, threaded
+   *  through `GenContext` by the runner. Adopters needing a different
+   *  lookup chain can pass an explicit provider.) */
+  provider?: Provider;
+  /** Optional named target — same as the other generators. */
+  target?: string;
+}
+
+export const templateGenerator = function templateGenerator(
+  opts: TemplateGeneratorOpts,
+): Generator {
+  const fmt: TemplateFormat = opts.format ?? "text";
+  const generator: Generator = {
+    name: opts.name,
+    async generate(ctx: GenContext): Promise<EmittedFile[]> {
+      let provider: Provider;
+      if (opts.provider !== undefined) {
+        provider = opts.provider;
+      } else if (ctx.projectRoot !== undefined) {
+        provider = projectProvider(ctx.projectRoot);
+      } else {
+        ctx.warn(
+          "templateGenerator: ctx.projectRoot is undefined; falling back to process.cwd() for project-template resolution. " +
+          "Project-scoped template overrides will resolve relative to the current working directory, which is fragile under " +
+          "`meta gen` invoked from a sub-directory. Drive via runGen(opts.projectRoot) to remove this warning.",
+        );
+        provider = projectProvider(process.cwd());
+      }
+      const walkRes = await opts.walk(ctx.loadedRoot);
+      const files: EmittedFile[] = [];
+      for (const { data, outputPath } of walkRes) {
+        let content: string;
+        try {
+          content = render({
+            ref: opts.template,
+            payload: data,
+            provider,
+            format: fmt,
+          });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new Error(
+            `templateGenerator(${opts.name}) failed rendering '${opts.template}' for '${outputPath}': ${msg}`,
+            { cause: err instanceof Error ? err : undefined },
+          );
+        }
+        files.push({ path: outputPath, content });
+      }
+      return files;
+    },
+  };
+  if (opts.filter) generator.filter = opts.filter;
+  if (opts.target) generator.target = opts.target;
+  return generator;
+} as GeneratorFactory<TemplateGeneratorOpts>;

package/src/index.ts

@@ -24,8 +24,14 @@ export { buildRelationMap } from "./relation-resolver.js";
 export type { RenderContext } from "./render-context.js";
 export { makeRenderContext } from "./render-context.js";
 
-export type { WriteStatus, WriteResult, MergeStrategy } from "./overwrite-policy.js";
-export { decideAndWrite } from "./overwrite-policy.js";
+export type {
+  WriteStatus,
+  WriteResult,
+  MergeStrategy,
+  BaselineMode,
+  DecideAndWriteOpts,
+} from "./overwrite-policy.js";
+export { decideAndWrite, GitMissingError } from "./overwrite-policy.js";
 
 export { CodegenError } from "./errors.js";
 export { GENERATED_HEADER, EXTRA_SUFFIX, DEFAULT_OUT_DIR } from "./constants.js";
@@ -45,3 +51,28 @@ export type { EmitOptions as ViewDdlEmitOptions } from "./projection/view-ddl-em
 export type { JoinNode, JoinTree, SelectColumn, SelectSpec, ViewSpec } from "./projection/view-spec.js";
 // Prompt construction (FR-004): typed payload + render-handle codegen.
 export { generatePayloadInterfaces, generatePayloadInterfacesBatch, generateRenderHandle } from "./payload-codegen.js";
+
+// Template-driven codegen (rc.12). Factory + framework Provider for adopters
+// who want to wire their own templateGenerator instances. The default
+// docsFile() uses this internally.
+export {
+  templateGenerator,
+  type TemplateGeneratorOpts,
+  type TemplateWalkResult,
+  type TemplateFormat,
+} from "./generators/template-generator.js";
+export {
+  FileSystemProvider,
+  ProviderChain,
+  frameworkTemplatesProvider,
+  projectProvider,
+} from "./render-engine/framework-provider.js";
+export type {
+  EntityDocData,
+  StorageFieldDoc,
+  IdentityDoc,
+  RelationshipDoc,
+  UsedByDoc,
+  GeneratedFileDoc,
+} from "./generators/docs-data.js";
+export { buildEntityDocData } from "./generators/docs-data-builder.js";

package/src/overwrite-policy.ts

@@ -1,39 +1,350 @@
-// Overwrite policy: drives the per-file write decision based on the @generated header.
-// Per design §8 — read-only generated files; refuse to clobber hand-written code.
+// Overwrite policy: per-file write decision using three-way merge against a
+// canonical snapshot kept under `.metaobjects/.gen-state/`.
+//
+// Replaces the rc.11 marker-based clobber-or-refuse policy (strategy (a) from
+// spike 002) with strategy (b) — git-merge-file-driven three-way merge. The
+// `@generated` marker becomes purely informational (templates may still emit
+// it for human readers); the policy no longer consults it.
+//
+// Per-file flow:
+//
+//   1. Render fresh content to a tmpfile.
+//   2. If the output doesn't exist → write + copy to .gen-state/.
+//   3. If .gen-state/<relPath> exists → run `git merge-file --diff3` against
+//      (current, .gen-state snapshot, fresh tmpfile). Exit 0 → clean merge,
+//      advance .gen-state to fresh content. Exit > 0 → leave conflict markers
+//      in the output file, do NOT advance .gen-state; status "conflict".
+//   4. If .gen-state/<relPath> is absent but the file exists ("first-time
+//      regen on an existing file") → write-if-different against the existing
+//      file as the baseline (no merge, no clobber). The `baseline: "fresh"`
+//      flag opts into "overwrite from fresh and re-baseline".
+//
+// Integrity (caveat 2 from the spike): we keep a sha-256 of each canonical
+// snapshot at `.gen-state/.hashes.json`. On load, mismatch → fall back to
+// first-time semantics and warn naming the file so the user can investigate.
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { GENERATED_HEADER } from "./constants.js";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  copyFileSync,
+} from "node:fs";
+import { dirname, join, isAbsolute, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { createHash, randomBytes } from "node:crypto";
 
-export type WriteStatus = "new" | "overwrite" | "refused" | "skipped";
+export type WriteStatus =
+  | "new"
+  | "unchanged"
+  | "overwrite"
+  | "merged"
+  | "conflict"
+  | "refused"
+  | "skipped";
+
+/**
+ * "overwrite" — default; three-way merge if .gen-state exists, else write-if-
+ *   different / first-time-existing flow.
+ * "skip-existing" — never write over an existing file; status "skipped".
+ *   Useful for `meta gen --dry-run` style flows.
+ */
 export type MergeStrategy = "overwrite" | "skip-existing";
 
+/** "default" — the standard three-way merge flow described in the file header.
+ *  "fresh" — opt-in via `meta gen --baseline=fresh`. When .gen-state is absent
+ *  but the file exists, OVERWRITE with fresh content and seed .gen-state from
+ *  the fresh content (caveat 3 escape hatch). */
+export type BaselineMode = "default" | "fresh";
+
+export interface DecideAndWriteOpts {
+  strategy?: MergeStrategy;
+  /** Absolute path to the .gen-state/ root for this project. When undefined,
+   *  we fall back to a process-isolated tmpdir — fine for tests but the CLI
+   *  always supplies the real project value via runGen(). */
+  genStateDir?: string;
+  /** Path the snapshot is keyed by — usually the path relative to the
+   *  project root, but ANY stable identifier works. When undefined, derived
+   *  from `path` (so unit tests can call without supplying it). */
+  outputRelPath?: string;
+  /** First-time-existing-file behavior. */
+  baseline?: BaselineMode;
+}
+
 export interface WriteResult {
   path: string;
   status: WriteStatus;
+  /** Present when status is "conflict" — human-readable hint identifying the
+   *  file the user must resolve. */
+  conflictHint?: string;
+}
+
+const HASHES_FILE = ".hashes.json";
+
+type HashesFile = Record<string, string>;
+
+function sha256(content: string | Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function loadHashes(genStateDir: string): HashesFile {
+  const f = join(genStateDir, HASHES_FILE);
+  if (!existsSync(f)) return {};
+  try {
+    const txt = readFileSync(f, "utf-8");
+    const parsed: unknown = JSON.parse(txt);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as HashesFile;
+    }
+    return {};
+  } catch {
+    return {};
+  }
 }
 
+function saveHashes(genStateDir: string, hashes: HashesFile): void {
+  mkdirSync(genStateDir, { recursive: true });
+  writeFileSync(join(genStateDir, HASHES_FILE), JSON.stringify(hashes, null, 2) + "\n");
+}
+
+function snapshotPath(genStateDir: string, relPath: string): string {
+  // `.hashes.json` is reserved at the top of .gen-state/; relPath must never
+  // collide with it. Output paths derived from entity names ("Post.ts" etc.)
+  // are JS-identifier-shape so this is a non-issue in practice.
+  return join(genStateDir, relPath);
+}
+
+/** Synchronously copy `src` content into the snapshot at `<genStateDir>/<relPath>`
+ *  and refresh the hash for `relPath`. */
+function advanceSnapshot(
+  genStateDir: string,
+  relPath: string,
+  content: string,
+): void {
+  const dest = snapshotPath(genStateDir, relPath);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, content);
+  const hashes = loadHashes(genStateDir);
+  hashes[relPath] = sha256(content);
+  saveHashes(genStateDir, hashes);
+}
+
+/** Return the snapshot text iff present AND the hash matches; else undefined. */
+function readSnapshotChecked(
+  genStateDir: string,
+  relPath: string,
+): { text: string } | undefined {
+  const path = snapshotPath(genStateDir, relPath);
+  if (!existsSync(path)) return undefined;
+  const text = readFileSync(path, "utf-8");
+  const hashes = loadHashes(genStateDir);
+  const expected = hashes[relPath];
+  if (expected !== undefined && expected !== sha256(text)) {
+    return undefined;
+  }
+  return { text };
+}
+
+/** Thrown when git is unavailable. Surfaces as a clear CLI error rather than
+ *  a generic ENOENT halfway through a regen. */
+export class GitMissingError extends Error {
+  constructor() {
+    super(
+      "meta gen: `git` binary not found on PATH. Three-way-merge regen " +
+        "requires git (any modern version). Install git and re-run.",
+    );
+    this.name = "GitMissingError";
+  }
+}
+
+interface MergeOutcome {
+  /** 0 → clean merge; > 0 → conflicts present (file contains diff3 markers). */
+  exitCode: number;
+  /** stderr text — surfaced on unexpected errors. */
+  stderr: string;
+  /** Resulting file contents on disk after the merge (always read; clean or
+   *  conflicting). */
+  mergedContent: string;
+}
+
+/** Run `git merge-file --diff3 -L<...> <out> <base> <fresh>`. The output is
+ *  written in-place into `outPath`. Returns the exit code (0 = clean, > 0 =
+ *  conflicts) and the resulting file contents.
+ *
+ *  The git binary is "git" by default; set `META_GEN_GIT` in the environment
+ *  to a different path (useful for tests that simulate "git not installed"). */
+function runGitMergeFile(
+  outPath: string,
+  basePath: string,
+  freshPath: string,
+): MergeOutcome {
+  const gitBin = process.env.META_GEN_GIT ?? "git";
+  let res;
+  try {
+    res = spawnSync(
+      gitBin,
+      [
+        "merge-file",
+        "--diff3",
+        "-L",
+        "your edits",
+        "-L",
+        "last generated",
+        "-L",
+        "fresh from meta gen",
+        outPath,
+        basePath,
+        freshPath,
+      ],
+      { encoding: "utf-8" },
+    );
+  } catch (err) {
+    const msg = (err as Error).message ?? "";
+    if (msg.includes("ENOENT")) throw new GitMissingError();
+    throw err;
+  }
+  if (res.error) {
+    const code = (res.error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new GitMissingError();
+    throw res.error;
+  }
+  // `git merge-file` returns the conflict count (0 = clean, > 0 = conflicts,
+  // < 0 = error). Negative is unexpected — surface verbatim.
+  const exitCode = res.status ?? 0;
+  if (exitCode < 0) {
+    throw new Error(
+      `git merge-file failed for ${outPath}: ${res.stderr || res.stdout}`,
+    );
+  }
+  const mergedContent = readFileSync(outPath, "utf-8");
+  return { exitCode, stderr: res.stderr ?? "", mergedContent };
+}
+
+/** Write `content` to a freshly-named tmpfile under the OS tmpdir; return the
+ *  path. Caller is responsible for cleanup (acceptable for codegen — tmpdir
+ *  is process-scoped). */
+function writeTmpfile(content: string): string {
+  const dir = join(tmpdir(), "meta-gen-merge");
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${Date.now()}-${randomBytes(6).toString("hex")}.tmp`);
+  writeFileSync(path, content);
+  return path;
+}
+
+/** Resolve the snapshot key for a given output path. Falls back to a stable
+ *  hash-of-path so unit tests that pass arbitrary tmpdir outputs still get a
+ *  consistent .gen-state key. */
+function defaultOutputRelPath(outputPath: string): string {
+  // Use sha256 of the absolute path → hex; lets tests work without supplying
+  // an explicit relPath. NOT used by the runner — runGen always passes the
+  // real project-relative path.
+  return sha256(resolve(outputPath)).slice(0, 32);
+}
+
+/**
+ * The main entry point. Backward-compatible with the rc.11 signature: passing
+ * a `MergeStrategy` string as the third argument continues to work; passing
+ * an options object opts into three-way merge.
+ */
 export function decideAndWrite(
   path: string,
   content: string,
-  strategy: MergeStrategy = "overwrite",
+  optsOrStrategy: DecideAndWriteOpts | MergeStrategy = {},
 ): WriteResult {
-  // 'skip-existing' only skips overwrites, not new files.
+  const opts: DecideAndWriteOpts =
+    typeof optsOrStrategy === "string"
+      ? { strategy: optsOrStrategy }
+      : optsOrStrategy;
+  const strategy: MergeStrategy = opts.strategy ?? "overwrite";
+  const baseline: BaselineMode = opts.baseline ?? "default";
+  const genStateDir =
+    opts.genStateDir !== undefined
+      ? (isAbsolute(opts.genStateDir)
+          ? opts.genStateDir
+          : resolve(opts.genStateDir))
+      : join(tmpdir(), "meta-gen-state-fallback");
+  const relPath = opts.outputRelPath ?? defaultOutputRelPath(path);
+
+  // 1. First-time write — file doesn't exist.
   if (!existsSync(path)) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, content);
+    advanceSnapshot(genStateDir, relPath, content);
     return { path, status: "new" };
   }
 
+  if (strategy === "skip-existing") {
+    return { path, status: "skipped" };
+  }
+
+  // 2. File exists. Load the canonical snapshot if any.
+  const snapshot = readSnapshotChecked(genStateDir, relPath);
+
+  // 3. First-time regen on a pre-existing file (no snapshot).
+  if (snapshot === undefined) {
+    const current = readFileSync(path, "utf-8");
+
+    if (baseline === "fresh") {
+      // Opt-in escape hatch: overwrite and seed the snapshot from fresh.
+      if (current === content) {
+        advanceSnapshot(genStateDir, relPath, content);
+        return { path, status: "unchanged" };
+      }
+      writeFileSync(path, content);
+      advanceSnapshot(genStateDir, relPath, content);
+      return { path, status: "overwrite" };
+    }
+
+    // Default: write-if-different. The EXISTING file is treated as the
+    // canonical baseline so subsequent runs do real three-way merges. If
+    // fresh output is identical, just seed the snapshot. If different, write
+    // the fresh content + seed snapshot — there's no marker policy left to
+    // refuse on, but this is the contract documented in the runbook (no
+    // marker check; users with hand-written files should never have the
+    // codegen output path colliding with them).
+    if (current === content) {
+      advanceSnapshot(genStateDir, relPath, current);
+      return { path, status: "unchanged" };
+    }
+    writeFileSync(path, content);
+    advanceSnapshot(genStateDir, relPath, content);
+    return { path, status: "overwrite" };
+  }
+
+  // 4. Snapshot exists — real three-way merge.
   const current = readFileSync(path, "utf-8");
-  if (!current.includes(GENERATED_HEADER)) {
-    return { path, status: "refused" };
+
+  // Fast path: nothing changed.
+  if (current === content && snapshot.text === content) {
+    return { path, status: "unchanged" };
   }
 
-  if (strategy === "skip-existing") {
-    return { path, status: "skipped" };
+  const baseTmp = writeTmpfile(snapshot.text);
+  const freshTmp = writeTmpfile(content);
+
+  const outcome = runGitMergeFile(path, baseTmp, freshTmp);
+
+  if (outcome.exitCode === 0) {
+    // Clean merge — advance the canonical snapshot to fresh.
+    advanceSnapshot(genStateDir, relPath, content);
+    // Distinguish "user had no changes vs canonical" from "merge integrated
+    // edits". The fresh equals snapshot case happened above (fast path) — so
+    // if outcome.mergedContent equals fresh we report a plain overwrite,
+    // otherwise it's a merge that pulled in user edits.
+    if (outcome.mergedContent === content) {
+      return { path, status: "overwrite" };
+    }
+    return { path, status: "merged" };
   }
 
-  writeFileSync(path, content);
-  return { path, status: "overwrite" };
+  // Conflict — do NOT advance the snapshot. The output now contains diff3
+  // markers from git merge-file.
+  return {
+    path,
+    status: "conflict",
+    conflictHint:
+      "merge conflict — resolve `<<<<<<<` markers and re-run `meta gen` to " +
+      "advance the canonical state.",
+  };
 }