@nodaro/prompts 1.13.0 → 1.15.0

package/src/__tests__/catalog-overlay.test.ts

@@ -0,0 +1,163 @@
+/**
+ * The resolver-side half of catalog curation: a pack that removes or rewrites
+ * an entry must change what the id→entry GETTERS return, because those are
+ * what turns a picker id into prompt text at run time. Before this overlay
+ * existed, a deployment's curation was visible in /v1/catalogs and invisible
+ * in every generated prompt.
+ *
+ * The totality test at the bottom is the one that keeps this fixed: every
+ * catalog with a getter must honor a deny pack, so a new catalog cannot ship
+ * with a getter that reads its base constant straight.
+ */
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  registerCatalogPack,
+  resetCatalogPacks,
+  getPickerCatalog,
+  PICKER_CATALOGS,
+  getSetting,
+  getSettingPromptHint,
+  getPose,
+  getPosePromptHint,
+  getParameterPromptHint,
+  renderSubjectHints,
+  SETTINGS,
+  POSES,
+} from "../index.js"
+import { ANIMALS } from "@nodaro/shared"
+
+afterEach(() => resetCatalogPacks())
+
+describe("overlayEntry — the four outcomes", () => {
+  const settingId = SETTINGS[0].id
+
+  it("no packs: the base entry, by identity (mainline byte-identical)", () => {
+    expect(getSetting(settingId)).toBe(SETTINGS[0])
+  })
+
+  it("deny pack: the id resolves to NOTHING on the prompt path", () => {
+    registerCatalogPack({ id: "t-deny", catalogId: "setting", mode: "deny", denyIds: [settingId] })
+    expect(getSetting(settingId)).toBeUndefined()
+    expect(getSettingPromptHint(settingId)).toBe("")
+    // A sibling the pack did not touch still resolves.
+    expect(getSetting(SETTINGS[1].id)).toBeDefined()
+  })
+
+  it("replace pack with a REWRITE: the composed wording reaches the getter", () => {
+    const base = getPickerCatalog("setting")!
+    const rewritten = {
+      ...base,
+      options: base.options!.map((o) =>
+        o.id === settingId ? { ...o, label: "Curated Label", promptHint: "curated prompt text" } : o,
+      ),
+    }
+    registerCatalogPack({ id: "t-replace", catalogId: "setting", mode: "replace", catalog: rewritten })
+    const s = getSetting(settingId)!
+    expect(s.label).toBe("Curated Label")
+    expect(s.promptHint).toBe("curated prompt text")
+    expect(getSettingPromptHint(settingId)).toBe("curated prompt text")
+    // Fields the composed option does not carry survive from the base entry.
+    expect(s.id).toBe(settingId)
+  })
+
+  it("replace pack that OMITS an entry: the omitted id resolves to nothing", () => {
+    const base = getPickerCatalog("setting")!
+    registerCatalogPack({
+      id: "t-replace-omit",
+      catalogId: "setting",
+      mode: "replace",
+      catalog: { ...base, options: base.options!.filter((o) => o.id !== settingId) },
+    })
+    expect(getSetting(settingId)).toBeUndefined()
+  })
+
+  it("extend pack: a pack-added id resolves to the composed option", () => {
+    registerCatalogPack({
+      id: "t-extend",
+      catalogId: "setting",
+      mode: "extend",
+      options: [{ id: "curated-only", label: "Curated Only", promptHint: "only in the pack", term: "curated" }],
+    })
+    expect(getSetting("curated-only")?.promptHint).toBe("only in the pack")
+  })
+})
+
+describe("the dispatcher honors the overlay end to end", () => {
+  it("a denied pose sub-pick contributes nothing to the hint", () => {
+    const poseId = POSES[0].id
+    const before = getParameterPromptHint({ id: "n", type: "pose", data: { pose: poseId } } as never)
+    expect(before).not.toBe("")
+    registerCatalogPack({ id: "t-pose", catalogId: "pose", mode: "deny", denyIds: [poseId] })
+    expect(getPose(poseId)).toBeUndefined()
+    expect(getPosePromptHint(poseId)).toBe("")
+    expect(getParameterPromptHint({ id: "n", type: "pose", data: { pose: poseId } } as never)).toBe("")
+  })
+
+  it("the @nodaro/shared-owned catalogs are overlaid at the dispatcher", () => {
+    const animalId = ANIMALS[0].id
+    const before = getParameterPromptHint({ id: "n", type: "animal", data: { animal: animalId } } as never)
+    expect(before).not.toBe("")
+    registerCatalogPack({ id: "t-animal", catalogId: "animals", mode: "deny", denyIds: [animalId] })
+    expect(getParameterPromptHint({ id: "n", type: "animal", data: { animal: animalId } } as never)).toBe("")
+  })
+})
+
+describe("TOTALITY — every catalog honors a deny pack ON THE PROMPT PATH", () => {
+  // Mechanical, not enumerated: walk every catalog, deny its first id, and
+  // assert the dispatcher produces NOTHING for a node carrying that id — the
+  // same call the orchestrator makes. A getter that still reads its base
+  // constant straight fails here whether or not anyone remembered to list it.
+  // The field the id lives in comes from the catalog itself (single-dim
+  // valueField / multi-dim dimension field), so a catalog cannot slip past by
+  // storing its value under a name this test did not know.
+  const cases = PICKER_CATALOGS.map((c) => {
+    const dim = c.dimensions?.[0]
+    const field = c.valueField ?? dim?.field
+    // The first REAL entry: a catalog's "auto"/"none" no-op (term "") injects
+    // nothing by design, which would make the pre-deny assertion vacuous.
+    const opt = (c.options ?? dim?.options ?? []).find((o) => o.term !== "")
+    return { nodeType: c.nodeType, catalogId: c.catalogId, field: field!, id: opt?.id ?? "" }
+  })
+
+  it.each(cases)("$nodeType", ({ nodeType, catalogId, field, id }) => {
+    expect(id, `${catalogId}: catalog has no options to deny`).not.toBe("")
+    // `instruments` is the one field whose node value is always an array.
+    const node = { id: "n", type: nodeType, data: { [field]: field === "instruments" ? [id] : id } } as never
+    const before = getParameterPromptHint(node)
+    expect(before, `${nodeType}: the stock id must produce SOME hint for the test to mean anything`).not.toBe("")
+    registerCatalogPack({ id: `tot-${catalogId}`, catalogId, mode: "deny", denyIds: [id] })
+    expect(getParameterPromptHint(node), `${nodeType}: denied "${id}" still reaches the prompt`).toBe("")
+  })
+
+  it("a REWRITE reaches the prompt text end to end, for a prompts-owned and a shared-owned catalog", () => {
+    for (const [nodeType, field] of [["setting", "setting"], ["animal", "animal"]] as const) {
+      resetCatalogPacks()
+      const cat = getPickerCatalog(nodeType)!
+      const id = cat.options![0].id
+      const stock = getParameterPromptHint({ id: "n", type: nodeType, data: { [field]: id } } as never)
+      registerCatalogPack({
+        id: `rw-${nodeType}`,
+        catalogId: cat.catalogId,
+        mode: "replace",
+        catalog: { ...cat, options: cat.options!.map((o) => (o.id === id ? { ...o, promptHint: "CURATED WORDING" } : o)) },
+      })
+      const curated = getParameterPromptHint({ id: "n", type: nodeType, data: { [field]: id } } as never)
+      expect(curated, nodeType).toContain("CURATED WORDING")
+      expect(curated, nodeType).not.toBe(stock)
+    }
+  })
+
+  it("the same animal id renders identically through the parameter node and the subject fold", () => {
+    const id = getPickerCatalog("animals")!.options![0].id
+    registerCatalogPack({
+      id: "rw-animal-subject",
+      catalogId: "animals",
+      mode: "replace",
+      catalog: { ...getPickerCatalog("animals")!, options: getPickerCatalog("animals")!.options!.map((o) => (o.id === id ? { ...o, promptHint: "SUBJECT WORDING" } : o)) },
+    })
+    const viaNode = getParameterPromptHint({ id: "n", type: "animal", data: { animal: id } } as never)
+    expect(viaNode).toContain("SUBJECT WORDING")
+    const viaSubject = renderSubjectHints({ animal: id }, "image")
+    expect(JSON.stringify(viaSubject)).toContain("SUBJECT WORDING")
+  })
+})

