@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-synthetic-data.ts

@@ -1,23 +1,51 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { base, en, Faker } from '@faker-js/faker'
+import { base, de, en, en_AU, en_GB, en_IN, es, Faker, fr, id_ID, ja, nl, pt_BR, type LocaleDefinition } from '@faker-js/faker'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 
+import { cityNear } from './local-cities'
+import { defaultPlaceholderPaths } from './local-media-placeholders'
+import { objectTypeFit } from './local-portability'
+import { isSampleDataset, readCsvRows, sampleStamp, stampedDescription } from './local-sample-data'
+import { readSnapshot } from './local-sync-snapshot'
+
 /**
  * Sample rows for a project's Blueprint, so a Blueprint pulled from a
  * workspace (which brings no records) can be explored, queried and used by
- * Agents without copying customer data to a laptop.
+ * Agents and Apps without copying customer data to a laptop.
  *
  * Each object type gets a CSV under `datasets/` with the definition beside
- * it. Values fit each property: its type, its name (an `email` gets an email,
- * an `amount` money) and the values its description lists ("open, pending or
- * closed"). Links stay consistent: a property another type's records are
- * linked by gets a value from those records, so every relation resolves.
- * The same seed gives the same rows.
+ * it. A value fits its property, most specific first:
+ *
+ *   1. the values the Blueprint allows: the property's semantic type (its own,
+ *      or its shared field's) — an enum, a number's bounds, a text's length —
+ *      or values listed on the property itself;
+ *   2. the values its description lists ("open, pending or closed");
+ *   3. for a property a governed Action writes from an input with an enum
+ *      (`set status ← input status` with `enum: [open, escalated]`), those values,
+ *      so every record is one the Action can act on;
+ *   4. its type and its name (an `email` gets an email, an `amount` money).
+ *
+ * Links stay consistent: a property that holds another type's key gets a
+ * value from those records (always, when the property is required), and the
+ * side holding the key is the one that is not its type's primary key.
+ * Timestamps in a row follow the lifecycle their names say (created, then
+ * assigned, then resolved; updated last), a record still open has no
+ * optional resolution time, and an open record's due time falls around
+ * today (some overdue). Text reads like the record, from the row's other
+ * values: a title names its category and the place it links to, a
+ * resolution what was done. A unit follows the row's reading type, and its
+ * value that kind's range. Geopoints, coordinates and phone numbers fall
+ * within a region: `--region`, else the project's `locale` (frontera.yaml),
+ * else the workspace's timezone, else the United States. The same seed gives
+ * the same rows on the same day.
  *
  * `data/generate.ts` in the project, when present, adjusts it: rows per type
  * and a function per property, for scenarios ("five tickets breaching SLA").
+ * A field function sees the whole generated row, and the rows already
+ * generated for other types (`ScenarioContext`). `SCENARIO_CONTRACT` says
+ * all of it in words, for `local data --help`.
  */
 
 interface Property {
@@ -27,15 +55,31 @@ interface Property {
   valueType?: string
   required?: boolean
   propertyType?: string
+  semanticType?: string | null
+  sharedField?: string | null
+  /** Values a property may list itself. */
+  allowedValues?: unknown[]
+  enum?: unknown[]
+  /** A calculated field (a location from latitude and longitude): computed by the Blueprint, never a column. */
+  calculation?: unknown
 }
 
+/**
+ * Whether a record may leave a property empty: unless it says `required:
+ * true`, as the Blueprint reads it (a property without `required` is
+ * optional), so the state rules apply to it too.
+ */
+const optional = (p: Pick<Property, 'required'> | undefined) => !!p && p.required !== true
+
 interface ObjectType {
   apiName: string
   displayName?: string
   pluralDisplayName?: string
   primaryKey?: string
+  /** The property a record is called by. */
+  title?: string
   properties?: Property[]
-  backing?: { dataset?: string; mapping?: Record<string, string> }
+  backing?: { dataset?: string; mapping?: Record<string, string | { column: string }> }
 }
 
 interface LinkType {
@@ -45,10 +89,52 @@ interface LinkType {
   to?: { objectType?: string; property?: string }
 }
 
+interface SemanticType {
+  apiName: string
+  dataType?: string
+  rule?: { enum?: unknown[]; minimum?: string | number; maximum?: string | number; minLength?: number; maxLength?: number }
+}
+
+interface SharedField {
+  apiName: string
+  description?: string
+  semanticType?: string | null
+}
+
+interface MetricFile {
+  apiName: string
+  displayName?: string
+  objectType?: string
+  definition?: { measures?: Array<{ property?: string; agg?: string; label?: string; apiName?: string; filters?: unknown }> }
+}
+
+interface ActionFile {
+  apiName: string
+  subject?: { objectType?: string }
+  inputs?: Array<{ apiName?: string; valueType?: { kind?: string; enum?: unknown[] } }>
+  businessOutcomes?: Array<{ expectedChanges?: Array<{ kind?: string; property?: string; value?: { kind?: string; field?: string; value?: unknown } }> }>
+}
+
+/**
+ * A field function's third argument: the rows already generated for other
+ * types. Types are generated in link order (a type before the types that
+ * point at it), so the types a row links to are always there; its own type
+ * and the types generated after it give none.
+ */
+export interface ScenarioContext {
+  /** The generated rows of a type, read-only; [] for its own type or one not generated yet. */
+  rowsOf: (objectType: string) => ReadonlyArray<Readonly<Record<string, unknown>>>
+  /** The generated row of a type whose primary key (or `property`) is `value`; undefined when none is. */
+  lookup: (objectType: string, value: unknown, property?: string) => Readonly<Record<string, unknown>> | undefined
+}
+
+/** A field function: the row so far, its position, and the rows of other types. */
+export type FieldFunction = (row: Record<string, unknown>, index: number, ctx: ScenarioContext) => unknown
+
 /** What `data/generate.ts` may return. */
 export interface Scenario {
   rows?: number
-  types?: Record<string, { rows?: number; fields?: Record<string, (row: Record<string, unknown>, index: number) => unknown> }>
+  types?: Record<string, { rows?: number; fields?: Record<string, FieldFunction> }>
 }
 
 export interface GeneratedDataset {
@@ -57,14 +143,33 @@ export interface GeneratedDataset {
   rows: number
   csvPath: string
   definitionPath: string
+  /**
+   * The dataset is not sample data (someone wrote or edited it, a Source
+   * loads it): its files were left as they are, and the sample rows of other
+   * types link to its records.
+   */
+  kept?: true
+  /**
+   * Fields whose description makes them conditional on something the record
+   * has nothing for ("empty unless escalated" with no `escalated` property
+   * and no value "escalated"): the condition never holds, so an "empty
+   * unless" field stays empty. Said, so the description can name it.
+   */
+  unresolved?: Array<{ property: string; condition: string }>
 }
 
 export interface SyntheticOptions {
   rows?: number
   seed?: number
-  /** Dates are spread over the months before this day; fixed by default so a seed gives the same rows. */
+  /**
+   * Dates are spread over the months before this day, and open records fall
+   * due around it. By default the day it runs (midnight UTC), so a seed gives
+   * the same rows all day and an overdue record is overdue now.
+   */
   today?: Date
   scenario?: Scenario
+  /** Where geopoints fall: a region (`resolveRegion`). Defaults to the project's. */
+  region?: Region
 }
 
 function readTree<T>(dir: string): Array<{ file: string; doc: T }> {
@@ -92,16 +197,44 @@ function plural(name: string): string {
 export function backingOf(type: ObjectType): { dataset: string; column: (property: string) => string } {
   const dataset = type.backing?.dataset || plural(snake(type.apiName))
   const mapping = type.backing?.mapping ?? {}
-  return { dataset, column: (p) => mapping[p] ?? snake(p) }
+  return {
+    dataset,
+    column: (p) => {
+      const m = mapping[p]
+      return typeof m === 'string' ? m : m && typeof m === 'object' && typeof m.column === 'string' ? m.column : snake(p)
+    },
+  }
 }
 
-/** "open, pending, resolved or closed" → the four values, when a description lists them. */
+/**
+ * "open, pending, resolved or closed" → the four values, when a description
+ * lists them: the whole text, what follows its last colon or dash ("The
+ * dispatch region — north, central or south."), or its last sentence ("The
+ * operating district a record belongs to. North, south, east, west or
+ * central."), with a leading "One of" or "Either" dropped.
+ */
 export function listedValues(description: string | undefined): string[] | null {
   if (!description) return null
-  const text = description.replace(/^[^:]*:\s*/, '').trim()
+  // After the last colon or dash: a spaced hyphen counts as one ("belongs to - north, south or east").
+  const separators = [...description.matchAll(/:|—|–|\s-\s/g)]
+  const lastSeparator = separators[separators.length - 1]
+  const tail = lastSeparator ? description.slice(lastSeparator.index! + lastSeparator[0].length).trim() || undefined : undefined
+  const sentences = description.trim().split(/(?<=[.!?;])\s+/).filter(Boolean)
+  const last = sentences.length > 1 ? sentences[sentences.length - 1] : undefined
+  for (const candidate of [tail, last, description.replace(/^[^:]*:\s*/, '')]) {
+    if (!candidate) continue
+    const found = listedIn(candidate.replace(/^\s*(one of|either|any of)\s+/i, ''))
+    if (found) return found
+  }
+  return null
+}
+
+function listedIn(raw: string): string[] | null {
+  const text = raw.trim()
   if (!/,|\bor\b/.test(text) || text.length > 160) return null
   const parts = text.split(/\s*,\s*|\s+or\s+|\s+and\s+/).map((p) => p.trim().replace(/^["'`]|["'`.]$/g, ''))
-  if (parts.length < 2 || parts.some((p) => !/^[A-Za-z0-9_-]{1,32}$/.test(p))) return null
+  // A word, a code or a unit symbol (`%`, `°C`, `m3/h`): never a phrase.
+  if (parts.length < 2 || parts.some((p) => !/^[\p{L}\p{N}_%°/³²µ$€£¥-]{1,32}$/u.test(p))) return null
   return [...new Set(parts)]
 }
 
@@ -116,10 +249,29 @@ interface Reference {
   /** The type whose records this property points at. */
   objectType: string
   property: string
+  /**
+   * Said by the property's name, not by a link type (`inferReferences`): the
+   * property takes that type's keys, but it is only a guess at a link, so it
+   * never makes another link of the row agree with it.
+   */
+  inferred?: true
+  /**
+   * An inferred link back along a declared one (a service request's
+   * `dispatchDecisionId`, when each dispatch decision links to its request):
+   * filled once the other type has rows, with the record that links back.
+   */
+  after?: true
 }
 
-/** Which property of which type points at which other type's key, from the link types. */
-export function referencesFrom(links: LinkType[]): Map<string, Map<string, Reference>> {
+/**
+ * Which property of which type points at which other type's key, from the
+ * link types. The side that holds the key is the one whose property is not
+ * its type's primary key; when that cannot tell (neither or both are), the
+ * cardinality says it: for one_to_many and one_to_one the `to` side holds
+ * the `from` side's key, for many_to_one the other way round. many_to_many
+ * links hold no key on either side.
+ */
+export function referencesFrom(links: LinkType[], primaryKeys: ReadonlyMap<string, string> = new Map()): Map<string, Map<string, Reference>> {
   const out = new Map<string, Map<string, Reference>>()
   const add = (type: string, property: string, ref: Reference) => {
     if (!out.has(type)) out.set(type, new Map())
@@ -129,13 +281,73 @@ export function referencesFrom(links: LinkType[]): Map<string, Map<string, Refer
     const from = link.from
     const to = link.to
     if (!from?.objectType || !from.property || !to?.objectType || !to.property) continue
-    if (link.cardinality === 'many_to_one') add(from.objectType, from.property, { objectType: to.objectType, property: to.property })
-    else if (link.cardinality === 'many_to_many') continue
-    else add(to.objectType, to.property, { objectType: from.objectType, property: from.property })
+    if (link.cardinality === 'many_to_many') continue
+    const fromIsKey = primaryKeys.get(from.objectType) === from.property
+    const toIsKey = primaryKeys.get(to.objectType) === to.property
+    const toHolds = fromIsKey !== toIsKey ? fromIsKey : link.cardinality !== 'many_to_one'
+    if (toHolds) add(to.objectType, to.property, { objectType: from.objectType, property: from.property })
+    else add(from.objectType, from.property, { objectType: to.objectType, property: to.property })
   }
   return out
 }
 
+const squash = (text: string) => text.toLowerCase().replace(/[^a-z0-9]/g, '')
+
+/** A type whose records do the work on other records: a staff member, a technician, an agent. */
+const WORKER = /\b(staff|technicians?|engineers?|agents?|employees?|workers?|operators?|dispatchers?|officers?|inspectors?|crew|team members?|users?|members?)\b/
+
+/**
+ * Links the Blueprint doesn't declare but a property's name says, added to
+ * `refs`: `propertyId` holds a Property's key, `dispatchDecisionId` a
+ * DispatchDecision's (its key `decisionId`), `homePropertyId` and
+ * `chosenStaffId` the type their name ends with, `staffId` the type whose
+ * key it is, and `assignedTo` (an assignee, an owner) the type of the people
+ * who do the work. Only a property no declared link holds, that lists no
+ * values, of the same value type as the key, and never its own type's key or
+ * a link to its own type. A name two types could answer is left alone.
+ */
+export function inferReferences(types: ObjectType[], refs: Map<string, Map<string, Reference>>, primaryKeys: ReadonlyMap<string, string>, hasValues: (type: ObjectType, p: Property) => boolean): void {
+  const keyOf = (t: ObjectType) => (t.properties ?? []).find((x) => x.apiName === primaryKeys.get(t.apiName))
+  const sameKind = (p: Property, t: ObjectType) => ((keyOf(t)?.valueType ?? 'string') === 'number') === ((p.valueType ?? 'string') === 'number')
+  const only = (list: ObjectType[]) => (list.length === 1 ? list[0] : undefined)
+  const workers = types.filter((t) => entityOf(t) === 'person' && WORKER.test(`${words(t.apiName)} ${(t.displayName ?? '').toLowerCase()}`))
+  // Where the declared links lead from each type: an inferred link the other way closes a loop.
+  const declared = new Map([...refs].map(([t, m]) => [t, [...m.values()].map((r) => r.objectType)] as const))
+  const leadsTo = (from: string, to: string) => {
+    const seen = new Set<string>([from])
+    const queue = [from]
+    while (queue.length) {
+      for (const next of declared.get(queue.shift()!) ?? []) {
+        if (next === to) return true
+        if (!seen.has(next)) (seen.add(next), queue.push(next))
+      }
+    }
+    return false
+  }
+  for (const type of types) {
+    const own = refs.get(type.apiName)
+    for (const p of type.properties ?? []) {
+      if (p.calculation || p.apiName === primaryKeys.get(type.apiName) || own?.has(p.apiName) || !['string', 'number'].includes(p.valueType ?? 'string') || hasValues(type, p)) continue
+      const others = types.filter((t) => t.apiName !== type.apiName && sameKind(p, t))
+      const name = squash(p.apiName)
+      // Another type's key by name: `staffId`, `decisionId`.
+      let target = only(others.filter((t) => squash(primaryKeys.get(t.apiName) ?? '') === name && name !== 'id'))
+      const stem = /^(.+?)(?:_?id|_?key|_?ref)$/i.exec(p.apiName)?.[1]
+      if (!target && stem) {
+        const s = squash(stem)
+        // The type it names: `propertyId` → Property; then the type its name ends with: `homePropertyId` → Property.
+        target = only(others.filter((t) => squash(t.apiName) === s))
+          ?? only(others.filter((t) => squash(t.apiName).length >= 4 && s.endsWith(squash(t.apiName)) && !others.some((u) => u !== t && squash(u.apiName).length > squash(t.apiName).length && s.endsWith(squash(u.apiName)))))
+      }
+      // Who it is assigned to: one of the people who do the work.
+      if (!target && /^(assigned to|assignee|assignee id|assigned (staff|technician|agent|engineer)( id)?|owner|owner id)$/.test(words(p.apiName))) target = workers.find((t) => t.apiName !== type.apiName && sameKind(p, t))
+      if (!target) continue
+      if (!refs.has(type.apiName)) refs.set(type.apiName, new Map())
+      refs.get(type.apiName)!.set(p.apiName, { objectType: target.apiName, property: primaryKeys.get(target.apiName)!, inferred: true, ...(leadsTo(target.apiName, type.apiName) ? { after: true as const } : {}) })
+    }
+  }
+}
+
 /** Types in an order where every referenced type comes before the types that point at it. */
 function dependencyOrder(types: ObjectType[], refs: Map<string, Map<string, Reference>>): ObjectType[] {
   const byName = new Map(types.map((t) => [t.apiName, t]))
@@ -144,7 +356,7 @@ function dependencyOrder(types: ObjectType[], refs: Map<string, Map<string, Refe
   const visit = (name: string, trail: Set<string>) => {
     if (done.has(name) || trail.has(name) || !byName.has(name)) return
     trail.add(name)
-    for (const ref of refs.get(name)?.values() ?? []) if (ref.objectType !== name) visit(ref.objectType, trail)
+    for (const ref of refs.get(name)?.values() ?? []) if (ref.objectType !== name && !ref.after) visit(ref.objectType, trail)
     trail.delete(name)
     done.add(name)
     out.push(byName.get(name)!)
@@ -157,77 +369,1150 @@ function words(name: string): string {
   return name.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase()
 }
 
-/** A value for one property, from its type, its name and its description. */
-function valueFor(faker: Faker, type: ObjectType, p: Property, row: Record<string, unknown>, state: { lastTime: number | null; today: Date }): unknown {
+// ── Regions: where geopoints fall ────────────────────────────────────────────
+
+/** A circle on the map, and what a record there reads like. */
+export interface Region {
+  /** A country code, or `custom` for a point given by hand. */
+  code: string
+  lat: number
+  lon: number
+  radiusKm: number
+  currency: string
+  locale: LocaleDefinition[]
+  /** The country its records are in: its own code, or the known country a custom point lies in. */
+  country?: string
+  /** The city its points are in: a known area's own, or the one a custom point is near. */
+  city?: string
+}
+
+/** A metropolitan area per country: records cluster where people and assets are, not across a whole country's ocean. */
+const REGIONS: Record<string, Omit<Region, 'code'>> = {
+  US: { lat: 40.73, lon: -73.94, radiusKm: 35, currency: 'USD', city: 'New York', locale: [en, base] },
+  ID: { lat: -6.2, lon: 106.82, radiusKm: 30, currency: 'IDR', city: 'Jakarta', locale: [id_ID, en, base] },
+  GB: { lat: 51.51, lon: -0.12, radiusKm: 30, currency: 'GBP', city: 'London', locale: [en_GB, en, base] },
+  AU: { lat: -33.87, lon: 151.21, radiusKm: 35, currency: 'AUD', city: 'Sydney', locale: [en_AU, en, base] },
+  IN: { lat: 19.08, lon: 72.88, radiusKm: 30, currency: 'INR', city: 'Mumbai', locale: [en_IN, en, base] },
+  SG: { lat: 1.35, lon: 103.82, radiusKm: 15, currency: 'SGD', city: 'Singapore', locale: [en, base] },
+  MY: { lat: 3.14, lon: 101.69, radiusKm: 25, currency: 'MYR', city: 'Kuala Lumpur', locale: [en, base] },
+  PH: { lat: 14.6, lon: 120.98, radiusKm: 25, currency: 'PHP', city: 'Manila', locale: [en, base] },
+  DE: { lat: 52.52, lon: 13.4, radiusKm: 25, currency: 'EUR', city: 'Berlin', locale: [de, en, base] },
+  FR: { lat: 48.86, lon: 2.35, radiusKm: 25, currency: 'EUR', city: 'Paris', locale: [fr, en, base] },
+  ES: { lat: 40.42, lon: -3.7, radiusKm: 25, currency: 'EUR', city: 'Madrid', locale: [es, en, base] },
+  NL: { lat: 52.37, lon: 4.9, radiusKm: 20, currency: 'EUR', city: 'Amsterdam', locale: [nl, en, base] },
+  JP: { lat: 35.68, lon: 139.69, radiusKm: 30, currency: 'JPY', city: 'Tokyo', locale: [ja, en, base] },
+  BR: { lat: -23.55, lon: -46.63, radiusKm: 35, currency: 'BRL', city: 'São Paulo', locale: [pt_BR, en, base] },
+  AE: { lat: 25.2, lon: 55.27, radiusKm: 30, currency: 'AED', city: 'Dubai', locale: [en, base] },
+}
+
+/** A timezone's country, for the ones a workspace commonly runs in. */
+const TIMEZONE_COUNTRY: Record<string, string> = {
+  'Asia/Jakarta': 'ID', 'Asia/Makassar': 'ID', 'Asia/Jayapura': 'ID', 'Asia/Pontianak': 'ID',
+  'Asia/Singapore': 'SG', 'Asia/Kuala_Lumpur': 'MY', 'Asia/Manila': 'PH', 'Asia/Tokyo': 'JP',
+  'Asia/Kolkata': 'IN', 'Asia/Calcutta': 'IN', 'Asia/Dubai': 'AE',
+  'Europe/London': 'GB', 'Europe/Berlin': 'DE', 'Europe/Paris': 'FR', 'Europe/Madrid': 'ES', 'Europe/Amsterdam': 'NL',
+  'Australia/Sydney': 'AU', 'Australia/Melbourne': 'AU', 'America/Sao_Paulo': 'BR',
+}
+
+export const REGION_CODES = Object.keys(REGIONS)
+
+/**
+ * Per known country: how its mobile numbers are written (`#` a digit, `N` a
+ * digit from 2 to 9) and a box around it (south, north, west, east), to tell
+ * which country a custom point is in.
+ */
+const COUNTRIES: Record<string, { phone: string[]; box: [number, number, number, number] }> = {
+  US: { phone: ['+1 N## N## ####'], box: [24, 50, -125, -66] },
+  ID: { phone: ['+62 81# #### ####', '+62 82# #### ####', '+62 85# #### ####', '+62 87# #### ####'], box: [-11, 6, 95, 141.5] },
+  GB: { phone: ['+44 7### ######'], box: [49.8, 61, -8.7, 1.8] },
+  AU: { phone: ['+61 4## ### ###'], box: [-44, -10, 112.5, 154] },
+  IN: { phone: ['+91 9#### #####', '+91 8#### #####', '+91 7#### #####'], box: [6, 36, 68, 97.5] },
+  SG: { phone: ['+65 8### ####', '+65 9### ####'], box: [1.15, 1.48, 103.6, 104.1] },
+  MY: { phone: ['+60 1N-### ####'], box: [0.85, 7.4, 99.6, 119.3] },
+  PH: { phone: ['+63 9## ### ####'], box: [4.5, 21.2, 116.9, 126.7] },
+  DE: { phone: ['+49 15N #######', '+49 17N #######'], box: [47.2, 55.1, 5.8, 15.1] },
+  FR: { phone: ['+33 6 ## ## ## ##', '+33 7 ## ## ## ##'], box: [41.3, 51.1, -5.2, 9.6] },
+  ES: { phone: ['+34 6## ### ###'], box: [36, 43.8, -9.4, 3.4] },
+  NL: { phone: ['+31 6 ########'], box: [50.7, 53.6, 3.3, 7.3] },
+  JP: { phone: ['+81 90 #### ####', '+81 80 #### ####'], box: [24, 45.6, 122.9, 146] },
+  BR: { phone: ['+55 11 9#### ####'], box: [-33.8, 5.3, -74, -34.8] },
+  AE: { phone: ['+971 5# ### ####'], box: [22.6, 26.1, 51.5, 56.4] },
+}
+
+/** The known country a point lies in: the smallest box that holds it, the nearest centre on a tie; undefined when none does. */
+export function countryAt(lat: number, lon: number): string | undefined {
+  const holding = Object.entries(COUNTRIES)
+    .filter(([, { box: [s, n, w, e] }]) => lat >= s && lat <= n && lon >= w && lon <= e)
+    .map(([code, { box: [s, n, w, e] }]) => ({ code, area: (n - s) * (e - w), distance: Math.hypot(lat - REGIONS[code]!.lat, lon - REGIONS[code]!.lon) }))
+    .sort((a, b) => a.area - b.area || a.distance - b.distance)
+  return holding[0]?.code
+}
+
+/** A compass word's bearing in degrees, or `centre` for the middle: English and Indonesian. */
+const COMPASS: Record<string, number | 'centre'> = {
+  north: 0, northeast: 45, east: 90, southeast: 135, south: 180, southwest: 225, west: 270, northwest: 315,
+  central: 'centre', centre: 'centre', center: 'centre', middle: 'centre',
+  utara: 0, timurlaut: 45, timur: 90, tenggara: 135, selatan: 180, baratdaya: 225, barat: 270, baratlaut: 315, pusat: 'centre', tengah: 'centre',
+}
+const compassKey = (value: string) => value.toLowerCase().replace(/[\s_-]+/g, '')
+
+/** Values that are all compass regions (`north, south, east, west or central`), at least two directions among them. */
+export function isCompassList(values: readonly string[]): boolean {
+  return values.length >= 2 && values.every((v) => compassKey(v) in COMPASS) && values.filter((v) => COMPASS[compassKey(v)] !== 'centre').length >= 2
+}
+
+/**
+ * The compass region a point is in, of those listed, seen from the region's
+ * centre: the middle quarter of the radius is the centre (when one is
+ * listed), else the listed direction nearest the point's bearing.
+ */
+export function compassOf(point: { lat: number; lon: number }, region: Pick<Region, 'lat' | 'lon' | 'radiusKm'>, values: readonly string[]): string {
+  const centre = values.find((v) => COMPASS[compassKey(v)] === 'centre')
+  if (centre && distanceKm(region, point) <= region.radiusKm / 4) return centre
+  const φ1 = rad(region.lat)
+  const φ2 = rad(point.lat)
+  const Δλ = rad(point.lon - region.lon)
+  const bearing = (deg(Math.atan2(Math.sin(Δλ) * Math.cos(φ2), Math.cos(φ1) * Math.sin(φ2) - Math.sin(φ1) * Math.cos(φ2) * Math.cos(Δλ))) + 360) % 360
+  const directions = values.filter((v) => typeof COMPASS[compassKey(v)] === 'number')
+  const apart = (v: string) => {
+    const d = Math.abs((COMPASS[compassKey(v)] as number) - bearing) % 360
+    return Math.min(d, 360 - d)
+  }
+  return directions.reduce((best, v) => (apart(v) < apart(best) ? v : best), directions[0]!)
+}
+
+/** One city per region an area has no city for: a circle of tens of kilometres is one place. */
+const drawnCities = new WeakMap<Region, string>()
+
+/** The city a region's records are in: its own, else one drawn once (a wide circle may span several). */
+function cityOf(faker: Faker, region: Region): string {
+  if (region.city) return region.city
+  if (region.radiusKm > 80) return faker.location.city()
+  let city = drawnCities.get(region)
+  if (!city) drawnCities.set(region, (city = faker.location.city()))
+  return city
+}
+
+/** A region's country: the one it names or a custom point lies in. */
+const countryOf = (region: Region): string | undefined => region.country ?? (REGIONS[region.code] ? region.code : undefined)
+
+/** A mobile number written as the region's country writes it; Faker's own when the country is unknown. */
+function phoneFor(faker: Faker, region: Region): string {
+  const formats = COUNTRIES[countryOf(region) ?? '']?.phone
+  if (!formats) return faker.phone.number({ style: 'international' })
+  return faker.helpers.arrayElement(formats).replace(/[#N]/g, (c) => String(faker.number.int({ min: c === 'N' ? 2 : 0, max: 9 })))
+}
+
+/**
+ * `ID`, `id-ID`, `en_GB`, or `<lat>,<lon>[,<radius km>]` → a region; null
+ * when it is none of those. A point in a known country reads like it: its
+ * names, currency and phone numbers.
+ */
+export function parseRegion(raw: string): Region | null {
+  const text = raw.trim()
+  const point = /^(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)(?:\s*,\s*(\d+(?:\.\d+)?))?$/.exec(text)
+  if (point) {
+    const lat = Number(point[1])
+    const lon = Number(point[2])
+    const radiusKm = point[3] ? Number(point[3]) : 25
+    if (Math.abs(lat) > 90 || Math.abs(lon) > 180 || radiusKm <= 0 || radiusKm > 2000) return null
+    const country = countryAt(lat, lon)
+    const known = country ? REGIONS[country] : undefined
+    // A point near a known area is in its city: within that area's own reach and the circle's.
+    // Else the large city it is near (Denver, Surabaya, Lyon), so a record's city agrees with its point.
+    const near = Object.values(REGIONS).find((r) => distanceKm(r, { lat, lon }) <= r.radiusKm + Math.min(radiusKm, 60))?.city ?? cityNear({ lat, lon }, radiusKm, distanceKm)?.name
+    return { code: 'custom', lat, lon, radiusKm, currency: known?.currency ?? 'USD', locale: known?.locale ?? [en, base], ...(country ? { country } : {}), ...(near ? { city: near } : {}) }
+  }
+  // A country code, or the country of a locale tag (`id-ID`, `en_GB`).
+  const code = (/^[a-z]{2,3}[-_]([a-z]{2})$/i.exec(text)?.[1] ?? text).toUpperCase()
+  const known = REGIONS[code]
+  return known ? { code, ...known, country: code } : null
+}
+
+/** The project's region: frontera.yaml's `locale` (or `region`), else the workspace's timezone, else the United States. */
+export function projectRegion(root: string): Region {
+  for (const file of ['frontera.yaml', 'frontera.solution.yaml']) {
+    try {
+      const doc = parseYaml(readFileSync(join(root, file), 'utf8')) as { locale?: unknown; region?: unknown } | null
+      for (const v of [doc?.region, doc?.locale]) {
+        const region = typeof v === 'string' ? parseRegion(v) : null
+        if (region) return region
+      }
+    } catch {
+      // No project file, or not YAML: the next source says.
+    }
+  }
+  const timezone = readSnapshot(root)?.settings?.timezone
+  const country = timezone ? TIMEZONE_COUNTRY[timezone] : undefined
+  if (country) return { code: country, ...REGIONS[country]!, country }
+  return { code: 'US', ...REGIONS.US!, country: 'US' }
+}
+
+const EARTH_RADIUS_KM = 6371.0088
+const rad = (deg: number) => (deg * Math.PI) / 180
+const deg = (r: number) => (r * 180) / Math.PI
+
+/** The great-circle distance between two points, in kilometres. */
+export function distanceKm(a: { lat: number; lon: number }, b: { lat: number; lon: number }): number {
+  const dLat = rad(b.lat - a.lat)
+  const dLon = rad(b.lon - a.lon)
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(rad(a.lat)) * Math.cos(rad(b.lat)) * Math.sin(dLon / 2) ** 2
+  return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)))
+}
+
+/**
+ * A point within the region's radius, spread evenly over its circle: a
+ * distance (the square root of a uniform draw, so the area is even, not the
+ * centre crowded) along a bearing, on the sphere. One point per row: its
+ * latitude and longitude come from the same draw, never one each.
+ */
+export function pointIn(faker: Faker, region: Pick<Region, 'lat' | 'lon' | 'radiusKm'>): { lat: number; lon: number } {
+  // A hair inside the radius, so rounding to six places never carries a point past it.
+  const reach = Math.max(0, region.radiusKm - 0.001)
+  const angular = (reach * Math.sqrt(faker.number.float({ min: 0, max: 1 }))) / EARTH_RADIUS_KM
+  const bearing = faker.number.float({ min: 0, max: 2 * Math.PI })
+  const φ1 = rad(region.lat)
+  const λ1 = rad(region.lon)
+  const φ2 = Math.asin(Math.sin(φ1) * Math.cos(angular) + Math.cos(φ1) * Math.sin(angular) * Math.cos(bearing))
+  const λ2 = λ1 + Math.atan2(Math.sin(bearing) * Math.sin(angular) * Math.cos(φ1), Math.cos(angular) - Math.sin(φ1) * Math.sin(φ2))
+  const lon = ((deg(λ2) + 540) % 360) - 180
+  return { lat: Number(deg(φ2).toFixed(6)), lon: Number(lon.toFixed(6)) }
+}
+
+// ── What a property allows ───────────────────────────────────────────────────
+
+/** What the Blueprint says a property's values are: allowed values, bounds, a length. */
+interface Constraint {
+  values?: string[]
+  min?: number
+  max?: number
+  minLength?: number
+  maxLength?: number
+  /** Where the values came from, for the reader of the code: semantic type, description, an Action's input. */
+  from?: 'property' | 'semantic-type' | 'description' | 'action' | 'metric'
+}
+
+const asStrings = (v: unknown): string[] | null => (Array.isArray(v) && v.length && v.every((x) => typeof x === 'string' || typeof x === 'number') ? [...new Set(v.map(String))] : null)
+
+const asNumber = (v: unknown): number | undefined => {
+  const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() ? Number(v) : NaN
+  return Number.isFinite(n) ? n : undefined
+}
+
+/**
+ * The values an Action allows into a property, per type: `property_set
+ * <property> ← input <field>` where the input's string value type has an enum.
+ */
+export function actionEnums(actions: ActionFile[]): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  for (const a of actions) {
+    const type = a.subject?.objectType
+    if (!type) continue
+    const inputs = new Map((a.inputs ?? []).flatMap((i) => (i.apiName ? [[i.apiName, i] as const] : [])))
+    for (const outcome of a.businessOutcomes ?? []) {
+      for (const change of outcome.expectedChanges ?? []) {
+        if (change.kind !== 'property_set' || !change.property) continue
+        const key = `${type}.${change.property}`
+        const values = change.value?.kind === 'input' && change.value.field ? asStrings(inputs.get(change.value.field)?.valueType?.enum) : change.value?.kind === 'literal' && change.value.value !== undefined ? [String(change.value.value)] : null
+        if (values) out.set(key, [...new Set([...(out.get(key) ?? []), ...values])])
+      }
+    }
+  }
+  return out
+}
+
+/** What the metrics say of a type's properties: the values their filters compare with, and the range a share is in. */
+export interface MetricHints {
+  /** `Type.property` → the values a metric filter keeps (`metricKey eq occupancy_pct`). */
+  values: Map<string, string[]>
+  /** `Type.property` → the range a metric reads it in: a percent averaged is between 0 and 100. */
+  ranges: Map<string, { min: number; max: number }>
+}
+
+const SHARE_WORDS = /\b(pct|percent|percentage|rate|ratio|share|occupancy|utili[sz]ation|conversion|churn|uptime)\b/
+
+/**
+ * The metrics' hints for sample data. A filter `{ property, op: eq, value }`
+ * names a value the property takes (else a metric over it counts nothing),
+ * and an average, minimum or maximum of a property over every row, in a
+ * metric that reads as a share (`occupancyRate`, "Occupancy percent"), keeps
+ * that property between 0 and 100. A measure with filters hints nothing
+ * about the range: only the rows it keeps are shares (a unit property and
+ * the kind it follows say those; `unitPlanOf`).
+ */
+export function metricHints(metrics: MetricFile[]): MetricHints {
+  const values = new Map<string, string[]>()
+  const ranges = new Map<string, { min: number; max: number }>()
+  const literals = (type: string, node: unknown) => {
+    if (Array.isArray(node)) return node.forEach((n) => literals(type, n))
+    if (!node || typeof node !== 'object') return
+    const o = node as Record<string, unknown>
+    if (typeof o.property === 'string' && (o.op === 'eq' || o.op === 'in')) {
+      const said = (Array.isArray(o.value) ? o.value : [o.value]).filter((v): v is string => typeof v === 'string' && v.length > 0 && v.length <= 64)
+      if (said.length) values.set(`${type}.${o.property}`, [...new Set([...(values.get(`${type}.${o.property}`) ?? []), ...said])])
+    }
+    for (const key of ['and', 'or', 'not']) if (key in o) literals(type, o[key])
+  }
+  for (const m of metrics) {
+    const type = m.objectType
+    if (!type) continue
+    for (const measure of m.definition?.measures ?? []) {
+      if (measure.filters !== undefined) literals(type, measure.filters)
+      if (!measure.property || measure.filters !== undefined || !/^(avg|average|mean|min|max|median)$/i.test(measure.agg ?? '')) continue
+      const said = `${words(m.apiName)} ${(m.displayName ?? '').toLowerCase()} ${(measure.label ?? '').toLowerCase()} ${words(measure.property)}`
+      if (SHARE_WORDS.test(said)) ranges.set(`${type}.${measure.property}`, { min: 0, max: 100 })
+    }
+  }
+  return { values, ranges }
+}
+
+function constraintFor(type: ObjectType, p: Property, semantic: Map<string, SemanticType>, shared: Map<string, SharedField>, fromActions: Map<string, string[]>, fromMetrics: MetricHints = { values: new Map(), ranges: new Map() }): Constraint {
+  const c = ownConstraint(type, p, semantic, shared, fromActions, fromMetrics)
+  // A share a metric averages stays a share, unless the Blueprint bounds it itself.
+  const range = (p.valueType ?? 'string') === 'number' ? fromMetrics.ranges.get(`${type.apiName}.${p.apiName}`) : undefined
+  if (range && c.min === undefined && c.max === undefined && !c.values) return { ...c, min: range.min, max: range.max, from: c.from ?? 'metric' }
+  return c
+}
+
+function ownConstraint(type: ObjectType, p: Property, semantic: Map<string, SemanticType>, shared: Map<string, SharedField>, fromActions: Map<string, string[]>, fromMetrics: MetricHints): Constraint {
+  const own = asStrings(p.allowedValues) ?? asStrings(p.enum)
+  if (own) return { values: own, from: 'property' }
+  const st = semantic.get(p.semanticType ?? '') ?? semantic.get((p.sharedField && shared.get(p.sharedField)?.semanticType) || '')
+  const rule = st?.rule
+  if (rule) {
+    const values = asStrings(rule.enum)
+    if (values) return { values, from: 'semantic-type' }
+    const c: Constraint = { from: 'semantic-type' }
+    const min = asNumber(rule.minimum)
+    const max = asNumber(rule.maximum)
+    if (min !== undefined) c.min = min
+    if (max !== undefined) c.max = max
+    if (typeof rule.minLength === 'number') c.minLength = rule.minLength
+    if (typeof rule.maxLength === 'number') c.maxLength = rule.maxLength
+    if (Object.keys(c).length > 1) return c
+  }
+  // The property's own words first, then the shared field's it implements.
+  const sharedDescription = p.sharedField ? shared.get(p.sharedField)?.description : undefined
+  // A number whose description gives its range ("How many hours … (1 to 12)") keeps to it.
+  const range = (p.valueType ?? 'string') === 'number' ? (describedRange(p.description) ?? describedRange(sharedDescription)) : null
+  if (range) return { ...range, from: 'description' }
+  const listed = (p.valueType ?? 'string') === 'string' ? (listedValues(p.description) ?? listedValues(sharedDescription)) : null
+  if (listed) return { values: listed, from: 'description' }
+  const action = fromActions.get(`${type.apiName}.${p.apiName}`)
+  if (action?.length) return { values: action, from: 'action' }
+  const metric = (p.valueType ?? 'string') === 'string' ? fromMetrics.values.get(`${type.apiName}.${p.apiName}`) : undefined
+  if (metric?.length) return { values: metric, from: 'metric' }
+  return {}
+}
+
+/**
+ * The range a description gives a number: in parentheses ("(1 to 12)",
+ * "(1-12 hours)", "(0–100)", "(between 1 and 5)") or said as "between 1 and
+ * 5". Null when it gives none, or the two ends are not low then high.
+ */
+export function describedRange(description: string | undefined): { min: number; max: number } | null {
+  if (!description) return null
+  const num = '(-?(?:\\d{1,3}(?:,\\d{3})+|\\d+)(?:\\.\\d+)?)'
+  const patterns = [
+    new RegExp(`\\(\\s*(?:from\\s+|between\\s+)?${num}\\s*(?:to|-|–|—|\\.\\.|and)\\s*${num}\\b[^()]*\\)`, 'i'),
+    new RegExp(`\\bbetween\\s+${num}\\s+and\\s+${num}\\b`, 'i'),
+  ]
+  for (const re of patterns) {
+    const m = re.exec(description)
+    if (!m) continue
+    const min = Number(m[1]!.replace(/,/g, ''))
+    const max = Number(m[2]!.replace(/,/g, ''))
+    if (Number.isFinite(min) && Number.isFinite(max) && min < max) return { min, max }
+  }
+  return null
+}
+
+/** A number that keeps to the bounds, near the guess the name gave. */
+function bounded(faker: Faker, guess: number, c: Constraint, integer: boolean): number {
+  if (c.min === undefined && c.max === undefined) return guess
+  const min = c.min ?? Math.min(guess, (c.max ?? 0) - 100)
+  const max = c.max ?? Math.max(guess, min + 1000)
+  if (guess >= min && guess <= max) return guess
+  // A whole number between bounds no whole number lies in (0.2 to 0.8) is a fraction.
+  return integer && Math.ceil(min) <= Math.floor(max) ? faker.number.int({ min: Math.ceil(min), max: Math.floor(max) }) : faker.number.float({ min, max, fractionDigits: 2 })
+}
+
+function fitLength(faker: Faker, text: string, c: Constraint): string {
+  let out = text
+  if (c.maxLength !== undefined && out.length > c.maxLength) out = out.slice(0, Math.max(0, c.maxLength)).trimEnd()
+  if (c.minLength !== undefined && out.length < c.minLength) out = out + faker.string.alphanumeric({ length: c.minLength - out.length, casing: 'upper' })
+  return out
+}
+
+// ── Time: a row's timestamps follow its lifecycle ────────────────────────────
+
+/** Where a time sits in a record's life, from its name: created first, updated last. */
+export function lifecycleRank(name: string): number {
+  const n = words(name)
+  if (/\b(birth|dob|born)\b/.test(n)) return -1
+  if (/\b(created|opened|submitted|registered|reported|requested|placed|received|started|start|joined|signed up|logged)\b/.test(n)) return 0
+  if (/\b(assigned|accepted|acknowledged|scheduled|dispatched|answered|responded|first response|approved|shipped|picked|confirmed|paid)\b/.test(n)) return 1
+  if (/\b(due|deadline|expires?|expiry|sla|target|expected|promised|eta)\b/.test(n)) return 2
+  if (/\b(resolved|closed|completed|finished|ended|end|delivered|cancell?ed|rejected|fulfilled|returned)\b/.test(n)) return 3
+  if (/\b(updated|modified|changed|last|synced|seen)\b/.test(n)) return 4
+  return 1.5
+}
+
+/**
+ * A time from before a record's own life, by its name: when an asset was
+ * installed or bought, a company founded, a person hired. Years back, not
+ * the last 120 days: the range in years before today; null for any other.
+ */
+export function yearsBack(p: Pick<Property, 'apiName' | 'displayName'>): { min: number; max: number } | null {
+  const n = `${words(p.apiName)} ${(p.displayName ?? '').toLowerCase()}`
+  if (/\b(installed|installation|install date|commissioned|commissioning|built|constructed|manufactured|purchased|purchase date|acquired|bought|in service since|erected|fitted|mounted|laid)\b/.test(n)) return { min: 0.5, max: 15 }
+  if (/\b(founded|established|incorporated|inception)\b/.test(n)) return { min: 2, max: 60 }
+  if (/\b(hired|hire date|employed since|employment start|start of employment)\b/.test(n)) return { min: 0.25, max: 20 }
+  return null
+}
+
+const ENDS_LIFE = 3
+/** A status that says the record has not reached its end yet. */
+const STILL_OPEN = /^(open|new|pending|in[_ -]?progress|active|assigned|waiting|on[_ -]?hold|queued|draft|todo|submitted|escalated|triage|scheduled)$/i
+
+// ── State: what a record's state allows the rest of it to hold ──────────────
+
+/** Where a record is in its life, by its state: not started, under way, or ended. */
+export type Phase = 'initial' | 'active' | 'terminal'
+
+/** A state nobody has started on. */
+const INITIAL_STATE = /^(new|draft|pending|submitted|created|requested|queued|todo|to[_ -]?do|unassigned|received|backlog|reported|raised|triage)$/i
+/** A state that ends a record's life. */
+const TERMINAL_STATE = /^(closed|resolved|done|complete|completed|cancell?ed|rejected|finished|archived|delivered|fulfilled|paid|won|lost|expired|retired|declined|refunded|returned|settled|withdrawn|abandoned|voided|dismissed|no[_ -]?show)$/i
+/**
+ * An end without the work done: the record ended (it has a closing time),
+ * but nothing was fixed, so a field that says what was done stays empty.
+ */
+const UNFINISHED_END = /^(cancell?ed|rejected|declined|lost|expired|withdrawn|abandoned|void|voided|dismissed|refused|no[_ -]?show|duplicate)$/i
+
+/**
+ * Each of a state property's values, as a phase: a value whose name says it
+ * (new, pending; closed, resolved, cancelled) is that phase, every other one
+ * is under way. With three or more values and no name that says so, the
+ * first is taken as the start and the last as the end, the order a semantic
+ * type usually lists a life in.
+ */
+export function statePhases(values: readonly string[]): Map<string, Phase> {
+  const out = new Map<string, Phase>(values.map((v) => [v, INITIAL_STATE.test(v) ? 'initial' : TERMINAL_STATE.test(v) ? 'terminal' : 'active']))
+  if (values.length >= 3) {
+    if (![...out.values()].includes('initial') && out.get(values[0]!) === 'active') out.set(values[0]!, 'initial')
+    if (![...out.values()].includes('terminal') && out.get(values[values.length - 1]!) === 'active') out.set(values[values.length - 1]!, 'terminal')
+  }
+  return out
+}
+
+/** A value's phase when the state has no listed values: by its name alone. */
+function phaseOf(value: string, phases: Map<string, Phase> | null): Phase | null {
+  if (!value) return null
+  const known = phases?.get(value)
+  if (known) return known
+  if (INITIAL_STATE.test(value)) return 'initial'
+  if (TERMINAL_STATE.test(value)) return 'terminal'
+  return STILL_OPEN.test(value) ? 'active' : null
+}
+
+/** A field that is set as a record ends: its resolution, its outcome, why it was closed. */
+function endsLife(p: Property): boolean {
+  const n = words(p.apiName)
+  return /\b(resolution|resolved|outcome|closure|closing|closed|completion|completed|cancell?ation|cancell?ed|root cause|fix|final)\b/.test(n) || /\b(once|when|after)\b[^.]*\b(closed|resolved|completed|done|finished)\b/i.test(p.description ?? '')
+}
+
+/**
+ * A field that is set once someone takes the record on: who it is assigned
+ * to, the technician sent, its owner; or one its description says is empty
+ * while the record is new.
+ */
+function startsWork(p: Property, ref: Reference | undefined, entities: ReadonlyMap<string, Entity | null>): boolean {
+  const n = words(p.apiName)
+  if (/\b(empty|blank|unset|none)\b[^.]*\b(while|until|when)\b[^.]*\b(new|unassigned|open|pending|created|raised)\b/i.test(p.description ?? '')) return true
+  if (/\b(assigned|assignee|technician|handler|responder|engineer|driver|courier|dispatcher|worker|owner)\b/.test(n)) return true
+  return !!ref && entities.get(ref.objectType) === 'person' && /\b(assigned|assignee|technician|handler|responder|engineer|driver|courier|agent|rep|owner|worker|staff)\b/.test(n)
+}
+
+/** A phrase standing on its own in a text: "escalated" in "unless escalated", not in "de-escalated". */
+const says = (text: string, phrase: string) => !!phrase && new RegExp(`(?<![\\w-])${phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w-])`, 'i').test(text)
+
+/**
+ * When a field holds a value, from its description: "empty unless
+ * escalated", "only when the work order is critical", "set only if the
+ * customer is a business", "empty while on hold". A test on the row (and
+ * its phase), or null when the description says no such thing or names
+ * nothing the row has. What the condition names, in order: a yes/no
+ * property ("escalated"), a value of a property that lists values ("on
+ * hold", "critical"), the record ending or still open ("closed", "open"),
+ * then another property by name (set when that one is). "not" turns it.
+ */
+/**
+ * The condition a description makes a field's value depend on, as written:
+ * "escalated" in "empty unless escalated" (`emptyWhen` false: the field is
+ * set while it holds), "on hold" in "empty while on hold" (`emptyWhen`
+ * true). Null when the description makes the field conditional on nothing.
+ */
+export function conditionOf(description: string | undefined): { text: string; emptyWhen: boolean } | null {
+  const d = (description ?? '').replace(/\s+/g, ' ')
+  let emptyWhen = false
+  let m = /\b(?:empty|blank|unset|null|none|left empty)\s+(?:unless|until|except (?:when|if|once))\s+([^.;]+)/i.exec(d)
+  m ??= /\bonly (?:when|if|once|while|for)\s+([^.;]+)/i.exec(d)
+  if (!m) {
+    m = /\b(?:empty|blank|unset|null|none|left empty)\s+(?:when|while|if|for)\s+([^.;]+)/i.exec(d)
+    emptyWhen = !!m
+  }
+  return m ? { text: m[1]!.trim(), emptyWhen } : null
+}
+
+export function filledWhen(
+  p: Pick<Property, 'apiName' | 'description'>,
+  properties: Property[],
+  statusProperty: Property | undefined,
+  phases: Map<string, Phase> | null,
+  valuesOf: (property: string) => readonly string[] | undefined = () => undefined,
+): ((row: Row, phase: Phase | null) => boolean) | null {
+  const condition = conditionOf(p.description)
+  if (!condition) return null
+  const { text, emptyWhen: negate } = condition
+  const not = /\b(not|no longer|isn't|is not|never|hasn't|has not)\b/i.test(text)
+  const flip = negate !== not
+  const others = properties.filter((x) => x.apiName !== p.apiName)
+  const done = (holds: (row: Row, phase: Phase | null) => boolean) => (flip ? (row: Row, phase: Phase | null) => !holds(row, phase) : holds)
+  // A yes/no property: `escalated`, `isEscalated`, "Escalated".
+  for (const b of others.filter((x) => x.valueType === 'boolean')) {
+    const named = words(b.apiName).replace(/^(is|has|was) /, '')
+    if (says(text, named) || says(text, words(b.apiName)) || (b.displayName && says(text, b.displayName.toLowerCase()))) return done((row) => row[b.apiName] === true || row[b.apiName] === 'true')
+  }
+  // A value of a property that lists values, the state first.
+  const listing = [...(statusProperty ? [statusProperty] : []), ...others.filter((x) => x !== statusProperty)]
+  for (const x of listing) {
+    const values = x === statusProperty && phases ? [...phases.keys()] : valuesOf(x.apiName)
+    const named = values?.filter((v) => says(text, valueWords(v)) || says(text, v))
+    if (named?.length) return done((row) => named.includes(String(row[x.apiName] ?? '')))
+  }
+  // The record's end, or its being open.
+  if (statusProperty && /\b(closed|resolved|done|completed|finished|ended|cancell?ed)\b/i.test(text)) return done((_row, phase) => phase === 'terminal')
+  if (statusProperty && /\b(open|active|in progress|under way|ongoing)\b/i.test(text)) return done((_row, phase) => phase !== null && phase !== 'terminal')
+  // Another property by name: set when that one is.
+  for (const x of others) {
+    const named = words(x.apiName).replace(/ id$/, '')
+    if (named.length > 2 && says(text, named)) return done((row) => filled(row[x.apiName]))
+  }
+  return null
+}
+
+// ── Values ───────────────────────────────────────────────────────────────────
+
+/**
+ * A property that says which record a row is, or what its figure means: its
+ * title, a period, a fiscal year, a key or code (`metricKey`), a case or
+ * scope, a currency or unit. Sample data never leaves it empty at random,
+ * only by the state rules.
+ */
+export function defining(type: Pick<ObjectType, 'title' | 'primaryKey'>, p: Pick<Property, 'apiName'>): boolean {
+  if (p.apiName === type.title && p.apiName !== type.primaryKey) return true
+  return /\b(period|fiscal year|year|month|quarter|week|key|code|scenario|case|scope|currency|unit|uom)$/.test(words(p.apiName))
+}
+
+/** This year, or the one before or after it. */
+const yearNear = (faker: Faker) => new Date().getUTCFullYear() + faker.number.int({ min: -1, max: 1 })
+
+/** How many of something a record has, by its name: rooms, floors, people. Null when the name doesn't count anything. */
+function smallCount(faker: Faker, name: string, description: string): number | null {
+  if (/\b(bedrooms?|bathrooms?|beds|baths|toilets)\b/.test(name)) return faker.number.int({ min: 1, max: 4 })
+  if (/\b(floors?|storeys?|stories|levels)\b/.test(name)) return faker.number.int({ min: 1, max: 30 })
+  if (/\b(rooms|doors|windows|lanes|spaces|parking|bays|pets|children|kids|adults|guests|occupants|residents|people|persons|headcount|attendees|visits|attempts|retries|stops|vehicles|reminders)\b/.test(name)) return faker.number.int({ min: 1, max: 8 })
+  // A count a description introduces ("How many leases…") stays small; one of hours, days or visits is at least one.
+  if (/^\s*how many\s+(minutes|hours|days|weeks|months|years|visits|times|steps)\b/i.test(description)) return faker.number.int({ min: 1, max: 10 })
+  if (/^\s*(how many|the number of|number of|count of)\b/i.test(description) || /^(num|number of|no of|count of) /.test(name)) return faker.number.int({ min: 0, max: 10 })
+  return null
+}
+
+/** A value for one property, from what it allows, its type and its name. */
+function valueFor(faker: Faker, type: ObjectType, p: Property, c: Constraint, region: Region): unknown {
   const name = words(p.apiName)
-  const listed = listedValues(p.description)
-  if (listed && (p.valueType ?? 'string') === 'string') return faker.helpers.arrayElement(listed)
-  switch (p.valueType ?? 'string') {
+  const valueType = p.valueType ?? 'string'
+  // Values a metric's filter names are some of a property's, not all of them: other rows read as they would.
+  if (c.values?.length && (valueType === 'string' || valueType === 'number') && (c.from !== 'metric' || faker.datatype.boolean({ probability: 0.7 }))) {
+    const v = faker.helpers.arrayElement(c.values)
+    return valueType === 'number' && Number.isFinite(Number(v)) ? Number(v) : v
+  }
+  switch (valueType) {
     case 'boolean':
       return faker.datatype.boolean({ probability: /^(is|has) /.test(name) ? 0.35 : 0.5 })
     case 'number': {
-      if (/csat|rating|stars|score/.test(name)) return faker.number.int({ min: 1, max: 5 })
-      if (/percent|rate|ratio|share/.test(name)) return faker.number.float({ min: 0, max: 100, fractionDigits: 1 })
-      if (/hours?\b|sla/.test(name)) return faker.helpers.arrayElement([4, 8, 24, 48, 72])
-      if (/days?\b/.test(name)) return faker.number.int({ min: 1, max: 30 })
-      if (/quantity|qty|count|units|items/.test(name)) return faker.number.int({ min: 1, max: 6 })
-      if (/age\b/.test(name)) return faker.number.int({ min: 18, max: 80 })
-      if (/price|amount|total|revenue|cost|value|fee|refund|balance|spend|discount/.test(name)) return Number(faker.commerce.price({ min: 5, max: 900 }))
-      if (/weight|kg/.test(name)) return faker.number.float({ min: 0.1, max: 25, fractionDigits: 2 })
-      if (/lat/.test(name)) return faker.location.latitude()
-      if (/lon|lng/.test(name)) return faker.location.longitude()
-      return faker.number.int({ min: 1, max: 1000 })
-    }
-    case 'date':
-      return faker.date.past({ years: 2, refDate: state.today }).toISOString().slice(0, 10)
-    case 'timestamp': {
-      // Times in a row follow one another (opened, then answered, then resolved).
-      const at = state.lastTime === null
-        ? faker.date.recent({ days: 120, refDate: state.today }).getTime()
-        : state.lastTime + faker.number.int({ min: 20, max: 72 * 60 }) * 60_000
-      const clamped = Math.min(at, state.today.getTime())
-      state.lastTime = clamped
-      return new Date(clamped).toISOString().replace(/\.\d{3}Z$/, 'Z')
+      const point = /\blat(itude)?\b/.test(name) || /\b(lon|lng|long|longitude)\b/.test(name) ? pointIn(faker, region) : null
+      if (point) return /\blat/.test(name) ? point.lat : point.lon
+      let guess: number
+      let integer = true
+      const counted = smallCount(faker, name, p.description ?? '')
+      if (/\b(fiscal year|year)$/.test(name) && !/\byears\b/.test(name)) guess = yearNear(faker)
+      else if (counted !== null) guess = counted
+      else if (/csat|rating|stars|score/.test(name)) guess = faker.number.int({ min: 1, max: 5 })
+      else if (/\b(probability|likelihood|confidence)\b/.test(name)) ((guess = faker.number.float({ min: 0.05, max: 0.98, fractionDigits: 2 })), (integer = false))
+      else if (/percent|\bpct\b|rate|ratio|share/.test(name)) ((guess = faker.number.float({ min: 0, max: 100, fractionDigits: 1 })), (integer = false))
+      else if (/\bmonths?\b/.test(name)) guess = faker.number.int({ min: 1, max: 36 })
+      else if (/\byears\b/.test(name)) guess = faker.number.int({ min: 1, max: 30 })
+      else if (/\b(minutes?|mins?)\b/.test(name)) guess = faker.helpers.arrayElement([15, 30, 30, 45, 60, 60, 90, 120])
+      else if (/\b(capacity|seats|max guests|max people|max occupants)\b/.test(name)) guess = faker.number.int({ min: 2, max: 60 })
+      else if (/hours?\b|sla/.test(name)) guess = faker.helpers.arrayElement([4, 8, 24, 48, 72])
+      else if (/days?\b/.test(name)) guess = faker.number.int({ min: 1, max: 30 })
+      else if (/quantity|qty|count|units|items/.test(name)) guess = faker.number.int({ min: 1, max: 6 })
+      else if (/age\b/.test(name)) guess = faker.number.int({ min: 18, max: 80 })
+      else if (/price|amount|total|revenue|cost|value|fee|refund|balance|spend|discount|\brent\b|income|\bnoi\b|salary|wage|budget|premium|deposit|payment|charge|\b(sgd|usd|eur|gbp|idr|aud|myr)\b/.test(name)) {
+        // A year's worth reads as a year's: annual rent is twelve months of it.
+        const yearly = /\b(annual|annualised|annualized|yearly|per year|ltm)\b/.test(name) ? 12 : 1
+        guess = Number((Number(faker.commerce.price({ min: 5, max: 900 })) * yearly).toFixed(2))
+        integer = false
+      }
+      else if (/weight|kg/.test(name)) ((guess = faker.number.float({ min: 0.1, max: 25, fractionDigits: 2 })), (integer = false))
+      else guess = faker.number.int({ min: 1, max: 1000 })
+      return bounded(faker, guess, c, integer)
     }
     case 'json':
       return JSON.stringify({})
     case 'geopoint':
-      return JSON.stringify({ lat: faker.location.latitude(), lon: faker.location.longitude() })
+      return JSON.stringify(pointIn(faker, region))
     case 'media_reference':
       return ''
+    case 'date':
+    case 'timestamp':
+      // Set with the row's other times, in lifecycle order (`fillTimes`).
+      return undefined
     default:
       break
   }
+  return fitLength(faker, textFor(faker, type, p, region), c)
+}
+
+/**
+ * A time of day a text property holds, by its name: when something opens or
+ * starts (`openTime`, `opensAt`, `start time`), or closes or ends
+ * (`closeTime`, `end time`). Null for any other text.
+ */
+export function timeOfDayRole(p: Pick<Property, 'apiName' | 'valueType'>): 'open' | 'close' | null {
+  if ((p.valueType ?? 'string') !== 'string') return null
+  const n = words(p.apiName)
+  const timed = /\b(time|hour)$/.test(n) || /^(opens?|closes?|starts?|ends?)( at)?$/.test(n)
+  if (!timed) return null
+  if (/\b(open|opens|opening|start|starts|starting|from)\b/.test(n)) return 'open'
+  if (/\b(close|closes|closing|end|ends|ending|until)\b/.test(n)) return 'close'
+  return null
+}
+
+/** A time of day, `HH:MM`, on the half hour: an opening in the morning, a closing in the evening, so it closes after it opens. */
+function timeOfDay(faker: Faker, role: 'open' | 'close'): string {
+  return timeOfDayFrom(() => faker.number.float({ min: 0, max: 0.999999 }), role)
+}
+
+function timeOfDayFrom(draw: () => number, role: 'open' | 'close'): string {
+  // 06:00–10:30 to open, 17:00–23:00 to close.
+  const halfHours = role === 'open' ? 12 + Math.floor(draw() * 10) : 34 + Math.floor(draw() * 13)
+  return `${String(Math.floor(halfHours / 2)).padStart(2, '0')}:${halfHours % 2 ? '30' : '00'}`
+}
+
+function textFor(faker: Faker, type: ObjectType, p: Property, region: Region): string {
+  const name = words(p.apiName)
+  const role = timeOfDayRole(p)
+  if (role) return timeOfDay(faker, role)
+  // Opening hours: from a morning to an evening time.
+  if (/^(hours|opening hours|business hours|operating hours|open hours)$/.test(name)) return `${timeOfDay(faker, 'open')}–${timeOfDay(faker, 'close')}`
+  // A reporting period a month long: `2026-09`, in the last year.
+  if (/^(period|month|reporting period|billing period|fiscal period|period month)$/.test(name)) {
+    const at = new Date(Date.UTC(new Date().getUTCFullYear(), new Date().getUTCMonth() - faker.number.int({ min: 0, max: 11 }), 1))
+    return `${at.getUTCFullYear()}-${String(at.getUTCMonth() + 1).padStart(2, '0')}`
+  }
+  // A fiscal year as finance says it (FY2027); a year, a quarter.
+  if (/\bfiscal year$|^fy$/.test(name)) return `FY${yearNear(faker)}`
+  if (/^(year|calendar year|reporting year)$/.test(name)) return String(yearNear(faker))
+  if (/^(quarter|fiscal quarter|reporting quarter)$/.test(name)) return `${new Date().getUTCFullYear()}-Q${faker.number.int({ min: 1, max: 4 })}`
   if (/e ?mail/.test(name)) return faker.internet.email({ provider: 'example.com' }).toLowerCase()
-  if (/phone|mobile/.test(name)) return faker.phone.number({ style: 'international' })
+  if (/phone|mobile/.test(name)) return phoneFor(faker, region)
   if (/first name|given name/.test(name)) return faker.person.firstName()
   if (/last name|surname|family name/.test(name)) return faker.person.lastName()
-  if (/(^|\b)(name|full name|customer name|contact)$/.test(name) && /customer|person|user|contact|employee|member|agent/i.test(type.apiName + name)) return faker.person.fullName()
+  if (/\bjob title\b|\bposition\b/.test(name)) return faker.person.jobTitle()
+  // A record's name reads like what the record is: a person's, a company's, a place's.
+  const named = nameFor(faker, type, name, p)
+  if (named !== null) return named
   if (/company|organi[sz]ation|account name|merchant|vendor|supplier/.test(name)) return faker.company.name()
   if (/product|item name/.test(name)) return faker.commerce.productName()
-  if (/sku|code|reference/.test(name)) return faker.string.alphanumeric({ length: 8, casing: 'upper' })
-  if (/city/.test(name)) return faker.location.city()
-  if (/country/.test(name)) return faker.location.countryCode()
+  if (/\b(idempotency|uuid|guid|request id|correlation id|trace id)\b/.test(name)) return faker.string.uuid()
+  // Another record's key, of a type the Blueprint doesn't have: a key like one (`portfolioId` → POR-00003), from a few, so rows share them.
+  const idOf = /^([a-z][a-z ]*?) (id|key)$/.exec(name)
+  if (idOf) return `${keyPrefix(idOf[1]!.replace(/\s+/g, ''))}-${String(faker.number.int({ min: 1, max: 12 })).padStart(5, '0')}`
+  if (/sku|code|reference|serial|\bnumber\b|\bno\b/.test(name)) return faker.string.alphanumeric({ length: 8, casing: 'upper' })
+  // The city the points are in: a record's city agrees with its coordinates, never a town across the country.
+  if (/city|town/.test(name)) return cityOf(faker, region)
+  // The region's own: a record's country and currency agree with where its points are.
+  if (/country/.test(name)) return countryOf(region) ?? faker.location.countryCode()
   if (/postal|zip/.test(name)) return faker.location.zipCode()
   if (/address|street/.test(name)) return faker.location.streetAddress()
-  if (/currency/.test(name)) return 'USD'
+  if (/currency/.test(name)) return region.currency
   if (/url|website|link/.test(name)) return faker.internet.url()
   if (/carrier|courier/.test(name)) return faker.helpers.arrayElement(['DHL', 'UPS', 'FedEx', 'Royal Mail', 'PostNL'])
-  if (/assignee|owner|agent|rep/.test(name)) return `agent-${faker.person.firstName().toLowerCase()}`
+  // Who did it: a person's name (prepared by, decided by, assigned to).
+  if (/\b(prepared|decided|approved|created|submitted|reviewed|requested|reported|signed|handled|updated|modified|assigned|raised|completed|closed|resolved|entered|recorded|written|authored|checked|verified|owned) by$|^assigned to$/.test(name)) return `${faker.person.firstName()} ${faker.person.lastName()}`
+  if (/\b(assignee|owner|agent|rep)\b/.test(name)) return `agent-${faker.person.firstName().toLowerCase()}`
   if (/segment|tier|plan/.test(name)) return faker.helpers.arrayElement(['standard', 'plus', 'enterprise'])
-  // English words, not lorem ipsum: sample rows are read by people and by Agents.
-  if (/subject|title|summary|headline/.test(name)) return phrase(faker)
-  if (/description|notes?|body|comment|message|reason|details?/.test(name)) return `${phrase(faker)}. ${faker.hacker.phrase()}`
-  if (/name/.test(name)) return faker.commerce.productName()
+  // A title, a description, a resolution or a note is written from the rest of the row (`proseFor`).
+  if (/name/.test(name)) return `${title(faker.word.adjective())} ${typeWords(type)}`
   if (/status|state|stage/.test(name)) return faker.helpers.arrayElement(['open', 'in_progress', 'done'])
+  if (/priority|severity|urgency/.test(name)) return faker.helpers.weightedArrayElement([{ value: 'low', weight: 3 }, { value: 'medium', weight: 4 }, { value: 'high', weight: 2 }, { value: 'critical', weight: 1 }])
   if (/category|type|kind/.test(name)) return faker.helpers.arrayElement(['general', 'billing', 'delivery', 'product'])
   return faker.word.noun()
 }
 
-/** "Replace damaged charger": a short line that reads like a title. */
-function phrase(faker: Faker): string {
-  const verb = faker.word.verb()
-  return `${verb[0]!.toUpperCase()}${verb.slice(1)} ${faker.word.adjective()} ${faker.word.noun()}`
+// ── What a record is: a person, an organization, a place, a thing ───────────
+
+/** The kind of record an object type (or a property's own words) says it is. */
+export type Entity = 'person' | 'organization' | 'place' | 'thing' | 'product'
+
+const ENTITY_WORDS: Array<[Entity, RegExp]> = [
+  ['person', /\b(customer|person|people|user|contact|employee|member|agent|technician|engineer|driver|staff|worker|doctor|patient|student|teacher|nurse|courier|representative|rep|owner|manager|operator|dispatcher|inspector|officer|resident|guest|passenger|candidate|applicant|volunteer|author|buyer|seller|subscriber|lead|clinician|physician|caller|requester|reporter|assignee|approver|reviewer|traveller|traveler|player|client|recipient|signatory|holder|beneficiary)s?\b/],
+  ['organization', /\b(company|companies|organi[sz]ations?|accounts?|vendors?|suppliers?|merchants?|partners?|business(es)?|firms?|carriers?|banks?|insurers?|providers?|manufacturers?|distributors?|agenc(y|ies)|institutions?|employers?|brands?|retailers?)\b/],
+  ['place', /\b(sites?|locations?|places?|stores?|branch(es)?|facilit(y|ies)|warehouses?|depots?|offices?|buildings?|propert(y|ies)|premises|venues?|stations?|substations?|plants?|campus(es)?|zones?|areas?|outlets?|hubs?|ports?|airports?|terminals?|clinics?|hospitals?|schools?|addresses)\b/],
+  ['thing', /\b(assets?|equipment|devices?|machines?|vehicles?|meters?|sensors?|units?|components?|parts?|tools?|instruments?|appliances?|transformers?|pumps?|valves?)\b/],
+  ['product', /\b(products?|items?|skus?|articles?|goods|offerings?|packages?)\b/],
+]
+
+/** What an object type's records are, from its name; null when the name does not say. */
+export function entityOf(type: Pick<ObjectType, 'apiName' | 'displayName'>): Entity | null {
+  const text = `${words(type.apiName)} ${(type.displayName ?? '').toLowerCase()}`
+  return ENTITY_WORDS.find(([, re]) => re.test(text))?.[0] ?? null
+}
+
+const title = (text: string) => (text ? text[0]!.toUpperCase() + text.slice(1) : text)
+
+/** The type's name in words, as a record's name ends: "Site", "Work order". */
+const typeWords = (type: ObjectType) => title((type.displayName ?? words(type.apiName)).toLowerCase())
+
+/**
+ * A record's name, when the property is its name (`name`, `full name`, or
+ * `<what> name`): a person's for a customer or technician, a company's for
+ * a supplier, a street and the type for a site, the type and a serial for
+ * an asset. Null when the property is not a name.
+ */
+function nameFor(faker: Faker, type: ObjectType, name: string, p?: Property): string | null {
+  const m = /^(?:(.+) )?(name|full name|display name)$/.exec(name)
+  if (!m) return null
+  // `company name` on a Contact names the company; `name` names the record.
+  const said = m[1] ? ENTITY_WORDS.find(([, re]) => re.test(m[1]!))?.[0] ?? null : null
+  if (m[1] && !said && !/^(full|display|legal|contact)$/.test(m[1])) return null
+  switch (said ?? (m[1] === 'contact' ? 'person' : entityOf(type))) {
+    case 'person':
+      // A first and a last name: no "Dr." or "Jr." to carry into an email address.
+      return `${faker.person.firstName()} ${faker.person.lastName()}`
+    case 'organization':
+      return faker.company.name()
+    case 'place':
+      // A place's name its property calls an address is one: "4 Green Walk".
+      if (!said && /\baddress\b/i.test(`${p?.displayName ?? ''} ${p?.description ?? ''}`)) return faker.location.streetAddress()
+      return `${faker.location.street()} ${said ? m[1]! : typeWords(type).toLowerCase()}`
+    case 'thing':
+      return `${said ? title(m[1]!) : typeWords(type)} ${faker.string.alpha({ length: 1, casing: 'upper' })}-${faker.string.numeric(3)}`
+    case 'product':
+      return faker.commerce.productName()
+    default:
+      return null
+  }
+}
+
+/**
+ * A draw of its own for one value of one row: the same seed, row and
+ * property give the same value however often it is written again, so a
+ * value made from the rest of the row changes only when the row does.
+ */
+function drawFor(seed: number, key: string): () => number {
+  let h = (2166136261 ^ seed) >>> 0
+  for (let i = 0; i < key.length; i++) h = Math.imul(h ^ key.charCodeAt(i), 16777619)
+  let a = h >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+const pickWith = <T>(draw: () => number, list: readonly T[]): T => list[Math.floor(draw() * list.length)]!
+
+/** A value's words: `line_damage` → "line damage", `meterFault` → "meter fault". */
+const valueWords = (value: string) => value.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').toLowerCase().trim()
+
+// ── Text: a title, a description, a resolution that read like the record ────
+
+/** The kind of free text a property holds, from its name; null when it is not free text. */
+export type Prose = 'title' | 'description' | 'resolution' | 'notes' | 'reason'
+
+export function proseKind(p: Pick<Property, 'apiName' | 'valueType' | 'description'>): Prose | null {
+  if ((p.valueType ?? 'string') !== 'string') return null
+  const n = words(p.apiName)
+  if (/\bjob title\b/.test(n) || /\b(id|ids|type|kind|category|code|status|state|stage|number|no|key|ref|url|uri|email|phone|name|priority|severity|level|count)$/.test(n)) return null
+  if (/\b(resolution|outcome|fix|fixed|remedy|root cause|closure|closing|action taken|work done|work performed)\b/.test(n) || /\bwhat was done\b|\bhow it was (fixed|resolved)\b/i.test(p.description ?? '')) return 'resolution'
+  if (/\b(reason|cause|justification|rationale)\b/.test(n) || /^\s*(why|the reason)\b/i.test(p.description ?? '')) return 'reason'
+  if (/\b(notes?|comments?|remarks?|memo|follow up)\b/.test(n)) return 'notes'
+  if (/\b(title|subject|summary|headline|topic|caption)\b/.test(n)) return 'title'
+  if (/\b(description|desc|details?|body|message|text|problem|issue|fault|complaint|symptoms?|report|narrative)\b/.test(n)) return 'description'
+  return null
+}
+
+/**
+ * Plain words for the kind of work a category names, matched on the
+ * category's own words: what a reporter says, what was done about it, the
+ * part it is usually about. `{thing}` is the asset the record is about.
+ */
+interface Vocabulary {
+  match: RegExp
+  details: string[]
+  fixes: string[]
+  part: string
+  /** Planned work (an inspection): nobody reports it. */
+  planned?: boolean
+}
+
+const VOCABULARIES: Vocabulary[] = [
+  {
+    match: /\b(outage|power|supply|electric\w*|blackout|trip\w*)\b/,
+    details: ['no supply since early morning', 'neighbouring premises are affected too', 'supply drops every few minutes', 'lights flicker before the power goes'],
+    fixes: ['Replaced the blown fuse on the {thing} and tested; supply restored', 'Reset the tripped breaker at the {thing}; supply restored', 'Re-terminated a loose connection at the {thing}; supply restored'],
+    part: 'service cable',
+  },
+  {
+    match: /\b(leak\w*|water|pipe|gas|drip\w*|burst)\b/,
+    details: ['water pooling around the meter box', 'a faint smell near the regulator', 'a steady drip from the valve', 'a damp patch spreading along the wall'],
+    fixes: ['Replaced the {thing} seal and pressure-tested; no further leak', 'Tightened the {thing} coupling and leak-tested', 'Replaced the damaged section of pipe and tested'],
+    part: 'valve',
+  },
+  {
+    match: /\b(meter\w*|reading)\b/,
+    details: ['the display has been blank since Monday', 'the reading has not changed in two weeks', 'readings stopped arriving', 'the meter shows an error code'],
+    fixes: ['Replaced the faulty meter and verified the readings', 'Re-paired the meter communications module; readings arriving', 'Reseated the meter and verified the reading'],
+    part: 'meter',
+  },
+  {
+    match: /\b(line|lines|cable|wire|pole|damage|damaged|down)\b/,
+    details: ['a branch brought the line down across the road', 'the line is sagging over a roof', 'a contractor hit a cable while digging', 'sparks seen near the pole', 'visible damage to the {thing}', 'the {thing} was struck by a vehicle'],
+    fixes: ['Repaired the damaged line and re-tensioned the span', 'Jointed the damaged cable and tested', 'Cleared vegetation and repaired the {thing} connection'],
+    part: 'line',
+  },
+  {
+    match: /\b(inspection|survey|audit|check|maintenance|preventive|routine)\b/,
+    details: ['routine inspection is due', 'requested by the asset team ahead of replacement', 'the annual safety check', 'a follow-up from the last visit'],
+    fixes: ['Inspected the {thing}; no defects found', 'Inspected and cleaned the {thing} contacts', 'Inspected the {thing}; minor corrosion treated'],
+    part: 'equipment',
+    planned: true,
+  },
+  {
+    match: /\b(noise|vibration|hum\w*|smell|smoke|heat|overheat\w*)\b/,
+    details: ['loud humming at night', 'vibration felt through the floor', 'a burning smell near the cabinet', 'the casing is hot to the touch'],
+    fixes: ['Tightened the {thing} mounting and tested', 'Replaced the worn {thing} bearing and tested', 'Cleaned the {thing} vents and checked the load'],
+    part: 'unit',
+  },
+  {
+    match: /\b(repair|broken|fault|failure|failed|defect|malfunction|breakdown)\b/,
+    details: ['it stopped working this morning', 'it works only intermittently', 'the error light is on', 'it makes a grinding noise'],
+    fixes: ['Replaced the faulty {thing} part and tested', 'Repaired the {thing} and ran a full test', 'Reset the {thing} and confirmed normal operation'],
+    part: 'unit',
+  },
+  {
+    match: /\b(billing|bill|invoice|payment|charge|charges|refund|price|fee)\b/,
+    details: ['charged twice on the last invoice', 'the amount is higher than expected', 'a payment is not showing', 'asking for a refund'],
+    fixes: ['Corrected the invoice and issued a credit', 'Applied the missing payment and confirmed the balance', 'Issued the refund and confirmed by email'],
+    part: 'account',
+  },
+  {
+    match: /\b(delivery|deliveries|shipping|shipment|parcel|package|courier|return|returns)\b/,
+    details: ['the parcel has not arrived', 'tracking has not updated in three days', 'the package arrived damaged', 'it was delivered to the wrong address'],
+    fixes: ['Re-shipped the order with tracking', 'Located the parcel with the carrier; delivered', 'Sent a replacement and arranged a return'],
+    part: 'parcel',
+  },
+  {
+    match: /\b(account|login|log in|access|password|sign in|signin)\b/,
+    details: ['cannot sign in since the update', 'locked out after a password reset', 'needs access for a new colleague'],
+    fixes: ['Reset access and confirmed sign-in', 'Unlocked the account and confirmed sign-in', 'Granted access and confirmed with the requester'],
+    part: 'account',
+  },
+  {
+    match: /\b(product|quality|item|wrong|missing)\b/,
+    details: ['the item does not match the description', 'it arrived with a part missing', 'it stopped working after a week'],
+    fixes: ['Replaced the item and confirmed with the customer', 'Sent the missing part', 'Refunded and arranged a return'],
+    part: 'item',
+  },
+]
+
+const GENERAL: Vocabulary = {
+  match: /$^/,
+  details: ['reported by phone this morning', 'needs someone to take a look', 'reported again after an earlier visit', 'details confirmed with the requester'],
+  fixes: ['Investigated and fixed the issue; the requester confirmed', 'Resolved on the first visit and tested', 'Handled and confirmed with the requester'],
+  part: 'equipment',
+}
+
+const GENERAL_ISSUES = ['service request', 'reported problem', 'follow-up request', 'general enquiry']
+const FOLLOW_UPS = ['Follow-up: call the {reporter} to confirm it is fixed', 'Follow-up: check again on the next visit', 'Follow-up: parts ordered, waiting for delivery', 'Follow-up: photos added to the record', 'Follow-up: access arranged with the site contact']
+const REASONS = ['Duplicate of an earlier request', 'Requested by the {reporter}', 'Waiting on parts', 'No access on the first visit', 'Outside the service area', 'Raised by routine monitoring']
+/** Reasons for what a field's name says happened: why it was escalated, cancelled, put on hold. */
+const REASONS_FOR: Array<[RegExp, string[]]> = [
+  [/\bescalat/, ['The {reporter} called again; still not fixed', 'At risk of breaching the SLA', 'Repeat fault within 30 days', 'Critical load at the site', 'Safety risk reported on site']],
+  [/\bcancel/, ['Duplicate of an earlier request', 'Withdrawn by the {reporter}', 'Raised in error']],
+  [/\b(hold|pause|suspend|block)/, ['Waiting on parts', 'No access on the first visit', 'Waiting for the {reporter} to confirm a time']],
+  [/\b(reject|declin|refus)/, ['Outside the service area', 'Not covered by the contract', 'Not enough detail to act on']],
+]
+
+/** A category that says nothing of the work. */
+const GENERIC_TOPIC = /^(other|others|general|misc|miscellaneous|unknown|none|n a|unspecified|default)$/
+
+/** What a row is about, from its own values and the records it links to. */
+export interface Scene {
+  /** Is the record a piece of work (a ticket, a work order) rather than a thing or a place? */
+  work: boolean
+  /** "line damage", "meter fault"; for a record that is not work, what it is ("transformer"). */
+  issue: string
+  vocabulary: Vocabulary
+  place?: string
+  /** The asset it is about, as its kind ("transformer") and its name ("Transformer A-104"). */
+  thing?: string
+  thingName?: string
+  /** Who reported it, as their type: "Customer". */
+  reporter?: string
+  /** Whose it is, by name: a customer, a company. */
+  owner?: string
+}
+
+/** Equipment a detail or a fix can name: one that names another kind than the record's is not said of it. */
+const THING_WORDS = ['pole', 'line', 'cable', 'wire', 'meter', 'valve', 'regulator', 'pipe', 'cabinet', 'transformer', 'pump', 'breaker', 'fuse', 'switchgear', 'span']
+const THING_ALIASES: Record<string, string[]> = { line: ['line', 'cable', 'wire', 'pole', 'span'], cable: ['cable', 'line', 'wire', 'pole', 'span'], wire: ['wire', 'line', 'cable'], pipe: ['pipe', 'valve'], meter: ['meter'] }
+
+/**
+ * The texts of a vocabulary that fit the record's thing (its asset's kind):
+ * "sparks seen near the pole" is not said of a meter. A text naming no
+ * equipment, or `{thing}`, fits any. None fitting, the general ones.
+ */
+export function forThing(texts: readonly string[], thing: string | undefined, fallback: readonly string[]): readonly string[] {
+  if (!thing) return texts
+  const kind = thing.toLowerCase()
+  const own = new Set(Object.entries(THING_ALIASES).flatMap(([k, words]) => (new RegExp(`\\b${k}\\b`).test(kind) ? words : [])).concat(kind.split(/\s+/)))
+  const fits = texts.filter((t) => THING_WORDS.every((w) => own.has(w) || !new RegExp(`\\b${w}s?\\b`, 'i').test(t.replace(/\{thing\}/g, ''))))
+  return fits.length ? fits : fallback
+}
+
+/** A line of free text of a kind, for a row's scene; `about` is the property's name, which may say what a reason is for. */
+export function proseFor(kind: Prose, scene: Scene, draw: () => number, about = ''): string {
+  const at = scene.place ? ` at ${scene.place}` : scene.thingName ? ` on ${scene.thingName}` : ''
+  const fill = (text: string) => text.replace(/\{thing\}/g, scene.thing ?? scene.vocabulary.part).replace(/\{reporter\}/g, (scene.reporter ?? 'requester').toLowerCase())
+  switch (kind) {
+    case 'title':
+      return `${title(scene.issue)}${at}`
+    case 'description': {
+      if (!scene.work) return `${title(scene.issue)}${at}${scene.owner ? ` for ${scene.owner}` : ''}.`
+      const detail = fill(pickWith(draw, forThing(scene.vocabulary.details, scene.thing, GENERAL.details)))
+      const what = `${scene.issue}${at}${scene.place && scene.thingName ? ` (${scene.thingName})` : ''}`
+      return scene.vocabulary.planned ? `${title(what)}: ${detail}.` : `${scene.reporter ?? 'Caller'} reports ${what}; ${detail}.`
+    }
+    case 'resolution':
+      return fill(pickWith(draw, forThing(scene.vocabulary.fixes, scene.thing, GENERAL.fixes)))
+    case 'notes':
+      return fill(pickWith(draw, FOLLOW_UPS))
+    case 'reason':
+      return fill(pickWith(draw, REASONS_FOR.find(([re]) => re.test(words(about)))?.[1] ?? REASONS))
+  }
+}
+
+// ── Readings: a unit that follows the reading's kind, a value in its range ──
+
+interface MeasureUnit {
+  unit: string
+  aliases?: string[]
+  min: number
+  max: number
+  digits: number
+}
+
+/** What a reading measures, by the words of its kind, and the units and ranges it is read in (the first is the usual one). */
+const MEASURES: Array<{ kind: RegExp; units: MeasureUnit[] }> = [
+  { kind: /\b(power factor|cos ?phi)\b/, units: [{ unit: 'PF', min: 0.8, max: 1, digits: 2 }] },
+  { kind: /\b(volt|volts|voltage)\b/, units: [{ unit: 'V', min: 205, max: 245, digits: 1 }, { unit: 'kV', min: 10, max: 22, digits: 2 }, { unit: 'mV', min: 50, max: 900, digits: 0 }] },
+  { kind: /\b(current|amps?|amperage)\b/, units: [{ unit: 'A', min: 0.5, max: 60, digits: 2 }, { unit: 'mA', min: 4, max: 20, digits: 1 }] },
+  { kind: /\b(energy|consumption|usage)\b/, units: [{ unit: 'kWh', min: 50, max: 4000, digits: 1 }, { unit: 'Wh', min: 500, max: 50000, digits: 0 }, { unit: 'MWh', min: 0.05, max: 4, digits: 3 }] },
+  { kind: /\b(power|load|demand)\b/, units: [{ unit: 'kW', min: 0.5, max: 150, digits: 2 }, { unit: 'W', min: 50, max: 5000, digits: 0 }, { unit: 'MW', min: 0.5, max: 40, digits: 2 }, { unit: '%', aliases: ['percent', 'pct'], min: 10, max: 95, digits: 1 }] },
+  { kind: /\b(temperature|temp)\b/, units: [{ unit: '°C', aliases: ['C', 'degC', 'celsius'], min: 20, max: 95, digits: 1 }, { unit: '°F', aliases: ['F', 'degF', 'fahrenheit'], min: 68, max: 203, digits: 1 }, { unit: 'K', min: 293, max: 368, digits: 1 }] },
+  { kind: /\bpressure\b/, units: [{ unit: 'bar', min: 0.5, max: 6, digits: 2 }, { unit: 'kPa', min: 50, max: 600, digits: 0 }, { unit: 'psi', min: 7, max: 90, digits: 1 }] },
+  { kind: /\bflow\b/, units: [{ unit: 'm3/h', aliases: ['m³/h', 'm3/hr'], min: 1, max: 120, digits: 1 }, { unit: 'L/min', aliases: ['lpm'], min: 5, max: 500, digits: 1 }, { unit: 'L/s', min: 0.1, max: 30, digits: 2 }] },
+  { kind: /\bhumidity\b/, units: [{ unit: '%', aliases: ['%RH', 'RH', 'percent'], min: 30, max: 90, digits: 1 }] },
+  { kind: /\bfrequency\b/, units: [{ unit: 'Hz', min: 49.8, max: 50.2, digits: 2 }] },
+  { kind: /\b(level|fill)\b/, units: [{ unit: '%', aliases: ['percent'], min: 5, max: 100, digits: 1 }, { unit: 'm', min: 0.2, max: 10, digits: 2 }] },
+  { kind: /\bvibration\b/, units: [{ unit: 'mm/s', min: 0.5, max: 12, digits: 2 }] },
+  { kind: /\b(speed|rpm|rotation)\b/, units: [{ unit: 'rpm', min: 600, max: 3600, digits: 0 }, { unit: 'km/h', min: 0, max: 120, digits: 1 }] },
+  { kind: /\bph\b/, units: [{ unit: 'pH', min: 6.5, max: 8.5, digits: 2 }] },
+  { kind: /\bvolume\b/, units: [{ unit: 'm3', aliases: ['m³'], min: 1, max: 500, digits: 1 }, { unit: 'L', min: 10, max: 5000, digits: 0 }] },
+  { kind: /\b(weight|mass)\b/, units: [{ unit: 'kg', min: 0.5, max: 500, digits: 1 }, { unit: 't', min: 0.5, max: 40, digits: 2 }] },
+  // Business measures a KPI row carries (`occupancy_pct`, `median_resolution_hours`): a share, a duration, a count, money.
+  { kind: /\b(pct|percent|percentage|rate|ratio|share|occupancy|utili[sz]ation|conversion|churn|uptime|availability)\b/, units: [{ unit: '%', aliases: ['percent', 'pct', 'percentage'], min: 55, max: 98, digits: 1 }] },
+  { kind: /\b(hours?|hrs)\b/, units: [{ unit: 'hours', aliases: ['h', 'hr', 'hrs', 'hour'], min: 1, max: 72, digits: 1 }] },
+  { kind: /\b(minutes?|mins)\b/, units: [{ unit: 'minutes', aliases: ['min', 'mins', 'minute'], min: 5, max: 240, digits: 0 }] },
+  { kind: /\b(days?)\b/, units: [{ unit: 'days', aliases: ['d', 'day'], min: 1, max: 30, digits: 0 }] },
+  { kind: /\b(rent|revenue|amount|price|cost|fee|fees|balance|spend|income|sales|arrears|budget|payment|payments)\b/, units: [{ unit: '¤', min: 500, max: 50000, digits: 2 }] },
+  // A count is said as one (`count`, `number of`) or as things that happened (`requests opened`), never a bare state word.
+  { kind: /\b(count|counts|number of|total)\b|\b[a-z]+s (opened|closed|created|raised|resolved|logged|received|sent|made)\b/, units: [{ unit: 'count', aliases: ['#', 'n', 'number', 'items'], min: 0, max: 60, digits: 0 }] },
+]
+
+/** A currency code (`SGD`) or a money word: what the money measure (`¤`) is written in. */
+const isCurrencyUnit = (unit: string) => /^[A-Z]{3}$/.test(unit) || /^(currency|money|[$€£¥])$/i.test(unit)
+
+const unitKey = (unit: string) => unit.toLowerCase().replace(/[°º\s]/g, '').replace(/³/g, '3')
+
+function measureOf(kind: string): (typeof MEASURES)[number] | null {
+  const text = valueWords(kind)
+  return MEASURES.find((m) => m.kind.test(text)) ?? null
+}
+
+function unitIn(measure: (typeof MEASURES)[number], unit: string): MeasureUnit | null {
+  const key = unitKey(unit)
+  const found = measure.units.find((u) => unitKey(u.unit) === key || u.aliases?.some((a) => unitKey(a) === key))
+  if (found) return found
+  // Money is written in a currency: `SGD` is the money measure's unit.
+  const money = measure.units.find((u) => u.unit === '¤')
+  return money && isCurrencyUnit(unit) ? { ...money, unit } : null
+}
+
+/**
+ * How a type's readings are written: its unit property, the property that
+ * says what a reading is (its values a kind of measure: voltage, energy),
+ * and its value. Null when the type has no unit property.
+ */
+interface UnitPlan {
+  unit: string
+  kind: string | null
+  value: string | null
+  /** The unit for a kind: by position when the unit's values line up with the kinds, else the one the kind is read in. */
+  unitFor: (kind: string) => string | null
+  /** The range a value of that kind in that unit falls in. */
+  rangeFor: (kind: string, unit: string) => MeasureUnit | null
+}
+
+function unitPlanOf(properties: Property[], constraints: Map<string, Constraint>, pk: string, currency = 'USD'): UnitPlan | null {
+  const isText = (p: Property) => (p.valueType ?? 'string') === 'string'
+  const unitProperty = properties.find((p) => isText(p) && /^(?:(?:value|reading|measure|measurement|metric) )?(?:unit|units|uom|unit of measure|unit of measurement)$/.test(words(p.apiName)))
+  if (!unitProperty) return null
+  const unitValues = constraints.get(unitProperty.apiName)?.values ?? null
+  const kindNamed = (p: Property) => /\b(reading|metric|type|kind|measure|measurement|parameter|quantity|channel|sensor|signal)\b/.test(words(p.apiName))
+  const scored = properties
+    .filter((p) => p !== unitProperty && p.apiName !== pk && isText(p) && constraints.get(p.apiName)?.values?.length)
+    .map((p) => {
+      const values = constraints.get(p.apiName)!.values!
+      const lined = !!unitValues && unitValues.length === values.length
+      return { p, values, score: values.filter((v) => measureOf(v)).length + (kindNamed(p) ? 0.5 : 0) + (lined ? 0.25 : 0), lined }
+    })
+    .filter((s) => s.score >= 1 || (s.lined && kindNamed(s.p)))
+    .sort((a, b) => b.score - a.score)
+  const kind = scored[0] ?? null
+  const valueProperty = properties.find((p) => p.valueType === 'number' && /^(value|reading|measurement|measured value|reading value|level|magnitude)$|\b(value|reading)$/.test(words(p.apiName)))
+  const rangeFor = (k: string, unit: string): MeasureUnit | null => {
+    const measure = k ? measureOf(k) : null
+    if (measure) return (unit ? unitIn(measure, unit) : null) ?? (unit ? null : measure.units[0]!)
+    for (const m of MEASURES) {
+      const u = unit ? unitIn(m, unit) : null
+      if (u) return u
+    }
+    return null
+  }
+  return {
+    unit: unitProperty.apiName,
+    kind: kind?.p.apiName ?? null,
+    value: valueProperty?.apiName ?? null,
+    unitFor: (k) => {
+      if (kind?.lined) {
+        const i = kind.values.indexOf(k)
+        if (i >= 0) return unitValues![i]!
+      }
+      const measure = measureOf(k)
+      if (!measure) return null
+      if (unitValues) return unitValues.find((u) => unitIn(measure, u)) ?? null
+      const usual = measure.units[0]!.unit
+      return usual === '¤' ? currency : usual
+    },
+    rangeFor,
+  }
+}
+
+const HOUR = 3_600_000
+const DAY = 86_400_000
+
+/** A time a record must be done by: due, a deadline, an SLA or target time, expected by. */
+const DUE_BY = /\b(due|deadline|sla|target|expected|promised|eta)\b/
+
+/** The share of open records with a due time that are past it. */
+const OVERDUE_SHARE = 0.28
+
+const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z')
+
+/** Midnight UTC of the day it runs: the default "today". */
+const startOfUtcDay = (at: Date) => new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate()))
+
+/**
+ * A row's dates and times, in the order its names say: the first one in the
+ * last 120 days, each later one after it, an update last, nothing after
+ * today except a due date. Within a date or time semantic type's bounds. An
+ * optional end of life (resolvedAt) stays empty while the row's status says
+ * it is still open. An open record with a due time is current work: raised
+ * in the last ten days and due around today, some of it overdue by hours or
+ * days, the rest due within the week. A closed one was due days after it
+ * started.
+ */
+function fillTimes(faker: Faker, row: Record<string, unknown>, times: Property[], constraints: Map<string, Constraint>, today: Date, open: boolean, notStarted = false): void {
+  const now = today.getTime()
+  const sorted = [...times].sort((a, b) => lifecycleRank(a.apiName) - lifecycleRank(b.apiName))
+  const dueSoon = open && sorted.some((p) => lifecycleRank(p.apiName) === 2 && DUE_BY.test(words(p.apiName)))
+  let at = dueSoon ? now - faker.number.int({ min: 2 * 60, max: 10 * 24 * 60 }) * 60_000 : faker.date.recent({ days: 120, refDate: today }).getTime()
+  const start = at
+  let latest = at
+  // A time that would fall after today falls between the last one and today instead, not all on today.
+  const notAfter = (value: number) => (value <= now ? value : latest + Math.floor((now - latest) * faker.number.float({ min: 0.2, max: 0.95 })))
+  let first = true
+  for (const p of sorted) {
+    const rank = lifecycleRank(p.apiName)
+    const c = constraints.get(p.apiName) ?? {}
+    if (rank === -1) {
+      const birth = faker.date.birthdate({ min: 18, max: 80, mode: 'age', refDate: today })
+      row[p.apiName] = p.valueType === 'date' ? birth.toISOString().slice(0, 10) : iso(birth.getTime())
+      continue
+    }
+    // Installed, bought, founded, hired: years before the record's own life, within a semantic type's bounds.
+    const back = yearsBack(p)
+    if (back) {
+      let value = now - Math.round(faker.number.float({ min: back.min, max: back.max }) * 365.25 * DAY)
+      if (c.min !== undefined && value < c.min) value = c.min
+      if (c.max !== undefined && value > c.max) value = c.max
+      row[p.apiName] = p.valueType === 'date' ? new Date(value).toISOString().slice(0, 10) : iso(value)
+      continue
+    }
+    if (rank >= ENDS_LIFE && rank < 4 && open && optional(p)) {
+      row[p.apiName] = ''
+      continue
+    }
+    // Nobody has taken it on yet: no optional time it was assigned, accepted or scheduled.
+    if (rank === 1 && notStarted && optional(p)) {
+      row[p.apiName] = ''
+      continue
+    }
+    let value: number
+    if (rank === 2 && dueSoon && DUE_BY.test(words(p.apiName))) {
+      // Around now: overdue by an hour to three days, or due in half a day to a week; never before it started.
+      const overdue = faker.datatype.boolean({ probability: OVERDUE_SHARE })
+      value = Math.max(start + HOUR, overdue ? now - faker.number.int({ min: 1, max: 72 }) * HOUR : now + faker.number.int({ min: 12, max: 7 * 24 }) * HOUR)
+    } else if (rank === 2) value = at + faker.number.int({ min: 1, max: 14 }) * DAY // a due date may be ahead
+    else if (rank === 4) value = notAfter(latest + faker.number.int({ min: 5, max: 6 * 60 }) * 60_000)
+    else if (first) value = at
+    else value = notAfter(latest + faker.number.int({ min: 20, max: 72 * 60 }) * 60_000)
+    first = false
+    // A date or time semantic type's bounds, when it has them.
+    if (c.min !== undefined && value < c.min) value = c.min
+    if (c.max !== undefined && value > c.max) value = c.max
+    if (rank !== 2) latest = Math.max(latest, value)
+    at = rank === 2 ? at : value
+    row[p.apiName] = p.valueType === 'date' ? new Date(value).toISOString().slice(0, 10) : iso(value)
+  }
 }
 
 function csvCell(value: unknown): string {
@@ -236,85 +1521,777 @@ function csvCell(value: unknown): string {
   return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text
 }
 
+/** A date or timestamp bound written as a date string, as epoch milliseconds. */
+function timeBound(c: Constraint, rule: SemanticType['rule'] | undefined): Constraint {
+  const min = typeof rule?.minimum === 'string' ? Date.parse(rule.minimum) : NaN
+  const max = typeof rule?.maximum === 'string' ? Date.parse(rule.maximum) : NaN
+  return { ...c, ...(Number.isFinite(min) ? { min } : {}), ...(Number.isFinite(max) ? { max } : {}) }
+}
+
+/** The properties a type's dataset holds a column for: not a calculated field, and in its mapping when it has one. */
+export function storedProperties(type: ObjectType): Property[] {
+  const mapping = type.backing?.mapping
+  const mapped = mapping && Object.keys(mapping).length ? new Set(Object.keys(mapping)) : null
+  return (type.properties ?? []).filter((p) => !p.calculation && (!mapped || mapped.has(p.apiName)))
+}
+
+type Row = Record<string, unknown>
+
+const filled = (v: unknown) => v !== '' && v !== undefined && v !== null
+
+/** A latitude and a longitude property of a type, by name, when it has both. */
+function coordinatesOf(properties: Property[]): { lat: string; lon: string } | null {
+  const lat = properties.find((p) => p.valueType === 'number' && /^lat(itude)?$/.test(words(p.apiName).replace(/\s+/g, '')))
+  const lon = properties.find((p) => p.valueType === 'number' && /^(lon|lng|long|longitude)$/.test(words(p.apiName).replace(/\s+/g, '')))
+  return lat && lon ? { lat: lat.apiName, lon: lon.apiName } : null
+}
+
+/** `ada.lovelace@example.com` from a person's name. */
+function emailFrom(name: string): string | null {
+  const local = name.normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '.').replace(/^\.+|\.+$/g, '')
+  return local ? `${local}@example.com` : null
+}
+
+/** How many more times a scenario's field functions may run for one row, while a value one read changes. */
+const SCENARIO_PASSES = 3
+
 /**
  * Generate a CSV and a dataset definition for every object type in the
- * project's Blueprint tree. Returns what was written.
+ * project's Blueprint tree, a media-backed one excepted. Returns what was
+ * written.
+ */
+/**
+ * The datasets `generateSyntheticData` writes rows for: each object type's
+ * but a media-backed one's (it reads a Media Set, never a sample dataset).
  */
+export function sampleDatasetNames(root: string): Set<string> {
+  return new Set(readTree<ObjectType>(join(root, 'blueprint', 'object-types'))
+    .map((f) => f.doc)
+    .filter((t) => t?.apiName && !objectTypeFit(t as unknown as Record<string, unknown>, () => true).leftOff && !objectTypeFit(t as unknown as Record<string, unknown>, () => true).mediaStub)
+    .map((t) => backingOf(t).dataset))
+}
+
 export function generateSyntheticData(root: string, opts: SyntheticOptions = {}): GeneratedDataset[] {
-  const types = readTree<ObjectType>(join(root, 'blueprint', 'object-types')).map((f) => f.doc).filter((t) => t?.apiName)
-  const links = readTree<LinkType>(join(root, 'blueprint', 'link-types')).map((f) => f.doc).filter((l) => l?.apiName)
+  const dir = (kind: string) => join(root, 'blueprint', kind)
+  // A type over the platform's media files reads a Media Set, never a file dataset: the local runtime
+  // stubs it over an empty Media Set or leaves it off (`objectTypeFit`), so it gets no sample rows; a
+  // dataset of its name would take the name the stand-in Media Set's catalog needs.
+  const allTypes = readTree<ObjectType>(dir('object-types')).map((f) => f.doc).filter((t) => t?.apiName)
+  const fitOf = (t: ObjectType) => objectTypeFit(t as unknown as Record<string, unknown>, () => true)
+  const types = allTypes.filter((t) => {
+    const fit = fitOf(t)
+    return !fit.leftOff && !fit.mediaStub
+  })
+  // The media-backed types the local runtime stubs over a stand-in Media Set, which `local dev` fills with placeholders.
+  const mediaTypes = allTypes.filter((t) => fitOf(t).mediaStub && !fitOf(t).leftOff)
+  const links = readTree<LinkType>(dir('link-types')).map((f) => f.doc).filter((l) => l?.apiName)
   if (!types.length) return []
-  const faker = new Faker({ locale: [en, base] })
+  /** The conditional fields whose condition names nothing their record has (`GeneratedDataset.unresolved`). */
+  const unresolved: Array<{ objectType: string; property: string; condition: string }> = []
+  const semantic = new Map(readTree<SemanticType>(dir('semantic-types')).map((f) => [f.doc?.apiName, f.doc] as const).filter(([n]) => !!n) as Array<[string, SemanticType]>)
+  const shared = new Map(readTree<SharedField>(dir('shared-fields')).map((f) => [f.doc?.apiName, f.doc] as const).filter(([n]) => !!n) as Array<[string, SharedField]>)
+  const fromActions = actionEnums(readTree<ActionFile>(dir('actions')).map((f) => f.doc).filter((a) => a?.apiName))
+  const fromMetrics = metricHints(readTree<MetricFile>(dir('metrics')).map((f) => f.doc).filter((m) => m?.apiName))
+  const region = opts.region ?? projectRegion(root)
+  const faker = new Faker({ locale: region.locale })
   faker.seed(opts.seed ?? 7)
-  const today = opts.today ?? new Date('2026-10-01T00:00:00Z')
-  const refs = referencesFrom(links)
+  const today = opts.today ?? startOfUtcDay(new Date())
+  const typesByName = new Map(types.map((t) => [t.apiName, t] as const))
+  const primaryKeys = new Map(types.map((t) => [t.apiName, t.primaryKey ?? t.properties?.[0]?.apiName ?? 'id'] as const))
+  const entities = new Map(types.map((t) => [t.apiName, entityOf(t)] as const))
+  const refs = referencesFrom(links, primaryKeys)
+  // A link the name says (`propertyId`, `assignedTo`) when no link type declares it: the property holds that type's keys.
+  inferReferences(types, refs, primaryKeys, (t, p) => !!constraintFor(t, p, semantic, shared, fromActions, fromMetrics).values?.length)
   const keys = new Map<string, unknown[]>()
-  const out: GeneratedDataset[] = []
+  // A link from a record to a media-backed type's file (`Amenity.imageUrl` → the photo's `path`): the record
+  // holds the path, drawn from the placeholders' paths, so the link resolves against the files `local dev` uploads.
+  for (const media of mediaTypes) {
+    const isPath = (property: string | undefined) => !!property && (property === 'path' || backingOf(media).column(property) === 'path')
+    for (const link of links) {
+      if (link.cardinality === 'many_to_many') continue
+      const [mine, other] = link.from?.objectType === media.apiName ? [link.from, link.to] : link.to?.objectType === media.apiName ? [link.to, link.from] : [null, null]
+      if (!mine?.property || !isPath(mine.property) || !other?.objectType || !other.property || !typesByName.has(other.objectType) || primaryKeys.get(other.objectType) === other.property) continue
+      // Whichever end the link names first, the non-media end holds the reference.
+      refs.get(media.apiName)?.delete(mine.property)
+      if (!refs.has(other.objectType)) refs.set(other.objectType, new Map())
+      refs.get(other.objectType)!.set(other.property, { objectType: media.apiName, property: mine.property })
+      keys.set(`${media.apiName}.${mine.property}`, defaultPlaceholderPaths(media.apiName))
+    }
+  }
+  // Each generated type's rows, and lookups into them: a link that agrees with the row's other links.
+  const rowsOf = new Map<string, Row[]>()
+  const indexes = new Map<string, Map<unknown, Row[]>>()
+  const rowsWhere = (type: string, property: string, value: unknown): Row[] => {
+    const key = `${type}.${property}`
+    // A type not generated yet (a cycle) has no rows to look in; nothing is kept for it.
+    if (!rowsOf.has(type)) return []
+    let index = indexes.get(key)
+    if (!index) {
+      index = new Map()
+      for (const r of rowsOf.get(type) ?? []) {
+        const v = r[property]
+        if (!filled(v)) continue
+        if (!index.has(v)) index.set(v, [])
+        index.get(v)!.push(r)
+      }
+      indexes.set(key, index)
+    }
+    return index.get(value) ?? []
+  }
   const baseRows = Math.max(1, Math.min(opts.scenario?.rows ?? opts.rows ?? 200, 100_000))
   mkdirSync(join(root, 'datasets'), { recursive: true })
 
+  /**
+   * Where a record leads through its links and theirs, by type: a work
+   * order's asset leads to its site, and the site to its customer. The
+   * nearest record of each type wins (a breadth-first walk); the record
+   * itself is not included. Only types generated so far are walked, and
+   * their rows are final, so each record's walk is kept.
+   */
+  let reached = new WeakMap<Row, Map<string, Row>>()
+  const reachedFrom = (typeName: string, start: Row): Map<string, Row> => {
+    const known = reached.get(start)
+    if (known) return known
+    const out = new Map<string, Row>()
+    const seen = new Set<Row>([start])
+    const queue: Array<[string, Row]> = [[typeName, start]]
+    while (queue.length) {
+      const [t, r] = queue.shift()!
+      for (const [q, via] of refs.get(t) ?? []) {
+        if (via.inferred || !filled(r[q])) continue
+        const next = rowsWhere(via.objectType, via.property, r[q])[0]
+        if (!next || seen.has(next)) continue
+        seen.add(next)
+        if (!out.has(via.objectType)) out.set(via.objectType, next)
+        queue.push([via.objectType, next])
+      }
+    }
+    reached.set(start, out)
+    return out
+  }
+  /** The types a type's records can lead to through links, at the level of the Blueprint. */
+  const typeReach = new Map<string, Set<string>>()
+  const reachOf = (typeName: string): Set<string> => {
+    const known = typeReach.get(typeName)
+    if (known) return known
+    const out = new Set<string>()
+    const queue = [typeName]
+    while (queue.length) {
+      for (const via of refs.get(queue.shift()!)?.values() ?? []) {
+        if (via.inferred || out.has(via.objectType)) continue
+        out.add(via.objectType)
+        queue.push(via.objectType)
+      }
+    }
+    typeReach.set(typeName, out)
+    return out
+  }
+  /** Per (type, reached type): the type's records by the record of the other type they lead to; `null` holds those that lead to none. */
+  const byReached = new Map<string, Map<Row | null, Row[]>>()
+  const recordsLeadingTo = (typeName: string, reachedType: string): Map<Row | null, Row[]> => {
+    const key = `${typeName}>${reachedType}`
+    let index = byReached.get(key)
+    if (!index) {
+      index = new Map()
+      for (const r of rowsOf.get(typeName) ?? []) {
+        const to = reachedFrom(typeName, r).get(reachedType) ?? null
+        if (!index.has(to)) index.set(to, [])
+        index.get(to)!.push(r)
+      }
+      byReached.set(key, index)
+    }
+    return index
+  }
+
+  /**
+   * The keys a link property may take in this row: those of the records that
+   * agree with the row's other links (`among`, else every other filled one).
+   * Two linked records agree when neither leads to a record of the other's
+   * type but that one, along any path: a work order at a site gets an asset
+   * at that site and the site's customer, and the other way round. Two links
+   * to the same type never constrain each other (a reporter and an assignee).
+   * When no record leads to the one a link fixes, a record that leads to no
+   * record of that type at all still agrees.
+   */
+  const consistentPool = (type: ObjectType, row: Row, property: string, ref: Reference, among?: ReadonlySet<string>): unknown[] => {
+    const all = keys.get(`${ref.objectType}.${ref.property}`) ?? []
+    const targets = rowsOf.get(ref.objectType)
+    if (!targets) return all
+    let candidates: Row[] | null = null
+    const narrow = (to: Row[]) => {
+      const keep = new Set(to)
+      candidates = candidates ? candidates.filter((r) => keep.has(r)) : to
+    }
+    for (const [other, otherRef] of refs.get(type.apiName) ?? []) {
+      if (other === property || otherRef.inferred || (among && !among.has(other)) || !filled(row[other]) || otherRef.objectType === ref.objectType) continue
+      const fixed = rowsWhere(otherRef.objectType, otherRef.property, row[other])[0]
+      if (!fixed) continue
+      // The other link's record leads to a record of this type: this one is that.
+      const led = reachedFrom(otherRef.objectType, fixed).get(ref.objectType)
+      if (led) narrow([led])
+      // This type's records lead to the other link's type: those that lead to that record.
+      if (reachOf(ref.objectType).has(otherRef.objectType)) {
+        const index = recordsLeadingTo(ref.objectType, otherRef.objectType)
+        const exact = index.get(fixed) ?? []
+        narrow(exact.length ? exact : (index.get(null) ?? []))
+      }
+      if (candidates !== null && (candidates as Row[]).length === 0) break
+    }
+    if (candidates === null) return all
+    return (candidates as Row[]).map((r) => r[ref.property]).filter(filled)
+  }
+
+  /**
+   * The order a row's links are chosen in: a link whose record leads to the
+   * records of more of the row's other links first, so those follow from it
+   * (a work order's asset, then its site, then its customer) instead of
+   * being picked apart and found not to agree.
+   */
+  const linkOrder = (type: ObjectType): string[] => {
+    const own = [...(refs.get(type.apiName) ?? new Map<string, Reference>())]
+    const score = (ref: Reference) => own.filter(([, o]) => o.objectType !== ref.objectType && reachOf(ref.objectType).has(o.objectType)).length
+    return own.map(([prop, ref], i) => ({ prop, s: score(ref), i })).sort((a, b) => b.s - a.s || a.i - b.i).map((x) => x.prop)
+  }
+
+  /**
+   * Shared fields along links: by type, each shared field one of its
+   * properties implements (other than its key), and that property.
+   */
+  const sharedFieldsOf = new Map(types.map((t) => [t.apiName, new Map((t.properties ?? []).flatMap((p) => (p.sharedField && p.apiName !== primaryKeys.get(t.apiName) && !p.calculation ? [[p.sharedField, p.apiName] as const] : [])))] as const))
+  /**
+   * The value of a shared field on the nearest record a row links to that
+   * implements it too: a work order's `serviceRegion` is its site's. Walked
+   * along declared and inferred links, breadth first (the row's own links in
+   * `order`), a few links deep; undefined when no linked record has a value.
+   */
+  const linkedSharedValue = (typeName: string, row: Row, field: string, order: readonly string[]): unknown => {
+    const seen = new Set<Row>([row])
+    let frontier: Array<[string, Row]> = [[typeName, row]]
+    for (let depth = 0; depth < 4 && frontier.length; depth++) {
+      const next: Array<[string, Row]> = []
+      for (const [t, r] of frontier) {
+        const own = refs.get(t) ?? new Map<string, Reference>()
+        for (const q of t === typeName && r === row ? order : [...own.keys()]) {
+          const via = own.get(q)
+          if (!via || !filled(r[q])) continue
+          const found = rowsWhere(via.objectType, via.property, r[q])[0]
+          if (!found || seen.has(found)) continue
+          seen.add(found)
+          const holder = sharedFieldsOf.get(via.objectType)?.get(field)
+          if (holder && filled(found[holder])) return found[holder]
+          next.push([via.objectType, found])
+        }
+      }
+      frontier = next
+    }
+    return undefined
+  }
+
+  /** What a field function may read of the other types' rows. */
+  const frozen = new Map<string, ReadonlyArray<Readonly<Row>>>()
+  const scenarioContext = (own: string): ScenarioContext => ({
+    rowsOf: (objectType) => {
+      if (objectType === own || !rowsOf.has(objectType)) return []
+      let rows = frozen.get(objectType)
+      if (!rows) {
+        rows = Object.freeze(rowsOf.get(objectType)!.map((r) => Object.freeze({ ...r })))
+        frozen.set(objectType, rows)
+      }
+      return rows
+    },
+    lookup: (objectType, value, property) => {
+      if (objectType === own || !rowsOf.has(objectType)) return undefined
+      const found = rowsWhere(objectType, property ?? primaryKeys.get(objectType) ?? 'id', value)[0]
+      return found ? Object.freeze({ ...found }) : undefined
+    },
+  })
+
+  const generated: Array<{ type: ObjectType; rows: Row[]; kept?: true }> = []
   for (const type of dependencyOrder(types, refs)) {
+    // A dataset that is not sample data is never rewritten: its own rows stand, and other types link to them.
+    const { dataset: ownDataset, column: ownColumn } = backingOf(type)
+    if (!isSampleDataset(root, ownDataset)) {
+      const rows = keptRows(root, ownDataset, storedProperties(type), ownColumn)
+      for (const p of type.properties ?? []) keys.set(`${type.apiName}.${p.apiName}`, rows.map((r) => r[p.apiName]).filter(filled))
+      rowsOf.set(type.apiName, rows)
+      reached = new WeakMap()
+      byReached.clear()
+      indexes.clear()
+      generated.push({ type, rows, kept: true })
+      continue
+    }
     const custom = opts.scenario?.types?.[type.apiName]
     // Types others point at are the fewer ones (customers, products); the rest scale with them.
     const referenced = [...refs.values()].some((m) => [...m.values()].some((r) => r.objectType === type.apiName))
-    const count = custom?.rows ?? (referenced ? Math.max(5, Math.round(baseRows / 2)) : baseRows)
-    const properties = type.properties ?? []
-    const pk = type.primaryKey ?? properties[0]?.apiName ?? 'id'
-    const { dataset, column } = backingOf(type)
+    const wanted = custom?.rows ?? (referenced ? Math.max(5, Math.round(baseRows / 2)) : baseRows)
+    // A calculated field is the Blueprint's to compute: no value, no column.
+    const properties = (type.properties ?? []).filter((p) => !p.calculation)
+    const pk = primaryKeys.get(type.apiName)!
     const prefix = keyPrefix(type.apiName)
     const ownRefs = refs.get(type.apiName) ?? new Map<string, Reference>()
-    const rows: Array<Record<string, unknown>> = []
-    for (let i = 0; i < count; i++) {
-      const row: Record<string, unknown> = {}
-      const state = { lastTime: null as number | null, today }
-      for (const p of properties) {
-        const fn = custom?.fields?.[p.apiName]
-        if (fn) {
-          row[p.apiName] = fn(row, i)
+    // A key that is also another type's key (one transcript per service request): each row takes one of
+    // that type's records, each once, so the link resolves and the key stays unique; no more rows than it has.
+    const keyRef = ownRefs.get(pk)
+    const keyPool = keyRef ? [...new Set(keys.get(`${keyRef.objectType}.${keyRef.property}`) ?? [])] : null
+    const count = keyPool?.length ? Math.min(wanted, keyPool.length) : wanted
+    const usedKeys = new Set<unknown>()
+    const constraints = new Map(
+      properties.map((p) => {
+        const c = constraintFor(type, p, semantic, shared, fromActions, fromMetrics)
+        const st = semantic.get(p.semanticType ?? '') ?? semantic.get((p.sharedField && shared.get(p.sharedField)?.semanticType) || '')
+        return [p.apiName, p.valueType === 'date' || p.valueType === 'timestamp' ? timeBound({}, st?.rule) : c] as const
+      }),
+    )
+    const times = properties.filter((p) => p.valueType === 'date' || p.valueType === 'timestamp')
+    const statusProperty = properties.find((p) => /^(status|state|stage)$/i.test(p.apiName) || /(Status|State)$/.test(p.apiName))
+    const phases = statusProperty?.apiName && constraints.get(statusProperty.apiName)?.values ? statePhases(constraints.get(statusProperty.apiName)!.values!) : null
+    const coordinates = coordinatesOf(properties)
+    const personType = entities.get(type.apiName) === 'person'
+    const nameProperty = properties.find((p) => /^(name|full name|display name)$/.test(words(p.apiName)))
+    const isTime = (p: Property) => p.valueType === 'date' || p.valueType === 'timestamp'
+    const seed = opts.seed ?? 7
+    const entity = entities.get(type.apiName) ?? null
+    // Free text written from the rest of the row: a property with listed values keeps to them.
+    const proseKinds = new Map(properties.flatMap((p) => {
+      const kind = constraints.get(p.apiName)?.values?.length || p.apiName === pk || ownRefs.has(p.apiName) ? null : proseKind(p)
+      return kind ? [[p.apiName, kind] as const] : []
+    }))
+    const unitPlan = unitPlanOf(properties, constraints, pk, region.currency)
+    // The pair of times of day a record opens and closes at (`openTime`, `closeTime`), when it has both.
+    const openingTimes = {
+      open: properties.find((p) => !constraints.get(p.apiName)?.values && timeOfDayRole(p) === 'open'),
+      close: properties.find((p) => !constraints.get(p.apiName)?.values && timeOfDayRole(p) === 'close'),
+    }
+    const links = linkOrder(type)
+    // The properties that implement a shared field another linked type implements too (not a link or the key).
+    const sharedHere = properties.filter((p) => p.sharedField && p.apiName !== pk && !ownRefs.has(p.apiName))
+    // A field its description says is empty unless something holds ("empty unless escalated"). A condition
+    // that names nothing the row has never holds: "empty unless X" stays empty, and the run says so.
+    const conditions = new Map(properties.flatMap((p) => {
+      if (!optional(p) || p.apiName === pk || p.apiName === statusProperty?.apiName || isTime(p) || startsWork(p, ownRefs.get(p.apiName), entities) || endsLife(p)) return []
+      const c = filledWhen(p, properties, statusProperty, phases, (name) => constraints.get(name)?.values)
+      if (c) return [[p.apiName, c] as const]
+      const said = conditionOf(p.description)
+      // "Empty when X", X never holding: the field is set as any other.
+      if (!said || said.emptyWhen) return []
+      unresolved.push({ objectType: type.apiName, property: p.apiName, condition: said.text })
+      return [[p.apiName, () => false] as const]
+    }))
+    // The value that says what a record is about: its category, its fault, its kind.
+    const topic = properties.find((p) => p !== statusProperty && p.apiName !== pk && p.apiName !== unitPlan?.unit && (p.valueType ?? 'string') === 'string' && constraints.get(p.apiName)?.values?.length && /\b(category|type|kind|issue|problem|fault|topic|reason|subject)\b/.test(words(p.apiName)) && !/\b(priority|severity)\b/.test(words(p.apiName)))
+    const work = !!statusProperty || /\b(orders?|tickets?|cases?|incidents?|requests?|issues?|jobs?|tasks?|complaints?|claims?|faults?|calls?|visits?|reports?|enquir(y|ies)|inquir(y|ies)|defects?|outages?)\b/.test(words(type.apiName))
+    const kindOf = (t: ObjectType, r: Row): string | undefined => {
+      const k = (t.properties ?? []).find((p) => p.apiName !== primaryKeys.get(t.apiName) && (p.valueType ?? 'string') === 'string' && /\b(type|kind|category|class|model)$/.test(words(p.apiName)) && typeof r[p.apiName] === 'string' && filled(r[p.apiName]))
+      return k ? valueWords(String(r[k.apiName])) : undefined
+    }
+    const labelOf = (t: ObjectType, r: Row): string | undefined => {
+      const props = t.properties ?? []
+      const named = (t.title && t.title !== primaryKeys.get(t.apiName) ? props.find((p) => p.apiName === t.title) : undefined) ?? props.find((p) => /^(name|full name|display name|title|label)$/.test(words(p.apiName))) ?? props.find((p) => /\b(name|address)$/.test(words(p.apiName)))
+      const v = named ? r[named.apiName] : undefined
+      return typeof v === 'string' && v ? v : undefined
+    }
+    /** What the row is about: its category, the place, asset and person it links to. */
+    const sceneOf = (row: Row, i: number): Scene => {
+      const scene: Partial<Scene> = {}
+      const linked: Array<[Reference, Row]> = []
+      for (const [prop, ref] of ownRefs) {
+        const target = typesByName.get(ref.objectType)
+        const r = filled(row[prop]) ? rowsWhere(ref.objectType, ref.property, row[prop])[0] : undefined
+        if (!target || !r) continue
+        linked.push([ref, r])
+        const kind = entities.get(ref.objectType)
+        const p = properties.find((x) => x.apiName === prop)
+        if (kind === 'place') scene.place ??= labelOf(target, r)
+        else if (kind === 'thing' && !scene.thing) ((scene.thing = kindOf(target, r) ?? typeWords(target).toLowerCase()), (scene.thingName = labelOf(target, r)))
+        else if (kind === 'person' && p && !startsWork(p, ref, entities) && !scene.reporter) ((scene.reporter = typeWords(target)), (scene.owner ??= labelOf(target, r)))
+        else if (kind === 'organization') scene.owner ??= labelOf(target, r)
+      }
+      // Through a linked record: a work order's site through its asset.
+      for (const [ref, r] of linked) {
+        if (scene.place) break
+        for (const [q, via] of refs.get(ref.objectType) ?? []) {
+          const target = typesByName.get(via.objectType)
+          const r2 = target && entities.get(via.objectType) === 'place' && filled(r[q]) ? rowsWhere(via.objectType, via.property, r[q])[0] : undefined
+          if (target && r2) scene.place ??= labelOf(target, r2)
+        }
+      }
+      // Who reported it, through a linked record: a work order's customer through its site.
+      for (const [ref, r] of linked) {
+        if (scene.reporter) break
+        for (const [q, via] of refs.get(ref.objectType) ?? []) {
+          const target = typesByName.get(via.objectType)
+          const r2 = target && entities.get(via.objectType) === 'person' && filled(r[q]) ? rowsWhere(via.objectType, via.property, r[q])[0] : undefined
+          if (target && r2 && !scene.reporter) ((scene.reporter = typeWords(target)), (scene.owner ??= labelOf(target, r2)))
+        }
+      }
+      // The record's own address.
+      if (!scene.place) {
+        const own = properties.find((p) => /\b(address|street|city)\b/.test(words(p.apiName)) && typeof row[p.apiName] === 'string' && filled(row[p.apiName]))
+        if (own) scene.place = String(row[own.apiName])
+      }
+      if (!work) {
+        const self = kindOf(type, row) ?? typeWords(type).toLowerCase()
+        return { ...scene, work, issue: self, vocabulary: GENERAL }
+      }
+      const said = topic && typeof row[topic.apiName] === 'string' ? valueWords(String(row[topic.apiName])) : ''
+      const generic = !said || GENERIC_TOPIC.test(said)
+      const issue = !generic ? said : scene.thing ? `${scene.thing} fault` : pickWith(drawFor(seed, `${type.apiName}.${i}.issue`), GENERAL_ISSUES)
+      const vocabulary = VOCABULARIES.find((v) => v.match.test(generic ? `${issue} ${words(type.apiName)}` : said)) ?? GENERAL
+      return { ...scene, work, issue, vocabulary }
+    }
+
+    /** The row's own values, from what each property allows, its type and its name; free text comes later. */
+    const baseValues = (row: Row, i: number) => {
+      // Links first, in the order that lets each follow from the ones before it.
+      for (const prop of links) {
+        const ref = ownRefs.get(prop)!
+        const p = properties.find((x) => x.apiName === prop)
+        if (!p) continue
+        if (prop === pk && keyPool?.length) {
+          // The key: a record of the other type no row has taken, one that agrees with the row's links when one does.
+          const free = (list: unknown[]) => list.filter((k) => !usedKeys.has(k))
+          const choice = free(consistentPool(type, row, prop, ref))
+          const v = choice.length ? faker.helpers.arrayElement(choice) : faker.helpers.arrayElement(free(keyPool).length ? free(keyPool) : keyPool)
+          usedKeys.add(v)
+          row[prop] = v
           continue
         }
+        const pool = consistentPool(type, row, prop, ref)
+        const any = keys.get(`${ref.objectType}.${ref.property}`) ?? []
+        // A required link always points at a record (one that agrees with the row's other links
+        // when there is one); an optional one usually does, and only to one that agrees.
+        if (!optional(p)) row[prop] = pool.length ? faker.helpers.arrayElement(pool) : any.length ? faker.helpers.arrayElement(any) : ''
+        else row[prop] = pool.length && faker.datatype.boolean({ probability: 0.85 }) ? faker.helpers.arrayElement(pool) : ''
+      }
+      // One point per row: its latitude and its longitude are the same place, within the radius.
+      let point = coordinates ? pointIn(faker, region) : null
+      // A compass region that is a shared field a linked record already holds (a site of a customer served
+      // in the east): the point is drawn in that region, so the region the point decides agrees along the link.
+      if (point) {
+        for (const p of sharedHere) {
+          const values = constraints.get(p.apiName)?.values
+          if (!values || !isCompassList(values)) continue
+          const want = linkedSharedValue(type.apiName, row, p.sharedField!, links)
+          if (typeof want !== 'string' || !values.includes(want)) continue
+          for (let tries = 0; tries < 64 && compassOf(point, region, values) !== want; tries++) point = pointIn(faker, region)
+          break
+        }
+      }
+      for (const p of properties) {
+        if (isTime(p) || ownRefs.has(p.apiName)) continue
         if (p.apiName === pk) {
           row[p.apiName] = (p.valueType ?? 'string') === 'number' ? i + 1 : `${prefix}-${String(i + 1).padStart(5, '0')}`
           continue
         }
-        const ref = ownRefs.get(p.apiName)
-        if (ref) {
-          const pool = keys.get(`${ref.objectType}.${ref.property}`) ?? []
-          row[p.apiName] = pool.length && (p.required !== false || faker.datatype.boolean({ probability: 0.85 })) ? faker.helpers.arrayElement(pool) : ''
+        if (point && (p.apiName === coordinates!.lat || p.apiName === coordinates!.lon)) {
+          row[p.apiName] = p.apiName === coordinates!.lat ? point.lat : point.lon
           continue
         }
-        // Optional values are sometimes empty, as real records are.
-        if (p.required === false && faker.datatype.boolean({ probability: 0.2 })) {
+        // Optional values are sometimes empty, as real records are; never what says which record it is.
+        if (optional(p) && p.apiName !== statusProperty?.apiName && !defining(type, p) && faker.datatype.boolean({ probability: 0.2 })) {
           row[p.apiName] = ''
           continue
         }
-        row[p.apiName] = valueFor(faker, type, p, row, state)
+        // Free text is written once the rest of the row is (`derive`).
+        if (proseKinds.has(p.apiName)) continue
+        row[p.apiName] = valueFor(faker, type, p, constraints.get(p.apiName) ?? {}, region)
+      }
+    }
+
+    /**
+     * What the row's state allows (`keep` names the fields a scenario function made):
+     * nobody assigned while it is new, no resolution until it ends, and one once it has.
+     */
+    const applyState = (row: Row, keep: (name: string) => boolean): Phase | null => {
+      const phase = statusProperty ? phaseOf(String(row[statusProperty.apiName] ?? ''), phases) : null
+      // Cancelled, rejected, withdrawn…: it ended, with nothing done, so no text says what was done.
+      const undone = (name: string) => phase === 'terminal' && UNFINISHED_END.test(String(row[statusProperty!.apiName] ?? '')) && proseKinds.get(name) === 'resolution'
+      for (const p of properties) {
+        if (keep(p.apiName) || p.apiName === pk || p.apiName === statusProperty?.apiName || isTime(p) || !phase || conditions.has(p.apiName)) continue
+        const ref = ownRefs.get(p.apiName)
+        const later = proseKinds.has(p.apiName)
+        if (optional(p) && startsWork(p, ref, entities)) {
+          if (phase === 'initial') row[p.apiName] = ''
+          else if (!filled(row[p.apiName])) {
+            if (ref) {
+              const pool = consistentPool(type, row, p.apiName, ref)
+              if (pool.length) row[p.apiName] = faker.helpers.arrayElement(pool)
+            } else row[p.apiName] = later ? undefined : valueFor(faker, type, p, constraints.get(p.apiName) ?? {}, region)
+          }
+        } else if (optional(p) && endsLife(p)) {
+          if (phase !== 'terminal' || undone(p.apiName)) row[p.apiName] = ''
+          else if (!filled(row[p.apiName]) && !ref) row[p.apiName] = later ? undefined : valueFor(faker, type, p, constraints.get(p.apiName) ?? {}, region)
+        }
+      }
+      // A field its description makes conditional: empty while the condition is false, set once it holds.
+      for (const [name, holds] of conditions) {
+        if (keep(name)) continue
+        if (!holds(row, phase) || undone(name)) row[name] = ''
+        else if (!filled(row[name])) {
+          const p = properties.find((x) => x.apiName === name)!
+          const ref = ownRefs.get(name)
+          if (ref) {
+            const pool = consistentPool(type, row, name, ref)
+            if (pool.length) row[name] = faker.helpers.arrayElement(pool)
+          } else row[name] = proseKinds.has(name) ? undefined : valueFor(faker, type, p, constraints.get(name) ?? {}, region)
+        }
+      }
+      return phase
+    }
+
+    /**
+     * Values made from the rest of the row: links that agree again (after a scenario
+     * function), a unit and value that follow the reading's kind, an asset's name from
+     * its kind, free text, a point from the coordinates, an email from a person's name.
+     * Each draw is the row's own (`drawFor`), so making them again changes only what
+     * the row's other values changed.
+     */
+    const derive = (row: Row, i: number, keep: (name: string) => boolean, relink: boolean, prose: Set<string>) => {
+      const draw = (name: string) => drawFor(seed, `${type.apiName}.${i}.${name}`)
+      if (relink) {
+        // Against the links a function set, then each link chosen before it, in link order.
+        const settled = new Set([...ownRefs.keys()].filter(keep))
+        for (const prop of links) {
+          // The key stays the record it took: each is taken once.
+          if (keep(prop) || (prop === pk && keyPool?.length)) continue
+          const ref = ownRefs.get(prop)!
+          const p = properties.find((x) => x.apiName === prop)
+          const pool = consistentPool(type, row, prop, ref, settled)
+          settled.add(prop)
+          if (filled(row[prop]) ? pool.includes(row[prop]) : optional(p) || !pool.length) continue
+          // None agrees: an optional link is left empty, a required one keeps the record it has.
+          if (pool.length) row[prop] = faker.helpers.arrayElement(pool)
+          else if (optional(p)) row[prop] = ''
+        }
+      }
+      if (unitPlan) {
+        const kind = unitPlan.kind && typeof row[unitPlan.kind] === 'string' ? String(row[unitPlan.kind]) : ''
+        const unit = kind && !keep(unitPlan.unit) ? unitPlan.unitFor(kind) : null
+        if (unit) row[unitPlan.unit] = unit
+        if (unitPlan.value && !keep(unitPlan.value) && filled(row[unitPlan.value])) {
+          const range = unitPlan.rangeFor(kind, typeof row[unitPlan.unit] === 'string' ? String(row[unitPlan.unit]) : '')
+          if (range) {
+            const c = constraints.get(unitPlan.value) ?? {}
+            let v = Number((range.min + draw(unitPlan.value)() * (range.max - range.min)).toFixed(range.digits))
+            if (c.min !== undefined) v = Math.max(v, c.min)
+            if (c.max !== undefined) v = Math.min(v, c.max)
+            row[unitPlan.value] = v
+          }
+        }
+      }
+      // An asset is called by its kind: "Transformer A-104".
+      if (entity === 'thing' && nameProperty && !keep(nameProperty.apiName) && !constraints.get(nameProperty.apiName)?.values && filled(row[nameProperty.apiName])) {
+        const kind = kindOf(type, row)
+        if (kind) {
+          const d = draw(nameProperty.apiName)
+          row[nameProperty.apiName] = `${title(kind)} ${String.fromCharCode(65 + Math.floor(d() * 26))}-${String(Math.floor(d() * 900) + 100)}`
+        }
+      }
+      if (proseKinds.size) {
+        let scene: Scene | null = null
+        for (const [name, kind] of proseKinds) {
+          if (keep(name)) continue
+          const v = row[name]
+          // Unwritten, or written here before from values that may have changed; an empty one stays empty.
+          if (v !== undefined && !(prose.has(name) && filled(v))) continue
+          scene ??= sceneOf(row, i)
+          row[name] = fitLength(faker, proseFor(kind, scene, draw(name), name), constraints.get(name) ?? {})
+          prose.add(name)
+        }
+      }
+      // Opening hours hold together: both times or neither, the close after the open, and an `hours` text that says them.
+      if (openingTimes.open && openingTimes.close) {
+        const [o, c] = [openingTimes.open.apiName, openingTimes.close.apiName]
+        if (!keep(o) && !keep(c) && (filled(row[o]) || filled(row[c]))) {
+          const d = draw(`${o}.${c}`)
+          if (!filled(row[o])) row[o] = timeOfDayFrom(d, 'open')
+          if (!filled(row[c])) row[c] = timeOfDayFrom(d, 'close')
+        }
+        const hours = properties.find((p) => /^(hours|opening hours|business hours|operating hours|open hours)$/.test(words(p.apiName)) && (p.valueType ?? 'string') === 'string')
+        if (hours && !keep(hours.apiName) && filled(row[o]) && filled(row[c])) row[hours.apiName] = `${row[o]}–${row[c]}`
+      }
+      // A point agrees with the row's own latitude and longitude, and so does a compass region (north, central…).
+      const fromPoint = new Set<string>()
+      if (coordinates && typeof row[coordinates.lat] === 'number' && typeof row[coordinates.lon] === 'number') {
+        const at = { lat: row[coordinates.lat] as number, lon: row[coordinates.lon] as number }
+        for (const p of properties) if (p.valueType === 'geopoint' && !keep(p.apiName)) row[p.apiName] = JSON.stringify(at)
+        for (const p of properties) {
+          const values = constraints.get(p.apiName)?.values
+          if (keep(p.apiName) || !values || !filled(row[p.apiName]) || !isCompassList(values)) continue
+          row[p.apiName] = compassOf(at, region, values)
+          fromPoint.add(p.apiName)
+        }
+      }
+      // A person's email reads like their name.
+      if (personType && nameProperty && typeof row[nameProperty.apiName] === 'string') {
+        for (const p of properties) {
+          if (keep(p.apiName) || !/e ?mail/.test(words(p.apiName)) || !filled(row[p.apiName])) continue
+          row[p.apiName] = emailFrom(String(row[nameProperty.apiName])) ?? row[p.apiName]
+        }
+      }
+      // A shared field agrees along links: the value of the nearest linked record that implements it too
+      // (a work order's service region is its site's). A region the row's own point decided stays: the
+      // point is the record's own fact, and the records that link to it take the region from it.
+      for (const p of sharedHere) {
+        if (keep(p.apiName) || fromPoint.has(p.apiName) || !filled(row[p.apiName])) continue
+        const v = linkedSharedValue(type.apiName, row, p.sharedField!, links)
+        if (v !== undefined) row[p.apiName] = v
+      }
+    }
+
+    const openOf = (phase: Phase | null, row: Row) => (phase ? phase !== 'terminal' : statusProperty ? STILL_OPEN.test(String(row[statusProperty.apiName] ?? '')) : false)
+    const nothing = () => false
+    // The scenario's field functions: every other value first, then the times, as the type lists them.
+    const fieldFns = custom?.fields ?? {}
+    const withFn = properties.filter((p) => typeof fieldFns[p.apiName] === 'function')
+    const fnOrder = [...withFn.filter((p) => !isTime(p)), ...withFn.filter(isTime)].map((p) => p.apiName)
+    const hasFn = new Set(fnOrder)
+    const keep = (name: string) => hasFn.has(name)
+    const context = scenarioContext(type.apiName)
+
+    const rows: Row[] = []
+    for (let i = 0; i < count; i++) {
+      // Every value first, as if there were no scenario.
+      const row: Row = {}
+      const prose = new Set<string>()
+      baseValues(row, i)
+      let phase = applyState(row, nothing)
+      derive(row, i, nothing, false, prose)
+      let open = openOf(phase, row)
+      let notStarted = phase === 'initial'
+      fillTimes(faker, row, times, constraints, today, open, notStarted)
+
+      if (fnOrder.length) {
+        // Then the scenario's functions, each seeing the whole row (its own default included).
+        const defaults = new Map(fnOrder.map((name) => [name, row[name]]))
+        const seen = new Map<string, Map<string, unknown>>()
+        const call = (name: string) => {
+          row[name] = defaults.get(name)
+          const reads = new Map<string, unknown>()
+          const view = new Proxy(row, {
+            get: (target, key, receiver) => {
+              const v = Reflect.get(target, key, receiver)
+              if (typeof key === 'string' && key !== name && !reads.has(key)) reads.set(key, v)
+              return v
+            },
+          })
+          row[name] = fieldFns[name]!(view, i, context)
+          seen.set(name, reads)
+        }
+        const stale = (name: string) => [...(seen.get(name) ?? [])].some(([k, v]) => !Object.is(row[k], v))
+        for (const name of fnOrder) call(name)
+        // The rules again for the fields without a function, now that the functions' values are in;
+        // a function that read a value changed since is run again, until what each read is final.
+        for (let pass = 0; ; pass++) {
+          phase = applyState(row, keep)
+          derive(row, i, keep, true, prose)
+          const nextOpen = openOf(phase, row)
+          if (nextOpen !== open || (phase === 'initial') !== notStarted) {
+            open = nextOpen
+            notStarted = phase === 'initial'
+            fillTimes(faker, row, times.filter((p) => !keep(p.apiName)), constraints, today, open, notStarted)
+          }
+          const dirty = fnOrder.filter(stale)
+          if (!dirty.length || pass === SCENARIO_PASSES) break
+          for (const name of dirty) call(name)
+        }
       }
       rows.push(row)
     }
-    for (const p of properties) keys.set(`${type.apiName}.${p.apiName}`, rows.map((r) => r[p.apiName]).filter((v) => v !== '' && v !== undefined))
+    for (const p of properties) keys.set(`${type.apiName}.${p.apiName}`, rows.map((r) => r[p.apiName]).filter(filled))
+    rowsOf.set(type.apiName, rows)
+    // A walk that stopped at this type before it had rows (a cycle) is walked again.
+    reached = new WeakMap()
+    byReached.clear()
+    generated.push({ type, rows })
+  }
 
+  // A link inside a cycle (two types pointing at each other) found no records the first time: filled now.
+  for (const { type, rows } of generated) {
+    for (const [property, ref] of refs.get(type.apiName) ?? []) {
+      const p = type.properties?.find((x) => x.apiName === property)
+      const pool = keys.get(`${ref.objectType}.${ref.property}`) ?? []
+      if (!p || !pool.length || opts.scenario?.types?.[type.apiName]?.fields?.[property]) continue
+      for (const row of rows) if (row[property] === '' && !optional(p)) row[property] = faker.helpers.arrayElement(pool)
+    }
+  }
+
+  // An inferred link back along a declared one: the record of the other type that links to this row.
+  for (const { type, rows, kept } of generated) {
+    if (kept) continue
+    const pk = primaryKeys.get(type.apiName)!
+    for (const [property, ref] of refs.get(type.apiName) ?? []) {
+      if (!ref.after || opts.scenario?.types?.[type.apiName]?.fields?.[property]) continue
+      const back = [...(refs.get(ref.objectType) ?? [])].filter(([, r]) => !r.inferred && r.objectType === type.apiName && r.property === pk).map(([q]) => q)
+      for (const row of rows) {
+        if (filled(row[property])) continue
+        const linked = back.flatMap((q) => rowsWhere(ref.objectType, q, row[pk]))
+        if (linked.length) row[property] = linked[0]![ref.property]
+      }
+    }
+  }
+
+  const out: GeneratedDataset[] = []
+  for (const { type, rows, kept } of generated) {
+    // Only the columns the dataset defines: a calculated field and a property its mapping leaves out have none.
+    const properties = storedProperties(type)
+    const pk = primaryKeys.get(type.apiName)!
+    const { dataset, column } = backingOf(type)
+    if (kept) {
+      out.push({ objectType: type.apiName, dataset, rows: rows.length, csvPath: join('datasets', `${dataset}.csv`), definitionPath: join('datasets', `${dataset}.json`), kept: true })
+      continue
+    }
     const columns = properties.map((p) => column(p.apiName))
     const csv = [columns.join(','), ...rows.map((r) => properties.map((p) => csvCell(r[p.apiName])).join(','))].join('\n') + '\n'
     const csvPath = join('datasets', `${dataset}.csv`)
     writeFileSync(join(root, csvPath), csv)
     const definitionPath = join('datasets', `${dataset}.json`)
+    const before = readDefinition(join(root, definitionPath))
+    // Every column a record may leave empty is declared nullable, so a CSV made again (other
+    // rows, another seed, a scenario) still fits the dataset's first contract.
+    const declared = new Map<string, Record<string, unknown>>((Array.isArray(before?.columns) ? (before.columns as Array<Record<string, unknown>>) : []).flatMap((c) => (typeof c?.name === 'string' && columns.includes(c.name) ? [[c.name, c] as const] : [])))
+    for (const p of properties) {
+      const name = column(p.apiName)
+      if (p.apiName !== pk && p.required !== true && !declared.has(name)) declared.set(name, { name, nullable: true })
+    }
     const definition = {
       apiName: dataset,
-      displayName: type.pluralDisplayName ?? plural(type.displayName ?? type.apiName),
-      description: `Sample ${(type.pluralDisplayName ?? plural(type.apiName)).toLowerCase()} made by \`frontera local data --synthetic\`: not real records.`,
+      displayName: typeof before?.displayName === 'string' ? before.displayName : type.pluralDisplayName ?? plural(type.displayName ?? type.apiName),
+      // Stamped with the rule set its rows were made by, so rows an older generator made are told apart (`local-sample-data.ts`).
+      description: stampedDescription(typeof before?.description === 'string' ? before.description : undefined, `Sample ${(type.pluralDisplayName ?? plural(type.apiName)).toLowerCase()} ${sampleStamp()}: not real records.`),
       kind: 'file',
       path: `./${dataset}.csv`,
       includedColumns: columns,
+      ...(declared.size ? { columns: columns.flatMap((c) => (declared.has(c) ? [declared.get(c)!] : [])) } : {}),
       keyColumns: [column(pk)],
       deterministicKeyConfirmed: true,
     }
     writeFileSync(join(root, definitionPath), `${JSON.stringify(definition, null, 2)}\n`)
-    out.push({ objectType: type.apiName, dataset, rows: rows.length, csvPath, definitionPath })
+    const vague = unresolved.filter((u) => u.objectType === type.apiName).map(({ property, condition }) => ({ property, condition }))
+    out.push({ objectType: type.apiName, dataset, rows: rows.length, csvPath, definitionPath, ...(vague.length ? { unresolved: vague } : {}) })
   }
   return out
 }
 
+/** The rows of a dataset sample data keeps, by property, as its CSV holds them; none when it has no CSV. */
+function keptRows(root: string, dataset: string, properties: Property[], column: (property: string) => string): Row[] {
+  const definition = readDefinition(join(root, 'datasets', `${dataset}.json`))
+  const rel = typeof definition?.path === 'string' ? definition.path.replace(/^\.\//, '') : `${dataset}.csv`
+  const path = join(root, 'datasets', rel)
+  if (!existsSync(path)) return []
+  return readCsvRows(readFileSync(path, 'utf8')).map((r) => Object.fromEntries(properties.map((p) => [p.apiName, r[column(p.apiName)] ?? ''])) as Row)
+}
+
+/** A dataset definition already in the project, or null. */
+function readDefinition(path: string): Record<string, unknown> | null {
+  try {
+    const doc = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? (doc as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * Give each object type without a dataset the one sample data writes, so the
  * Blueprint reads its rows. A type pulled with its own backing keeps it.
@@ -326,7 +2303,8 @@ export function addMissingBackings(root: string): string[] {
   for (const { file, doc } of readTree<ObjectType>(dir)) {
     if (!doc?.apiName || doc.backing?.dataset) continue
     const { dataset, column } = backingOf(doc)
-    const next = { ...doc, backing: { dataset, mapping: Object.fromEntries((doc.properties ?? []).map((p) => [p.apiName, column(p.apiName)])) } }
+    // A calculated field reads no column.
+    const next = { ...doc, backing: { dataset, mapping: Object.fromEntries((doc.properties ?? []).filter((p) => !p.calculation).map((p) => [p.apiName, column(p.apiName)])) } }
     const path = join(dir, file)
     writeFileSync(path, file.endsWith('.json') ? `${JSON.stringify(next, null, 2)}\n` : stringifyYaml(next, { lineWidth: 0 }))
     changed.push(join('blueprint', 'object-types', file))
@@ -334,18 +2312,51 @@ export function addMissingBackings(root: string): string[] {
   return changed
 }
 
+/**
+ * How sample data is made and what `data/generate.ts` may change, in words:
+ * `frontera local data --help` prints these, and the scenario template and
+ * the project's AGENTS.md say the same.
+ */
+export const SCENARIO_CONTRACT: readonly string[] = [
+  'Every object type in blueprint/object-types/ gets datasets/<dataset>.csv and its definition, one column per property its backing maps (a calculated field, such as a location from latitude and longitude, has none), except a type with a media property (a file in a Media Set): it reads a Media Set, not a dataset, so it gets no sample rows (the local runtime gives it a stand-in Media Set, which `frontera local dev` fills with placeholder files named after the paths the linked records give, or leaves it off), and a link to it is left empty. A value fits its property: the semantic type it carries (its own, or its shared field\'s), the values its description or its shared field\'s description lists ("low, medium, high or critical", alone or after a colon or dash: "The region - north, south or central"), an enum a governed Action writes into it, the values a metric\'s filter compares it with (some rows, so the metric counts something), then its type and name. A number a metric averages as a share (occupancyRate, "Occupancy percent") stays between 0 and 100. A time of day (openTime, closeTime, opensAt) is HH:MM, the close after the open, and both or neither; an `hours` text says the two; a `period` is a month (2026-09). A record\'s name reads like what the record is: a person\'s for a customer or technician, a company\'s for a supplier, a street for a site, the type and a serial for an asset; a person\'s email follows their name, and an asset\'s name its kind ("Transformer A-104"). Free text is written from the rest of the row: a title or summary names the record\'s category and the place or asset it links to ("Line damage at 4 Green Walk"), a description says who reported what and a detail, a resolution or outcome what was done (only once the record has ended, and not when it ended undone: cancelled, rejected, withdrawn…); a detail or a fix that names equipment (a pole, a cable, a meter) is used only for a record about that equipment, notes a follow-up, a reason a plain reason. A unit property (unit, uom) follows the row\'s reading kind (a sibling whose values are voltage, energy, temperature…, or measures such as occupancy_pct, annualised_rent, requests_opened, resolution_hours): by position when the unit\'s listed values line up with the kinds ("V, A, C or %" for "voltage, current, temperature or load"), else the unit among those listed that the kind is read in (percent, a currency code, count, hours), else the kind\'s usual unit; the value falls in that kind\'s range. Latitude, longitude and phone numbers follow --region: a country code, or a <lat>,<lon>[,<radius km>] point and radius (a true radius: every point lies within that many kilometres of it, spread evenly over the circle; a point takes the known country it lies in, for its names, currency, country and phone numbers). A row\'s latitude and longitude are one point, and a geopoint agrees with them; a compass region (values north, south, east, west, central) is the one the point lies in seen from the region\'s centre, and a city is the city of --region (one known area, or the large city a custom point is near: 39.74,-104.99 is Denver).',
+  'Links stay consistent: a property that holds another type\'s key gets one of its records (a primary key that is also a link key, as a transcript keyed by its service request, takes each record once, so the link resolves and the key stays unique: such a type has no more rows than the other), and when a row has two links whose records lead to each other along any path of links, they agree (a work order\'s asset is at the work order\'s site, and its customer is the customer that owns that site). A link whose record leads to more of the row\'s other links is chosen first, and the others follow from it. Two links to the same type (a reporter and an assignee) do not constrain each other. An optional link with no record that agrees is left empty. A property no link type declares but whose name says it holds another type\'s key (`propertyId` a Property\'s, `dispatchDecisionId` a DispatchDecision\'s even when its key is `decisionId`, `homePropertyId` the type its name ends with, `staffId` the type whose key it is, `assignedTo` or `owner` one of the people who do the work, such as Staff or Technician) takes that type\'s keys too, agreeing with the declared links but never constraining them; one that points back along a declared link (a request\'s dispatch decision, when each decision links to its request) takes the record that links to it. An id of a type the Blueprint doesn\'t have reads like a key (`portfolioId` → PRT-00003), from a few that rows share.',
+  'A property is optional unless it says `required: true`, as the Blueprint reads it: an optional value is sometimes empty, as real records are, except one that says which record it is or what its figure means (its title, a period, a fiscal year, a key or code, a case or scope, a currency or unit). Counts and sizes stay small (bedrooms 1–4, floors up to 30, a count a description introduces with "How many": up to 10), a number keeps to the range its description gives, in parentheses or as "between" ("How many hours the job takes (1 to 12)", "between 1 and 5"), months and years in a plausible span, a percent (pct) between 0 and 100, a probability between 0 and 1, an annual figure a year\'s worth, a fiscal year like FY2027, and who did something (prepared by, decided by) a person\'s name.',
+  'A record\'s state decides what else it holds. The state property is the one named status, state or stage (or ending in Status/State); its values (from its semantic type or description) each have a phase: new, pending, draft, submitted… start a life, closed, resolved, done, cancelled… end one, and every other value is under way; with three or more values and none named so, the first starts and the last ends. While a record has not started, an optional field for who took it on (assigned, assignee, technician, owner, or one whose description says it is empty while the record is new) is empty, and set once it has. Until it ends, an optional field set at the end (resolution, outcome, closedAt, resolvedAt) is empty, and set once it has. An optional field whose description makes it conditional ("empty unless escalated", "only when the priority is critical", "empty while on hold") is empty while the condition is false and set while it holds. The condition has to name something the record has: a yes/no property ("escalated" for a boolean escalated or isEscalated), a value of a property that lists values ("critical" for a priority with that value, "on hold" for a state on_hold), the record being closed or open, or another property (set when that one is), and "not" turns it. A condition that names nothing the record has never holds: an "empty unless" or "only when" field stays empty on every row, and the run names it under `unresolved` so the description can name a property or value, or a field function can set it. Times follow the life their names say: created, then assigned, then resolved, an update last, spread over the 120 days before today (the day it runs, midnight UTC, so the same seed gives the same rows that day). An open record with a due time (due, deadline, SLA, target, expected by) was raised in the last ten days and is due around today: about a quarter overdue by hours to days, the rest due within a week. A closed record was due days after it started. A time from before the record\'s own life follows its name instead: installed, commissioned, bought or built (an asset) from six months to 15 years back, founded or established from 2 to 60 years, hired up to 20 years; a birth date makes an adult.',
+  'Every column a record may leave empty is declared `nullable: true` in the definition\'s `columns`, so a CSV made again still fits the dataset.',
+  'Only sample data is written: a dataset this command made (its description says it was made by `frontera local data --synthetic`, with the sample rules its rows follow), one with no rows yet, and the scaffold\'s sample tickets while they are unedited. Any other dataset (one you wrote or edited, one a Source loads, one you brought into the folder) is kept as it is, and the sample rows of other types link to its records. `frontera local dev` and `frontera local status` say when sample data was made by older rules than today\'s, and running this command again remakes it.',
+  'data/generate.ts adjusts it: `export default function scenario({ faker })` returns `{ rows?, types?: { <ObjectType>: { rows?, fields?: { <property>: (row, index, ctx) => value } } } }`. `rows` is the count (per type, or for every type); a field function gives that property\'s value and receives the whole row (`row`: every property already generated, its own default included, so a function can read any property whatever the order the object type lists them in, or adjust its own), the row\'s position (`index`, from 0) and the rows of other types (`ctx.rowsOf(\'Site\')`: every generated Site row, read-only; `ctx.lookup(\'Site\', row.siteId)`: the Site whose primary key is that, or `ctx.lookup(\'Site\', value, \'property\')` by another property; undefined when none is). Types are generated in link order, a type before the types that point at it, so the types a row links to are there; its own type and the ones generated after it give [] and undefined. Functions run in the order the type lists their properties, every date and time after the others; a function that reads another function\'s value sees it, and one whose read value changes later is run again (at most three more times) until what it read is final. Return \'\' or null for an empty value. A field with a function is left as the function made it; the fields without one follow the functions\' values: the state, link, text, unit and point rules above apply again (a state a function sets empties or fills the fields it decides, and changes the times when the record\'s phase changes). `faker` is the CLI\'s own Faker (https://fakerjs.dev/api/), seeded, so the same --seed gives the same rows.',
+]
+
 /** The scenario template written the first time, for the FDE or a coding agent to edit. */
 export const SCENARIO_TEMPLATE = `/**
  * Adjusts the sample data \`frontera local data --synthetic\` writes into
- * datasets/. Return rows per object type and, per property, a function that
- * gives its value; anything left out is generated from the property's type,
- * name and description. \`faker\` is seeded, so the same seed gives the same rows.
+ * datasets/ (\`frontera local data --help\` says how the rest is made).
+ *
+ * Return rows per object type and, per property, a function that gives its
+ * value; anything left out is generated from the property's semantic type,
+ * description, type and name, with links and states kept consistent.
+ *
+ * A field function is called as \`(row, index, ctx)\`:
+ *   row    the whole record, every property already generated (its own
+ *          default too), whatever order the object type lists them in; a
+ *          function that reads another function's value sees that value
+ *   index  the row's position, from 0
+ *   ctx    the rows of other types, read-only: \`ctx.rowsOf('Site')\` is
+ *          every generated Site, \`ctx.lookup('Site', row.siteId)\` the one
+ *          with that primary key (undefined when none is). The types a row
+ *          links to are generated before it; its own type gives none.
+ * Return '' or null for an empty value. A field with a function is left as
+ * it made it; the fields without one follow it (a state a function sets
+ * empties or fills the fields it decides; links, text and points agree).
  *
  *   frontera local data --synthetic --seed 7
  *
- * \`faker\` is the CLI's own (https://fakerjs.dev/api/), so the project
- * installs nothing for it.
+ * \`faker\` is the CLI's own (https://fakerjs.dev/api/), seeded, so the same
+ * seed gives the same rows and the project installs nothing for it.
  */
+type Row = Record<string, unknown>
+type Context = { rowsOf: (type: string) => readonly Row[]; lookup: (type: string, value: unknown, property?: string) => Row | undefined }
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default function scenario({ faker }: { faker: any }) {
   return {
@@ -355,6 +2366,12 @@ export default function scenario({ faker }: { faker: any }) {
       //   rows: 300,
       //   fields: {
       //     priority: () => faker.helpers.weightedArrayElement([{ value: 'urgent', weight: 1 }, { value: 'normal', weight: 6 }]),
+      //     // Reads another property of the same row, wherever the type lists it.
+      //     subject: (row: Row) => (row.priority === 'urgent' ? 'Service down' : 'Question about an invoice'),
+      //     // Reads the generated times, and adjusts its own default.
+      //     resolvedAt: (row: Row) => (row.status === 'closed' ? row.updatedAt : null),
+      //     // Reads the record a link points at: the customer's tier decides the priority.
+      //     // priority: (row: Row, _i: number, ctx: Context) => (ctx.lookup('Customer', row.customerId)?.tier === 'enterprise' ? 'urgent' : 'normal'),
       //   },
       // },
     },