@sungen/driver-data-factory 3.2.12-beta.1 → 3.2.12-beta.11

package/src/catalog-loader.ts

@@ -14,7 +14,7 @@ import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { parse as parseYaml } from 'yaml';
-import type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning } from './types';
+import type { Catalog, FieldType, SecurityBank, Technique, Experience, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance } from './types';
 
 /** Resolve the packaged `common/` dir (works from src/ in dev via tsx and from dist/ when built). */
 export function commonDir(): string {
@@ -49,30 +49,70 @@ export function loadShippedCatalog(root = commonDir()): Catalog {
   for (const { data } of readYamlFilesDeep(join(root, 'techniques'))) {
     if (data?.technique) techniques[data.technique] = data as Technique;
   }
-  return { fieldTypes, security, techniques };
+  const experience: Record<string, Experience> = {};
+  for (const { data } of readYamlFilesDeep(join(root, 'experience'))) {
+    if (data?.experience) experience[data.experience] = data as Experience;
+  }
+  return { fieldTypes, security, techniques, experience };
 }
 
-/** Merge a field-type's group by DataPoint.id — overlay entries replace same-id, new ids append. */
-function mergeGroup(base: DataPoint[] = [], overlay: DataPoint[] = []): DataPoint[] {
+/**
+ * Merge a field-type group by DataPoint.id, honoring three explicit operations:
+ *   - EXTEND: an overlay id not in `base` is appended (`added`).
+ *   - REPLACE: an overlay id already in `base` wins (`replaced`).
+ *   - DISABLE: an id in `disableSet` is dropped (`disabled`).
+ * Records provenance and stamps each point's `source` so a reader can trace where it came from.
+ */
+function mergeGroup(
+  base: DataPoint[] = [],
+  overlay: DataPoint[] = [],
+  disableSet: Set<string>,
+  prov: FieldTypeProvenance,
+): DataPoint[] {
   const byId = new Map<string, DataPoint>();
-  for (const dp of base) byId.set(dp.id, dp);
-  for (const dp of overlay) byId.set(dp.id, { ...byId.get(dp.id), ...dp });
+  for (const dp of base) byId.set(dp.id, { ...dp, source: 'shipped' });
+  for (const dp of overlay) {
+    if (byId.has(dp.id)) prov.replaced.push(dp.id);
+    else prov.added.push(dp.id);
+    byId.set(dp.id, { ...byId.get(dp.id), ...dp, source: 'overwrite' });
+  }
+  for (const id of disableSet) {
+    if (byId.delete(id)) prov.disabled.push(id);
+  }
   return [...byId.values()];
 }
 
-function mergeFieldType(base: FieldType, overlay: Partial<FieldType>): FieldType {
+/** An overlay field-type entry may carry a `disable:` list of ids alongside partial field-type data. */
+type FieldTypeOverlay = Partial<FieldType> & { disable?: string[] };
+
+function mergeFieldType(base: FieldType, overlay: FieldTypeOverlay, prov: FieldTypeProvenance): FieldType {
+  const disableSet = new Set(overlay.disable || []);
+  const constraintsOverridden = Object.keys(overlay.constraints || {}).filter(
+    (k) => (base.constraints || {})[k] !== (overlay.constraints || {})[k],
+  );
+  prov.constraintsOverridden = constraintsOverridden;
+  prov.securityChanged = overlay.uses_security != null;
+  const { disable: _disable, ...rest } = overlay;
   return {
     ...base,
-    ...overlay,
+    ...rest,
     constraints: { ...(base.constraints || {}), ...(overlay.constraints || {}) },
     uses_security: overlay.uses_security ?? base.uses_security,
-    valid: mergeGroup(base.valid, overlay.valid),
-    boundary: mergeGroup(base.boundary, overlay.boundary),
-    invalid: mergeGroup(base.invalid, overlay.invalid),
+    valid: mergeGroup(base.valid, overlay.valid, disableSet, prov),
+    boundary: mergeGroup(base.boundary, overlay.boundary, disableSet, prov),
+    invalid: mergeGroup(base.invalid, overlay.invalid, disableSet, prov),
     notes: [...(base.notes || []), ...(overlay.notes || [])],
   };
 }
 
+/** Merge a security bank by payload id (same rules: replace same-id, append new). */
+function mergeSecurity(base: SecurityBank, overlay: Partial<SecurityBank>): SecurityBank {
+  const byId = new Map<string, any>();
+  for (const p of base.payloads || []) byId.set(p.id, p);
+  for (const p of overlay.payloads || []) byId.set(p.id, { ...byId.get(p.id), ...p });
+  return { ...base, ...overlay, payloads: [...byId.values()] };
+}
+
 /**
  * Load the effective catalog = shipped common + project overwrite overlay.
  * `projectDir` is the QA repo root; overlay is read from `qa/data-factory/common.overwrite.yaml`.
@@ -80,22 +120,33 @@ function mergeFieldType(base: FieldType, overlay: Partial<FieldType>): FieldType
 export function loadEffectiveCatalog(projectDir: string, root = commonDir()): {
   catalog: Catalog;
   warnings: OverwriteWarning[];
+  provenance: CatalogProvenance;
 } {
   const shipped = loadShippedCatalog(root);
   const overlayPath = join(projectDir, 'qa', 'data-factory', 'common.overwrite.yaml');
   const warnings: OverwriteWarning[] = [];
-  if (!existsSync(overlayPath)) return { catalog: shipped, warnings };
+  const provenance: CatalogProvenance = { fieldTypes: {}, newFieldTypes: [], security: { added: [], replaced: [] }, techniques: { added: [], replaced: [] } };
+  if (!existsSync(overlayPath)) return { catalog: shipped, warnings, provenance };
 
   const overlay = parseYaml(readFileSync(overlayPath, 'utf8')) || {};
-  const overlayFieldTypes: Record<string, Partial<FieldType>> = overlay.fieldTypes || overlay['field-types'] || {};
+  const overlayFieldTypes: Record<string, FieldTypeOverlay> = overlay.fieldTypes || overlay['field-types'] || {};
   const merged: Catalog = {
     fieldTypes: { ...shipped.fieldTypes },
     security: { ...shipped.security },
     techniques: { ...shipped.techniques },
+    experience: { ...shipped.experience },
   };
+
   for (const [type, ov] of Object.entries(overlayFieldTypes)) {
     if (merged.fieldTypes[type]) {
-      merged.fieldTypes[type] = mergeFieldType(merged.fieldTypes[type], ov);
+      const prov: FieldTypeProvenance = { type, disabled: [], replaced: [], added: [], constraintsOverridden: [], securityChanged: false };
+      // Warn on a disable target that does not exist in the shipped field-type (likely a typo/stale id).
+      const known = new Set([...(merged.fieldTypes[type].valid || []), ...(merged.fieldTypes[type].boundary || []), ...(merged.fieldTypes[type].invalid || [])].map((d) => d.id));
+      for (const id of ov.disable || []) {
+        if (!known.has(id)) warnings.push({ fieldType: type, detail: `disable target "${id}" does not exist in the shipped "${type}" catalog`, suggestion: `remove the stale id from the "${type}".disable list in qa/data-factory/common.overwrite.yaml` });
+      }
+      merged.fieldTypes[type] = mergeFieldType(merged.fieldTypes[type], ov, prov);
+      provenance.fieldTypes[type] = prov;
       // Drift warning: overlay references a security bank the shipped common no longer has.
       for (const bank of ov.uses_security || []) {
         if (!merged.security[bank]) {
@@ -108,10 +159,45 @@ export function loadEffectiveCatalog(projectDir: string, root = commonDir()): {
       }
     } else {
       // Wholly new field-type from the user — accept as-is (project-specific type).
-      merged.fieldTypes[type] = ov as FieldType;
+      const { disable: _d, ...rest } = ov;
+      merged.fieldTypes[type] = rest as FieldType;
+      provenance.newFieldTypes.push(type);
     }
   }
-  return { catalog: merged, warnings };
+
+  // Security-bank overrides (`security:` in the overwrite) — replace same-id payloads, append new banks.
+  const overlaySecurity: Record<string, Partial<SecurityBank>> = overlay.security || {};
+  for (const [cls, ov] of Object.entries(overlaySecurity)) {
+    if (merged.security[cls]) { merged.security[cls] = mergeSecurity(merged.security[cls], ov); provenance.security.replaced.push(cls); }
+    else { merged.security[cls] = { class: cls, payloads: [], ...ov } as SecurityBank; provenance.security.added.push(cls); }
+  }
+
+  // Technique overrides (`techniques:` in the overwrite) — shallow replace/add by name.
+  const overlayTech: Record<string, Partial<Technique>> = overlay.techniques || {};
+  for (const [name, ov] of Object.entries(overlayTech)) {
+    if (merged.techniques[name]) { merged.techniques[name] = { ...merged.techniques[name], ...ov }; provenance.techniques.replaced.push(name); }
+    else { merged.techniques[name] = { technique: name, ...ov } as Technique; provenance.techniques.added.push(name); }
+  }
+
+  return { catalog: merged, warnings, provenance };
+}
+
+/** Human-readable one-liners describing what `.overwrite` changed (for lint/sensor "no silent overwrite"). */
+export function describeProvenance(p: CatalogProvenance): string[] {
+  const lines: string[] = [];
+  for (const ft of Object.values(p.fieldTypes)) {
+    const parts: string[] = [];
+    if (ft.disabled.length) parts.push(`disabled ${ft.disabled.join(', ')}`);
+    if (ft.replaced.length) parts.push(`replaced ${ft.replaced.join(', ')}`);
+    if (ft.added.length) parts.push(`added ${ft.added.join(', ')}`);
+    if (ft.constraintsOverridden.length) parts.push(`constraints[${ft.constraintsOverridden.join(', ')}]`);
+    if (ft.securityChanged) parts.push('uses_security replaced');
+    if (parts.length) lines.push(`${ft.type}: ${parts.join('; ')}`);
+  }
+  for (const t of p.newFieldTypes) lines.push(`${t}: new project field-type`);
+  if (p.security.replaced.length || p.security.added.length) lines.push(`security: ${[...p.security.replaced.map((s) => `replaced ${s}`), ...p.security.added.map((s) => `added ${s}`)].join('; ')}`);
+  if (p.techniques.replaced.length || p.techniques.added.length) lines.push(`techniques: ${[...p.techniques.replaced.map((s) => `replaced ${s}`), ...p.techniques.added.map((s) => `added ${s}`)].join('; ')}`);
+  return lines;
 }
 
 /** Stable hash of the shipped common — recorded in df-manifest.json to detect update drift. */

package/src/cli.ts

@@ -10,13 +10,35 @@ 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 { coverageUnit } from './coverage';
+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). */
@@ -47,17 +69,24 @@ 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'; }
 
   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
@@ -95,10 +124,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();
       ensureDataFactoryReadme(cwd);
-      if (opts.screen) { await genOne(cwd, opts.screen, opts); return; }
+      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;
@@ -115,7 +150,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.`);
     });
 
@@ -123,9 +158,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);
@@ -133,7 +174,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 ? '⚠' : '✓';
@@ -146,12 +187,138 @@ 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 + coverage Gate: testcase ↔ data agree (no dangling {{var}}, shared datasets identical) AND the authored data COVERS the required BVA + the login experience checklist')
+    .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 { catalog } = loadEffectiveCatalog(cwd);
+      const findings = [
+        ...names.flatMap((n) => crosscheckUnit(cwd, n)),
+        ...(opts.screen ? [] : crosscheckShared(cwd)),
+        ...names.flatMap((n) => coverageUnit(cwd, n, catalog)),
+      ];
+      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 as any).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 + _violation column)')
+    .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();
@@ -165,12 +332,18 @@ export function registerDataFactoryCommand(program: any): void {
       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'); console.log(`  ✓ wrote ${p.replace(cwd + '/', '')} (${res.headers.length} columns)`); }
+      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),
+  };
+}