@sungen/driver-data-factory 3.2.12-beta.5 → 3.2.12-beta.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-data-factory",
-  "version": "3.2.12-beta.5",
+  "version": "3.2.12-beta.7",
   "description": "Sungen Data Factory capability — standardized test-data generation from a field-type + security knowledge catalog (valid/boundary/invalid + traceability), the .overwrite merge layer, and (opt-in) @dataFactory runtime seeding. Design-time knowledge is runtime-free. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,7 +14,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.12-beta.5",
+    "@sun-asterisk/sungen": "3.2.12-beta.7",
     "yaml": "^2.4.0"
   },
   "files": [

package/src/cli.ts

@@ -12,6 +12,9 @@ import { createInterface } from 'readline';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { loadEffectiveCatalog, describeProvenance } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
+import { buildRequest, fingerprint } from './contract';
+import { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, hasDatasource } from './state';
+import { crosscheckUnit, crosscheckShared } from './crosscheck';
 import { lintFieldMap, summarize } from './lint';
 import { validateGenerated } from './validate';
 import { generateFixture } from './fixture';
@@ -78,6 +81,10 @@ async function genOne(cwd: string, name: string, opts: { force?: boolean; ctx?:
   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
@@ -228,12 +235,61 @@ export function registerDataFactoryCommand(program: any): void {
       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)')
+    .action((opts: { recipe?: string }) => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      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();
@@ -247,12 +303,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),
+  };
+}

package/src/crosscheck.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 {}; }
+}
+
+/** 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('_')));
+
+  // 1. Dangling vars — a {{var}} whose root key is absent from test-data.
+  for (const v of referencedVars(feature)) {
+    if (!topKeys.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;
+}

package/src/fixture.ts

@@ -6,9 +6,11 @@
  * Export` checklist area. Two products:
  *   • the VALID fixture  — N rows of valid values (should import cleanly). Unique fields get a
  *     per-row suffix so rows don't collide.
- *   • the INVALID fixture — one row per field's first invalid case (all-valid except that one field),
- *     plus a trailing `_violation` column naming the field + reason + expected error — so a row-level
- *     import-rejection test knows which row should fail and why.
+ *   • the INVALID fixture — one row per field's first invalid case (all-valid except that one field).
+ *     It carries the SAME headers as the valid file (no extra column) so a schema-strict importer
+ *     fails on the DATA, not on an unexpected column. The "which row is bad and why" lives in a
+ *     SIDECAR (`<name>.invalid.expected.yaml`), keyed by 0-based data-row index — the expected result
+ *     never alters the payload under test.
  *
  * Deterministic: same field-map + catalog → same CSV. Columns are the flattened leaf paths (nested
  * groups → dotted headers, e.g. `address.city`). Reference the file from an `@api` upload (`files:`)
@@ -31,7 +33,11 @@ function leaves(expanded: ExpandedField[], prefix = ''): Leaf[] {
 }
 
 const validOf = (f: ExpandedField): string => f.points.find((p) => p.group === 'valid' && p.value != null)?.value ?? '';
-const firstInvalid = (f: ExpandedField) => f.points.find((p) => p.group === 'invalid' && p.value != null);
+// First concrete invalid, preferring a plain (non-adversarial) format/boundary invalid over a
+// security payload — a bulk-import row-rejection test wants a data violation, not an injection string.
+const firstInvalid = (f: ExpandedField) =>
+  f.points.find((p) => p.group === 'invalid' && p.category !== 'adversarial' && p.value != null) ??
+  f.points.find((p) => p.group === 'invalid' && p.value != null);
 
 /** RFC-4180-ish CSV cell quoting. */
 function cell(v: string): string {
@@ -41,9 +47,23 @@ function row(cells: string[]): string {
   return cells.map(cell).join(',');
 }
 
+/** One expected-rejection entry in the sidecar, keyed to a 0-based data row of the invalid CSV. */
+export interface ExpectedRow {
+  row: number;
+  field: string;
+  chk: string;
+  reason: string;
+  expected_error?: string;
+}
+export interface FixtureExpected {
+  _note: string;
+  rows: ExpectedRow[];
+}
+
 export interface FixtureResult {
   valid: string;               // CSV text (header + N valid rows)
-  invalid?: string;            // CSV text (header + _violation + one bad row per field)
+  invalid?: string;            // CSV text (SAME headers as valid + one bad row per field — no extra column)
+  expected?: FixtureExpected;  // sidecar: per-row expected rejection (0-based data-row index)
   headers: string[];
 }
 
@@ -62,18 +82,30 @@ export function generateFixture(map: FieldMap, catalog: Catalog, opts: { rows?:
   const valid = [row(headers), ...validRows].join('\n') + '\n';
 
   let invalid: string | undefined;
+  let expected: FixtureExpected | undefined;
   if (opts.includeInvalid) {
-    const invHeaders = [...headers, '_violation'];
     const invRows: string[] = [];
+    const expectedRows: ExpectedRow[] = [];
     for (const target of ls) {
       const bad = firstInvalid(target.field);
       if (!bad) continue; // no concrete invalid value to seed
+      // Same columns as the valid file — only the target cell is bad. No `_violation` column: a
+      // schema-strict importer must fail on the data, not reject the file for an unexpected column.
       const cells = ls.map((l) => (l === target ? (bad.value as string) : validOf(l.field).replace(/\{\{\$timestamp\}\}/g, '1')));
-      const why = `${target.path}: ${bad.reason || 'invalid'}${bad.expectedError ? ` (${bad.expectedError})` : ''}`;
-      invRows.push(row([...cells, why]));
+      expectedRows.push(trimExpected({ row: invRows.length, field: target.path, chk: bad.id, reason: bad.reason || 'invalid', expected_error: bad.expectedError }));
+      invRows.push(row(cells));
     }
-    invalid = [row(invHeaders), ...invRows].join('\n') + '\n';
+    invalid = [row(headers), ...invRows].join('\n') + '\n';
+    expected = {
+      _note: 'Each row of the .invalid.csv should be REJECTED. `row` is the 0-based data-row index (header excluded). The CSV carries no extra columns so a strict importer fails on the data, not the schema.',
+      rows: expectedRows,
+    };
   }
 
-  return { valid, invalid, headers };
+  return { valid, invalid, expected, headers };
+}
+
+function trimExpected(e: ExpectedRow): ExpectedRow {
+  if (e.expected_error == null) { const { expected_error, ...rest } = e; return rest as ExpectedRow; }
+  return e;
 }

package/src/index.ts

@@ -28,9 +28,15 @@ export type { ValidationFinding } from './validate';
 export { expandBoundaryHint, satisfiesConstraints } from './boundary';
 export type { Validity, BoundaryPoint } from './boundary';
 export { evaluateWhen, inProfile, fieldFacts } from './applicability';
+export { generate, buildRequest, validateRequest, fingerprint, GENERATOR_VERSION, SCHEMA_VERSION } from './contract';
+export type { DataFactoryRequest, DataFactoryResult } from './contract';
+export { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, topoSort, hasDatasource } from './state';
+export type { StateRecipe, StateResource, StatePlan, StateFinding, Provenance, Lifecycle } from './state';
+export { crosscheckUnit, crosscheckShared, crosscheckAll, referencedVars } from './crosscheck';
+export type { CrossFinding } from './crosscheck';
 export { registerDataFactoryCommand } from './cli';
 export { generateFixture } from './fixture';
-export type { FixtureResult } from './fixture';
+export type { FixtureResult, FixtureExpected, ExpectedRow } from './fixture';
 export { dataFactoryCoverageSensor } from './sensor';
 export { dfPreconditionCodegen } from './precondition';
 export type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance, SelectionContext, Profile } from './types';

package/src/state.ts

@@ -0,0 +1,178 @@
+/**
+ * Data Factory — domain/stateful data, Layer 0: the DECLARATION (M3-A).
+ *
+ * Grounded in a real spec-only project (`examples/nextjp`, web-only, no datasource): domain/stateful
+ * preconditions are everywhere in spec + viewpoint, and QA already writes them by hand in prose + tags
+ * (e.g. "requires a valid, unused reset token ≤24h; seeded via fixture / prior flow; where it cannot be
+ * seeded, treat as @manual"). This module standardizes that: a `state-recipe` (entity graph + relations
+ * + desired state + bindings + lifecycle + PROVENANCE) becomes a reviewable, traceable **manual
+ * precondition** rendered into the testcase — working with only spec + viewpoint, no DB/API, no Core.
+ *
+ * Layer 1 (opt-in runtime provisioning) reuses the SAME declaration where an api/db datasource exists;
+ * this file does not execute anything — it validates + renders the declaration deterministically.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml } from 'yaml';
+
+/** WHERE a resource's state comes from — NOT only api/db (nextjp: prior-flow / fixture / manual dominate). */
+export type Provenance = 'prior-flow' | 'fixture' | 'client-storage' | 'server-context' | 'api' | 'db' | 'manual';
+export type Lifecycle = 'reusable' | 'unique-per-run' | 'consumable' | 'leased' | 'expiring' | 'mutable-state';
+
+const PROVENANCES: Provenance[] = ['prior-flow', 'fixture', 'client-storage', 'server-context', 'api', 'db', 'manual'];
+const LIFECYCLES: Lifecycle[] = ['reusable', 'unique-per-run', 'consumable', 'leased', 'expiring', 'mutable-state'];
+/** Provenances that need a runtime datasource — Layer 1. The rest resolve at design time (Layer 0). */
+const RUNTIME_PROVENANCE = new Set<Provenance>(['api', 'db']);
+
+export interface StateResource {
+  ref: string;
+  entity: string;
+  provenance?: Provenance;      // default 'manual'
+  provider?: string;            // @api:x / @query:x — required only for api/db provenance (Layer 1)
+  transition?: string;          // endpoint that moves the entity to desiredState (Layer 1)
+  dependsOn?: string[];
+  with?: Record<string, unknown>;
+  desiredState?: string;
+  lifecycle?: Lifecycle;
+  note?: string;
+}
+
+export interface StateRecipe {
+  name: string;
+  description?: string;
+  resources?: StateResource[];
+  bindings?: Record<string, string>;
+  cleanup?: string | { keep: true; reason: string };
+  /** 1b — cross-screen flow-shared dataset: `entity`'s data is shared verbatim across `screens`. */
+  shared?: { entity: string; screens: string[] };
+}
+
+export interface StateFinding {
+  recipe: string;
+  severity: 'error' | 'warn' | 'info';
+  code: string;
+  message: string;
+}
+
+export interface StatePlan {
+  recipe: string;
+  /** Topologically ordered resources (dependencies first). */
+  order: string[];
+  resources: StateResource[];
+  bindings: Record<string, string>;
+  /** True when NO resource can be auto-provisioned here (no api/db provenance, or missing datasource). */
+  manual: boolean;
+  /** The identity pairs a shared dataset implies (for the Cross-artifact Gate). */
+  sharedIdentity?: { entity: string; screens: string[] };
+  /** Human-readable precondition lines (Gherkin Given/And) for weaving into a Background. */
+  preconditionLines: string[];
+  cleanup?: string;
+}
+
+/** Load state-recipes (recipes with a `resources` graph) from qa/data-factory/recipes.yaml. */
+export function loadStateRecipes(cwd: string): StateRecipe[] {
+  const p = join(cwd, 'qa', 'data-factory', 'recipes.yaml');
+  if (!existsSync(p)) return [];
+  const doc = parseYaml(readFileSync(p, 'utf8')) || {};
+  const recipes = doc.recipes || {};
+  const out: StateRecipe[] = [];
+  for (const [name, r] of Object.entries<any>(recipes)) {
+    if (r && (Array.isArray(r.resources) || r.shared)) out.push({ name, ...r });
+  }
+  return out;
+}
+
+/** Topologically sort resources by dependsOn. Returns { order, cycle } — cycle non-empty ⇒ error. */
+export function topoSort(resources: StateResource[]): { order: string[]; cycle: string[] } {
+  const byRef = new Map(resources.map((r) => [r.ref, r]));
+  const state = new Map<string, 0 | 1 | 2>(); // 0=unseen,1=in-stack,2=done
+  const order: string[] = [];
+  let cycle: string[] = [];
+  const visit = (ref: string, stack: string[]): boolean => {
+    const s = state.get(ref) || 0;
+    if (s === 2) return true;
+    if (s === 1) { cycle = [...stack.slice(stack.indexOf(ref)), ref]; return false; }
+    state.set(ref, 1);
+    for (const dep of byRef.get(ref)?.dependsOn || []) {
+      if (!byRef.has(dep)) continue; // dangling dep reported separately
+      if (!visit(dep, [...stack, ref])) return false;
+    }
+    state.set(ref, 2);
+    order.push(ref);
+    return true;
+  };
+  for (const r of resources) if (!visit(r.ref, [])) break;
+  return { order, cycle };
+}
+
+/** Validate a state-recipe (structure only — no runtime). */
+export function validateStateRecipe(recipe: StateRecipe): StateFinding[] {
+  const out: StateFinding[] = [];
+  const F = (severity: StateFinding['severity'], code: string, message: string) => out.push({ recipe: recipe.name, severity, code, message });
+  const resources = recipe.resources || [];
+  const refs = new Set(resources.map((r) => r.ref));
+  if (!resources.length && !recipe.shared) F('warn', 'EMPTY', 'recipe has neither resources nor a shared dataset');
+  for (const r of resources) {
+    if (!r.ref) F('error', 'NO_REF', 'a resource has no `ref`');
+    if (!r.entity) F('error', 'NO_ENTITY', `resource "${r.ref}" has no \`entity\``);
+    if (r.provenance && !PROVENANCES.includes(r.provenance)) F('error', 'BAD_PROVENANCE', `resource "${r.ref}" provenance "${r.provenance}" ∉ ${PROVENANCES.join('|')}`);
+    if (r.lifecycle && !LIFECYCLES.includes(r.lifecycle)) F('error', 'BAD_LIFECYCLE', `resource "${r.ref}" lifecycle "${r.lifecycle}" ∉ ${LIFECYCLES.join('|')}`);
+    for (const dep of r.dependsOn || []) if (!refs.has(dep)) F('error', 'DANGLING_DEP', `resource "${r.ref}" dependsOn "${dep}" which is not a resource`);
+    // api/db provenance needs a provider endpoint (Layer 1); others must NOT pretend to auto-provision.
+    if (RUNTIME_PROVENANCE.has(r.provenance as Provenance) && !r.provider) F('error', 'NO_PROVIDER', `resource "${r.ref}" provenance "${r.provenance}" needs a \`provider\` endpoint (@api:/@query:)`);
+    if (r.desiredState && !r.transition && RUNTIME_PROVENANCE.has(r.provenance as Provenance)) F('warn', 'NO_TRANSITION', `resource "${r.ref}" desiredState "${r.desiredState}" has no \`transition\` endpoint — Layer 1 cannot move it automatically`);
+  }
+  // Bindings must reference a real ${ref.field}.
+  for (const [k, v] of Object.entries(recipe.bindings || {})) {
+    const m = /^\$\{([^.}]+)\.[^}]+\}$/.exec(String(v));
+    if (!m) F('warn', 'BINDING_SHAPE', `binding "${k}: ${v}" is not of the form \${ref.field}`);
+    else if (!refs.has(m[1])) F('error', 'BINDING_REF', `binding "${k}" references unknown resource "${m[1]}"`);
+  }
+  const { cycle } = topoSort(resources);
+  if (cycle.length) F('error', 'CYCLE', `dependsOn cycle: ${cycle.join(' → ')}`);
+  return out;
+}
+
+const article = (w: string) => (/^[aeiou]/i.test(w) ? 'an' : 'a');
+
+/** Build the deterministic plan + the human-readable precondition block for a state-recipe. */
+export function buildStatePlan(recipe: StateRecipe, opts: { datasource?: boolean } = {}): StatePlan {
+  const resources = (recipe.resources || []).map((r) => ({ provenance: 'manual' as Provenance, ...r }));
+  const { order } = topoSort(resources);
+  const ordered = order.length ? order.map((ref) => resources.find((r) => r.ref === ref)!) : resources;
+  // A resource is auto-provisionable only when its provenance is api/db AND a datasource is configured.
+  const autoable = (r: StateResource) => RUNTIME_PROVENANCE.has(r.provenance as Provenance) && !!opts.datasource;
+  const manual = ordered.length > 0 && !ordered.every(autoable);
+
+  const lines: string[] = [];
+  for (const r of ordered) {
+    const withStr = r.with && Object.keys(r.with).length ? '  ' + Object.entries(r.with).map(([k, v]) => `${k}=${v}`).join(', ') : '';
+    const owner = (r.dependsOn || []).length ? ` owned by ${r.dependsOn!.join('/')}` : '';
+    const stateStr = r.desiredState ? ` in state "${r.desiredState}"` : '';
+    const meta = `[provenance: ${r.provenance}${r.lifecycle ? `; lifecycle: ${r.lifecycle}` : ''}${autoable(r) ? `; auto: ${r.provider}` : ''}]`;
+    lines.push(`Given ${article(r.entity)} ${r.entity} "${r.ref}"${owner} exists${stateStr}  ${meta}${withStr}`);
+  }
+  for (const [k, v] of Object.entries(recipe.bindings || {})) lines.push(`# binding: ${k} ← ${v}`);
+
+  return {
+    recipe: recipe.name,
+    order: ordered.map((r) => r.ref),
+    resources: ordered,
+    bindings: recipe.bindings || {},
+    manual,
+    ...(recipe.shared ? { sharedIdentity: recipe.shared } : {}),
+    preconditionLines: lines,
+    cleanup: typeof recipe.cleanup === 'string' ? recipe.cleanup : recipe.cleanup ? `keep — ${recipe.cleanup.reason}` : undefined,
+  };
+}
+
+/** Whether the project has a datasource (⇒ Layer 1 possible). */
+export function hasDatasource(cwd: string): boolean {
+  return existsSync(join(cwd, 'datasources.yaml')) || existsSync(join(cwd, 'qa', 'datasources.yaml'));
+}
+
+/** Render the precondition block for weaving into a Gherkin Background (with the @manual tag if needed). */
+export function renderPreconditionBlock(plan: StatePlan): string {
+  const tag = plan.manual ? '# @manual:data-setup — required state (auto-provisions when an api/db datasource is added)' : '# required state (Layer 1: auto-provisioned via the referenced endpoints)';
+  return [`${tag}`, `# recipe: ${plan.recipe}`, ...plan.preconditionLines].join('\n');
+}