@sungen/driver-data-factory 3.2.10-beta.6 → 3.2.12-beta.10

package/src/cli.ts

@@ -10,11 +10,34 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from
 import { join, dirname } from 'path';
 import { createInterface } from 'readline';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { loadEffectiveCatalog } from './catalog-loader';
+import { loadEffectiveCatalog, describeProvenance } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
+import { buildRequest, fingerprint } from './contract';
+import { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, hasDatasource, scaffoldRecipe, renderRecipeYaml } from './state';
+import { crosscheckUnit, crosscheckShared } from './crosscheck';
+import { detectPreconditionSignals } from './detect';
 import { lintFieldMap, summarize } from './lint';
+import { validateGenerated } from './validate';
+import { generateFixture } from './fixture';
+import { ensureDataFactoryReadme } from './readme';
+import type { SelectionContext, Profile } from './types';
 
 const FIELDMAP_DIR = (cwd: string) => join(cwd, 'qa', 'data-factory');
+
+const PROFILES: Profile[] = ['regression', 'functional', 'smoke', 'security-min'];
+
+/** Build a SelectionContext from the shared --profile/--locale/--channel/--sink flags. */
+function ctxFromOpts(o: { profile?: string; locale?: string; channel?: string; sink?: string }): SelectionContext {
+  const ctx: SelectionContext = {};
+  if (o.profile) {
+    if (!PROFILES.includes(o.profile as Profile)) throw new Error(`--profile must be one of ${PROFILES.join(' | ')}`);
+    ctx.profile = o.profile as Profile;
+  }
+  if (o.locale) ctx.locale = o.locale;
+  if (o.channel === 'api' || o.channel === 'ui') ctx.channel = o.channel;
+  if (o.sink) ctx.sink = o.sink;
+  return ctx;
+}
 const fieldMapPath = (cwd: string, name: string) => join(FIELDMAP_DIR(cwd), `${name}.fields.yaml`);
 
 /** Resolve where a unit's test-data lives: screen or flow (mirrors sungen auto-detect). */
@@ -45,24 +68,48 @@ function loadFieldMap(cwd: string, name: string): FieldMap | null {
   return parseYaml(readFileSync(p, 'utf8')) as FieldMap;
 }
 
