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

package/src/index.ts

@@ -18,15 +18,30 @@ 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';
 export type { LintIssue } from './lint';
+export { validateGenerated, validatePoints } from './validate';
+export type { ValidationFinding } from './validate';
+export { expandBoundaryHint, satisfiesConstraints, ensureBvaComplete, emailOfTotalLength } from './boundary';
+export type { Validity, BoundaryPoint, BvaExtra } from './boundary';
+export { evaluateWhen, inProfile, fieldFacts } from './applicability';
+export { generate, buildRequest, validateRequest, fingerprint, GENERATOR_VERSION, SCHEMA_VERSION } from './contract';
+export type { DataFactoryRequest, DataFactoryResult } from './contract';
+export { loadStateRecipes, validateStateRecipe, buildStatePlan, renderPreconditionBlock, topoSort, hasDatasource, scaffoldRecipe, renderRecipeYaml, guessProvenance } from './state';
+export type { StateRecipe, StateResource, StatePlan, StateFinding, Provenance, Lifecycle } from './state';
+export { crosscheckUnit, crosscheckShared, crosscheckAll, referencedVars } from './crosscheck';
+export type { CrossFinding } from './crosscheck';
+export { detectUnit, hasInputFields, hasFieldMap, detectPreconditionSignals, hasStateDeclaration } from './detect';
+export type { DetectFinding } from './detect';
 export { registerDataFactoryCommand } from './cli';
+export { generateFixture } from './fixture';
+export type { FixtureResult, FixtureExpected, ExpectedRow } from './fixture';
 export { dataFactoryCoverageSensor } from './sensor';
 export { dfPreconditionCodegen } from './precondition';
