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

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

@@ -24,7 +24,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.3",
+  "version": "3.2.12-beta.5",
   "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.3",
+    "@sun-asterisk/sungen": "3.2.12-beta.5",
     "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/catalog-loader.ts

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

package/src/cli.ts

@@ -10,14 +10,30 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from
 import { join, dirname } from 'path';
 import { createInterface } from 'readline';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { loadEffectiveCatalog } from './catalog-loader';
+import { loadEffectiveCatalog, describeProvenance } from './catalog-loader';
 import { expandFieldMap, renderTestData, type FieldMap } from './generator';
 import { lintFieldMap, summarize } from './lint';
 import { validateGenerated } from './validate';
 import { generateFixture } from './fixture';
 import { ensureDataFactoryReadme } from './readme';
+import type { SelectionContext, Profile } from './types';
 
 const FIELDMAP_DIR = (cwd: string) => join(cwd, 'qa', 'data-factory');
+
+const PROFILES: Profile[] = ['regression', 'functional', 'smoke', 'security-min'];
+
+/** Build a SelectionContext from the shared --profile/--locale/--channel/--sink flags. */
+function ctxFromOpts(o: { profile?: string; locale?: string; channel?: string; sink?: string }): SelectionContext {
+  const ctx: SelectionContext = {};
+  if (o.profile) {
+    if (!PROFILES.includes(o.profile as Profile)) throw new Error(`--profile must be one of ${PROFILES.join(' | ')}`);
+    ctx.profile = o.profile as Profile;
+  }
+  if (o.locale) ctx.locale = o.locale;
+  if (o.channel === 'api' || o.channel === 'ui') ctx.channel = o.channel;
+  if (o.sink) ctx.sink = o.sink;
+  return ctx;
+}
 const fieldMapPath = (cwd: string, name: string) => join(FIELDMAP_DIR(cwd), `${name}.fields.yaml`);
 
 /** Resolve where a unit's test-data lives: screen or flow (mirrors sungen auto-detect). */
@@ -48,13 +64,16 @@ function loadFieldMap(cwd: string, name: string): FieldMap | null {
   return parseYaml(readFileSync(p, 'utf8')) as FieldMap;
 }
 