package/src/__tests__/dod-replace-pack-acceptance.test.ts

@@ -39,3 +39,20 @@ describe("DoD — adopt a vendored replacement pack by registration", () => {
     expect(JSON.stringify(PICKER_CATALOGS)).toBe(upstreamSnapshot)
   })
 })
+
+describe("adultOnly survives packs (W1-a)", () => {
+  it("a replace pack keeps the flag on its options; an extend pack adds a flagged option", () => {
+    const upstreamMood = PICKER_CATALOGS.find((c) => c.catalogId === "mood")!
+    const vendored: PickerCatalog = {
+      ...upstreamMood,
+      options: [
+        { id: "calm", label: "Calm", promptHint: "with a calm mood", term: "calm", category: upstreamMood.options![0].category },
+        { id: "sultry", label: "Sultry", promptHint: "with a sultry expression", term: "sultry", category: upstreamMood.options![0].category, adultOnly: true },
+      ],
+    }
+    registerCatalogPack({ id: "sai/mood", catalogId: "mood", mode: "replace", catalog: vendored })
+    const out = getRegisteredPickerCatalogs().find((c) => c.catalogId === "mood")!.options!
+    expect(out.find((o) => o.id === "sultry")!.adultOnly).toBe(true)
+    expect(out.find((o) => o.id === "calm")!.adultOnly).toBeUndefined()
+  })
+})