-export type { Catalog, FieldType, SecurityBank, Technique, DataPoint, OverwriteWarning } from './types';
+export type { Catalog, FieldType, SecurityBank, Technique, Experience, DataPoint, OverwriteWarning, CatalogProvenance, FieldTypeProvenance, SelectionContext, Profile } from './types';
 
 /** Register the Data Factory capability. */
 export function register(registry: CapabilityRegistry): void {

package/src/lint.ts

@@ -1,13 +1,13 @@
 /**
  * Data Factory lint — the deterministic coverage oracle from phuong-phap-tao-test-data.md §6.
  *
- * For each field it confirms the "đủ" checklist: ≥1 valid, boundary present when the field has a
+ * For each field it confirms the "is it enough" checklist: >=1 valid, boundary present when the field has a
  * length/number bound, ≥1 invalid per rule, no unresolved values, error codes mapped (not left as
  * 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 { FieldMap, ExpandedField } from './generator';
+import type { Catalog, SelectionContext } from './types';
+import type { FieldMap, ExpandedField, FieldDef } from './generator';
 import { expandFieldMap } from './generator';
 
 export interface LintIssue {
@@ -19,14 +19,25 @@ 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[] = [];
-  const byName = new Map(map.fields.map((f) => [f.name, f]));
 
-  for (const f of expanded) {
+  // Flatten nested groups to leaf fields (dotted path), pairing each with its FieldDef (for `required`).
+  const leaves: Array<{ f: ExpandedField; def?: FieldDef; path: string }> = [];
+  const walk = (efs: ExpandedField[], defs: FieldDef[], prefix: string) => {
+    for (const ef of efs) {
+      const def = defs.find((d) => d.name === ef.name);
+      const path = prefix ? `${prefix}.${ef.name}` : ef.name;
+      if (ef.children) walk(ef.children, def?.fields || [], path);
+      else leaves.push({ f: ef, def, path });
+    }
+  };
+  walk(expanded, map.fields, '');
+
+  for (const { f, def, path } of leaves) {
     if (f.blindSpot) {
-      issues.push({ field: f.name, severity: 'error', code: 'BLIND_SPOT',
+      issues.push({ field: path, severity: 'error', code: 'BLIND_SPOT',
         message: `type "${f.type}" is not in the Data Factory catalog — supply qa/data-factory/project/${f.name}.yaml (valid set, invalid/nonexistent values, error code, dependencies)` });
       continue;
     }
@@ -34,26 +45,30 @@ export function lintFieldMap(map: FieldMap, catalog: Catalog): { issues: LintIss
     const boundary = f.points.filter((p) => p.group === 'boundary');
     const invalid = f.points.filter((p) => p.group === 'invalid');
 
-    if (valid.length === 0) issues.push({ field: f.name, severity: 'error', code: 'NO_VALID', message: 'no valid representative value' });
-    if (invalid.length === 0) issues.push({ field: f.name, severity: 'error', code: 'NO_INVALID', message: 'no invalid value — every rule needs at least one' });
-    if (BOUNDED.has(f.type) && boundary.length === 0) {
-      issues.push({ field: f.name, severity: 'warn', code: 'NO_BOUNDARY', message: `type "${f.type}" usually has min/max — add boundary values or state why not (phuong-phap §6)` });
+    if (valid.length === 0) issues.push({ field: path, severity: 'error', code: 'NO_VALID', message: 'no valid representative value' });
+    if (invalid.length === 0) issues.push({ field: path, severity: 'error', code: 'NO_INVALID', message: 'no invalid value — every rule needs at least one' });
+    if (f.type && BOUNDED.has(f.type) && boundary.length === 0) {
+      issues.push({ field: path, severity: 'warn', code: 'NO_BOUNDARY', message: `type "${f.type}" usually has min/max — add boundary values or state why not (phuong-phap §6)` });
     }
 
     // Unresolved (todo) values — a boundary/gen the constraints could not synthesize.
     for (const p of f.points) {
-      if (p.todo) issues.push({ field: f.name, severity: 'warn', code: 'UNRESOLVED',
+      if (p.todo) issues.push({ field: path, severity: 'warn', code: 'UNRESOLVED',
         message: `${p.id} (${p.group}) needs input: ${p.todo}${p.note ? ` — ${p.note}` : ''}` });
     }
     // Placeholder error codes still unmapped.
     const openErrs = invalid.filter((p) => p.open);
     if (openErrs.length) {
-      issues.push({ field: f.name, severity: 'info', code: 'OPEN_ERRORREF',
+      issues.push({ field: path, severity: 'info', code: 'OPEN_ERRORREF',
         message: `${openErrs.length} invalid case(s) use placeholder error codes (${[...new Set(openErrs.map((p) => p.expectedError))].join(', ')}) — map to real codes via errorMap in the field-map, or confirm with BA/Dev` });
     }
-    const def = byName.get(f.name);
     if (def?.required && valid.length === 0) {
-      issues.push({ field: f.name, severity: 'error', code: 'REQUIRED_NO_VALID', message: 'required field with no valid value' });
+      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/readme.ts

@@ -0,0 +1,52 @@
+/**
+ * Drops a `qa/data-factory/README.md` into the user's project so the folder explains itself.
+ * Write-if-absent (never clobbers a user-edited README), like a config file.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const README = `# \`qa/data-factory/\` — Data Factory (your project's test-data knowledge)
+
+This folder is your project's **test-data standard**: machine-readable data rules that
+\`sungen data gen\` / \`/sungen:create-data-test\` (and \`/sungen:create-test\` step 5.3) expand into
+standardized test-data — **valid / boundary / invalid** values, each carrying a \`CHK-*\` trace id back
+to the spec. It is a reusable asset that **survives \`sungen update\`** (only the driver's shipped
+catalog is refreshed; nothing here is touched).
+
+It is **not** a copy of your spec — it is the structured, reusable data-rules layer the deterministic
+generator needs, complementary to \`requirements/spec.md\` (which is prose spec per screen/flow).
+
+## What lives here
+
+| File | What it is |
+|---|---|
+| \`<name>.fields.yaml\` | **Field-map** for a screen/flow — one entry per input field: its catalog \`type\`, the project's real \`constraints\`, an \`errorMap\` (catalog placeholder code → your real message code), and optionally \`unique: true\`, nested \`fields:\`, \`dependsOn:\`. Authored from \`requirements/spec.md\`; expanded deterministically. A unit with **no input fields** (navigation/list) has no field-map — that's correct. |
+| \`common.overwrite.yaml\` | **Project-wide overrides** to the shipped catalog — your real length limits, real error codes, banned values, extra invalid cases. Deep-merged over the common (later-wins, keyed by \`type\` + data-point \`id\`). Genuinely new project knowledge the shipped catalog can't have. |
+| \`project/<entity>.yaml\` | **Blind-spot answers** — business enums, cross-entity rules, data models the catalog can't know. You fill these when Data Factory hits a field \`type\` it doesn't have (instead of it guessing). |
+| \`recipes.yaml\` | Seed recipes for the \`@dataFactory:<recipe>\` annotation — named field sets bound into \`{{recipe.*}}\` at runtime. |
+
+## Good to know
+
+- **\`sungen data gen\` merges** into \`test-data/<name>.yaml\` — it replaces only the field keys it owns
+  and preserves everything else (create-test data, flow-namespaced keys, \`@cases\`, overrides).
+- **\`unique: true\`** makes a field's valid value fresh per run (\`{{$timestamp}}\`) so a register
+  email/username never collides — no cross-run cache.
+- \`sungen data lint\` checks coverage; \`sungen data fixture\` builds a CSV import fixture under
+  \`qa/fixtures/\`.
+- Edit the field-map / \`.overwrite\` and re-run — never hand-edit the generated \`test-data\` values.
+
+Full guide: https://sungen.sun-asterisk.vn/docs/guides/data-factory
+`;
+
+/** Ensure `qa/data-factory/README.md` exists (write-if-absent). */
+export function ensureDataFactoryReadme(cwd: string): void {
+  const dir = join(cwd, 'qa', 'data-factory');
+  const path = join(dir, 'README.md');
+  if (existsSync(path)) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, README, 'utf8');
+  } catch {
+    /* best-effort — a missing README must never fail a data command */
+  }
+}

