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

package/common/experience/auth-account-states.yaml

@@ -0,0 +1,19 @@
+# Experience checklist: authentication credential / account states — from real login-testing experience.
+# These are LOGIN/AUTH *scenarios*, NOT field-format data: each case is a credential pair whose ACCOUNT
+# is in a particular state, with an expected auth outcome. Most need a domain-state PRECONDITION (a
+# seeded account in that state) — declare it with a state-recipe (`sungen data state`) so it renders a
+# @manual:data-setup Background. Data Factory carries this knowledge; create-test's login viewpoint
+# generates the scenarios. Confirm the exact outcome/message code with the spec/BA — never assume.
+experience: auth-account-states
+description: Credential/account states a login (email+password or credential form) screen must cover.
+applies_when: "a login / sign-in / authentication screen (credential form)"
+cases:
+  - { id: CHK-AUTH-01, state: active, expect: "login succeeds → authenticated destination", note: "happy path — a valid ACTIVE account" }
+  - { id: CHK-AUTH-02, state: wrong-password, expect: "auth fails with a generic error (no user-enumeration)" }
+  - { id: CHK-AUTH-03, state: non-existent-account, expect: "auth fails with the SAME generic error as wrong-password (don't reveal which is wrong)" }
+  - { id: CHK-AUTH-04, state: soft-deleted, expect: "login REJECTED — a soft-deleted account must NOT authenticate", note: "real-world bug precedent: soft-deleted rows still passing auth because the query didn't filter deleted_at" }
+  - { id: CHK-AUTH-05, state: locked-or-suspended, expect: "login blocked with a locked/suspended message (not the generic auth error)" }
+  - { id: CHK-AUTH-06, state: unverified-email, expect: "login blocked or routed to verification, per spec" }
+  - { id: CHK-AUTH-07, state: password-expired, expect: "routed to password reset / forced change, per spec" }
+  - { id: CHK-AUTH-08, state: valid-with-surrounding-whitespace, expect: "email trimmed then login succeeds (pair a valid account email with leading/trailing spaces)", note: "trim behaviour — see the email field-type CHK-EMAIL-WS" }
+oracle: "Each non-happy state needs a seeded account IN that state (a domain-state precondition / fixture). The 'wrong-password' and 'non-existent' outcomes should be indistinguishable (anti-enumeration). soft-deleted / locked / unverified / expired must each be blocked with the correct, spec-defined outcome."

package/common/field-types/currency.yaml