package/src/__tests__/fixtures/parameter-hint-golden.json

@@ -1703,7 +1703,7 @@
         }
       },
       "ctx": null,
-      "expected": "a man, a baby under 1 year old, of Asian descent, a California beach aesthetic — laid-back beach-town vibe, golden-hour sun-warmed energy, easy carefree mood, petite, lean build, small bust, defined waist, narrow hips, hourglass silhouette, an oval face shape, a strong, sharply defined jawline, almond-shaped eyes, a straight nose, thin lips, with chapped, cracked, weather-worn dry lips, a shaved bald head, platinum blonde hair, very pale and icy, natural eyebrows, very fair pale skin, with flawless, silky smooth skin, brown eyes, with eyes fully closed in a peaceful expression, clean-shaven, wearing glasses"
+      "expected": "a man, a baby under 1 year old, of Asian descent, a California beach aesthetic — laid-back beach-town vibe, golden-hour sun-warmed energy, easy carefree mood, petite, lean build, an oval face shape, a strong, sharply defined jawline, almond-shaped eyes, a straight nose, thin lips, with chapped, cracked, weather-worn dry lips, a shaved bald head, platinum blonde hair, very pale and icy, natural eyebrows, very fair pale skin, with flawless, silky smooth skin, brown eyes, with eyes fully closed in a peaceful expression, clean-shaven, wearing glasses"
     },
     {
       "key": "person/last-of-each",
@@ -1748,7 +1748,7 @@
         }
       },
       "ctx": null,