package/src/sensor.ts

@@ -5,7 +5,10 @@
  * coverage lint as `sungen data lint` and surfaces the gaps in the generate output — so weak
  * test-data coverage (missing boundary/invalid, unresolved values, unmapped error codes, blind
  * spots) is visible in the standard harness flow, not only when you remember to run `data lint`.
- * A unit with no field-map produces no findings (Data Factory is opt-in per unit).
+ *
+ * Auto-detection (Layer A): even with NO field-map, it NOTICES what's missing — a unit with input
+ * fields but no standardized data, or a spec that describes a stateful precondition the test never
+ * declares — so Sungen nudges QA instead of staying silent (was: "no field-map → nothing to say").
  *
  * Advisory, not gate: the ContextRouter scopes gate sensors by the annotation tags a feature carries,
  * and test-data generation is a design-time concern with no `.feature` tag — so gating here would
@@ -17,6 +20,8 @@ import { parse as parseYaml } from 'yaml';
 import type { Sensor } from '@sun-asterisk/sungen';
 import { loadEffectiveCatalog } from './catalog-loader';
 import { lintFieldMap, summarize } from './lint';
+import { validateGenerated } from './validate';
+import { detectUnit } from './detect';
 import type { FieldMap } from './generator';
 
 export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
@@ -25,11 +30,21 @@ export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
   kind: 'advisory',
   run: ({ dir, cwd }) => {
     const name = basename(dir);
+    // Layer A auto-detection — runs regardless of whether a field-map exists, so a unit that needs
+    // standardization or a declared precondition is NOTICED, not silently skipped.
+    const detected = detectUnit(cwd, dir, name).map((d) => ({
+      sensorId: 'data-factory-coverage',
+      capability: 'data-factory',
+      scenario: d.scenario,
+      message: d.message,
+      severity: d.severity,
+    }));
+
     const fieldMapPath = join(cwd, 'qa', 'data-factory', `${name}.fields.yaml`);
-    if (!existsSync(fieldMapPath)) return []; // opt-in per unit — no field-map, nothing to say
+    if (!existsSync(fieldMapPath)) return detected; // no field-map: report only what detection noticed
     let map: FieldMap;
-    try { map = parseYaml(readFileSync(fieldMapPath, 'utf8')) as FieldMap; } catch { return []; }
-    if (!map || !Array.isArray(map.fields)) return [];
+    try { map = parseYaml(readFileSync(fieldMapPath, 'utf8')) as FieldMap; } catch { return detected; }
+    if (!map || !Array.isArray(map.fields)) return detected;
 
     const { catalog, warnings } = loadEffectiveCatalog(cwd);
     const { issues } = lintFieldMap(map, catalog);
@@ -49,6 +64,17 @@ export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
         severity: 'warn',
       });
     }