@@ -14,7 +14,7 @@ boundary:
 invalid:
   - { id: CHK-CUR-I1, gen: "alphabetic / stray characters", reason: "not a number", errorRef: M13 }
   - { id: CHK-CUR-I2, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
-  - { id: CHK-CUR-I3, value: "", reason: "empty (per spec)", errorRef: M02 }
+  - { id: CHK-CUR-I3, value: "", reason: "empty (per spec)", errorRef: M02, when: { required: true } }
 notes:
   - "Check separately: leading zero (0100) not stripped; thousands separator display format."
 uses_security: [sqli]

package/common/field-types/email.yaml

@@ -16,6 +16,9 @@ boundary:
   - { id: CHK-EMAIL-B1, gen: "local part = maxLocal", note: "local part = max (64)" }
   - { id: CHK-EMAIL-B2, gen: "local part = maxLocal-1", note: "local part = max-1" }
   - { id: CHK-EMAIL-B3, gen: "total = maxTotal", note: "total length = max (255)" }
+  # min-length side (total = minLength / minLength±1) is auto-completed by the BVA pass from the
+  # field-map's `minLength` — see ensureBvaComplete; no gen entry needed here.
+  - { id: CHK-EMAIL-WS, value: " user@example.com ", validity: valid, note: "leading/trailing whitespace — server MUST trim then accept (pair with a valid password); if the spec rejects instead, override validity to invalid" }
 invalid:
   - { id: CHK-EMAIL-I1, value: "user@", reason: "missing domain", errorRef: M13 }
   - { id: CHK-EMAIL-I2, value: "user@.com", reason: "dot in wrong position", errorRef: M13 }
@@ -24,7 +27,7 @@ invalid:
   - { id: CHK-EMAIL-I5, value: "ｕｓｅｒ@example.com", reason: "full-width characters", errorRef: M39 }
   - { id: CHK-EMAIL-I6, gen: "local > maxLocal", reason: "exceeds maxLocal", errorRef: M13 }
   - { id: CHK-EMAIL-I7, gen: "total > maxTotal", reason: "exceeds maxTotal", errorRef: M13 }
-  - { id: CHK-EMAIL-I8, value: "", reason: "empty (required)", errorRef: M02 }
+  - { id: CHK-EMAIL-I8, value: "", reason: "empty (required)", errorRef: M02, when: { required: true } }
 notes:
   - "Normalize: lowercase, NFKC, trim before comparison."
   - "Soft-delete: if a deleted email gets a suffix appended, test maxTotal LOWER than the DB column limit to leave room for the suffix."

package/common/field-types/number-float.yaml

@@ -16,5 +16,5 @@ invalid:
   - { id: CHK-FLOAT-I1, gen: "alphabetic characters", reason: "not a number", errorRef: M13 }
   - { id: CHK-FLOAT-I2, gen: "wrong format (multiple dots, +/- wrong position)", reason: "wrong format", errorRef: M13 }
   - { id: CHK-FLOAT-I3, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
-  - { id: CHK-FLOAT-I4, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
+  - { id: CHK-FLOAT-I4, value: "", reason: "empty/multi-space (per spec)", errorRef: M02, when: { required: true } }
 uses_security: [sqli]

package/common/field-types/number-integer.yaml

@@ -6,7 +6,7 @@ constraints:
   max: 2147483647 # placeholder
 valid:
   - { id: CHK-INT-01, value: "123", note: "digits only" }
-  - { id: CHK-INT-02, value: "-45", note: "leading - (if spec allows negatives)" }
+  - { id: CHK-INT-02, value: "-45", note: "leading - (if spec allows negatives)", when: { negativesAllowed: true } }
 boundary:
   - { id: CHK-INT-B1, gen: "min / min+1" }
   - { id: CHK-INT-B2, gen: "max / max-1" }
@@ -15,7 +15,7 @@ invalid:
   - { id: CHK-INT-I2, gen: "full-width (Japanese) digits", reason: "full-width characters", errorRef: M39 }
   - { id: CHK-INT-I3, gen: "+/- in wrong position (mid-string)", reason: "wrong format", errorRef: M13 }
   - { id: CHK-INT-I4, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
-  - { id: CHK-INT-I5, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
+  - { id: CHK-INT-I5, value: "", reason: "empty/multi-space (per spec)", errorRef: M02, when: { required: true } }
 notes:
   - "Check leading zero (007) is not stripped; redundant spaces before/after handled correctly."
 uses_security: [sqli]

package/common/field-types/password.yaml

@@ -17,7 +17,7 @@ boundary:
   - { id: CHK-PW-B3, gen: "max length", note: "max" }
   - { id: CHK-PW-B4, gen: "max-1", note: "max-1" }
 invalid:
-  - { id: CHK-PW-I1, value: "", reason: "empty/multi-space (required)", errorRef: M02 }
+  - { id: CHK-PW-I1, value: "", reason: "empty/multi-space (required)", errorRef: M02, when: { required: true } }
   - { id: CHK-PW-I2, gen: "< min length", reason: "below minimum length", errorRef: M29 }
   - { id: CHK-PW-I3, gen: "> max length", reason: "exceeds maximum length", errorRef: M30 }
   - { id: CHK-PW-I4, value: "passw0rd", reason: "missing uppercase", errorRef: M31 }

package/common/field-types/phone.yaml

@@ -19,5 +19,5 @@ invalid:
   - { id: CHK-PHONE-I4, value: "090 123 4567", reason: "spaces between digits", errorRef: M13 }
   - { id: CHK-PHONE-I5, gen: "+/- not first; () wrong position", reason: "wrong format", errorRef: M13 }
   - { id: CHK-PHONE-I6, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }
-  - { id: CHK-PHONE-I7, value: "", reason: "empty/multi-space (per spec)", errorRef: M02 }
+  - { id: CHK-PHONE-I7, value: "", reason: "empty/multi-space (per spec)", errorRef: M02, when: { required: true } }
 uses_security: [sqli]

package/common/field-types/postcode.yaml

@@ -12,5 +12,5 @@ boundary:
 invalid:
   - { id: CHK-ZIP-I1, gen: "alphabetic / stray characters", reason: "invalid characters", errorRef: M13 }
   - { id: CHK-ZIP-I2, gen: "wrong region format", reason: "wrong format", errorRef: M13 }
-  - { id: CHK-ZIP-I3, value: "", reason: "empty (per spec)", errorRef: M02 }
+  - { id: CHK-ZIP-I3, value: "", reason: "empty (per spec)", errorRef: M02, when: { required: true } }
 uses_security: [sqli]

package/common/field-types/string.yaml

@@ -16,5 +16,5 @@ boundary:
   - { id: CHK-STR-B1, gen: "min / min+1 length" }
   - { id: CHK-STR-B2, gen: "max / max-1 length" }
 invalid:
-  - { id: CHK-STR-I1, value: "", reason: "empty/multi-space (success/fail per spec)", errorRef: M02 }
+  - { id: CHK-STR-I1, value: "", reason: "empty/multi-space (success/fail per spec)", errorRef: M02, when: { required: true } }
   - { id: CHK-STR-I2, gen: "min-1 / max+1", reason: "out of bounds", errorRef: M13 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-data-factory",
-  "version": "3.2.12-beta.1",
+  "version": "3.2.12-beta.11",
   "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",
@@ -9,12 +9,12 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
-    "test": "tsx tests/run.ts"
+    "test": "tsx tests/run.ts && tsx tests/golden.ts"
   },
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.12-beta.1",
+    "@sun-asterisk/sungen": "3.2.12-beta.11",
     "yaml": "^2.4.0"
   },
   "files": [

package/src/applicability.ts

@@ -0,0 +1,80 @@
+/**
+ * Data Factory — applicability (M2b).
+ *
+ * A catalog case is not universally applicable: an "empty (required)" invalid means nothing for an
+ * OPTIONAL field, a negative-number example only applies when the field allows negatives, a katakana
+ * or locale-specific case only applies under that locale, and a security payload is an *adversarial*
+ * case that belongs in its own bucket rather than mixed into plain `invalid`. Both reviews flagged
+ * this: the driver must return `not-applicable` (with a reason) instead of silently emitting a case
+ * that doesn't fit — and it must let Core (or a CLI flag) select a reduced profile.
+ *
+ * Pure + deterministic. Field-derived predicates (`required`, `negativesAllowed`) are always enforced;
+ * environment predicates (`locale`, `channel`, `sink`) only filter when the context supplies them.
+ */
+import type { DataPoint, SelectionContext, Profile } from './types';
+import type { FieldDef } from './generator';
+
+export interface FieldFacts {
+  required?: boolean;
+  min?: number;
+}
+
+export interface Applicability {
+  applicable: boolean;
+  /** Why it was excluded — shown to the QA ("not-applicable, không âm thầm sinh data"). */
+  reason?: string;
+}
+
+/** Evaluate a point's `when` conditions against the field facts + selection context. */
+export function evaluateWhen(when: Record<string, unknown> | undefined, facts: FieldFacts, ctx: SelectionContext): Applicability {
+  if (!when) return { applicable: true };
+  // Field-derived: always enforced (a definite field fact can rule the case out).
+  if (when.required === true && facts.required === false) {
+    return { applicable: false, reason: 'requires a required field; this field is optional' };
+  }
+  if (when.negativesAllowed === true && Number.isFinite(facts.min) && (facts.min as number) >= 0) {
+    return { applicable: false, reason: `requires negatives (min < 0); this field has min=${facts.min}` };
+  }
+  // Environment-derived: only filter when the context supplies the axis (else permissive).
+  if (typeof when.locale === 'string' && ctx.locale && !ctx.locale.toLowerCase().startsWith(String(when.locale).toLowerCase())) {
+    return { applicable: false, reason: `locale ${when.locale} ≠ context ${ctx.locale}` };
+  }
+  if (typeof when.channel === 'string' && ctx.channel && ctx.channel !== when.channel) {
+    return { applicable: false, reason: `channel ${when.channel} ≠ context ${ctx.channel}` };
+  }
+  if (typeof when.sink === 'string' && ctx.sink && ctx.sink !== when.sink) {
+    return { applicable: false, reason: `sink ${when.sink} ≠ context ${ctx.sink}` };
+  }
+  return { applicable: true };
+}
+
+/** Field facts the field-derived predicates read (required + numeric min after constraint merge). */
+export function fieldFacts(field: FieldDef, mergedConstraints: Record<string, any>): FieldFacts {
+  const min = mergedConstraints.min;
+  return { required: field.required, min: typeof min === 'number' ? min : undefined };
+}
+
+/**
+ * Is a point kept under the chosen profile? (Applied AFTER `when` applicability.) Rule-based over
+ * group + category, so it needs no per-point tagging:
+ *   - regression (default): everything.
+ *   - functional: valid + boundary + non-adversarial invalid (drops security/adversarial).
+ *   - smoke: valid + boundary (the "does it work" set — no invalid, no adversarial).
+ *   - security-min: valid + adversarial (security sanity).
+ */
+export function inProfile(group: 'valid' | 'boundary' | 'invalid', category: string | undefined, profile: Profile | undefined): boolean {
+  const adversarial = category === 'adversarial';
+  switch (profile) {
+    case undefined:
+    case 'regression':
+      return true;
+    case 'functional':
+      return !adversarial;
+    case 'smoke':
+      return group === 'valid' || group === 'boundary';
+    case 'security-min':
+      return group === 'valid' || adversarial;
+    default:
+      return true;
+  }
+}

package/src/boundary.ts

@@ -0,0 +1,319 @@
+/**
+ * Data Factory — structured boundary expansion + the deterministic validity oracle.
+ *
+ * This replaces the old prose-parsing (`hint.includes('min')`) that produced semantically WRONG data:
+ *   - password `< min` (minLength 7) synthesized a 7-char string — which is VALID, not the invalid
+ *     "below minimum" case it claims to be;
+ *   - integer `min / min+1` collapsed to a single value, dropping one of the two boundary cases.
+ *
+ * A boundary/invalid hint is tokenized into one or more BoundaryPoints — one case per point
+ * (`min / min+1` → two, `min-1 / max+1` → two) — each carrying the value AND its expected validity,
+ * computed by the same oracle that later re-checks the value. So "the rule says valid" and "the value
+ * actually satisfies the constraints" can never silently disagree (that disagreement is a golden-test
+ * failure). Pure, deterministic; no runtime, no LLM.
+ */
+
+export type Validity = 'valid' | 'invalid';
+
+export interface BoundaryPoint {
+  /** Id suffix so one catalog point can expand to several: '' (first), 'b', 'c', … */
+  suffix: string;
+  value: string | null;
+  /** What the oracle expects this value to be — locked by golden tests against the real check. */
+  validity: Validity;
+  /** Human label for the point, e.g. 'min', 'min+1', 'max+1', 'length-1'. */
+  label: string;
+  todo?: string;
+}
+
+const STR_TYPES = new Set(['string', 'password', 'phone', 'postcode', 'katakana']);
+const NUM_TYPES = new Set(['number-integer', 'number-float', 'currency']);
+
+/** Deterministic filler: a string of exactly `n` chars from a charset seed. */
+export function fillLen(n: number, base = 'a'): string {
+  if (!Number.isFinite(n) || n <= 0) return '';
+  return base.repeat(Math.ceil(n / base.length)).slice(0, n);
+}
+
+/** Password seed that satisfies upper+lower+digit for any length ≥ 3. */
+function fillPassword(n: number): string {
+  if (n <= 0) return '';
+  // Prefix guarantees the character classes; pad with lowercase to reach n.
+  const prefix = 'Aa1';
+  if (n <= prefix.length) return prefix.slice(0, n);
+  return prefix + 'a'.repeat(n - prefix.length);
+}
+
+function seedFor(type: string): string {
+  return type === 'password' ? 'PW' : type === 'katakana' ? 'ア' : type === 'phone' || type === 'postcode' ? '0' : 'a';
+}
+
+function fillString(type: string, n: number): string {
+  return type === 'password' ? fillPassword(n) : fillLen(n, seedFor(type));
+}
+
+/** Precision step for a numeric type: 1 for integers/currency(0dp), 10^-dp for floats. */
+function step(type: string, c: Record<string, any>): number {
+  if (type === 'number-float' || (type === 'currency' && Number.isFinite(c.decimalPlaces) && c.decimalPlaces > 0)) {
+    const dp = Number.isFinite(c.decimalPlaces) ? c.decimalPlaces : 2;
+    return Number((1 / Math.pow(10, dp)).toFixed(dp));
+  }
+  return 1;
+}
+
+/** Round to the type's decimal places so we don't emit float noise like 999999.9899999999. */
+function fmtNum(type: string, c: Record<string, any>, n: number): string {
+  if (type === 'number-float' || (type === 'currency' && c.decimalPlaces > 0)) {
+    const dp = Number.isFinite(c.decimalPlaces) ? c.decimalPlaces : 2;
+    return n.toFixed(dp);
+  }
+  return String(Math.round(n));
+}
+
+/** Split a prose hint into per-point segments: "min / min+1" → ["min","min+1"]. */
+function segments(hint: string): string[] {
+  return hint
+    .split(/[/,]/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** Resolve a single segment to a signed offset off min/max: "< min" → {base:'min',off:-1}. */
+function readOffset(seg: string): { base: 'min' | 'max' | 'length' | null; off: number; label: string } {
+  const s = seg.toLowerCase();
+  const base: 'min' | 'max' | 'length' | null =
+    /\bmax\b|maximum|maxlength|maxlocal|maxtotal/.test(s) ? 'max'
+    : /\bmin\b|minimum|minlength/.test(s) ? 'min'
+    : /exact|length|byte/.test(s) ? 'length'
+    : null;
+  // Offset: explicit ±1 wins; then relational (< / over / exceeds → out-of-range).
+  let off = 0;
+  if (/\+\s*1|plus one|one extra/.test(s)) off = 1;
+  else if (/-\s*1|minus one/.test(s)) off = -1;
+  else if (/<|below|under|less than|shorter/.test(s)) off = -1;
+  else if (/>|over|above|exceed|greater than|longer|too long/.test(s)) off = 1;
+  const sign = off > 0 ? '+1' : off < 0 ? '-1' : '';
+  const label = (base || 'bound') + sign;
+  return { base, off, label };
+}
+
+/**
+ * Expand a length-bounded string hint into one BoundaryPoint per segment.
+ * min/max come from the constraints; a point OUTSIDE [min,max] is invalid, inside/on-edge is valid.
+ */
+function expandLength(type: string, hint: string, c: Record<string, any>): BoundaryPoint[] {
+  const min = c.minLength ?? c.length ?? c.minlength;
+  const max = c.maxLength ?? c.length ?? c.maxlength;
+  const segs = segments(hint);
+  const out: BoundaryPoint[] = [];
+  let idx = 0;
+  for (const seg of segs) {
+    const { base, off, label } = readOffset(seg);
+    const anchor = base === 'max' ? max : base === 'length' ? (c.length ?? max ?? min) : min;
+    if (!Number.isFinite(anchor)) {
+      out.push({ suffix: suffixOf(idx++), value: null, validity: base === null ? 'valid' : 'valid', label, todo: 'minLength/maxLength/length' });
+      continue;
+    }
+    const n = anchor + off;
+    const lo = Number.isFinite(min) ? min : 0;
+    const hi = Number.isFinite(max) ? max : Infinity;
+    const validity: Validity = n >= lo && n <= hi && n >= 1 ? 'valid' : 'invalid';
+    out.push({ suffix: suffixOf(idx++), value: fillString(type, Math.max(0, n)), validity, label });
+  }
+  return out.length ? out : [{ suffix: '', value: null, validity: 'valid', label: 'bound', todo: 'minLength/maxLength' }];
+}
+
+/** Expand a numeric value hint. Float/currency use a precision step, not a fixed ±1. */
+function expandNumeric(type: string, hint: string, c: Record<string, any>): BoundaryPoint[] {
+  const min = c.min, max = c.max;
+  const st = step(type, c);
+  const segs = segments(hint);
+  const out: BoundaryPoint[] = [];
+  let idx = 0;
+  for (const seg of segs) {
+    const s = seg.toLowerCase();
+    // Decimal-places boundary (float): "exact decimal places" valid; "one extra digit" invalid.
+    if (/decimal|precision|extra digit/.test(s)) {
+      const dp = Number.isFinite(c.decimalPlaces) ? c.decimalPlaces : 2;
+      if (/extra|one extra|\+1|too many/.test(s)) {
+        out.push({ suffix: suffixOf(idx++), value: '0.' + '1'.repeat(dp + 1), validity: 'invalid', label: `decimalPlaces+1` });
+      } else {
+        out.push({ suffix: suffixOf(idx++), value: '0.' + '1'.repeat(Math.max(1, dp)), validity: 'valid', label: `decimalPlaces` });
+      }
+      continue;
+    }
+    const { base, off, label } = readOffset(seg);
+    const anchor = base === 'max' ? max : min;
+    if (!Number.isFinite(anchor)) {
+      out.push({ suffix: suffixOf(idx++), value: null, validity: 'valid', label, todo: 'min/max' });
+      continue;
+    }
+    const n = anchor + off * st;
+    const lo = Number.isFinite(min) ? min : -Infinity;
+    const hi = Number.isFinite(max) ? max : Infinity;
+    const validity: Validity = n >= lo && n <= hi ? 'valid' : 'invalid';
+    out.push({ suffix: suffixOf(idx++), value: fmtNum(type, c, n), validity, label });
+  }
+  return out.length ? out : [{ suffix: '', value: null, validity: 'valid', label: 'bound', todo: 'min/max' }];
+}
+
+/** Build an email at a target local or total length while honoring BOTH maxLocal and maxTotal. */
+function synthEmail(c: Record<string, any>, which: 'maxLocal' | 'maxTotal', off: number): string | null {
+  const maxLocal = Number(c.maxLocal);
+  const maxTotal = Number(c.maxTotal);
+  if (which === 'maxLocal') {
+    if (!Number.isFinite(maxLocal)) return null;
+    const localLen = Math.max(1, maxLocal + off);
+    return fillLen(localLen) + '@example.com';
+  }
+  // maxTotal: keep the local part ≤ maxLocal, pad the DOMAIN to reach the total length.
+  if (!Number.isFinite(maxTotal)) return null;
+  const total = maxTotal + off;
+  const localLen = Number.isFinite(maxLocal) ? Math.min(maxLocal, 24) : 24;
+  const fixed = 1 /* @ */ + 4 /* .com */;
+  const subLen = total - localLen - fixed;
+  if (subLen < 1) return fillLen(Math.max(1, total - fixed)) + '@x.io'.slice(0, Math.max(4, fixed));
+  return fillLen(localLen) + '@' + fillLen(subLen) + '.com';
+}
+
+/** Expand an email length hint (single point per catalog entry today, but honors both constraints). */
+function expandEmail(hint: string, c: Record<string, any>): BoundaryPoint[] {
+  const segs = segments(hint);
+  const out: BoundaryPoint[] = [];
+  let idx = 0;
+  for (const seg of segs) {
+    const { off, label } = readOffset(seg);
+    const s = seg.toLowerCase();
+    const which: 'maxLocal' | 'maxTotal' = /total/.test(s) ? 'maxTotal' : 'maxLocal';
+    const value = synthEmail(c, which, off);
+    if (value == null) { out.push({ suffix: suffixOf(idx++), value: null, validity: 'valid', label, todo: which }); continue; }
+    const validity: Validity = satisfiesEmail(value, c) ? 'valid' : 'invalid';
+    out.push({ suffix: suffixOf(idx++), value, validity, label: `${which}${off > 0 ? '+1' : off < 0 ? '-1' : ''}` });
+  }
+  return out.length ? out : [{ suffix: '', value: null, validity: 'valid', label: 'bound', todo: 'maxLocal/maxTotal' }];
+}
+
+function suffixOf(i: number): string {
+  return i === 0 ? '' : String.fromCharCode(96 + i); // 0→'' , 1→'a', 2→'b', … (id becomes CHK-INT-B1, CHK-INT-B1a, …)
+}
+
+/**
+ * Public entry: expand a boundary/invalid hint into structured points.
+ * Returns one point per segment; each carries the value AND the oracle's expected validity.
+ */
+export function expandBoundaryHint(hint: string, type: string, c: Record<string, any>): BoundaryPoint[] {
+  if (type === 'email') return expandEmail(hint, c);
+  if (STR_TYPES.has(type)) return expandLength(type, hint, c);
+  if (NUM_TYPES.has(type)) return expandNumeric(type, hint, c);
+  return [{ suffix: '', value: null, validity: 'valid', label: 'bound', todo: 'value/gen not resolvable' }];
+}
+
+// ---- The validity oracle: does a value structurally satisfy the constraints? --------------------
+
+export function satisfiesEmail(value: string, c: Record<string, any>): boolean {
+  const at = value.indexOf('@');
+  if (at <= 0 || at === value.length - 1) return false;
+  const local = value.slice(0, at);
+  if (Number.isFinite(c.maxLocal) && local.length > c.maxLocal) return false;
+  if (Number.isFinite(c.maxTotal) && value.length > c.maxTotal) return false;
+  // Total-length MIN (a spec often sets an email min length, e.g. 5) — the oracle must enforce it so a
+  // below-min email is correctly INVALID (was ignored → the min boundary silently missing).
+  const minTotal = c.minLength ?? c.minTotal;
+  if (Number.isFinite(minTotal) && value.length < minTotal) return false;
+  return true;
+}
+
+/** Build an email of exactly `n` total chars (for the total-length MIN boundary — small n). */
+export function emailOfTotalLength(n: number): string | null {
+  if (!Number.isFinite(n) || n < 1) return null;
+  if (n < 3) return 'a'.repeat(n);              // too short to be a real address → malformed (below-min case)
+  const rest = n - 2;                            // chars after "a@"
+  if (rest < 3) return 'a@' + 'b'.repeat(rest);  // e.g. n=4 → "a@bb" (no dot → also malformed, below-min)
+  return 'a@' + 'b'.repeat(rest - 2) + '.c';     // e.g. n=5 → "a@b.c", n=6 → "a@bb.c"
+}
+
+function satisfiesLength(type: string, value: string, c: Record<string, any>): boolean {
+  const min = c.minLength ?? c.length;
+  const max = c.maxLength ?? c.length;
+  if (Number.isFinite(min) && value.length < min) return false;
+  if (Number.isFinite(max) && value.length > max) return false;
+  return true;
+}
+
+function satisfiesNumeric(type: string, value: string, c: Record<string, any>): boolean {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return false;
+  if (Number.isFinite(c.min) && n < c.min) return false;
+  if (Number.isFinite(c.max) && n > c.max) return false;
+  if ((type === 'number-integer') && !Number.isInteger(n)) return false;
+  if ((type === 'number-float' || type === 'currency') && Number.isFinite(c.decimalPlaces)) {
+    const dec = (value.split('.')[1] || '').length;
+    if (dec > c.decimalPlaces) return false;
+  }
+  return true;
+}
+
+/**
+ * The oracle. Given a concrete value and the constraints, decide whether it structurally satisfies
+ * them (length/range/precision — NOT charset/format, which the catalog encodes as literal invalids).
+ * Returns null when the type has no numeric/length constraint to check against (nothing to assert).
+ */
+export function satisfiesConstraints(type: string, value: string | null, c: Record<string, any>): boolean | null {
+  if (value == null) return null;
+  if (type === 'email') return satisfiesEmail(value, c);
+  if (STR_TYPES.has(type)) {
+    if (!Number.isFinite(c.minLength ?? c.length) && !Number.isFinite(c.maxLength ?? c.length)) return null;
+    return satisfiesLength(type, value, c);
+  }
+  if (NUM_TYPES.has(type)) {
+    if (!Number.isFinite(c.min) && !Number.isFinite(c.max) && !Number.isFinite(c.decimalPlaces)) return null;
+    return satisfiesNumeric(type, value, c);
+  }
+  return null;
+}
+
+// ---- BVA completeness: every bounded dimension gets its full min-1/min/min+1/max-1/max/max+1 set ----
+
+export interface BvaExtra { label: string; value: string; validity: Validity; group: 'boundary' | 'invalid'; }
+
+/**
+ * Ensure the canonical Boundary-Value-Analysis set is present for EVERY bounded dimension declared in
+ * the constraints — even one the field-type's catalog `gen:` entries don't exercise. This closes the
+ * QA-reported gap: email declared `minLength: 5` but the catalog only modelled maxLocal/maxTotal, so
+ * the min side (length 4 = min-1 invalid, 5 = min, 6 = min+1) was silently missing. Emits only the
+ * MISSING points (dedup by exact value), so a type whose catalog already covers a dimension (string /
+ * password / number) yields nothing — no churn.
+ */
+export function ensureBvaComplete(type: string, c: Record<string, any>, existing: Array<string | null>): BvaExtra[] {
+  const have = new Set(existing.filter((v): v is string => v != null));
+  const out: BvaExtra[] = [];
+  const push = (label: string, value: string | null) => {
+    if (value == null || have.has(value)) return;
+    const ok = satisfiesConstraints(type, value, c);
+    const validity: Validity = ok === false ? 'invalid' : 'valid';
+    out.push({ label, value, validity, group: validity === 'invalid' ? 'invalid' : 'boundary' });
+    have.add(value);
+  };
+  if (type === 'email') {
+    const minTotal = c.minLength ?? c.minTotal;
+    if (Number.isFinite(minTotal)) {
+      push('minTotal-1', emailOfTotalLength((minTotal as number) - 1));
+      push('minTotal', emailOfTotalLength(minTotal as number));
+      push('minTotal+1', emailOfTotalLength((minTotal as number) + 1));
+    }
+    return out;
+  }
+  if (STR_TYPES.has(type)) {
+    const min = c.minLength ?? c.length, max = c.maxLength ?? c.length;
+    if (Number.isFinite(min)) { push('minLen-1', fillString(type, min - 1)); push('minLen', fillString(type, min)); push('minLen+1', fillString(type, min + 1)); }
+    if (Number.isFinite(max)) { push('maxLen-1', fillString(type, max - 1)); push('maxLen', fillString(type, max)); push('maxLen+1', fillString(type, max + 1)); }
+    return out;
+  }
+  if (NUM_TYPES.has(type)) {
+    const min = c.min, max = c.max, st = step(type, c);
+    if (Number.isFinite(min)) { push('min-1', fmtNum(type, c, min - st)); push('min', fmtNum(type, c, min)); push('min+1', fmtNum(type, c, min + st)); }
+    if (Number.isFinite(max)) { push('max-1', fmtNum(type, c, max - st)); push('max', fmtNum(type, c, max)); push('max+1', fmtNum(type, c, max + st)); }
+    return out;
+  }
+  return out;
+}