-      "expected": "the Grim Reaper — tall hooded skeletal figure in a tattered black robe, bony hands gripping a long wooden scythe, face hidden in shadow, of mixed heritage, an Auckland coastal aesthetic — New Zealand harbor-city vibe, considered Pacific polish, broad-framed, heavy-set build, very full bust, straight waistline, wide hips, athletic silhouette, a triangular face shape with a narrow forehead and wide jaw, a visible double chin, wide, prominent cheekbones, a round face with soft, rounded cheeks, narrow, elongated eyes, deep-set eyes, downturned eyes with the outer corners angled down, negative canthal tilt, wide-set eyes spaced widely apart, eyes set well below the brow with generous brow-to-eye distance, doe eyes, a hooked nose with a strongly curved tip, a slightly drooping, downward-pointing nose tip, full lips with a noticeably fuller lower lip, a small petite mouth, with a full pouting expression, wet, slick hair, rainbow hair with streaks of multiple bright dyed colors, a connected unibrow, very dark ebony skin, the deepest skin tone, with visible acne scarring, healed pitted-skin texture and uneven surface from past breakouts, jet-black eyes with a truly black iris, deeper than brown, with glassy, tear-glazed wet eyes, a five-o'clock shadow, daily growth heavier than light stubble, with visible fangs at the canines, character / vampire archetype"
+      "expected": "the Grim Reaper — tall hooded skeletal figure in a tattered black robe, bony hands gripping a long wooden scythe, face hidden in shadow, of mixed heritage, an Auckland coastal aesthetic — New Zealand harbor-city vibe, considered Pacific polish, broad-framed, heavy-set build, athletic silhouette, a triangular face shape with a narrow forehead and wide jaw, a visible double chin, wide, prominent cheekbones, a round face with soft, rounded cheeks, narrow, elongated eyes, deep-set eyes, downturned eyes with the outer corners angled down, negative canthal tilt, wide-set eyes spaced widely apart, eyes set well below the brow with generous brow-to-eye distance, doe eyes, a hooked nose with a strongly curved tip, a slightly drooping, downward-pointing nose tip, full lips with a noticeably fuller lower lip, a small petite mouth, wet, slick hair, rainbow hair with streaks of multiple bright dyed colors, a connected unibrow, very dark ebony skin, the deepest skin tone, with visible acne scarring, healed pitted-skin texture and uneven surface from past breakouts, jet-black eyes with a truly black iris, deeper than brown, with glassy, tear-glazed wet eyes, a five-o'clock shadow, daily growth heavier than light stubble, with visible fangs at the canines, character / vampire archetype"
     },
     {
       "key": "person/mid-of-each",

package/src/__tests__/minor-age-floor.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from "vitest"
+import { buildPersonHints } from "../person.js"
+import { buildStylingHints } from "../styling.js"
+import { getAdultOnlyEntries, applyMinorAgeFloorToPickerValues, getAdultOnlyHintStrings, ADULT_SWEPT_CATALOG_IDS, FLOORED_PICKER_KEYS } from "../age-floor.js"
+
+/** The seven P0 prompts' shape (2026-07-30): a 5-year-old + fitted clothing +
+ *  parted lips + baby-soft skin + direct gaze. Assembled from picker values —
+ *  the stored prompts are never replayed. */
+const CHILD = {
+  type: "boy-next-door",
+  age: "age-young-child",
+  frame: "frame-slim",
+  lipState: ["lip-state-parted"],
+  eyeState: ["eye-state-staring-camera"],
+  skinTexture: ["texture-baby-soft"],
+} as const
+
+describe("Layer 1 — the collectors drop adultOnly entries for a minor", () => {
+  it("a child with flagged lip/eye/skin picks emits none of their hints, keeps the rest", () => {
+    const hints = buildPersonHints({ ...CHILD, bust: "bust-very-full", distinctiveFeature: ["feature-midriff-visible"] } as never)
+    const joined = hints.join(", ")
+    expect(joined).toContain("a young child around 5 years old")
+    expect(joined).toContain("slim")
+    expect(joined).not.toMatch(/bust|midriff|lips slightly parted|soft breath/i)
+    // eye-state-staring-camera and texture-baby-soft are NOT flagged — they stay.
+    expect(joined).toContain("staring directly at the camera with unbroken eye contact")
+  })
+
+  it("compact mode drops the same ids", () => {
+    const terms = buildPersonHints({ ...CHILD, bust: "bust-very-full", lipState: ["lip-state-glossy"] } as never, "compact")
+    expect(terms.join(", ")).not.toMatch(/bust|glossy/i)
+  })
+
+  it("styling on the flat subject bag drops flagged garments when the bag says minor", () => {
+    const hints = buildStylingHints({ age: "age-child", wardrobeState: ["state-fitted"], top: "top-crop-top", outfit: "outfit-bikini" } as never)
+    const joined = hints.join(", ")
+    expect(joined).not.toMatch(/hugging the contours|bikini/i)
+    expect(joined).toMatch(/cropped top/i) // top-crop-top is deliberately NOT flagged
+  })
+
+  it("styling with no age signal on the bag is untouched (separate-node consumers; Layer 2 covers them)", () => {
+    const hints = buildStylingHints({ wardrobeState: ["state-fitted"] } as never)
+    expect(hints.join(", ")).toMatch(/hugging the contours/i)
+  })
+
+  it("adults are byte-identical to before: every flagged entry still emits for age-30s", () => {
+    for (const e of getAdultOnlyEntries().filter((x) => x.id.startsWith("bust-") || x.id.startsWith("lip-state-"))) {
+      const field = e.id.startsWith("bust-") ? "bust" : "lipState"
+      const value = field === "bust" ? e.id : [e.id]
+      const hints = buildPersonHints({ age: "age-30s", [field]: value } as never)
+      expect(hints.join(" "), e.id).toContain(e.promptHint)
+    }
+  })
+
+  it("a minor-implying type with no age is floored too", () => {
+    const hints = buildPersonHints({ type: "alice-wonderland", bust: "bust-full" } as never)
+    expect(hints.join(", ")).not.toMatch(/bust/i)
+  })
+})
+
+describe("applyMinorAgeFloorToPickerValues", () => {
+  it("strips flagged ids from person/styling/pose/mood when the person is a minor", () => {
+    const out = applyMinorAgeFloorToPickerValues({
+      person: { age: "age-early-teen", bust: "bust-full", lipState: ["lip-state-glossy", "lip-state-bold-red"] },
+      styling: { top: "top-bra-top", wardrobeState: ["state-fitted", "state-layered"] },
+      pose: { pose: "arched-back" },
+      mood: { mood: ["sultry", "calm"] },
+    })
+    expect(out.person).toEqual({ age: "age-early-teen", lipState: ["lip-state-bold-red"] })
+    expect(out.styling).toEqual({ wardrobeState: ["state-layered"] })
+    expect(out.pose).toEqual({})
+    expect(out.mood).toEqual({ mood: ["calm"] })
+  })
+
+  it("is the identity for an adult", () => {
+    const values = { person: { age: "age-30s", bust: "bust-full" }, styling: { top: "top-bra-top" } }
+    expect(applyMinorAgeFloorToPickerValues(values)).toBe(values)
+  })
+
+  // The final-review gap: `photo-genre` is swept for the flag
+  // (ADULT_SWEPT_CATALOG_IDS) but the hand-written strip list omitted it, so a
+  // minor kept `glamour-portrait` / `brand-helmut-newton`. FLOORED_PICKER_KEYS
+  // is derived from the sweep list now, which is what makes this pass.
+  it("strips a flagged photo-genre id from a minor's values", () => {
+    // The real analyzer field for this picker is `photoGenre`
+    // (picker-analyzer-registry.ts) — `stripIds` drops by VALUE, so the key
+    // name is immaterial; both shapes are pinned so neither can regress.
+    const out = applyMinorAgeFloorToPickerValues({
+      person: { age: "age-child" },
+      "photo-genre": { photoGenre: "glamour-portrait" },
+    })
+    expect(out["photo-genre"]).toEqual({})
+
+    const coordinatorShape = applyMinorAgeFloorToPickerValues({
+      person: { age: "age-child" },
+      "photo-genre": { genre: "glamour-portrait" },
+    })
+    expect(coordinatorShape["photo-genre"]).toEqual({})
+  })
+
+  it("an adult keeps the same photo-genre id (identity)", () => {
+    const values = { person: { age: "age-30s" }, "photo-genre": { photoGenre: "glamour-portrait" } }
+    expect(applyMinorAgeFloorToPickerValues(values)).toBe(values)
+  })
+
+  // Totality: the strip list can never again be a subset of the sweep list.
+  it("every swept catalog is a floored picker key, and person leads the list", () => {
+    for (const id of ADULT_SWEPT_CATALOG_IDS) {
+      expect(FLOORED_PICKER_KEYS as ReadonlyArray<string>, id).toContain(id)
+    }
+    expect(FLOORED_PICKER_KEYS[0]).toBe("person")
+    expect(FLOORED_PICKER_KEYS).toHaveLength(ADULT_SWEPT_CATALOG_IDS.length + 1)
+  })
+})
+
+describe("getAdultOnlyHintStrings", () => {
+  it("contains the seven-prompt trigger clause and is longest-first", () => {
+    const strings = getAdultOnlyHintStrings()
+    expect(strings).toContain("the clothing fitted and form-conscious, hugging the contours of the body")
+    expect(strings.length).toBeGreaterThan(0)
+    for (let i = 1; i < strings.length; i++) expect(strings[i - 1].length).toBeGreaterThanOrEqual(strings[i].length)
+  })
+
+  it("excludes bare derived terms that are absent from every promptHint (fix round 1: promptHint-only)", () => {
+    const strings = getAdultOnlyHintStrings()
+    // "lounging" (pose id/label, no explicit term — deriveTerm(label) would
+    // back-fill it in the composed catalog) and "cropped top" (state-cropped's
+    // explicit `term`, distinct from its promptHint "the top cropped above the
+    // midriff with the stomach visible") are exactly the short, generic strings
+    // that over-strip unrelated benign text when swept as needles.
+    expect(strings).not.toContain("lounging")
+    expect(strings).not.toContain("cropped top")
+    expect(strings).not.toContain("school uniform")
+    expect(strings).not.toContain("lying down")
+  })
+})

package/src/__tests__/multi-picker-spec.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest"
-import { buildMultiPickerAnalyzerSpec, buildPickerAnalyzerSpec, pickerFanoutTargets } from "../index.js"
+import { buildMultiPickerAnalyzerSpec, buildPickerAnalyzerSpec, pickerFanoutTargets, PICKER_TYPES } from "../index.js"
 
 describe("buildMultiPickerAnalyzerSpec", () => {
   it("composes one section per wired picker plus gaps, order-independent", () => {
@@ -23,6 +23,26 @@ describe("buildMultiPickerAnalyzerSpec", () => {
     expect(withGaps.gaps.missingItems).toHaveLength(1)
   })
 
+  it("otherPickersLegend names the non-wired pickers by key, excluding the wired ones", () => {
+    const { otherPickersLegend } = buildMultiPickerAnalyzerSpec(["person", "styling"])
+    expect(otherPickersLegend.length).toBeGreaterThan(0)
+    // non-wired pickers are attributable by their exact key
+    expect(otherPickersLegend).toContain("- era:")
+    expect(otherPickersLegend).toContain("- setting:")
+    expect(otherPickersLegend).toContain("- held-prop:")
+    // wired pickers must NOT appear as their own bullet lines
+    expect(otherPickersLegend).not.toContain("- person:")
+    expect(otherPickersLegend).not.toContain("- styling:")
+    // discriminated pickers carry their dimension labels; flat ones carry the label
+    expect(otherPickersLegend).toContain("Era / Period") // flat `era` label
+    expect(otherPickersLegend).toMatch(/- exposure-settings: Exposure Settings — .*Aperture/) // title-cased key + dims
+  })
+
+  it("otherPickersLegend is empty when every picker is wired", () => {
+    const { otherPickersLegend } = buildMultiPickerAnalyzerSpec(PICKER_TYPES)
+    expect(otherPickersLegend).toBe("")
+  })
+
   it("FUZZ: arbitrary gaps content never alters the enum-validated picker sections", () => {
     const { schema } = buildMultiPickerAnalyzerSpec(["person"])
     const personSpec = buildPickerAnalyzerSpec("person")

package/src/__tests__/person-pack-adult-only.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { registerPersonPack, resetPersonPacks, getRegisteredPeople } from "../person-packs.js"
+import { registerCatalogPack, resetCatalogPacks } from "../catalog-packs.js"
+
+beforeEach(() => {
+  resetPersonPacks()
+  resetCatalogPacks()
+})
+
+describe("person packs carry adultOnly", () => {
+  it("an extend person pack entry keeps its flag in getRegisteredPeople()", () => {
+    registerPersonPack({
+      id: "test/person-extend",
+      dimensions: [{ dimension: "vibe", field: "vibe", label: "Vibe" }],
+      entries: [
+        { id: "vibe-boudoir", label: "Boudoir", dimension: "vibe", description: "Boudoir styling", promptHint: "in a boudoir setting", adultOnly: true },
+        { id: "vibe-picnic", label: "Picnic", dimension: "vibe", description: "Picnic styling", promptHint: "at a picnic" },
+      ],
+    })
+    const people = getRegisteredPeople()
+    expect(people.find((p) => p.id === "vibe-boudoir")?.adultOnly).toBe(true)
+    expect(people.find((p) => p.id === "vibe-picnic")?.adultOnly).toBeUndefined()
+  })
+
+  it("a replace catalog pack for person keeps the flag through personEntriesFromDims", () => {
+    registerCatalogPack({
+      id: "test/person-replace",
+      catalogId: "person",
+      mode: "replace",
+      catalog: {
+        catalogId: "person",
+        kind: "multi",
+        label: "Person",
+        dimensions: [
+          {
+            field: "bust",
+            label: "Bust",
+            options: [{ id: "bust-very-full", label: "Very Full", promptHint: "very full bust", adultOnly: true }],
+          },
+        ],
+      } as never,
+    })
+    expect(getRegisteredPeople().find((p) => p.id === "bust-very-full")?.adultOnly).toBe(true)
+  })
+})

package/src/__tests__/person-regional-aesthetic.test.ts

@@ -26,7 +26,7 @@ describe("regional-aesthetic dimension — wiring", () => {
 
 describe("regional-aesthetic catalog — coverage and structure", () => {
   it("ships the expected total entry count", () => {
-    expect(REGIONAL_ENTRIES.length).toBe(86)
+    expect(REGIONAL_ENTRIES.length).toBe(88)
   })
 
   it.each([
@@ -34,6 +34,7 @@ describe("regional-aesthetic catalog — coverage and structure", () => {
     ["USA — African-American", 6],
     ["Europe", 16],
     ["Asia", 12],
+    ["Central Asia", 2],
     ["Latin America", 7],
     ["Middle East", 7],
     ["North Africa", 3],

package/src/__tests__/picker-analyzer-registry.test.ts

@@ -7,6 +7,7 @@ import {
 import {
   buildPickerAnalyzerSpec,
   buildPickerZodSchema,
+  PICKER_ANALYZER_REGISTRY,
 } from "../picker-analyzer-registry.js"
 // NOTE: the existing test file already imports `buildPickerAnalyzerSpec` from
 // "../picker-analyzer-registry.js" — do NOT re-import it here (duplicate-identifier
@@ -116,3 +117,16 @@ describe("registry invariants (all analyzable pickers)", () => {
     expect(buildPickerAnalyzerSpec("lens").dimensions[0].entryIds).toEqual(LENSES.map((l) => l.id))
   })
 })
+
+describe("personCleanup (W1-a: minor-age floor)", () => {
+  it("drops flagged ids from the patch when the patch itself is a minor", () => {
+    const patch: Record<string, unknown> = {
+      age: "age-child",
+      bust: "bust-full",
+      lipState: ["lip-state-glossy", "lip-state-bold-red"],
+    }
+    PICKER_ANALYZER_REGISTRY.person.cleanup?.(patch, "fill-empty")
+    expect(patch.bust).toBeUndefined()
+    expect(patch.lipState).toEqual(["lip-state-bold-red"])
+  })
+})

package/src/__tests__/provider-prompt-doctrine.test.ts

@@ -66,4 +66,43 @@ describe("PROVIDER_PROMPT_DOCTRINES", () => {
     expect(tips).toMatch(/2\.0 SKUs ignore timestamps/)
     expect(tips).toMatch(/seedance-2-5 honours integer-second timestamps/)
   })
+
+  it("Wan 3.0 has its OWN doctrine — the 2.x token format must not leak onto it", () => {
+    // WAN_DOCTRINE teaches "Image 1" / "Video 1" (capitalised, WITH a space),
+    // which is the Wan 2.x format. The Wan 3.0 KIE contract binds Image1 /
+    // Video1 / Audio1 (no space). Folding 3.0 into the 2.x entry would ship a
+    // token format the model does not use — a prompt-quality regression that
+    // costs real generations, so the split is the point of this test.
+    const d = getPromptDoctrine("wan-3")!
+    expect(d.providers).toEqual(["wan-3", "wan-3-prime"])
+    expect(getPromptDoctrine("wan-3-prime")).toBe(d)
+    expect(d.doctrine).toContain("Image1")
+    expect(d.doctrine).toContain("Audio1")
+    // The 2.x spelling may appear ONLY as an explicit contrast, never as the
+    // instruction — so the body must say the format has no space.
+    expect(d.doctrine).toMatch(/NO space/)
+    expect(d.doctrine).toMatch(/Wan 2\.x's "Image 1"/)
+
+    // The 2.x doctrine must stay the 2.x doctrine.
+    const wan2 = getPromptDoctrine("wan-i2v")!
+    expect(wan2).not.toBe(d)
+    expect(wan2.providers).not.toContain("wan-3")
+    expect(wan2.doctrine).toContain("Image 1")
+
+    // KIE contract facts the body is required to carry.
+    expect(d.doctrine).toMatch(/mutually exclusive|CANNOT be combined/i)
+    expect(d.doctrine).toMatch(/20,000 characters/)
+    expect(d.doctrine).toMatch(/≤ 30 seconds/)
+    // Prime is the SPEED tier — never described as higher quality.
+    expect(d.doctrine).toMatch(/faster turnaround/i)
+    expect(d.doctrine).not.toMatch(/higher quality/i)
+  })
+
+  it("Gemini Omni Flash rides the sibling's doctrine (identical request surface)", () => {
+    const d = getPromptDoctrine("gemini-omni-flash")!
+    expect(d).toBe(getPromptDoctrine("gemini-omni-video"))
+    expect(d.providers).toEqual(["gemini-omni-video", "gemini-omni-flash"])
+    expect(d.heading).toContain("gemini-omni-flash")
+    expect(d.doctrine).toMatch(/gemini-omni-flash is the faster\/cheaper tier/)
+  })
 })

package/src/action-fx.ts

@@ -18,6 +18,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type ActionFxCategory =
   | "disaster"
@@ -224,7 +225,7 @@ const actionFxById = new Map<string, ActionFx>(ACTION_FX.map((fx) => [fx.id, fx]
 
 export function getActionFx(id: string | undefined | null): ActionFx | undefined {
   if (!id) return undefined
-  return actionFxById.get(id)
+  return overlayEntry("action-fx", id, actionFxById.get(id))
 }
 
 export function getActionFxLabel(id: string | undefined | null, fallback?: string): string {

package/src/aesthetic.ts

@@ -20,6 +20,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type AestheticCategory = "mainstream" | "niche" | "era" | "mood"
 
@@ -400,7 +401,7 @@ const aestheticById = new Map<string, Aesthetic>(
 
 export function getAesthetic(id: string | undefined | null): Aesthetic | undefined {
   if (!id) return undefined
-  return aestheticById.get(id)
+  return overlayEntry("aesthetic", id, aestheticById.get(id))
 }
 
 export function getAestheticLabel(id: string | undefined | null, fallback?: string): string {