+    // Semantic validity (M1): a value labeled valid that violates the constraints (or a synthesized
+    // boundary that lands in-range) — the "structurally right but semantically wrong" class.
+    for (const v of validateGenerated(map, catalog)) {
+      findings.push({
+        sensorId: 'data-factory-coverage',
+        capability: 'data-factory',
+        scenario: v.field,
+        message: `DATA-FACTORY-${v.code}: ${v.message}`,
+        severity: v.severity,
+      });
+    }
     if (findings.length) {
       const s = summarize(issues);
       findings.unshift({
@@ -59,6 +85,8 @@ export const dataFactoryCoverageSensor: Sensor<{ dir: string; cwd: string }> = {
         severity: s.errors ? 'warn' : 'info',
       });
     }
+    // Detection findings (e.g. an undeclared stateful precondition) are still relevant with a field-map.
+    findings.push(...detected);
     return findings;
   },
 };

package/src/state.ts

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

package/src/types.ts

@@ -9,7 +9,7 @@ export interface DataPoint {
   id: string;
   /** Literal value (present for concrete cases). */
   value?: string;
-  /** Human instruction to synthesize the value when it depends on project constraints (e.g. "local@ đúng maxLocal"). */
+  /** Human instruction to synthesize the value when it depends on project constraints (e.g. "local part = maxLocal"). */
   gen?: string;
   /** Why this value is invalid (invalid group only). */
   reason?: string;
@@ -18,6 +18,33 @@ export interface DataPoint {
   /** Pull values from a security bank (e.g. `security/sqli`) into this group. */
   from?: string;
   note?: string;
+  /**
+   * Optional explicit validity for this point (`valid` | `invalid`). Normally the generator's oracle
+   * computes it from the constraints; set this only to pin an intent the constraints can't express
+   * (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 {
@@ -48,10 +75,40 @@ export interface Technique {
   [k: string]: unknown;
 }
 
+/**
+ * A domain-EXPERIENCE checklist — cases that come from real-world testing experience, not from a
+ * field's format (e.g. the credential/account states a login screen must cover: soft-deleted, locked,
+ * unverified…). Each case is a SCENARIO that usually needs a domain-state precondition, so it is
+ * knowledge for the login/auth viewpoint + a state-recipe — not a field-level value.
+ */
+export interface Experience {
+  experience: string;
+  description?: string;
+  applies_when?: string;
+  cases: Array<Record<string, unknown> & { id: string; expect?: string }>;
+  oracle?: string;
+}
+
 export interface Catalog {
   fieldTypes: Record<string, FieldType>;
   security: Record<string, SecurityBank>;
   techniques: Record<string, Technique>;
+  experience: Record<string, Experience>;
+}
+
+/** 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. */
@@ -60,3 +117,27 @@ export interface OverwriteWarning {
   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[] };
+}