-async function genOne(cwd: string, name: string, opts: { force?: boolean }): Promise<'written' | 'skipped' | 'missing'> {
+async function genOne(cwd: string, name: string, opts: { force?: boolean; ctx?: SelectionContext }): Promise<'written' | 'skipped' | 'missing'> {
   const map = loadFieldMap(cwd, name);
   if (!map) { console.error(`  ✗ ${name}: no field-map at qa/data-factory/${name}.fields.yaml (author it first, e.g. via /sungen:create-data-test)`); return 'missing'; }
-  const { catalog, warnings } = loadEffectiveCatalog(cwd);
+  const { catalog, warnings, provenance } = loadEffectiveCatalog(cwd);
   for (const w of warnings) console.warn(`  ⚠ overwrite: ${w.detail} → ${w.suggestion}`);
+  for (const line of describeProvenance(provenance)) console.log(`  ⟲ .overwrite → ${line}`);
 
-  const expanded = expandFieldMap(map, catalog);
+  const expanded = expandFieldMap(map, catalog, opts.ctx || {});
+  const na = expanded.flatMap((f) => (f.excluded || []).map((e) => `${f.name}.${e.id}`));
+  if (na.length) console.log(`  ⊘ ${name}: ${na.length} case(s) not applicable for this context (see _not_applicable in the file)`);
   const out = testDataPath(cwd, name);
   if (!out) { console.error(`  ✗ ${name}: no qa/screens/${name} or qa/flows/${name}`); return 'missing'; }
 
-  if (existsSync(out) && !opts.force) {
-    const a = (await ask(`  ? ${name}: test-data already exists — overwrite? [y/N] `)).toLowerCase();
-    if (a !== 'y' && a !== 'yes') { console.log(`  · ${name}: skipped`); return 'skipped'; }
+  const dfData = renderTestData(expanded) as Record<string, any>;
+  // Reproducibility fingerprint (M3-C): stamped into the file so a reader/cache can tell whether the
+  // catalog/generator/context that produced this data has changed. Same fingerprint ⇒ identical data.
+  const fp = fingerprint(buildRequest(map, opts.ctx || {}), catalog);
+  dfData._fingerprint = fp;
+  const exists = existsSync(out);
+
+  // MERGE, don't clobber. Data Factory owns only the keys it generates (`_generated_by` + each
+  // field name); every OTHER key in the existing test-data (create-test's data, flow-namespaced
+  // keys like `login.email`, @cases datasets, overrides) is preserved. A regenerated field key is
+  // replaced by its standardized version (that's the point). Fixes the whole-file clobber.
+  let final = dfData;
+  let mergedInto = false;
+  if (exists) {
+    if (!opts.force) {
+      const a = (await ask(`  ? ${name}: test-data exists — merge standardized field data in (keeps other keys)? [y/N] `)).toLowerCase();
+      if (a !== 'y' && a !== 'yes') { console.log(`  · ${name}: skipped`); return 'skipped'; }
+    }
+    let existing: Record<string, any> = {};
+    try { existing = (parseYaml(readFileSync(out, 'utf8')) as Record<string, any>) || {}; } catch { existing = {}; }
+    final = { ...existing, ...dfData }; // DF-owned keys win; all other existing keys preserved
+    mergedInto = true;
   }
   mkdirSync(dirname(out), { recursive: true });
-  writeFileSync(out, stringifyYaml(renderTestData(expanded)), 'utf8');
+  writeFileSync(out, stringifyYaml(final), 'utf8');
   const blind = expanded.filter((f) => f.blindSpot).map((f) => f.name);
-  console.log(`  ✓ ${name}: wrote ${out.replace(cwd + '/', '')}${blind.length ? ` (blind spots: ${blind.join(', ')})` : ''}`);
+  const verb = mergedInto ? 'merged into' : 'wrote';
+  const fieldKeys = expanded.map((f) => f.name).length;
+  console.log(`  ✓ ${name}: ${verb} ${out.replace(cwd + '/', '')} (${fieldKeys} field key(s)${mergedInto ? ', other keys preserved' : ''})${blind.length ? ` — blind spots: ${blind.join(', ')}` : ''}`);
   return 'written';
 }
 
@@ -76,9 +123,16 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--all', 'Generate for every field-map under qa/data-factory/ (requires confirm)')
     .option('--yes', 'Assume yes for the --all confirmation')
     .option('--force', 'Overwrite existing test-data without asking (implies --yes)')
-    .action(async (opts: { screen?: string; all?: boolean; yes?: boolean; force?: boolean }) => {
+    .option('--profile <name>', `Case selection: ${PROFILES.join(' | ')} (default: regression = all)`)
+    .option('--locale <tag>', 'Selection context locale (e.g. ja-JP) — filters locale-gated cases')
+    .option('--channel <api|ui>', 'Selection context channel')
+    .option('--sink <name>', 'Selection context output sink (e.g. html)')
+    .action(async (opts: { screen?: string; all?: boolean; yes?: boolean; force?: boolean; profile?: string; locale?: string; channel?: string; sink?: string }) => {
       const cwd = process.cwd();
-      if (opts.screen) { await genOne(cwd, opts.screen, opts); return; }
+      ensureDataFactoryReadme(cwd);
+      let ctx: SelectionContext;
+      try { ctx = ctxFromOpts(opts); } catch (e: any) { console.error(e.message); process.exitCode = 1; return; }
+      if (opts.screen) { await genOne(cwd, opts.screen, { ...opts, ctx }); return; }
       if (!opts.all) {
         console.error('Specify --screen <name> for one unit, or --all for every unit (with confirmation).');
         process.exitCode = 1;
@@ -95,7 +149,7 @@ export function registerDataFactoryCommand(program: any): void {
         if (a !== 'y' && a !== 'yes') { console.log('Cancelled.'); return; }
       }
       let written = 0;
-      for (const n of names) if ((await genOne(cwd, n, { force: opts.force })) === 'written') written++;
+      for (const n of names) if ((await genOne(cwd, n, { force: opts.force, ctx })) === 'written') written++;
       console.log(`Done: ${written}/${names.length} written.`);
     });
 
@@ -103,8 +157,15 @@ export function registerDataFactoryCommand(program: any): void {
     .command('lint')
     .description('Check test-data coverage (valid/boundary/invalid + traceability) per phuong-phap §6')
     .option('--screen <name>', 'Lint one unit (default: all field-maps)')
-    .action((opts: { screen?: string }) => {
+    .option('--profile <name>', `Case selection: ${PROFILES.join(' | ')} (default: regression = all)`)
+    .option('--locale <tag>', 'Selection context locale (e.g. ja-JP)')
+    .option('--channel <api|ui>', 'Selection context channel')
+    .option('--sink <name>', 'Selection context output sink')
+    .action((opts: { screen?: string; profile?: string; locale?: string; channel?: string; sink?: string }) => {
       const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      let ctx: SelectionContext;
+      try { ctx = ctxFromOpts(opts); } catch (e: any) { console.error(e.message); process.exitCode = 1; return; }
       const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
       if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
       const { catalog } = loadEffectiveCatalog(cwd);
@@ -112,7 +173,7 @@ export function registerDataFactoryCommand(program: any): void {
       for (const name of names) {
         const map = loadFieldMap(cwd, name);
         if (!map) { console.error(`✗ ${name}: no field-map`); totalErrors++; continue; }
-        const { issues } = lintFieldMap(map, catalog);
+        const { issues } = lintFieldMap(map, catalog, ctx);
         const s = summarize(issues);
         totalErrors += s.errors;
         const badge = s.errors ? '✗' : s.warns ? '⚠' : '✓';
@@ -124,4 +185,162 @@ export function registerDataFactoryCommand(program: any): void {
       }
       if (totalErrors) process.exitCode = 1;
     });
+
+  data
+    .command('validate')
+    .description('Verify every generated value is semantically correct (valid values satisfy the constraints; synthesized invalid values violate them)')
+    .option('--screen <name>', 'Validate one unit (default: all field-maps)')
+    .option('--profile <name>', `Case selection: ${PROFILES.join(' | ')} (default: regression = all)`)
+    .option('--locale <tag>', 'Selection context locale (e.g. ja-JP)')
+    .option('--channel <api|ui>', 'Selection context channel')
+    .option('--sink <name>', 'Selection context output sink')
+    .action((opts: { screen?: string; profile?: string; locale?: string; channel?: string; sink?: string }) => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      let ctx: SelectionContext;
+      try { ctx = ctxFromOpts(opts); } catch (e: any) { console.error(e.message); process.exitCode = 1; return; }
+      const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
+      if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
+      const { catalog } = loadEffectiveCatalog(cwd);
+      let totalErrors = 0;
+      for (const name of names) {
+        const map = loadFieldMap(cwd, name);
+        if (!map) { console.error(`✗ ${name}: no field-map`); totalErrors++; continue; }
+        const findings = validateGenerated(map, catalog, ctx);
+        const errors = findings.filter((f) => f.severity === 'error').length;
+        const warns = findings.filter((f) => f.severity === 'warn').length;
+        totalErrors += errors;
+        const badge = errors ? '✗' : warns ? '⚠' : '✓';
+        console.log(`${badge} ${name}: ${errors} error · ${warns} warn`);
+        for (const f of findings) {
+          console.log(`${f.severity === 'error' ? '  ✗' : '  ⚠'} [${f.field}] ${f.code}: ${f.message}`);
+        }
+      }
+      if (totalErrors) process.exitCode = 1;
+    });
+
+  data
+    .command('provenance')
+    .description('Show what qa/data-factory/common.overwrite.yaml changed vs the shipped company catalog (extend/replace/disable) — "no silent overwrite"')
+    .action(() => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      const { provenance, warnings } = loadEffectiveCatalog(cwd);
+      const lines = describeProvenance(provenance);
+      if (lines.length === 0) {
+        console.log('No project overrides — the effective catalog is the shipped company common as-is.');
+      } else {
+        console.log('Project overrides (qa/data-factory/common.overwrite.yaml):');
+        for (const l of lines) console.log(`  ⟲ ${l}`);
+      }
+      for (const w of warnings) console.warn(`  ⚠ ${w.detail} → ${w.suggestion}`);
+    });
+
+  data
+    .command('crosscheck')
+    .description('Cross-artifact Gate (M3-B): verify the testcase and its test-data agree — no dangling {{var}}, shared datasets identical across the journey, declared state-preconditions surfaced')
+    .option('--screen <name>', 'Cross-check one unit (default: all field-maps + all shared datasets)')
+    .action((opts: { screen?: string }) => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
+      const findings = [
+        ...names.flatMap((n) => crosscheckUnit(cwd, n)),
+        ...(opts.screen ? [] : crosscheckShared(cwd)),
+      ];
+      const errors = findings.filter((f) => f.severity === 'error').length;
+      const warns = findings.filter((f) => f.severity === 'warn').length;
+      const badge = errors ? '✗' : warns ? '⚠' : '✓';
+      console.log(`${badge} crosscheck: ${errors} error · ${warns} warn (${names.length} unit(s))`);
+      for (const f of findings) console.log(`  ${f.severity === 'error' ? '✗' : f.severity === 'warn' ? '⚠' : '·'} [${f.unit}] ${f.code}: ${f.message}`);
+      if (errors) process.exitCode = 1;
+    });
+
+  data
+    .command('state')
+    .description('Domain/stateful data (M3-A Layer 0): validate the state-recipes in recipes.yaml and render each as a standardized manual precondition block (+ a resolved .state.yaml plan)')
+    .option('--recipe <name>', 'Only this recipe (default: all recipes with a `resources`/`shared` graph)')
+    .option('--scaffold <unit>', 'Auto-draft a state-recipe SKELETON from the unit\'s spec.md precondition signals (Layer-C auto-draft), then review/fill it')
+    .option('--force', 'With --scaffold: overwrite an existing recipe of the same name')
+    .action((opts: { recipe?: string; scaffold?: string; force?: boolean }) => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+
+      // --scaffold: auto-draft a recipe skeleton from the unit's spec precondition signals.
+      if (opts.scaffold) {
+        const unit = opts.scaffold;
+        const specPath = ['screens', 'flows'].map((k) => join(cwd, 'qa', k, unit, 'requirements', 'spec.md')).find(existsSync);
+        const specText = specPath ? readFileSync(specPath, 'utf8') : '';
+        const signals = detectPreconditionSignals(specText);
+        const recipe = scaffoldRecipe(unit, signals);
+        if (!recipe) { console.log(`No stateful-precondition signals found in ${unit}'s spec — nothing to scaffold (a screen may simply have no precondition).`); return; }
+        const recipesPath = join(FIELDMAP_DIR(cwd), 'recipes.yaml');
+        const doc: any = existsSync(recipesPath) ? (parseYaml(readFileSync(recipesPath, 'utf8')) || {}) : {};
+        doc.recipes = doc.recipes || {};
+        if (doc.recipes[recipe.name] && !opts.force) { console.error(`✗ recipe "${recipe.name}" already exists — edit it, or pass --force to overwrite the scaffold.`); process.exitCode = 1; return; }
+        // Splice the human-friendly (commented) block rather than a bare re-serialize, to preserve TODO hints.
+        const header = existsSync(recipesPath) ? readFileSync(recipesPath, 'utf8').replace(/\s*$/, '') + '\n' : 'recipes:\n';
+        const block = renderRecipeYaml(recipe);
+        writeFileSync(recipesPath, (header.includes('recipes:') ? header : 'recipes:\n' + header) + block, 'utf8');
+        console.log(`  ✓ scaffolded recipe "${recipe.name}" → ${recipesPath.replace(cwd + '/', '')} (${signals.length} signal(s))`);
+        console.log(`  → REVIEW: name each entity, set desiredState/bindings, confirm domain values with QA, then \`sungen data state --recipe ${recipe.name}\`.`);
+        for (const s of signals) console.log(`    · signal: ${s}`);
+        return;
+      }
+
+      let recipes = loadStateRecipes(cwd);
+      if (opts.recipe) recipes = recipes.filter((r) => r.name === opts.recipe);
+      if (recipes.length === 0) { console.error('No state-recipes (recipes with a `resources` or `shared` graph) in qa/data-factory/recipes.yaml.'); process.exitCode = 1; return; }
+      const ds = hasDatasource(cwd);
+      console.log(`Data Factory — domain-state (${recipes.length} recipe(s); datasource ${ds ? 'present → Layer 1 possible' : 'absent → Layer 0 manual preconditions'})`);
+      let errors = 0;
+      for (const r of recipes) {
+        const findings = validateStateRecipe(r);
+        errors += findings.filter((f) => f.severity === 'error').length;
+        const plan = buildStatePlan(r, { datasource: ds });
+        const badge = findings.some((f) => f.severity === 'error') ? '✗' : findings.some((f) => f.severity === 'warn') ? '⚠' : '✓';
+        console.log(`\n${badge} ${r.name}${plan.manual ? ' [manual setup]' : ' [auto-provisionable]'}`);
+        for (const f of findings) console.log(`  ${f.severity === 'error' ? '✗' : f.severity === 'warn' ? '⚠' : '·'} ${f.code}: ${f.message}`);
+        for (const line of renderPreconditionBlock(plan).split('\n')) console.log(`    ${line}`);
+        if (plan.sharedIdentity) console.log(`    # shared dataset: "${plan.sharedIdentity.entity}" identical across ${plan.sharedIdentity.screens.join(', ')} (asserted by \`data crosscheck\`)`);
+        const planPath = join(FIELDMAP_DIR(cwd), `${r.name}.state.yaml`);
+        writeFileSync(planPath, stringifyYaml({ _generated_by: 'sungen data state — resolved domain-state plan (Layer 0). Edit recipes.yaml, not this file.', ...plan }), 'utf8');
+        console.log(`  ✓ wrote ${planPath.replace(cwd + '/', '')}`);
+      }
+      if (errors) process.exitCode = 1;
+    });
+
+  data
+    .command('fixture')
+    .description('Generate a CSV import fixture from the field-map (bulk-import / file-upload testing)')
+    .requiredOption('--screen <name>', 'Unit whose field-map to build a fixture from')
+    .option('--rows <n>', 'Number of valid rows', '3')
+    .option('--invalid', 'Also write <name>.invalid.csv (one seeded-bad row per field) + <name>.invalid.expected.yaml (per-row expected rejection)')
+    .option('--force', 'Overwrite existing fixture file(s) without asking')
+    .action(async (opts: { screen: string; rows?: string; invalid?: boolean; force?: boolean }) => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      const map = loadFieldMap(cwd, opts.screen);
+      if (!map) { console.error(`✗ ${opts.screen}: no field-map at qa/data-factory/${opts.screen}.fields.yaml`); process.exitCode = 1; return; }
+      const { catalog } = loadEffectiveCatalog(cwd);
+      const res = generateFixture(map, catalog, { rows: parseInt(opts.rows || '3', 10), includeInvalid: !!opts.invalid });
+      const dir = join(cwd, 'qa', 'fixtures');
+      mkdirSync(dir, { recursive: true });
+      const validPath = join(dir, `${opts.screen}.csv`);
+      const writes: Array<[string, string]> = [[validPath, res.valid]];
+      if (res.invalid) writes.push([join(dir, `${opts.screen}.invalid.csv`), res.invalid]);
+      // Sidecar: expected rejection per row — keeps the CSV payload clean (no _violation column).
+      if (res.expected) writes.push([join(dir, `${opts.screen}.invalid.expected.yaml`), stringifyYaml(res.expected)]);
+      for (const [p] of writes) {
+        if (existsSync(p) && !opts.force) {
+          const a = (await ask(`  ? ${p.replace(cwd + '/', '')} exists — overwrite? [y/N] `)).toLowerCase();
+          if (a !== 'y' && a !== 'yes') { console.log('  · skipped'); return; }
+        }
+      }
+      for (const [p, content] of writes) {
+        writeFileSync(p, content, 'utf8');
+        const label = p.endsWith('.expected.yaml') ? 'expected-rejection sidecar' : `${res.headers.length} columns`;
+        console.log(`  ✓ wrote ${p.replace(cwd + '/', '')} (${label})`);
+      }
+    });
 }

package/src/contract.ts

@@ -0,0 +1,93 @@
+/**
+ * Data Factory — the versioned request/result contract + reproducibility fingerprint (M3-C).
+ *
+ * Formalizes the generator's input/output so Core and the driver share a checked, versioned contract
+ * (not a raw YAML cast) and every generation is reproducible. The **fingerprint** is the connective
+ * tissue for M3: same fingerprint ⇒ byte-identical output, and it is the safe cache key for the
+ * lifecycle model (a value must never be reused across a different catalog/generator/seed/context).
+ *
+ * Pure + deterministic; no runtime, no LLM.
+ */
+import { createHash } from 'crypto';
+import type { Catalog, SelectionContext } from './types';
+import { expandFieldMap, type FieldMap, type FieldDef, type ExpandedField } from './generator';
+
+/** Bump when the generator's SEMANTICS change (boundary synthesis, applicability, render shape). */
+export const GENERATOR_VERSION = '3.3.0-df1';
+/** Bump when the request/result SHAPE changes (breaking contract). */
+export const SCHEMA_VERSION = '1.0';
+
+export interface DataFactoryRequest {
+  schemaVersion: string;
+  unit: { kind: 'screen' | 'flow'; id: string };
+  /** Selection context (M2b) — locale/channel/sink/profile. */
+  ctx: SelectionContext;
+  /** Optional seed for any future randomized synthesis (today generation is fully deterministic). */
+  seed?: number;
+  fields: FieldDef[];
+}
+
+export interface DataFactoryResult {
+  schemaVersion: string;
+  generatorVersion: string;
+  request: DataFactoryRequest;
+  /** Reproducibility fingerprint — same fingerprint ⇒ identical `fields`. */
+  fingerprint: string;
+  fields: ExpandedField[];
+}
+
+/** Build a versioned request from a field-map + selection context. */
+export function buildRequest(map: FieldMap, ctx: SelectionContext = {}, opts: { seed?: number } = {}): DataFactoryRequest {
+  const kind: 'screen' | 'flow' = map.flow ? 'flow' : 'screen';
+  const id = (map.flow || map.screen || 'unit') as string;
+  return { schemaVersion: SCHEMA_VERSION, unit: { kind, id }, ctx, seed: opts.seed, fields: map.fields || [] };
+}
+
+/** Validate a request; returns path-specific error strings (empty = valid). */
+export function validateRequest(req: DataFactoryRequest): string[] {
+  const errs: string[] = [];
+  if (req.schemaVersion !== SCHEMA_VERSION) errs.push(`schemaVersion: expected "${SCHEMA_VERSION}", got "${req.schemaVersion}"`);
+  if (!req.unit?.id) errs.push('unit.id: required');
+  if (!Array.isArray(req.fields)) errs.push('fields: must be an array');
+  else req.fields.forEach((f, i) => { if (!f.name) errs.push(`fields[${i}].name: required`); });
+  return errs;
+}
+
+/** Stable JSON (sorted keys) so the hash is order-independent. */
+function stableStringify(v: unknown): string {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(v as Record<string, unknown>).sort();
+  return `{${keys.map((k) => JSON.stringify(k) + ':' + stableStringify((v as Record<string, unknown>)[k])).join(',')}}`;
+}
+
+/**
+ * Reproducibility fingerprint over (generator version + the effective catalog subset the request uses
+ * + the request itself). The catalog subset captures `.overwrite` edits to any referenced field-type,
+ * so an overlay change that alters output also changes the fingerprint.
+ */
+export function fingerprint(req: DataFactoryRequest, catalog: Catalog): string {
+  const referenced = new Set<string>();
+  const walk = (fields: FieldDef[]) => { for (const f of fields) { if (f.type) referenced.add(f.type); if (f.fields) walk(f.fields); } };
+  walk(req.fields);
+  const catalogSubset: Record<string, unknown> = {};
+  for (const t of [...referenced].sort()) if (catalog.fieldTypes[t]) catalogSubset[t] = catalog.fieldTypes[t];
+  // Security banks a referenced type pulls in also affect output.
+  const banks: Record<string, unknown> = {};
+  for (const t of referenced) for (const b of catalog.fieldTypes[t]?.uses_security || []) if (catalog.security[b]) banks[b] = catalog.security[b];
+  const h = createHash('sha256');
+  h.update(GENERATOR_VERSION).update('\0').update(stableStringify({ req, catalogSubset, banks }));
+  return h.digest('hex').slice(0, 16);
+}
+
+/** Generate: expand + wrap in a fingerprinted, versioned result. The one-call entry for Core. */
+export function generate(map: FieldMap, catalog: Catalog, ctx: SelectionContext = {}, opts: { seed?: number } = {}): DataFactoryResult {
+  const request = buildRequest(map, ctx, opts);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatorVersion: GENERATOR_VERSION,
+    request,
+    fingerprint: fingerprint(request, catalog),
+    fields: expandFieldMap(map, catalog, ctx),
+  };
+}

package/src/crosscheck.ts

@@ -0,0 +1,149 @@
+/**
+ * Data Factory — Cross-artifact Gate (M3-B).
+ *
+ * `data validate` checks the DATA in isolation (values are semantically correct). This checks that the
+ * TESTCASE and its test-data actually AGREE — the "genuinely new piece" from the harness-merge review:
+ *   - every `{{var}}` a scenario references resolves to a key in the unit's test-data (no dangling ref);
+ *   - a cross-screen SHARED dataset (M3-A `shared:`) is present and identical across its member screens
+ *     (the registration setup→confirmation→register lineage: confirmation must show what setup buffered);
+ *   - a unit that declares a manual state-precondition (a state-recipe) surfaces it in the feature
+ *     (a `@manual` tag or a Background) rather than silently dropping the required state.
+ *
+ * Deterministic; no runtime, no LLM. Invoked from the create-test / create-data-test AI loop (and by
+ * `sungen data crosscheck`), exit-1 on an error finding.
+ */
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { loadStateRecipes, buildStatePlan, hasDatasource } from './state';
+
+export interface CrossFinding {
+  unit: string;
+  scenario?: string;
+  severity: 'error' | 'warn' | 'info';
+  code: 'DANGLING_VAR' | 'SHARED_MISSING' | 'SHARED_MISMATCH' | 'PRECONDITION_MISSING';
+  message: string;
+}
+
+/** Resolve a unit's feature dir + test-data path (screen or flow). */
+function unitPaths(cwd: string, name: string): { featureDir: string; testData: string } | null {
+  for (const kind of ['screens', 'flows']) {
+    const base = join(cwd, 'qa', kind, name);
+    if (existsSync(base)) return { featureDir: join(base, 'features'), testData: join(base, 'test-data', `${name}.yaml`) };
+  }
+  return null;
+}
+
+function readFeatureText(featureDir: string): string {
+  if (!existsSync(featureDir)) return '';
+  return readdirSync(featureDir)
+    .filter((f) => f.endsWith('.feature'))
+    .map((f) => readFileSync(join(featureDir, f), 'utf8'))
+    .join('\n');
+}
+
+/** Extract `{{var}}` roots referenced in a feature, excluding dynamic `{{$...}}` runtime vars. */
+export function referencedVars(featureText: string): string[] {
+  const out = new Set<string>();
+  const re = /\{\{\s*([^}]+?)\s*\}\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(featureText))) {
+    const tok = m[1].trim();
+    if (tok.startsWith('$')) continue; // {{$timestamp}} etc. — runtime dynamic, not a test-data key
+    const root = tok.split(/[.|[]/)[0].trim(); // login.email → login ; name|upper → name
+    if (root) out.add(root);
+  }
+  return [...out];
+}
+
+function loadYaml(path: string): Record<string, any> {
+  if (!existsSync(path)) return {};
+  try { return (parseYaml(readFileSync(path, 'utf8')) as Record<string, any>) || {}; } catch { return {}; }
+}
+
+/**
+ * Column names supplied per-row by every `@cases:<dataset>` referenced in the feature (where the
+ * dataset is a top-level LIST in test-data). A `{{col}}` inside a data-driven scenario resolves to
+ * the current row, not a top-level key — so these are valid roots, not dangling. Mirrors the
+ * compiler's data-driven lint, which is @cases-aware; without this, any @cases scenario that reads
+ * a row column (`{{input}}`, `{{code}}`, …) would be a false-positive DANGLING_VAR.
+ */
+export function casesColumns(featureText: string, data: Record<string, any>): Set<string> {
+  const cols = new Set<string>();
+  const re = /@cases:([A-Za-z0-9_.-]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(featureText))) {
+    const ds = data[m[1]];
+    if (!Array.isArray(ds)) continue;
+    for (const row of ds) {
+      if (row && typeof row === 'object' && !Array.isArray(row)) {
+        for (const k of Object.keys(row)) cols.add(k);
+      }
+    }
+  }
+  return cols;
+}
+
+/** Cross-check one unit's feature ↔ test-data. */
+export function crosscheckUnit(cwd: string, name: string): CrossFinding[] {
+  const out: CrossFinding[] = [];
+  const paths = unitPaths(cwd, name);
+  if (!paths) return out;
+  const feature = readFeatureText(paths.featureDir);
+  if (!feature) return out;
+  const data = loadYaml(paths.testData);
+  const topKeys = new Set(Object.keys(data).filter((k) => !k.startsWith('_')));
+  const caseCols = casesColumns(feature, data); // @cases row columns resolve per-row, not as top-level keys
+
+  // 1. Dangling vars — a {{var}} whose root key is absent from test-data (and not a @cases column).
+  for (const v of referencedVars(feature)) {
+    if (!topKeys.has(v) && !caseCols.has(v)) {
+      out.push({ unit: name, severity: 'error', code: 'DANGLING_VAR', message: `scenario references {{${v}}} but no "${v}" key exists in test-data/${name}.yaml` });
+    }
+  }
+
+  // 3. Manual state-precondition declared but not surfaced in the feature.
+  const ds = hasDatasource(cwd);
+  for (const r of loadStateRecipes(cwd)) {
+    const plan = buildStatePlan(r, { datasource: ds });
+    if (plan.manual && new RegExp(`@dataFactory:${r.name}\\b`).test(feature) === false) {
+      const surfaced = /@manual/.test(feature) || /Background:/.test(feature);
+      if (!surfaced) out.push({ unit: name, severity: 'warn', code: 'PRECONDITION_MISSING', message: `state-recipe "${r.name}" needs a manual precondition, but the feature has no Background / @manual tag — weave its precondition block (\`sungen data state --recipe ${r.name}\`)` });
+    }
+  }
+  return out;
+}
+
+/** Cross-check a cross-screen SHARED dataset: present + identical across all member screens. */
+export function crosscheckShared(cwd: string): CrossFinding[] {
+  const out: CrossFinding[] = [];
+  for (const r of loadStateRecipes(cwd)) {
+    if (!r.shared) continue;
+    const { entity, screens } = r.shared;
+    const datasets = screens.map((s) => {
+      const paths = unitPaths(cwd, s);
+      const data = paths ? loadYaml(paths.testData) : {};
+      return { screen: s, present: paths != null && entity in data, value: data[entity] };
+    });
+    const present = datasets.filter((d) => d.present);
+    for (const d of datasets) if (!d.present) out.push({ unit: d.screen, severity: 'warn', code: 'SHARED_MISSING', message: `shared dataset "${entity}" (recipe "${r.name}") is not present in ${d.screen}'s test-data` });
+    // Identity: every present copy must equal the first.
+    if (present.length >= 2) {
+      const ref = JSON.stringify(present[0].value);
+      for (const d of present.slice(1)) {
+        if (JSON.stringify(d.value) !== ref) {
+          out.push({ unit: d.screen, severity: 'error', code: 'SHARED_MISMATCH', message: `shared dataset "${entity}" differs between ${present[0].screen} and ${d.screen} — the same values must flow across the ${r.name} journey (e.g. confirmation must show what setup entered)` });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Cross-check the whole project (all units + shared datasets). */
+export function crosscheckAll(cwd: string, units: string[]): CrossFinding[] {
+  const out: CrossFinding[] = [];
+  for (const u of units) out.push(...crosscheckUnit(cwd, u));
+  out.push(...crosscheckShared(cwd));
+  return out;
+}