-async function genOne(cwd: string, name: string, opts: { force?: boolean }): Promise<'written' | 'skipped' | 'missing'> {
+async function genOne(cwd: string, name: string, opts: { force?: boolean; ctx?: SelectionContext }): Promise<'written' | 'skipped' | 'missing'> {
   const map = loadFieldMap(cwd, name);
   if (!map) { console.error(`  ✗ ${name}: no field-map at qa/data-factory/${name}.fields.yaml (author it first, e.g. via /sungen:create-data-test)`); return 'missing'; }
-  const { catalog, warnings } = loadEffectiveCatalog(cwd);
+  const { catalog, warnings, provenance } = loadEffectiveCatalog(cwd);
   for (const w of warnings) console.warn(`  ⚠ overwrite: ${w.detail} → ${w.suggestion}`);
+  for (const line of describeProvenance(provenance)) console.log(`  ⟲ .overwrite → ${line}`);
 
-  const expanded = expandFieldMap(map, catalog);
+  const expanded = expandFieldMap(map, catalog, opts.ctx || {});
+  const na = expanded.flatMap((f) => (f.excluded || []).map((e) => `${f.name}.${e.id}`));
+  if (na.length) console.log(`  ⊘ ${name}: ${na.length} case(s) not applicable for this context (see _not_applicable in the file)`);
   const out = testDataPath(cwd, name);
   if (!out) { console.error(`  ✗ ${name}: no qa/screens/${name} or qa/flows/${name}`); return 'missing'; }
 
@@ -96,10 +115,16 @@ export function registerDataFactoryCommand(program: any): void {
     .option('--all', 'Generate for every field-map under qa/data-factory/ (requires confirm)')
     .option('--yes', 'Assume yes for the --all confirmation')
     .option('--force', 'Overwrite existing test-data without asking (implies --yes)')
-    .action(async (opts: { screen?: string; all?: boolean; yes?: boolean; force?: boolean }) => {
+    .option('--profile <name>', `Case selection: ${PROFILES.join(' | ')} (default: regression = all)`)
+    .option('--locale <tag>', 'Selection context locale (e.g. ja-JP) — filters locale-gated cases')
+    .option('--channel <api|ui>', 'Selection context channel')
+    .option('--sink <name>', 'Selection context output sink (e.g. html)')
+    .action(async (opts: { screen?: string; all?: boolean; yes?: boolean; force?: boolean; profile?: string; locale?: string; channel?: string; sink?: string }) => {
       const cwd = process.cwd();
       ensureDataFactoryReadme(cwd);
-      if (opts.screen) { await genOne(cwd, opts.screen, opts); return; }
+      let ctx: SelectionContext;
+      try { ctx = ctxFromOpts(opts); } catch (e: any) { console.error(e.message); process.exitCode = 1; return; }
+      if (opts.screen) { await genOne(cwd, opts.screen, { ...opts, ctx }); return; }
       if (!opts.all) {
         console.error('Specify --screen <name> for one unit, or --all for every unit (with confirmation).');
         process.exitCode = 1;
@@ -116,7 +141,7 @@ export function registerDataFactoryCommand(program: any): void {
         if (a !== 'y' && a !== 'yes') { console.log('Cancelled.'); return; }
       }
       let written = 0;
-      for (const n of names) if ((await genOne(cwd, n, { force: opts.force })) === 'written') written++;
+      for (const n of names) if ((await genOne(cwd, n, { force: opts.force, ctx })) === 'written') written++;
       console.log(`Done: ${written}/${names.length} written.`);
     });
 
@@ -124,9 +149,15 @@ export function registerDataFactoryCommand(program: any): void {
     .command('lint')
     .description('Check test-data coverage (valid/boundary/invalid + traceability) per phuong-phap §6')
     .option('--screen <name>', 'Lint one unit (default: all field-maps)')
-    .action((opts: { screen?: string }) => {
+    .option('--profile <name>', `Case selection: ${PROFILES.join(' | ')} (default: regression = all)`)
+    .option('--locale <tag>', 'Selection context locale (e.g. ja-JP)')
+    .option('--channel <api|ui>', 'Selection context channel')
+    .option('--sink <name>', 'Selection context output sink')
+    .action((opts: { screen?: string; profile?: string; locale?: string; channel?: string; sink?: string }) => {
       const cwd = process.cwd();
       ensureDataFactoryReadme(cwd);
+      let ctx: SelectionContext;
+      try { ctx = ctxFromOpts(opts); } catch (e: any) { console.error(e.message); process.exitCode = 1; return; }
       const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
       if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
       const { catalog } = loadEffectiveCatalog(cwd);
@@ -134,7 +165,7 @@ export function registerDataFactoryCommand(program: any): void {
       for (const name of names) {
         const map = loadFieldMap(cwd, name);
         if (!map) { console.error(`✗ ${name}: no field-map`); totalErrors++; continue; }
-        const { issues } = lintFieldMap(map, catalog);
+        const { issues } = lintFieldMap(map, catalog, ctx);
         const s = summarize(issues);
         totalErrors += s.errors;
         const badge = s.errors ? '✗' : s.warns ? '⚠' : '✓';
@@ -151,9 +182,15 @@ export function registerDataFactoryCommand(program: any): void {
     .command('validate')
     .description('Verify every generated value is semantically correct (valid values satisfy the constraints; synthesized invalid values violate them)')
     .option('--screen <name>', 'Validate one unit (default: all field-maps)')
-    .action((opts: { screen?: string }) => {
+    .option('--profile <name>', `Case selection: ${PROFILES.join(' | ')} (default: regression = all)`)
+    .option('--locale <tag>', 'Selection context locale (e.g. ja-JP)')
+    .option('--channel <api|ui>', 'Selection context channel')
+    .option('--sink <name>', 'Selection context output sink')
+    .action((opts: { screen?: string; profile?: string; locale?: string; channel?: string; sink?: string }) => {
       const cwd = process.cwd();
       ensureDataFactoryReadme(cwd);
+      let ctx: SelectionContext;
+      try { ctx = ctxFromOpts(opts); } catch (e: any) { console.error(e.message); process.exitCode = 1; return; }
       const names = opts.screen ? [opts.screen] : listFieldMaps(cwd);
       if (names.length === 0) { console.error('No field-maps under qa/data-factory/*.fields.yaml.'); process.exitCode = 1; return; }
       const { catalog } = loadEffectiveCatalog(cwd);
@@ -161,7 +198,7 @@ export function registerDataFactoryCommand(program: any): void {
       for (const name of names) {
         const map = loadFieldMap(cwd, name);
         if (!map) { console.error(`✗ ${name}: no field-map`); totalErrors++; continue; }
-        const findings = validateGenerated(map, catalog);
+        const findings = validateGenerated(map, catalog, ctx);
         const errors = findings.filter((f) => f.severity === 'error').length;
         const warns = findings.filter((f) => f.severity === 'warn').length;
         totalErrors += errors;
@@ -174,6 +211,23 @@ export function registerDataFactoryCommand(program: any): void {
       if (totalErrors) process.exitCode = 1;
     });
 
+  data
+    .command('provenance')
+    .description('Show what qa/data-factory/common.overwrite.yaml changed vs the shipped company catalog (extend/replace/disable) — "no silent overwrite"')
+    .action(() => {
+      const cwd = process.cwd();
+      ensureDataFactoryReadme(cwd);
+      const { provenance, warnings } = loadEffectiveCatalog(cwd);
+      const lines = describeProvenance(provenance);
+      if (lines.length === 0) {
+        console.log('No project overrides — the effective catalog is the shipped company common as-is.');
+      } else {
+        console.log('Project overrides (qa/data-factory/common.overwrite.yaml):');
+        for (const l of lines) console.log(`  ⟲ ${l}`);
+      }
+      for (const w of warnings) console.warn(`  ⚠ ${w.detail} → ${w.suggestion}`);
+    });
+
   data
     .command('fixture')
     .description('Generate a CSV import fixture from the field-map (bulk-import / file-upload testing)')

package/src/generator.ts

@@ -9,8 +9,9 @@
  * 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, type Validity } from './boundary';
+import { evaluateWhen, fieldFacts, inProfile } from './applicability';
 
 export interface FieldDef {
   name: string;
@@ -71,6 +72,10 @@ export interface ExpandedPoint {
    * 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 {
@@ -82,6 +87,29 @@ export interface ExpandedField {
   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 }>;
+}
+
+/**
+ * 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 String(Math.round(out));
 }
 
 /** A gen hint that references a numeric/length boundary the generator can expand structurally. */
@@ -112,7 +140,7 @@ function makeUnique(value: string, type: string): string {
 }
 
 /** Expand one field into valid/boundary/invalid data points using the effective catalog. */
-export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
+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 {
@@ -120,7 +148,7 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
       type: undefined,
       blindSpot: false,
       points: [],
-      children: field.fields.map((sub) => expandField(sub, catalog)),
+      children: field.fields.map((sub) => expandField(sub, catalog, ctx)),
       ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}),
     };
   }
@@ -130,6 +158,16 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
   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);
+
+  // 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).
@@ -138,24 +176,41 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
   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;
-    // Oracle: if the constraints can judge this value, they win; else fall back to declared/group validity.
-    const oracle = satisfiesConstraints(type, isUniqueValid ? value : v, c);
-    const validity: Validity = dp.validity ?? (oracle == null ? (opts.validity ?? groupValidity(group)) : oracle ? 'valid' : 'invalid');
+    // 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: v,
       todo: opts.todo,
       reason: dp.reason,
-      note: isUniqueValid ? `${dp.note ? dp.note + ' · ' : ''}fresh per run` : (opts.label ? `${dp.note ? dp.note + ' · ' : ''}${opts.label}` : 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);
 
@@ -173,6 +228,7 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
           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),
         });
       }
@@ -189,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',
@@ -203,16 +260,24 @@ export function expandField(field: FieldDef, catalog: Catalog): ExpandedField {
         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, ...(field.dependsOn ? { dependsOn: field.dependsOn } : {}) };
+  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));
 }
 
 /**
@@ -240,13 +305,18 @@ function renderOne(f: ExpandedField): Record<string, any> {
   }
   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');
-  return {
+  // 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, note: p.note, todo: p.todo })),
-    invalid: invalid.map((p) => trim({ id: p.id, value: p.value, expected: p.expectedValidity, expected_error: p.expectedError, open: p.open, reason: p.reason, todo: p.todo })),
+    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> {

package/src/index.ts

@@ -18,7 +18,7 @@ import { registerDataFactoryCommand } from './cli';
 import { dataFactoryCoverageSensor } from './sensor';
 import { dfPreconditionCodegen } from './precondition';
 
-export { loadShippedCatalog, loadEffectiveCatalog, shippedCommonHash, commonDir } from './catalog-loader';
+export { loadShippedCatalog, loadEffectiveCatalog, shippedCommonHash, commonDir, describeProvenance } from './catalog-loader';
 export { expandField, expandFieldMap, renderTestData } from './generator';
 export type { FieldDef, FieldMap, ExpandedField, ExpandedPoint } from './generator';
 export { lintFieldMap, summarize } from './lint';
@@ -27,12 +27,13 @@ export { validateGenerated, validatePoints } from './validate';
 export type { ValidationFinding } from './validate';
 export { expandBoundaryHint, satisfiesConstraints } from './boundary';
 export type { Validity, BoundaryPoint } from './boundary';
+export { evaluateWhen, inProfile, fieldFacts } from './applicability';
 export { registerDataFactoryCommand } from './cli';
 export { generateFixture } from './fixture';
 export type { FixtureResult } from './fixture';
 export { dataFactoryCoverageSensor } from './sensor';
 export { dfPreconditionCodegen } from './precondition';
-export type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning } from './types';
+export type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance, SelectionContext, Profile } from './types';
 
 /** Register the Data Factory capability. */
 export function register(registry: CapabilityRegistry): void {

package/src/lint.ts

@@ -6,7 +6,7 @@
  * placeholders). It also surfaces blind spots (type not in catalog) and — via the catalog loader —
  * stale `.overwrite` warnings. Pure functions; no side effects.
  */
-import type { Catalog } from './types';
+import type { Catalog, SelectionContext } from './types';
 import type { FieldMap, ExpandedField, FieldDef } from './generator';
 import { expandFieldMap } from './generator';
 
@@ -19,8 +19,8 @@ export interface LintIssue {
 
 const BOUNDED = new Set(['email', 'string', 'password', 'phone', 'postcode', 'katakana', 'number-integer', 'number-float', 'currency']);
 
-export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIssue[]; expanded: ExpandedField[] } {
-  const expanded = expandFieldMap(map, catalog);
+export function lintFieldMap(map: FieldMap, catalog: Catalog, ctx: SelectionContext = {}): { issues: LintIssue[]; expanded: ExpandedField[] } {
+  const expanded = expandFieldMap(map, catalog, ctx);
   const issues: LintIssue[] = [];
 
   // Flatten nested groups to leaf fields (dotted path), pairing each with its FieldDef (for `required`).
@@ -65,6 +65,11 @@ export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIss
     if (def?.required && valid.length === 0) {
       issues.push({ field: path, severity: 'error', code: 'REQUIRED_NO_VALID', message: 'required field with no valid value' });
     }
+    // Applicability (M2b): cases NOT materialized for this field/context — surfaced, never silent.
+    if (f.excluded?.length) {
+      issues.push({ field: path, severity: 'info', code: 'NOT_APPLICABLE',
+        message: `${f.excluded.length} case(s) not applicable here: ${f.excluded.map((e) => `${e.id} (${e.reason})`).join('; ')}` });
+    }
   }
   return { issues, expanded };
 }

package/src/types.ts

@@ -24,6 +24,27 @@ export interface DataPoint {
    * (e.g. a format-invalid value whose length happens to sit inside the range).
    */
   validity?: 'valid' | 'invalid';
+  /**
+   * Where this point ended up coming from after the `.overwrite` merge — `shipped` (company common) or
+   * `overwrite` (the project replaced/added it). Set by the loader; carried through to the generated
+   * value so a reader can answer "why is this value here?". Not authored by hand.
+   */
+  source?: 'shipped' | 'overwrite';
+  /**
+   * Applicability conditions (M2b). The point is materialized only when ALL conditions hold for the
+   * field + selection context. Field-derived keys are always enforced; environment keys only filter
+   * when the context supplies them (a missing context value = "no filter", so the point is kept):
+   *   - `required: true`  — applies only to a REQUIRED field (dropped when the field is explicitly optional).
+   *   - `negativesAllowed: true` — applies only when the numeric field allows negatives (min < 0 / no min).
+   *   - `locale: <prefix>` — applies only when ctx.locale starts with the prefix (e.g. `ja`).
+   *   - `channel: api|ui` / `sink: html|text|…` — applies only when ctx.channel/ctx.sink matches.
+   */
+  when?: Record<string, unknown>;
+  /**
+   * Bucket for output + profile selection. `adversarial` = a security/injection payload (kept out of
+   * the plain `invalid` bucket so a QA sees attack cases separately). Default (unset) = functional.
+   */
+  category?: 'adversarial';
 }
 
 export interface FieldType {
@@ -60,9 +81,48 @@ export interface Catalog {
   techniques: Record<string, Technique>;
 }
 
+/** Named case-selection profiles (which groups/categories a run wants). */
+export type Profile = 'regression' | 'functional' | 'smoke' | 'security-min';
+
+/**
+ * The selection context Core (or a CLI flag) passes to the generator to pick applicable cases.
+ * All fields optional — an absent field means "no filter on that axis" (permissive default).
+ */
+export interface SelectionContext {
+  locale?: string;
+  channel?: 'api' | 'ui';
+  sink?: string;
+  /** `regression` (default) = every case; see Profile for the reduced sets. */
+  profile?: Profile;
+}
+
 /** A warning that a project's common.overwrite.yaml entry looks stale against the shipped common. */
 export interface OverwriteWarning {
   fieldType: string;
   detail: string;
   suggestion: string;
 }
+
+/** What the `.overwrite` layer changed for one field-type (provenance — "no silent overwrite"). */
+export interface FieldTypeProvenance {
+  type: string;
+  /** Ids removed via `disable:` (an id that was not in the shipped common is reported as a warning). */
+  disabled: string[];
+  /** Ids that existed in shipped AND the overlay — the overlay value won. */
+  replaced: string[];
+  /** Ids new from the overlay (a project-specific case). */
+  added: string[];
+  /** Constraint keys the overlay changed. */
+  constraintsOverridden: string[];
+  /** True when the overlay replaced `uses_security`. */
+  securityChanged: boolean;
+}
+
+/** Catalog-wide provenance of the shipped-common → project-overwrite merge. */
+export interface CatalogProvenance {
+  fieldTypes: Record<string, FieldTypeProvenance>;
+  /** Wholly new field-types added by the project (not in shipped common). */
+  newFieldTypes: string[];
+  security: { added: string[]; replaced: string[] };
+  techniques: { added: string[]; replaced: string[] };
+}

package/src/validate.ts

@@ -8,7 +8,7 @@
  * (see docs/spec/data-factory-quality-roadmap.md) calls; today it powers the golden tests and the
  * `sungen data validate` CLI. Pure + deterministic — no AI, no runtime.
  */
-import type { Catalog } from './types';
+import type { Catalog, SelectionContext } from './types';
 import { expandFieldMap, type FieldMap, type FieldDef, type ExpandedField, type ExpandedPoint } from './generator';
 import { satisfiesConstraints } from './boundary';
 
@@ -59,8 +59,8 @@ function describe(type: string, c: Record<string, any>): string {
 }
 
 /** Validate a whole field-map: expand it, then check every value against its expected validity. */
-export function validateGenerated(map: FieldMap, catalog: Catalog): ValidationFinding[] {
-  const expanded = expandFieldMap(map, catalog);
+export function validateGenerated(map: FieldMap, catalog: Catalog, ctx: SelectionContext = {}): ValidationFinding[] {
+  const expanded = expandFieldMap(map, catalog, ctx);
   const out: ValidationFinding[] = [];
   const walk = (efs: ExpandedField[], defs: FieldDef[], prefix: string) => {
     for (const ef of efs) {