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

package/src/detect.ts

@@ -0,0 +1,122 @@
+/**
+ * Data Factory — auto-detection (Layer A of the auto-orchestration design).
+ *
+ * Makes Sungen NOTICE what test-data work a unit needs, without QA having to know to run a command:
+ *   - a unit that HAS input fields but has NO field-map → its data was never standardized;
+ *   - a spec that describes a STATEFUL PRECONDITION (a required entity/state) with no state-recipe and
+ *     no Background/@manual precondition → the stateful setup is undeclared.
+ * Both are surfaced as advisory findings at `sungen generate`/`sungen audit` (the DF advisory sensor).
+ * Deterministic heuristics over spec.md + the feature; no runtime, no LLM. Advisory only — a nudge +
+ * an auto-draft prompt, never a hard fail (the fuzzy precondition scan must not block).
+ */
+import { join } from 'path';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { loadStateRecipes } from './state';
+
+export interface DetectFinding {
+  code: 'UNSTANDARDIZED' | 'PRECONDITION_UNDECLARED';
+  scenario: string;
+  message: string;
+  severity: 'warn' | 'info';
+}
+
+function readIfExists(path: string): string {
+  try { return existsSync(path) ? readFileSync(path, 'utf8') : ''; } catch { return ''; }
+}
+
+function readSpec(dir: string): string {
+  return readIfExists(join(dir, 'requirements', 'spec.md'));
+}
+
+function readFeature(dir: string): string {
+  const fdir = join(dir, 'features');
+  if (!existsSync(fdir)) return '';
+  try {
+    return readdirSync(fdir).filter((f) => f.endsWith('.feature')).map((f) => readIfExists(join(fdir, f))).join('\n');
+  } catch { return ''; }
+}
+
+/**
+ * Does the unit take user input? Strongest signal: a Gherkin `fill [X] field` / `type` step; plus a
+ * spec field table row typed as input/select/textarea. A pure navigation / list / capture screen has
+ * none → we must NOT nag it ("no input fields → nothing to generate").
+ */
+export function hasInputFields(specText: string, featureText: string): boolean {
+  if (/\b(fill|type|enter|input|select|choose)\b\s+\[[^\]]+\]\s*(field|input|dropdown|textbox)?/i.test(featureText)) return true;
+  if (/\|\s*(input|select|textarea|checkbox|radio|combobox)\b/i.test(specText)) return true;
+  if (/\binput\s*\(|\bselect\s*\(|\btextarea\b/i.test(specText)) return true;
+  return false;
+}
+
+/** A field-map exists for this unit. */
+export function hasFieldMap(cwd: string, name: string): boolean {
+  return existsSync(join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`));
+}
+
+/** Precondition signal phrases — a spec sentence hinting the test needs a pre-existing entity/state. */
+const PRECONDITION_SIGNALS = [
+  'requires', 'required before', 'precondition', 'pre-condition', 'prerequisite',
+  'logged in', 'authenticated', 'signed in', 'must be logged',
+  'already exists', 'already registered', 'existing ', 'pre-existing', 'must exist',
+  'reset token', 'verification', 'provisional account', 'session-storage', 'session storage',
+  'buffer', 'seeded', 'must have', 'previously', 'valid token', 'auth token',
+];
+
+/** Extract spec sentences that look like a stateful precondition (deduped, capped). */
+export function detectPreconditionSignals(specText: string): string[] {
+  if (!specText) return [];
+  const hits: string[] = [];
+  const seen = new Set<string>();
+  // Split into sentence-ish units (lines / bullet items / sentences).
+  const units = specText.split(/\n|(?<=[.。])\s+/).map((s) => s.replace(/\s+/g, ' ').trim()).filter(Boolean);
+  for (const u of units) {
+    const low = u.toLowerCase();
+    // Skip markdown headings/table separators, and spec-template meta lines (US labels, rationale)
+    // that mention auth/priority only descriptively — not an actual precondition.
+    if (/^#{1,6}\s|^\|?\s*-{3,}/.test(u)) continue;
+    if (/^\*\*(why|independent test|acceptance|business context|target users|priority)\b/i.test(u)) continue;
+    if (/\bpriority\b/i.test(low) && /\bp[0-9]\b/i.test(low)) continue;
+    const sig = PRECONDITION_SIGNALS.find((s) => low.includes(s));
+    if (sig) {
+      const key = low.slice(0, 60);
+      if (!seen.has(key)) { seen.add(key); hits.push(u.length > 160 ? u.slice(0, 157) + '…' : u); }
+    }
+    if (hits.length >= 4) break;
+  }
+  return hits;
+}
+
+/** Is a stateful precondition already declared — a state-recipe with resources, or a Background/@manual? */
+export function hasStateDeclaration(cwd: string, featureText: string): boolean {
+  if (/^\s*Background:/m.test(featureText) || /@manual\b/.test(featureText)) return true;
+  return loadStateRecipes(cwd).some((r) => (r.resources && r.resources.length) || r.shared);
+}
+
+/** Run Layer-A detection for one unit dir. Returns advisory findings (possibly empty). */
+export function detectUnit(cwd: string, dir: string, name: string): DetectFinding[] {
+  const spec = readSpec(dir);
+  const feature = readFeature(dir);
+  const out: DetectFinding[] = [];
+
+  // 1. Inputs exist but never standardized.
+  if (!hasFieldMap(cwd, name) && hasInputFields(spec, feature)) {
+    out.push({
+      code: 'UNSTANDARDIZED',
+      scenario: name,
+      severity: 'warn',
+      message: `DATA-FACTORY-UNSTANDARDIZED: ${name} has input fields but no standardized test-data (no qa/data-factory/${name}.fields.yaml) — run \`/sungen:create-data-test ${name}\` (or it is authored inline by \`/sungen:create-test\`) so values are standardized valid/boundary/invalid, not hand-invented.`,
+    });
+  }
+
+  // 2. Stateful precondition described in the spec but not declared anywhere.
+  const signals = detectPreconditionSignals(spec);
+  if (signals.length && !hasStateDeclaration(cwd, feature)) {
+    out.push({
+      code: 'PRECONDITION_UNDECLARED',
+      scenario: name,
+      severity: 'info',
+      message: `DATA-FACTORY-PRECONDITION-UNDECLARED: ${name}'s spec describes a stateful precondition but the test declares none (no state-recipe, no Background/@manual). Declare it with a state-recipe + \`sungen data state\` so it renders a @manual:data-setup Background. Signals: ${signals.map((s) => `"${s}"`).join('; ')}`,
+    });
+  }
+  return out;
+}

