@metaobjectsdev/codegen-ts 0.7.0-rc.9 → 0.8.0-rc.1

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.",
+  };
 }

package/src/render-context.ts

@@ -39,6 +39,8 @@ export interface RenderContext {
   columnNamingStrategy: ColumnNamingStrategy;
   /** Path prefix applied to generated route registrations + hook fetch URLs. Defaults to "". */
   apiPrefix: string;
+  /** Whether abstract entities emit their shape artifact (type-only interface / value-object file). Defaults to true. Instance/write artifacts are never emitted for abstract entities regardless. */
+  emitAbstractShapes: boolean;
   /** Output layout mode: "flat" (default) — all files in outDir; "package" — sub-paths from entity metadata package. */
   outputLayout: OutputLayout;
   /** The target THIS generator emits to (drives path layout + same-target imports). */
@@ -53,11 +55,12 @@ export interface RenderContext {
 }
 
 /** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). */
-export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
+export type RenderContextInput = Omit<RenderContext, "extStyle" | "omImport" | "columnNamingStrategy" | "apiPrefix" | "emitAbstractShapes" | "outputLayout" | "packageOf" | "selfTarget" | "entityModuleTarget"> & {
   extStyle?: ExtStyle;
   omImport?: string;
   columnNamingStrategy?: ColumnNamingStrategy;
   apiPrefix?: string;
+  emitAbstractShapes?: boolean;
   outputLayout?: OutputLayout;
   packageOf?: Map<string, string | undefined>;
   selfTarget?: ResolvedTarget;
@@ -85,6 +88,7 @@ export function makeRenderContext(opts: RenderContextInput): RenderContext {
     omImport: opts.omImport ?? "../index",
     columnNamingStrategy: opts.columnNamingStrategy ?? "snake_case",
     apiPrefix: opts.apiPrefix ?? "",
+    emitAbstractShapes: opts.emitAbstractShapes ?? true,
     outputLayout,
     packageOf: opts.packageOf ?? new Map(),
     selfTarget: defaultTarget,

package/src/render-engine/framework-provider.ts

@@ -0,0 +1,107 @@
+// FrameworkTemplateProvider — resolves template refs (e.g. "docs/entity-page.md")
+// against the codegen-ts package's `templates/` directory. Adopters who want
+// to override a framework template create their own `templates/<ref>.mustache`
+// file in their project; `ProviderChain` (below) consults the project first
+// and falls back to the framework defaults.
+//
+// Decision D1 from the template-driven-codegen design — hybrid: framework
+// ships defaults, adopters override by file-system convention.
+//
+// The framework Provider is filesystem-backed so it works identically whether
+// codegen-ts runs from source (bun, dev) or from `dist/` (npm install). The
+// `templates/` directory is included in the published tarball via
+// package.json `files: ["dist", "src", "templates", ...]`.
+
+import type { Provider } from "@metaobjectsdev/render";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Canonical shipped template — used to verify a candidate framework
+ *  templates directory actually contains our defaults. Without this check a
+ *  hoisted-install layout (pnpm/bun workspaces) can walk up to a CONSUMER
+ *  package.json and silently return a templates dir that doesn't exist. */
+const CANONICAL_TEMPLATE_REL = "docs/entity-page.md.mustache";
+
+/** Walk up from `start` until we find a `package.json` whose neighbour
+ *  `templates/` directory contains our canonical shipped template (i.e., the
+ *  codegen-ts package root). Works the same way from
+ *  `src/render-engine/framework-provider.ts` (during dev) and
+ *  `dist/render-engine/framework-provider.js` (after `npm install`). */
+function findFrameworkTemplatesDir(start: string): string {
+  let dir = start;
+  while (true) {
+    const pkgJson = join(dir, "package.json");
+    if (existsSync(pkgJson)) {
+      const templatesDir = join(dir, "templates");
+      // Assert we landed at the codegen-ts package root, not a consumer's.
+      if (existsSync(join(templatesDir, CANONICAL_TEMPLATE_REL))) {
+        return templatesDir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `framework templates dir unresolved: walked up from ${start} without finding a package.json ` +
+    `whose templates/${CANONICAL_TEMPLATE_REL} exists. This usually means codegen-ts was installed ` +
+    `via a hoisted layout (pnpm/bun workspaces) into an unexpected location, or the published ` +
+    `tarball is missing the templates/ directory.`,
+  );
+}
+
+// In ESM (CLAUDE.md: "ESM only. No CommonJS."), `import.meta.url` is
+// guaranteed to be a file: URL; no defensive try/catch needed.
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
+
+const FRAMEWORK_TEMPLATES_DIR = findFrameworkTemplatesDir(SELF_DIR);
+
+/** Provider backed by an arbitrary on-disk template directory. References
+ *  resolve as `<dir>/<ref>.mustache`. Used by both the framework default
+ *  and adopter override paths. */
+export class FileSystemProvider implements Provider {
+  constructor(private readonly root: string) {}
+  resolve(ref: string): string | undefined {
+    const path = join(this.root, `${ref}.mustache`);
+    if (!existsSync(path)) return undefined;
+    return readFileSync(path, "utf-8");
+  }
+}
+
+/** The framework defaults provider — resolves refs against codegen-ts's own
+ *  `templates/` directory. */
+export const frameworkTemplatesProvider: Provider = new FileSystemProvider(
+  FRAMEWORK_TEMPLATES_DIR,
+);
+
+/** Compose providers: first match wins. Adopters typically chain
+ *  `[projectProvider, frameworkTemplatesProvider]` so their own templates
+ *  override the framework defaults. */
+export class ProviderChain implements Provider {
+  constructor(private readonly providers: readonly Provider[]) {}
+  resolve(ref: string): string | undefined {
+    for (const p of this.providers) {
+      const text = p.resolve(ref);
+      if (text !== undefined) return text;
+    }
+    return undefined;
+  }
+}
+
+/** Build a project-scoped Provider: layers an optional project `templates/`
+ *  directory over the framework defaults. Returns just the framework provider
+ *  when `projectRoot` is undefined / its `templates/` dir doesn't exist. */
+export function projectProvider(projectRoot?: string): Provider {
+  if (projectRoot === undefined) return frameworkTemplatesProvider;
+  const projTemplates = resolve(projectRoot, "templates");
+  if (!existsSync(projTemplates)) return frameworkTemplatesProvider;
+  return new ProviderChain([
+    new FileSystemProvider(projTemplates),
+    frameworkTemplatesProvider,
+  ]);
+}
+
+/** Exposed for tests that want to inspect / clear the resolved framework
+ *  templates directory (don't use outside tests). */
+export const __frameworkTemplatesDirForTests = FRAMEWORK_TEMPLATES_DIR;

package/src/runner.ts

@@ -1,4 +1,5 @@
-import { join } from "node:path";
+import { join, relative, resolve, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
 import type { MetaData, MetaObject } from "@metaobjectsdev/metadata";
 import { MetaRoot } from "@metaobjectsdev/metadata";
 import type { Generator, GenContext, EmittedFile } from "./generator.js";
@@ -8,7 +9,12 @@ import type { ResolvedTarget } from "./import-path.js";
 import { buildPkMap } from "./pk-resolver.js";
 import { buildRelationMap } from "./relation-resolver.js";
 import { makeRenderContext } from "./render-context.js";
-import { decideAndWrite, type WriteResult, type MergeStrategy } from "./overwrite-policy.js";
+import {
+  decideAndWrite,
+  type WriteResult,
+  type MergeStrategy,
+  type BaselineMode,
+} from "./overwrite-policy.js";
 
 /** JS-identifier-shape only. Prevents filesystem traversal when metadata comes
  *  from untrusted sources (e.g. MCP). Mirrors the guard in legacy generate.ts. */
@@ -21,16 +27,48 @@ export interface RunGenOpts {
   entityFilter?: string[];
   /** Overwrite strategy passed to decideAndWrite. Defaults to "overwrite". */
   mergeStrategy?: MergeStrategy;
+  /** Project root (used to derive the .gen-state/ snapshot directory and to
+   *  key snapshots by project-relative output path). When omitted, falls back
+   *  to process.cwd(). */
+  projectRoot?: string;
+  /** Override the snapshot directory location. Defaults to
+   *  `<projectRoot>/.metaobjects/.gen-state/`. */
+  genStateDir?: string;
+  /** First-time-on-existing-file behavior. Defaults to "default" (write-if-
+   *  different). "fresh" → overwrite and re-baseline (the `--baseline=fresh`
+   *  CLI flag). */
+  baseline?: BaselineMode;
 }
 
 export interface RunGenResult {
   files: WriteResult[];
   warnings: string[];
+  /** Subset of `files` with status "conflict" — surfaced separately so the
+   *  CLI can print the end-of-run summary. */
+  conflicts: WriteResult[];
 }
 
 export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
   const warnings: string[] = [];
   const strategy = opts.mergeStrategy ?? "overwrite";
+  const baseline = opts.baseline ?? "default";
+  // When projectRoot is not supplied we DON'T fall back to process.cwd() —
+  // that would leak .gen-state/ into whatever directory happens to be cwd
+  // (e.g. the package dir during a unit-test run). Instead, fall back to a
+  // process-isolated tmpdir, which gives the new-write semantics every call
+  // (the snapshot exists only for the current process). The CLI's
+  // `genCommand` always passes a real projectRoot, so this fallback only
+  // affects programmatic callers (tests, library embedding).
+  const projectRoot = opts.projectRoot !== undefined
+    ? (isAbsolute(opts.projectRoot) ? opts.projectRoot : resolve(opts.projectRoot))
+    : undefined;
+  const genStateDir = opts.genStateDir !== undefined
+    ? (isAbsolute(opts.genStateDir)
+        ? opts.genStateDir
+        : resolve(projectRoot ?? process.cwd(), opts.genStateDir))
+    : (projectRoot !== undefined
+        ? join(projectRoot, ".metaobjects", ".gen-state")
+        : join(tmpdir(), `meta-gen-state-${process.pid}`));
 
   // loadMemory now returns MetaRoot; guard here also covers callers that pass a
   // plain MetaData (e.g. test helpers that build trees programmatically).
@@ -50,7 +88,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       ? "no object children match the provided entityFilter"
       : "root has no object children";
     warnings.push(`No entities to generate — ${reason}.`);
-    return { files: [], warnings };
+    return { files: [], warnings, conflicts: [] };
   }
 
   const safeEntities: MetaObject[] = [];
@@ -64,7 +102,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     safeEntities.push(entity);
   }
   if (safeEntities.length === 0) {
-    return { files: [], warnings };
+    return { files: [], warnings, conflicts: [] };
   }
 
   // 2. Resolve targets + entity-module target.
@@ -117,6 +155,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       extStyle: config.extStyle,
       columnNamingStrategy: config.columnNamingStrategy,
       apiPrefix: config.apiPrefix,
+      emitAbstractShapes: config.emitAbstractShapes,
       outputLayout: selfTarget.outputLayout,
       pkMap,
       relationMap,
@@ -136,6 +175,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         outputLayout: selfTarget.outputLayout,
       },
       renderContext,
+      ...(projectRoot !== undefined && { projectRoot }),
       warn: (msg) => warnings.push(`[${generator.name}] ${msg}`),
     };
 
@@ -163,9 +203,29 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
 
   // 5. Write phase.
   const writes: WriteResult[] = [];
+  const conflicts: WriteResult[] = [];
   for (const file of emitted) {
-    const result = decideAndWrite(file.fullPath, file.content, strategy);
+    // Key the snapshot by project-relative path so multi-target projects keep
+    // distinct entries (e.g. `database/Post.ts` vs `web/Post.queries.ts`).
+    // Without an explicit projectRoot we let decideAndWrite derive a stable
+    // hash-of-path key — fine for ephemeral test runs.
+    const policyOpts: import("./overwrite-policy.js").DecideAndWriteOpts = {
+      strategy,
+      genStateDir,
+      baseline,
+    };
+    if (projectRoot !== undefined) {
+      policyOpts.outputRelPath = relative(projectRoot, file.fullPath);
+    }
+    const result = decideAndWrite(file.fullPath, file.content, policyOpts);
     writes.push(result);
+    if (result.status === "conflict") {
+      conflicts.push(result);
+      warnings.push(
+        `Merge conflict in ${file.fullPath}: resolve diff3 markers and re-run ` +
+        `'meta gen' to advance the canonical state.`,
+      );
+    }
     if (result.status === "refused") {
       warnings.push(
         `Refused to overwrite ${file.fullPath}: file exists without @generated header. ` +
@@ -174,5 +234,5 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     }
   }
 
-  return { files: writes, warnings };
+  return { files: writes, warnings, conflicts };
 }