@specverse/engines 4.1.30 → 4.2.1

package/libs/instance-factories/applications/templates/react-starter/__tests__/orchestrator.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import * as ts from 'typescript';
+import { generate } from '../orchestrator.js';
+import { sha256, HASHES_DIR, HASHES_FILE } from '../regen-safety.js';
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), 'react-starter-orch-'));
+  // Suppress the orchestrator's console.log summary during tests.
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+function makeSpec() {
+  return {
+    metadata: { name: 'My App' },
+    models: {
+      Post: {
+        name: 'Post',
+        attributes: {
+          id: { type: 'UUID', auto: 'uuid4' },
+          title: { type: 'String', required: true },
+          body: { type: 'Text' },
+        },
+      },
+    },
+    views: {},
+  };
+}
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const msg = errors.map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n')).join('\n');
+    throw new Error(`${label} failed to parse:\n${msg}`);
+  }
+}
+
+/**
+ * Drive the orchestrator with the per-test tmp dir as the effective
+ * frontend root. `frontendDir='.'` collapses the
+ * `${outputDir}/${frontendDir}` join so files land directly under
+ * `projectRoot`, which keeps test assertions terse.
+ */
+async function runGenerate(spec = makeSpec()) {
+  return generate({ spec, outputDir: projectRoot, frontendDir: '.' });
+}
+
+/** List every file the orchestrator wrote under projectRoot. */
+function walk(dir: string, prefix = ''): string[] {
+  const { readdirSync, statSync } = require('fs');
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    const rel = prefix ? `${prefix}/${entry}` : entry;
+    if (statSync(abs).isDirectory()) out.push(...walk(abs, rel));
+    else out.push(rel);
+  }
+  return out.sort();
+}
+
+describe('orchestrator — first-run (empty project)', () => {
+  it('writes the full set of files: views + helpers + App.tsx + package.json + hash manifest', async () => {
+    const ret = await runGenerate();
+    // Contract: returns '' (realize's single-file writeOutput skips it).
+    expect(ret).toBe('');
+
+    const written = walk(projectRoot);
+    expect(written).toEqual([
+      `${HASHES_DIR}/${HASHES_FILE}`,
+      'package.json',
+      'src/App.tsx',
+      'src/lib/entity-display.ts',
+      'src/views/PostDashboardView.tsx',
+      'src/views/PostDetailView.tsx',
+      'src/views/PostFormView.tsx',
+      'src/views/PostListView.tsx',
+    ]);
+  });
+
+  it('every emitted .tsx parses as valid TSX', async () => {
+    await runGenerate();
+    for (const path of walk(projectRoot)) {
+      if (path.endsWith('.tsx')) {
+        const source = readFileSync(join(projectRoot, path), 'utf8');
+        assertValidTsx(source, path);
+      }
+    }
+  });
+
+  it('package.json has no @specverse/runtime dependency', async () => {
+    await runGenerate();
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    expect(deps['@specverse/runtime']).toBeUndefined();
+  });
+
+  it('the emitted hash manifest records every approved file', async () => {
+    await runGenerate();
+    const manifestPath = join(projectRoot, HASHES_DIR, HASHES_FILE);
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    for (const path of walk(projectRoot)) {
+      if (path === `${HASHES_DIR}/${HASHES_FILE}`) continue;
+      const content = readFileSync(join(projectRoot, path), 'utf8');
+      expect(manifest[path]).toBe(sha256(content));
+    }
+  });
+});
+
+describe('orchestrator — regeneration safety', () => {
+  it('re-approves pristine files on a second run', async () => {
+    await runGenerate();
+
+    // Record the first-run hash of one of the view files.
+    const listPath = 'src/views/PostListView.tsx';
+    const listAbs = join(projectRoot, listPath);
+    const firstContent = readFileSync(listAbs, 'utf8');
+
+    // Second run. Pristine files should be rewritten (the orchestrator
+    // writes them, possibly with identical bytes).
+    await runGenerate();
+    expect(existsSync(listAbs)).toBe(true);
+    expect(readFileSync(listAbs, 'utf8')).toBe(firstContent);
+  });
+
+  it('preserves a user-edited file across regeneration', async () => {
+    await runGenerate();
+
+    const editedPath = 'src/views/PostListView.tsx';
+    const editedAbs = join(projectRoot, editedPath);
+    const userEdit = '/* user edit */';
+    writeFileSync(editedAbs, userEdit, 'utf8');
+
+    await runGenerate();
+
+    // File on disk is unchanged — user edit survived.
+    expect(readFileSync(editedAbs, 'utf8')).toBe(userEdit);
+    // Manifest still records the ORIGINAL (pre-edit) hash so a future
+    // un-edit can re-sync cleanly.
+    const manifest = JSON.parse(
+      readFileSync(join(projectRoot, HASHES_DIR, HASHES_FILE), 'utf8')
+    );
+    expect(manifest[editedPath]).toBeDefined();
+    expect(manifest[editedPath]).not.toBe(sha256(userEdit));
+  });
+
+  it('is cautious when the user deletes the hash manifest', async () => {
+    await runGenerate();
+
+    // User deletes the hash manifest but keeps the view files.
+    rmSync(join(projectRoot, HASHES_DIR), { recursive: true, force: true });
+
+    // Record the existing file contents (may be identical to what the
+    // orchestrator would emit, but we're treating them as unknown origin).
+    const listPath = join(projectRoot, 'src/views/PostListView.tsx');
+    const before = readFileSync(listPath, 'utf8');
+
+    await runGenerate();
+
+    // No hash manifest means we can't tell user edits from originals, so
+    // existing files are skipped. Content is unchanged.
+    expect(readFileSync(listPath, 'utf8')).toBe(before);
+    // A fresh hash manifest was written.
+    expect(existsSync(join(projectRoot, HASHES_DIR, HASHES_FILE))).toBe(true);
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/parity-p2-factory-imports.test.ts

@@ -0,0 +1,116 @@
+/**
+ * P2 — Factory generators consume the pattern library, not forks
+ *
+ * Architectural invariant I5 from VIEW-RENDERING-ARCHITECTURE.md:
+ *   "Factory generators are consumers of the pattern library, not
+ *    reimplementations of it."
+ *
+ * Every composer / body-generator under react-starter must import
+ * from `@specverse/runtime/views/core` or `@specverse/runtime/views/tailwind`.
+ * A generator that doesn't is a reimplementation — it's drift-prone
+ * and violates the "one pattern library, three consumers" contract.
+ *
+ * Scope: files matching *-composer.ts or view-emitter.ts / generator
+ * files that actually produce view-layout code. Skeletons (.tsx.template)
+ * are content-only and exempt. helpers-emitter / html-to-jsx are
+ * transformation utilities, exempt — they don't consume pattern data.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const HERE = fileURLToPath(import.meta.url);
+const STARTER_DIR = resolve(HERE, '..', '..');
+
+const RUNTIME_IMPORT_PATTERN =
+  /from\s+['"]@specverse\/runtime\/views\/(core|tailwind)['"]/;
+
+/**
+ * Files required to import from @specverse/runtime/views/core or
+ * /views/tailwind. The filenames match the convention of any generator
+ * that emits view layout or composes pattern data.
+ */
+const MUST_IMPORT_FROM_RUNTIME = (filename: string): boolean => {
+  // Every body composer (list / detail / form / dashboard).
+  if (/-body-composer\.ts$/.test(filename)) return true;
+  return false;
+};
+
+/**
+ * Files explicitly exempt from P2 — orchestrators, transformers, and
+ * utilities that don't consume pattern data. Each exemption carries
+ * a short justification as an inline comment near the import list.
+ */
+const EXEMPT_FILES = new Set([
+  // Orchestrator: dispatches to composers (which do import runtime).
+  'views-generator.ts',
+  'view-emitter.ts',
+  'orchestrator.ts',
+  // Pure string transformer, no pattern data.
+  'html-to-jsx.ts',
+  // Emits inline source code; no adapter calls needed.
+  'helpers-emitter.ts',
+  'app-tsx-generator.ts',
+  'package-json-generator.ts',
+  // Pure utility for content-hashing, no pattern consumption.
+  'regen-safety.ts',
+]);
+
+function collectTypeScriptFiles(dir: string, prefix = ''): string[] {
+  const out: string[] = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === '__tests__' || entry.name === 'skeletons') continue;
+    const full = join(dir, entry.name);
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...collectTypeScriptFiles(full, rel));
+    } else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+describe('P2 — factory generators consume the pattern library', () => {
+  const files = collectTypeScriptFiles(STARTER_DIR);
+
+  it('produces a non-empty file list (sanity)', () => {
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  for (const relPath of files) {
+    const filename = relPath.split('/').pop()!;
+
+    if (EXEMPT_FILES.has(filename)) continue;
+    if (!MUST_IMPORT_FROM_RUNTIME(filename)) continue;
+
+    it(`${relPath} imports from @specverse/runtime/views/{core|tailwind}`, () => {
+      const content = readFileSync(join(STARTER_DIR, relPath), 'utf8');
+      const imports = RUNTIME_IMPORT_PATTERN.test(content);
+      if (!imports) {
+        throw new Error(
+          `${relPath} must import from @specverse/runtime/views/core or ` +
+          `@specverse/runtime/views/tailwind to satisfy invariant I5. ` +
+          `If it genuinely doesn't need pattern data, add it to the ` +
+          `EXEMPT_FILES set with a justification. Generators that emit ` +
+          `view-layout code inevitably use pattern constants (field ` +
+          `classification, atomic components) — sourcing those from ` +
+          `runtime is what keeps the three consumers in sync.`
+        );
+      }
+    });
+  }
+
+  it('every composer is covered by an explicit rule (no silent skips)', () => {
+    const composers = files.filter(f => f.endsWith('-body-composer.ts'));
+    expect(composers.length).toBeGreaterThanOrEqual(4); // list/detail/form/dashboard at minimum
+    for (const c of composers) {
+      const filename = c.split('/').pop()!;
+      expect(MUST_IMPORT_FROM_RUNTIME(filename)).toBe(true);
+      expect(EXEMPT_FILES.has(filename)).toBe(false);
+    }
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/parity-p3-rendered-output.test.ts

@@ -0,0 +1,183 @@
+/**
+ * P3 — Rendered-output equivalence
+ *
+ * Architectural invariant: the same (spec, view, model) must produce
+ * semantically equivalent output in app-demo (runtime React adapter)
+ * and in ReactAppStarter (Factory B emitter). They differ only in
+ * execution model — one renders in the browser, the other emits
+ * static JSX — but the visible structure must match.
+ *
+ * This file tests the LIST VIEW path, where parity is most
+ * tractable because both consumers call the same Tailwind adapter
+ * for the table shell. The test covers:
+ *
+ *   1. Column selection — both use `inferFieldsFromSchema` from
+ *      the canonical pattern engine. Drift in either composer's
+ *      column-filter logic would diverge here.
+ *   2. Table shell HTML — the Tailwind adapter renders the same
+ *      shell for both paths; ensured by Factory B importing
+ *      `createUniversalTailwindAdapter` directly.
+ *   3. Field humanisation — `camelCase` → `Title Case` for headers.
+ *
+ * Not yet covered (future extensions):
+ *   - Detail / form / dashboard views — would need a reference
+ *     React-adapter render path captured as an HTML string, then
+ *     diffed against the Factory B emitted JSX modulo structural
+ *     differences. Doable but bigger test machinery.
+ *   - FK display-name resolution — blocked on Factory B's TODO to
+ *     replace plain-FK inputs with dropdowns.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { inferFieldsFromSchema } from '@specverse/runtime/views/core';
+import { createUniversalTailwindAdapter } from '@specverse/runtime/views/tailwind';
+import { composeListBody } from '../list-body-composer.js';
+import type { EmitContext, ModelSpec } from '../view-emitter.js';
+
+// ───────────────────────────────────────────────────────────────────────
+// Reference model + view-spec setup
+// ───────────────────────────────────────────────────────────────────────
+
+function makeReferenceModel(): ModelSpec {
+  return {
+    name: 'Article',
+    attributes: {
+      id: { type: 'UUID', required: true, auto: 'uuid4' },      // excluded
+      title: { type: 'String', required: true },                // included
+      slug: { type: 'String', required: true, unique: true },   // included
+      content: { type: 'Text', required: false },               // included
+      status: { type: 'String', values: ['draft', 'published'] },// included
+      authorId: { type: 'UUID', required: true },               // included (FK)
+      createdAt: { type: 'DateTime', auto: 'now' },             // excluded (auto)
+      updatedAt: { type: 'DateTime', auto: 'now' },             // excluded (auto)
+    },
+  };
+}
+
+function makeContext(): EmitContext {
+  const model = makeReferenceModel();
+  return {
+    view: { type: 'list', model: 'Article' },
+    viewName: 'ArticleListView',
+    model,
+    modelSchemas: { Article: model },
+    renderBody: composeListBody,
+  };
+}
+
+function humanize(s: string): string {
+  return s.replace(/([A-Z])/g, ' $1').replace(/^./, c => c.toUpperCase()).trim();
+}
+
+// ───────────────────────────────────────────────────────────────────────
+// Parity assertions
+// ───────────────────────────────────────────────────────────────────────
+
+describe('P3 — list view column inference parity', () => {
+  it('runtime inferFieldsFromSchema and Factory B composer see the same columns', () => {
+    const ctx = makeContext();
+    const runtimeColumns = inferFieldsFromSchema(ctx.modelSchemas, ctx.model.name);
+
+    // We can extract Factory B's column choices by looking at what
+    // headers it emits into the rendered output.
+    const body = composeListBody(ctx);
+
+    for (const col of runtimeColumns) {
+      const label = humanize(col);
+      expect(body, `runtime column "${col}" (label: "${label}") must appear in Factory B output`)
+        .toContain(`>${label}<`);
+    }
+
+    // And nothing EXTRA from the model that runtime excludes:
+    const runtimeSet = new Set(runtimeColumns);
+    const allAttrs = Object.keys(ctx.model.attributes);
+    const runtimeExcluded = allAttrs.filter(a => !runtimeSet.has(a));
+    for (const excluded of runtimeExcluded) {
+      const label = humanize(excluded);
+      // Factory B must NOT emit a <th> for this field.
+      const headerPattern = new RegExp(`<th\\b[^>]*>${label}</th>`);
+      expect(body).not.toMatch(headerPattern);
+    }
+  });
+
+  it('matches the expected column set for the reference model', () => {
+    const cols = inferFieldsFromSchema(makeContext().modelSchemas, 'Article');
+    // Canonical expectation for this reference spec.
+    expect(cols).toEqual(['title', 'slug', 'content', 'status', 'authorId']);
+  });
+});
+
+describe('P3 — list view table shell parity', () => {
+  it('emits a table shell byte-identical to a direct Tailwind adapter call', () => {
+    // The composer calls createUniversalTailwindAdapter() + table.render()
+    // with a known columns list and a sentinel in children. If we call
+    // the adapter directly with the same args, we should get the same
+    // shell HTML (modulo the sentinel vs the Factory B JSX injection).
+    const ctx = makeContext();
+    const runtimeColumns = inferFieldsFromSchema(ctx.modelSchemas, ctx.model.name);
+    const headers = runtimeColumns.map(humanize);
+
+    const adapter = createUniversalTailwindAdapter({ darkMode: true });
+    const SENTINEL = 'SENTINEL';
+    const shellHtml = adapter.components.table.render({
+      properties: { columns: headers },
+      children: SENTINEL,
+    });
+
+    // Every column header appears in the shell, in order.
+    let lastIdx = -1;
+    for (const header of headers) {
+      const idx = shellHtml.indexOf(`>${header}</th>`);
+      expect(idx, `header "${header}" must appear in Tailwind adapter output`).toBeGreaterThan(-1);
+      expect(idx, `header "${header}" must appear AFTER the previous header`).toBeGreaterThan(lastIdx);
+      lastIdx = idx;
+    }
+
+    // Factory B's composer output must preserve the same header order.
+    const body = composeListBody(ctx);
+    let lastBodyIdx = -1;
+    for (const header of headers) {
+      const idx = body.indexOf(`>${header}</th>`);
+      expect(idx).toBeGreaterThan(-1);
+      expect(idx).toBeGreaterThan(lastBodyIdx);
+      lastBodyIdx = idx;
+    }
+  });
+
+  it('Factory B output carries Tailwind classes from the canonical adapter shell', () => {
+    const body = composeListBody(makeContext());
+    // A sampling of classes that come from the adapter's table template.
+    // If the adapter changes its classes, both consumers update together.
+    expect(body).toContain('overflow-x-auto');
+    expect(body).toContain('min-w-full');
+    expect(body).toContain('divide-y divide-gray-200');
+    expect(body).toContain('bg-gray-50 dark:bg-gray-800');
+  });
+
+  it('rows are synthesized by Factory B (the adapter emits placeholder for react mount)', () => {
+    const body = composeListBody(makeContext());
+    // The body should contain a real JSX .map() — Factory B's
+    // contribution to the shared shell.
+    expect(body).toContain('filtered.map((item, idx) =>');
+    expect(body).toContain('onClick={() => onSelect?.(item)}');
+  });
+});
+
+describe('P3 — field humanisation parity', () => {
+  it('both paths humanise column names the same way (camelCase → Title Case)', () => {
+    // Factory B's humanize is inlined in the composer. The runtime
+    // adapter humanises via the same-shaped regex in pattern-engine /
+    // react-pattern-adapter. This test documents the contract by
+    // comparing against a fixture.
+    const cases: [string, string][] = [
+      ['title', 'Title'],
+      ['authorId', 'Author Id'],
+      ['createdAt', 'Created At'],
+      ['slugifiedURL', 'Slugified U R L'],
+      ['name', 'Name'],
+    ];
+    for (const [input, expected] of cases) {
+      expect(humanize(input), `humanize("${input}")`).toBe(expected);
+    }
+  });
+});

package/libs/instance-factories/applications/templates/react-starter/__tests__/regen-safety.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  loadHashManifest,
+  saveHashManifest,
+  reconcileWrites,
+  sha256,
+  HASHES_DIR,
+  HASHES_FILE,
+} from '../regen-safety.js';
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), 'specverse-regen-safety-'));
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+});
+
+describe('hash manifest persistence', () => {
+  it('loadHashManifest returns {} when the file is missing', () => {
+    expect(loadHashManifest(projectRoot)).toEqual({});
+  });
+
+  it('round-trips through save → load', () => {
+    saveHashManifest(projectRoot, { 'src/a.ts': 'abc', 'src/b.ts': 'def' });
+    const loaded = loadHashManifest(projectRoot);
+    expect(loaded).toEqual({ 'src/a.ts': 'abc', 'src/b.ts': 'def' });
+    expect(existsSync(join(projectRoot, HASHES_DIR, HASHES_FILE))).toBe(true);
+  });
+
+  it('tolerates a malformed manifest file by returning {}', () => {
+    const dir = join(projectRoot, HASHES_DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, HASHES_FILE), '{ not valid JSON', 'utf8');
+    expect(loadHashManifest(projectRoot)).toEqual({});
+  });
+});
+
+describe('reconcileWrites — pure planning (no I/O writes)', () => {
+  it('approves brand-new files and records their hashes', () => {
+    const proposed = { 'src/views/PostListView.tsx': 'content-a' };
+    const result = reconcileWrites(projectRoot, proposed, {});
+    expect(result.approvedWrites).toEqual(proposed);
+    expect(result.skipped).toEqual([]);
+    expect(existsSync(join(projectRoot, 'src/views/PostListView.tsx'))).toBe(false);
+    expect(result.manifest['src/views/PostListView.tsx']).toBe(sha256('content-a'));
+  });
+
+  it('approves overwriting a pristine file and updates its hash', () => {
+    const path = 'src/a.ts';
+    const absPath = join(projectRoot, path);
+    const originalContent = 'v1';
+    const newContent = 'v2';
+
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(absPath, originalContent, 'utf8');
+    const prevManifest = { [path]: sha256(originalContent) };
+
+    const result = reconcileWrites(projectRoot, { [path]: newContent }, prevManifest);
+
+    expect(result.approvedWrites[path]).toBe(newContent);
+    expect(result.skipped).toEqual([]);
+    // reconcileWrites is pure planning — filesystem unchanged
+    expect(readFileSync(absPath, 'utf8')).toBe(originalContent);
+    expect(result.manifest[path]).toBe(sha256(newContent));
+  });
+
+  it('skips a user-edited file and keeps the old hash record', () => {
+    const path = 'src/edited.ts';
+    const absPath = join(projectRoot, path);
+    const originalContent = 'v1';
+    const editedContent = 'v1 + user edits';
+    const newContent = 'v2';
+
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(absPath, editedContent, 'utf8');
+    const prevManifest = { [path]: sha256(originalContent) };
+
+    const result = reconcileWrites(projectRoot, { [path]: newContent }, prevManifest);
+
+    expect(result.approvedWrites[path]).toBeUndefined();
+    expect(result.skipped).toHaveLength(1);
+    expect(result.skipped[0]).toMatchObject({
+      path,
+      reason: expect.stringContaining('edited'),
+    });
+    expect(readFileSync(absPath, 'utf8')).toBe(editedContent);
+    expect(result.manifest[path]).toBe(prevManifest[path]);
+  });
+
+  it('skips files that exist but have no prior hash record', () => {
+    const path = 'src/unknown.ts';
+    const absPath = join(projectRoot, path);
+
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(absPath, 'manually placed', 'utf8');
+
+    const result = reconcileWrites(projectRoot, { [path]: 'would-overwrite' }, {});
+
+    expect(result.approvedWrites[path]).toBeUndefined();
+    expect(result.skipped).toHaveLength(1);
+    expect(result.skipped[0].reason).toContain('no prior hash recorded');
+    expect(readFileSync(absPath, 'utf8')).toBe('manually placed');
+  });
+
+  it('does not mutate the input prevManifest', () => {
+    const prev = { 'a.ts': sha256('old') };
+    const prevSnapshot = { ...prev };
+    reconcileWrites(projectRoot, { 'a.ts': 'new', 'b.ts': 'also new' }, prev);
+    expect(prev).toEqual(prevSnapshot);
+  });
+
+  it('handles a batch of mixed outcomes correctly', () => {
+    mkdirSync(join(projectRoot, 'src'), { recursive: true });
+    writeFileSync(join(projectRoot, 'src/pristine.ts'), 'v1', 'utf8');
+    writeFileSync(join(projectRoot, 'src/edited.ts'), 'v1 + user edit', 'utf8');
+    const prev = {
+      'src/pristine.ts': sha256('v1'),
+      'src/edited.ts': sha256('v1'),
+    };
+
+    const proposed = {
+      'src/pristine.ts': 'v2',
+      'src/edited.ts': 'v2',
+      'src/new.ts': 'brand new',
+    };
+
+    const result = reconcileWrites(projectRoot, proposed, prev);
+
+    expect(Object.keys(result.approvedWrites).sort()).toEqual(['src/new.ts', 'src/pristine.ts']);
+    expect(result.skipped.map(s => s.path)).toEqual(['src/edited.ts']);
+    // No writes happened
+    expect(readFileSync(join(projectRoot, 'src/pristine.ts'), 'utf8')).toBe('v1');
+    expect(readFileSync(join(projectRoot, 'src/edited.ts'), 'utf8')).toBe('v1 + user edit');
+    expect(result.manifest['src/pristine.ts']).toBe(sha256('v2'));
+    expect(result.manifest['src/edited.ts']).toBe(prev['src/edited.ts']);
+    expect(result.manifest['src/new.ts']).toBe(sha256('brand new'));
+  });
+});