package/src/fixture.ts

@@ -0,0 +1,111 @@
+/**
+ * Data Factory — CSV/file fixture generator (5b).
+ *
+ * Turns a field-map into a **bulk-import fixture file** (a CSV whose columns are the fields and whose
+ * rows are standardized data), for testing CSV/Excel import, bulk upload, etc. — the `CSV / Import /
+ * 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).
+ *     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:`)
+ * or a UI file-input step.
+ */
+import type { Catalog } from './types';
+import { expandFieldMap, type FieldMap, type ExpandedField } from './generator';
+
+interface Leaf { path: string; field: ExpandedField }
+
+/** Flatten nested groups to leaf fields with dotted-path headers. */
+function leaves(expanded: ExpandedField[], prefix = ''): Leaf[] {
+  const out: Leaf[] = [];
+  for (const f of expanded) {
+    const path = prefix ? `${prefix}.${f.name}` : f.name;
+    if (f.children) out.push(...leaves(f.children, path));
+    else out.push({ path, field: f });
+  }
+  return out;
+}
+
+const validOf = (f: ExpandedField): string => f.points.find((p) => p.group === 'valid' && p.value != null)?.value ?? '';
+// 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 {
+  return /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+}
+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 (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[];
+}
+
+/** Build the CSV fixture(s) from a field-map. */
+export function generateFixture(map: FieldMap, catalog: Catalog, opts: { rows?: number; includeInvalid?: boolean } = {}): FixtureResult {
+  const rows = Math.max(1, opts.rows ?? 3);
+  const ls = leaves(expandFieldMap(map, catalog));
+  const headers = ls.map((l) => l.path);
+
+  // VALID rows — resolve the valid value per field; a `unique` field's `{{$timestamp}}` token is a
+  // runtime var, not valid in a static file, so replace it with the row index to keep rows distinct.
+  const validRows: string[] = [];
+  for (let i = 1; i <= rows; i++) {
+    validRows.push(row(ls.map((l) => validOf(l.field).replace(/\{\{\$timestamp\}\}/g, String(i)))));
+  }
+  const valid = [row(headers), ...validRows].join('\n') + '\n';
+
+  let invalid: string | undefined;
+  let expected: FixtureExpected | undefined;
+  if (opts.includeInvalid) {
+    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')));
+      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(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, 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/generator.ts

@@ -9,17 +9,37 @@
  * payloads, and resolving placeholder error codes through the field's `errorMap`. Same input →
  * same output (determinism is an asset). Nothing here reads a live page or an LLM.
  */
-import type { Catalog, FieldType, DataPoint } from './types';
+import type { Catalog, FieldType, DataPoint, SelectionContext } from './types';
+import { expandBoundaryHint, satisfiesConstraints, ensureBvaComplete, type Validity } from './boundary';
+import { evaluateWhen, fieldFacts, inProfile } from './applicability';
 
 export interface FieldDef {
   name: string;
-  /** Catalog field-type id (email/password/…). A type absent from the catalog → blind spot. */
-  type: string;
+  /** Catalog field-type id (email/password/…). Omit for a GROUP (a field with nested `fields`). A type absent from the catalog → blind spot. */
+  type?: string;
   required?: boolean;
   /** Project overrides merged over the catalog constraints (maxLength, min, max, …). */
   constraints?: Record<string, any>;
   /** Placeholder errorRef (Mxx) → real project message code. Unmapped refs are flagged open. */
   errorMap?: Record<string, string>;
+  /**
+   * Field must be fresh/unique per test run (e.g. a register email/username that can't collide
+   * with a record left by a previous run). When true, the VALID value(s) get a runtime `{{$timestamp}}`
+   * suffix so `resolveDynamicVars` produces a new value every run — no cross-run cache, no flakiness.
+   */
+  unique?: boolean;
+  /**
+   * Nested / group field (complex form): sub-fields expanded recursively under this name
+   * (e.g. `address` → `city`, `postcode`). A field with `fields` is a group and needs no `type`.
+   */
+  fields?: FieldDef[];
+  /**
+   * Inter-field dependency: this field's rule/format depends on another field's value
+   * (e.g. postcode format `dependsOn: { field: country, value: JP }`). Carried through as metadata
+   * so the scenario weave + QA honor the relationship — the generator does not resolve the runtime
+   * condition (that is scenario/@cases logic), it records it.
+   */
+  dependsOn?: { field: string; value?: string };
 }
 
 export interface FieldMap {
@@ -39,85 +59,64 @@ export interface ExpandedPoint {
   open?: boolean;
   /** Value could not be synthesized deterministically (missing constraint) — needs input. */
   todo?: string;
+  /**
+   * The generator's expectation for this value: does it satisfy the field's constraints (`valid`) or
+   * violate them (`invalid`)? Computed by the boundary oracle for synthesized points; `valid` for the
+   * happy-path group and `invalid` for declared-invalid values. `validateGenerated` re-checks it — a
+   * mismatch (a `valid`-expected value that fails the constraints, or vice versa) is a defect.
+   */
+  expectedValidity?: Validity;
+  /**
+   * True when the VALUE was synthesized from a numeric/length boundary (so its whole validity claim is
+   * about range). The validator only second-guesses an `invalid` point when it is synthesized — a
+   * literal charset/format invalid (or a security payload) legitimately satisfies the length oracle.
+   */
+  synthesized?: boolean;
+  /** Provenance: `overwrite` when the project's `.overwrite` replaced/added this point (else shipped). */
+  source?: 'shipped' | 'overwrite';
+  /** Bucket: `adversarial` = a security/injection payload (rendered separately from plain invalid). */
+  category?: 'adversarial';
 }
 
 export interface ExpandedField {
   name: string;
-  type: string;
+  type?: string;
   blindSpot: boolean;
   points: ExpandedPoint[];
+  /** Nested sub-fields (a group field). When present, `points` is empty and children hold the data. */
+  children?: ExpandedField[];
+  /** Recorded inter-field dependency (metadata only — not resolved deterministically). */
+  dependsOn?: { field: string; value?: string };
+  /** Cases NOT materialized for the selection context (applicability) — surfaced, never silent. */
+  excluded?: Array<{ id: string; reason: string }>;
 }
 
-/** Deterministic filler: a string of exactly `n` chars from a charset seed. */
-function fillLen(n: number, base = 'a'): string {
-  if (!Number.isFinite(n) || n <= 0) return '';
-  return base.repeat(n).slice(0, n);
-}
-
-/** Build an email of a given total or local length (half-width), with a boundary offset (-1/0/+1). */
-function synthEmail(constraints: Record<string, any>, which: 'maxLocal' | 'maxTotal', offset = 0): string | null {
-  const domain = '@example.com';
-  if (which === 'maxLocal' && Number.isFinite(constraints.maxLocal)) {
-    return fillLen(constraints.maxLocal + offset) + domain;
-  }
-  if (which === 'maxTotal' && Number.isFinite(constraints.maxTotal)) {
-    const localLen = Math.max(1, constraints.maxTotal + offset - domain.length);
-    return fillLen(localLen) + domain;
+/**
+ * Coerce an out-of-range numeric VALID literal into range, so a project's `valid` representative is
+ * actually valid for its constraints (a generic catalog example like `123` under `max: 100` becomes
+ * `100`). Returns null when in range already, or the type isn't numeric (non-numeric mismatches are
+ * left for the validator to flag — the field-map should supply a fitting value).
+ */
+function coerceValidNumeric(type: string, value: string, c: Record<string, any>): string | null {
+  if (!['number-integer', 'number-float', 'currency'].includes(type)) return null;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  let out = n;
+  if (Number.isFinite(c.min) && out < c.min) out = c.min;
+  if (Number.isFinite(c.max) && out > c.max) out = c.max;
+  if (out === n) return null; // already in range
+  if (type === 'number-float' || (type === 'currency' && c.decimalPlaces > 0)) {
+    const dp = Number.isFinite(c.decimalPlaces) ? c.decimalPlaces : 2;
+    return out.toFixed(dp);
   }
-  return null;
+  return String(Math.round(out));
 }
 
-/** Try to synthesize a boundary/gen value from constraints. Returns null when data is insufficient. */
-function synthesize(dp: DataPoint, type: string, c: Record<string, any>): { value: string | null; todo?: string } {
-  if (dp.value != null) return { value: dp.value };
-  const hint = `${dp.gen || ''} ${dp.note || ''}`.toLowerCase();
-
-  // Email length boundaries. `>` / "vượt" → over-boundary (invalid, offset +1).
-  if (type === 'email') {
-    const over = hint.includes('>') || hint.includes('vượt') || hint.includes('over');
-    const offset = over ? 1 : hint.includes('-1') ? -1 : hint.includes('+1') ? 1 : 0;
-    if (hint.includes('maxlocal') || (hint.includes('local') && (hint.includes('max') || over))) {
-      const v = synthEmail(c, 'maxLocal', offset); return v ? { value: v } : { value: null, todo: 'maxLocal' };
-    }
-    if (hint.includes('maxtotal') || (hint.includes('tổng') && (hint.includes('max') || over)) || (hint.includes('total'))) {
-      const v = synthEmail(c, 'maxTotal', offset); return v ? { value: v } : { value: null, todo: 'maxTotal' };
-    }
-  }
-
-  // String-length types: min / max length boundaries.
-  const strTypes = ['string', 'password', 'phone', 'postcode', 'katakana'];
-  if (strTypes.includes(type)) {
-    const min = c.minLength ?? c.length;
-    const max = c.maxLength ?? c.length;
-    if (hint.includes('min') && Number.isFinite(min)) {
-      const n = hint.includes('+1') ? min + 1 : min;
-      return { value: fillLen(n, type === 'password' ? 'Aa1' : 'a') };
-    }
-    if (hint.includes('max') && Number.isFinite(max)) {
-      const n = hint.includes('-1') ? max - 1 : max;
-      return { value: fillLen(n, type === 'password' ? 'Aa1' : 'a') };
-    }
-    return { value: null, todo: 'minLength/maxLength' };
-  }
-
-  // Numeric types: min / max value boundaries.
-  const numTypes = ['number-integer', 'number-float', 'currency'];
-  if (numTypes.includes(type)) {
-    const min = c.min, max = c.max;
-    if (hint.includes('min') && Number.isFinite(min)) {
-      if (hint.includes('-1')) return { value: String(min - 1) };
-      if (hint.includes('+1')) return { value: String(min + 1) };
-      return { value: String(min) };
-    }
-    if (hint.includes('max') && Number.isFinite(max)) {
-      if (hint.includes('+1')) return { value: String(max + 1) };
-      if (hint.includes('-1')) return { value: String(max - 1) };
-      return { value: String(max) };
-    }
-    return { value: null, todo: 'min/max' };
-  }
-
-  return { value: null, todo: 'value/gen not resolvable' };
+/** A gen hint that references a numeric/length boundary the generator can expand structurally. */
+function isBoundaryHint(hint: string): boolean {
+  return /\bmin\b|\bmax\b|minimum|maximum|length|byte|exact|decimal|precision|local|total|over|below|under|exceed|\+\s*1|-\s*1|<|>/.test(
+    hint.toLowerCase(),
+  );
 }
 
 function resolveError(dp: DataPoint, errorMap?: Record<string, string>): { expectedError?: string; open?: boolean } {
@@ -126,27 +125,119 @@ function resolveError(dp: DataPoint, errorMap?: Record<string, string>): { expec
   return { expectedError: dp.errorRef, open: true }; // placeholder survives; flagged open to confirm
 }
 
+/**
+ * Make a valid value fresh-per-run by injecting a `{{$timestamp}}` token (resolved at runtime by the
+ * TestDataLoader's resolveDynamicVars). Email keeps validity via a `+tag` in the local part; other
+ * types append the token. Deterministic at compile time (same token string) — uniqueness is at run time.
+ */
+function makeUnique(value: string, type: string): string {
+  if (value.includes('{{$')) return value; // already dynamic
+  if (type === 'email' && value.includes('@')) {
+    const at = value.indexOf('@');
+    return `${value.slice(0, at)}+{{$timestamp}}${value.slice(at)}`;
+  }
+  return `${value}{{$timestamp}}`;
+}
+
 /** Expand one field into valid/boundary/invalid data points using the effective catalog. */
-export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
-  const ft: FieldType | undefined = catalog.fieldTypes[field.type];
-  if (!ft) return { name: field.name, type: field.type, blindSpot: true, points: [] };
+export function expandField(field: FieldDef, catalog: Catalog, ctx: SelectionContext = {}): ExpandedField {
+  // Group / nested field: no own type — expand each sub-field recursively.
+  if (field.fields && field.fields.length) {
+    return {
+      name: field.name,
+      type: undefined,
+      blindSpot: false,
+      points: [],
+      children: field.fields.map((sub) => expandField(sub, catalog, ctx)),
+      ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}),
+    };
+  }
+  const ft: FieldType | undefined = field.type ? catalog.fieldTypes[field.type] : undefined;
+  if (!ft) return { name: field.name, type: field.type, blindSpot: true, points: [], ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}) };
 
   const c = { ...(ft.constraints || {}), ...(field.constraints || {}) };
+  const type = field.type as string;
   const points: ExpandedPoint[] = [];
+  const excluded: Array<{ id: string; reason: string }> = [];
+  const facts = fieldFacts(field, c);
 
-  const push = (dp: DataPoint, group: ExpandedPoint['group']) => {
-    const s = synthesize(dp, field.type, c);
-    points.push({
+  // Gate a catalog case by applicability (`when`) then by the selection profile. A `when` miss is
+  // reported as excluded (not silently dropped); a profile miss is an explicit selection (not reported).
+  const admit = (dp: DataPoint, group: ExpandedPoint['group'], category?: 'adversarial'): boolean => {
+    const ap = evaluateWhen(dp.when, facts, ctx);
+    if (!ap.applicable) { excluded.push({ id: dp.id, reason: ap.reason || 'not applicable' }); return false; }
+    return inProfile(group, category, ctx.profile);
+  };
+
+  // Default validity for a group: the happy path is valid; the invalid group is invalid; a boundary
+  // point's validity is decided per-point by the oracle (in/out of range).
+  const groupValidity = (group: ExpandedPoint['group']): Validity => (group === 'invalid' ? 'invalid' : 'valid');
+
+  const emit = (p: Omit<ExpandedPoint, 'expectedValidity'> & { expectedValidity: Validity }) => points.push(p);
+
+  const pushLiteral = (dp: DataPoint, group: ExpandedPoint['group'], value: string | null, opts: { validity?: Validity; label?: string; todo?: string } = {}) => {
+    // A valid representative must be valid for the project: clamp an out-of-range numeric literal.
+    let coerceNote: string | undefined;
+    if (group === 'valid' && value != null && satisfiesConstraints(type, value, c) === false) {
+      const fixed = coerceValidNumeric(type, value, c);
+      if (fixed != null) { value = fixed; coerceNote = 'adjusted to fit constraints'; }
+    }
+    const isUniqueValid = group === 'valid' && field.unique && value != null;
+    const v = isUniqueValid ? makeUnique(value!, type) : value;
+    // Expected validity reflects INTENT by group, so the validator (validateGenerated) can catch a
+    // mismatch against the oracle instead of the mismatch being silently absorbed here:
+    //   - valid group   → `valid` (a value that actually violates the constraints is a VALUE_NOT_VALID).
+    //   - invalid group → `invalid` (declared: charset/format/blocklist/behavior — the length oracle
+    //     cannot "prove" such a literal valid, so it must NOT flip it to valid).
+    //   - boundary group → the oracle decides (that group is precisely about range).
+    let validity: Validity;
+    if (dp.validity) validity = dp.validity;
+    else if (group === 'boundary') {
+      const oracle = satisfiesConstraints(type, isUniqueValid ? value : v, c);
+      validity = oracle == null ? (opts.validity ?? 'valid') : oracle ? 'valid' : 'invalid';
+    } else validity = opts.validity ?? groupValidity(group);
+    emit({
       id: dp.id,
       group,
-      value: s.value,
-      todo: s.todo,
+      value: v,
+      todo: opts.todo,
       reason: dp.reason,
-      note: dp.note,
+      note: isUniqueValid ? `${dp.note ? dp.note + ' · ' : ''}fresh per run` : coerceNote ? `${dp.note ? dp.note + ' · ' : ''}${coerceNote}` : (opts.label ? `${dp.note ? dp.note + ' · ' : ''}${opts.label}` : dp.note),
+      expectedValidity: validity,
+      ...(dp.source === 'overwrite' ? { source: 'overwrite' as const } : {}),
       ...resolveError(dp, field.errorMap),
     });
   };
 
+  const push = (dp: DataPoint, group: ExpandedPoint['group']) => {
+    if (!admit(dp, group)) return; // not applicable / out of profile
+    // Literal value in the catalog/overwrite → one point (oracle still judges its validity).
+    if (dp.value != null) return pushLiteral(dp, group, dp.value);
+
+    const hint = `${dp.gen || ''} ${dp.note || ''}`.trim();
+    // A boundary/length/numeric hint → expand to one case PER boundary point, each with its validity.
+    if (hint && isBoundaryHint(hint)) {
+      const pts = expandBoundaryHint(hint, type, c);
+      for (const bp of pts) {
+        emit({
+          id: dp.id + bp.suffix,
+          group,
+          value: bp.value,
+          todo: bp.todo,
+          reason: dp.reason,
+          note: bp.label && !bp.todo ? `${dp.note ? dp.note + ' · ' : ''}${bp.label}` : dp.note,
+          expectedValidity: dp.validity ?? bp.validity,
+          synthesized: bp.value != null,
+          ...(dp.source === 'overwrite' ? { source: 'overwrite' as const } : {}),
+          ...resolveError(dp, field.errorMap),
+        });
+      }
+      return;
+    }
+    // A non-boundary gen (charset/full-width/format) — can't synthesize deterministically; keep open.
+    pushLiteral(dp, group, null, { validity: groupValidity(group), todo: dp.gen ? `synthesize: ${dp.gen}` : 'value/gen not resolvable' });
+  };
+
   for (const dp of ft.valid || []) push(dp, 'valid');
   for (const dp of ft.boundary || []) push(dp, 'boundary');
   for (const dp of ft.invalid || []) {
@@ -154,11 +245,12 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
     push(dp, 'invalid');
   }
 
-  // Append security payloads referenced by uses_security.
+  // Append security payloads referenced by uses_security — the `adversarial` category (own bucket).
   for (const bank of ft.uses_security || []) {
     const b = catalog.security[bank];
     if (!b) continue;
     for (const p of b.payloads || []) {
+      if (!admit(p as DataPoint, 'invalid', 'adversarial')) continue;
       points.push({
         id: p.id,
         group: 'invalid',
@@ -166,16 +258,43 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
         todo: p.value == null ? `security technique: ${p.technique || bank}` : undefined,
         reason: `${bank}: ${(p.reason as string) || (p.kind as string) || (p.technique as string) || ''}`.trim(),
         note: b.oracle,
+        // Adversarial payloads are treated as invalid input (must be rejected/escaped, never accepted).
+        expectedValidity: 'invalid',
+        category: 'adversarial',
       });
     }
   }
 
-  return { name: field.name, type: field.type, blindSpot: false, points };
+  // BVA completeness: for every bounded dimension in the constraints, ensure the full
+  // min-1/min/min+1/max-1/max/max+1 set exists — auto-adding only what the catalog left out (e.g. an
+  // email `minLength` the catalog didn't model). Only in-range points are `boundary`; out-of-range are
+  // `invalid`. Appended after the catalog cases so it never overrides an authored one.
+  const idCode = type.toUpperCase().replace(/[^A-Z0-9]/g, '');
+  for (const ex of ensureBvaComplete(type, c, points.map((p) => p.value))) {
+    points.push({
+      id: `CHK-${idCode}-BVA-${ex.label}`,
+      group: ex.group,
+      value: ex.value,
+      expectedValidity: ex.validity,
+      synthesized: true,
+      note: `BVA (auto): ${ex.label}`,
+      ...(ex.validity === 'invalid' ? { reason: `out of bounds (${ex.label})` } : {}),
+    });
+  }
+
+  return {
+    name: field.name,
+    type: field.type,
+    blindSpot: false,
+    points,
+    ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}),
+    ...(excluded.length ? { excluded } : {}),
+  };
 }
 
 /** Expand a whole field-map. */
-export function expandFieldMap(map: FieldMap, catalog: Catalog): ExpandedField[] {
-  return (map.fields || []).map((f) => expandField(f, catalog));
+export function expandFieldMap(map: FieldMap, catalog: Catalog, ctx: SelectionContext = {}): ExpandedField[] {
+  return (map.fields || []).map((f) => expandField(f, catalog, ctx));
 }
 
 /**
@@ -186,23 +305,37 @@ export function renderTestData(expanded: ExpandedField[]): Record<string, any> {
   const out: Record<string, any> = {
     _generated_by: 'sungen data gen — standardized test-data (valid/boundary/invalid + CHK trace). Do not hand-edit values; edit the .fields.yaml or common.overwrite.yaml and re-run.',
   };
-  for (const f of expanded) {
-    if (f.blindSpot) {
-      out[f.name] = { _blind_spot: `type "${f.type}" not in Data Factory catalog — provide qa/data-factory/project/${f.name}.yaml` };
-      continue;
-    }
-    const valid = f.points.filter((p) => p.group === 'valid');
-    const boundary = f.points.filter((p) => p.group === 'boundary');
-    const invalid = f.points.filter((p) => p.group === 'invalid');
-    out[f.name] = {
-      valid: valid[0]?.value ?? null,
-      boundary: boundary.map((p) => trim({ id: p.id, value: p.value, note: p.note, todo: p.todo })),
-      invalid: invalid.map((p) => trim({ id: p.id, value: p.value, expected_error: p.expectedError, open: p.open, reason: p.reason, todo: p.todo })),
-    };
-  }
+  for (const f of expanded) out[f.name] = renderOne(f);
   return out;
 }
 
+/** Render one expanded field — recurses for nested groups; carries a dependsOn note. */
+function renderOne(f: ExpandedField): Record<string, any> {
+  const dep = f.dependsOn ? { _depends_on: f.dependsOn.value != null ? `${f.dependsOn.field} = ${f.dependsOn.value}` : f.dependsOn.field } : {};
+  if (f.children) {
+    const group: Record<string, any> = { ...dep };
+    for (const c of f.children) group[c.name] = renderOne(c);
+    return group;
+  }
+  if (f.blindSpot) {
+    return { _blind_spot: `type "${f.type}" not in Data Factory catalog — provide qa/data-factory/project/${f.name}.yaml`, ...dep };
+  }
+  const valid = f.points.filter((p) => p.group === 'valid');
+  const boundary = f.points.filter((p) => p.group === 'boundary');
+  // Plain invalid excludes the adversarial (security) cases — those get their own bucket.
+  const invalid = f.points.filter((p) => p.group === 'invalid' && p.category !== 'adversarial');
+  const adversarial = f.points.filter((p) => p.category === 'adversarial');
+  const row: Record<string, any> = {
+    ...dep,
+    valid: valid[0]?.value ?? null,
+    boundary: boundary.map((p) => trim({ id: p.id, value: p.value, expected: p.expectedValidity, via: p.source === 'overwrite' ? '.overwrite' : undefined, note: p.note, todo: p.todo })),
+    invalid: invalid.map((p) => trim({ id: p.id, value: p.value, expected: p.expectedValidity, via: p.source === 'overwrite' ? '.overwrite' : undefined, expected_error: p.expectedError, open: p.open, reason: p.reason, todo: p.todo })),
+  };
+  if (adversarial.length) row.adversarial = adversarial.map((p) => trim({ id: p.id, value: p.value, reason: p.reason, note: p.note, todo: p.todo }));
+  if (f.excluded?.length) row._not_applicable = f.excluded.map((e) => `${e.id}: ${e.reason}`);
+  return row;
+}
+
 function trim(o: Record<string, any>): Record<string, any> {
   const r: Record<string, any> = {};
   for (const [k, v] of Object.entries(o)) if (v != null) r[k] = v;