@nodaro/prompts 1.13.0 → 1.15.0

package/src/age-floor.ts

@@ -0,0 +1,296 @@
+/**
+ * The minor-age floor — Layer 1 of spec 2026-09-01-app-reports-triage-design.md
+ * §3.3 (W1-a). Content-free: this module decides WHICH catalog entries a minor
+ * subject may not carry; the clause a deployment appends lives in its
+ * registered PromptPolicy (backend/src/lib/prompt-policies/), never here.
+ *
+ * `ADULT_ONLY_FLAG`, `ADULT_AGE_IDS`, `MINOR_IMPLYING_TYPE_IDS` and
+ * `isMinorAge` live in the import-free leaf `age-signal.ts` and are
+ * re-exported here unchanged — this module's own catalog-funnel imports
+ * (`person-packs.js`, `picker-catalogs.js`) are exactly what `person.ts` /
+ * `styling.ts` must NOT reach through, on pain of reopening the
+ * person → age-floor → picker-catalogs load-time cycle (see `age-signal.ts`'s
+ * header). `person.ts` / `styling.ts` import `isMinorAge` from
+ * `age-signal.ts` directly instead of from here.
+ */
+
+import { getRegisteredPeople } from "./person-packs.js"
+import { getRegisteredPickerCatalogs, type PickerCatalog, type PickerOption } from "./picker-catalogs.js"
+import { isMinorAge, ADULT_AGE_IDS, MINOR_IMPLYING_TYPE_IDS } from "./age-signal.js"
+
+export { ADULT_ONLY_FLAG, ADULT_AGE_IDS, MINOR_IMPLYING_TYPE_IDS, isMinorAge } from "./age-signal.js"
+
+/** Shape shared by every catalog entry the floor reads. */
+export interface AdultOnlyEntry {
+  readonly id: string
+  readonly promptHint: string
+  readonly term?: string
+  readonly adultOnly?: true
+}
+
+/** The picker catalogs (by `catalogId`) this floor sweeps beside person.
+ *  Exported because it is the SINGLE source of truth for two things that used
+ *  to be maintained by hand and drifted: which catalogs `getAdultOnlyEntries`
+ *  sweeps for the flag, and which analyzer keys `FLOORED_PICKER_KEYS` strips
+ *  flagged ids out of (a `photo-genre` swept for the flag but absent from the
+ *  strip list let `glamour-portrait` survive on a minor). */
+export const ADULT_SWEPT_CATALOG_IDS = ["styling", "mood", "pose", "photo-genre"] as const
+
+/** Membership form of the list above (the sweep does one lookup per catalog). */
+const ADULT_SWEPT_CATALOG_ID_SET: ReadonlySet<string> = new Set(ADULT_SWEPT_CATALOG_IDS)
+
+/** Flatten a catalog's options regardless of shape: single-dim catalogs carry
+ *  `options` directly, multi-dim ones carry `dimensions[].options` (mirrors
+ *  `applyDeny` in catalog-packs.ts, the other consumer that has to handle
+ *  both shapes). */
+function optionsOf(catalog: PickerCatalog): ReadonlyArray<PickerOption> {
+  if (catalog.kind === "single") return catalog.options ?? []
+  return (catalog.dimensions ?? []).flatMap((d) => d.options)
+}
+
+/** Every entry, across the swept catalogs, that carries the flag. Reads every
+ *  catalog through the pack-composed funnel — `getRegisteredPeople()` for
+ *  person, `getRegisteredPickerCatalogs()` for styling/mood/pose/photo-genre —
+ *  so a pack-added or pack-replaced entry is included. */
+export function getAdultOnlyEntries(): ReadonlyArray<AdultOnlyEntry> {
+  const catalogEntries = getRegisteredPickerCatalogs()
+    .filter((c) => ADULT_SWEPT_CATALOG_ID_SET.has(c.catalogId))
+    .flatMap(optionsOf)
+  const all: ReadonlyArray<AdultOnlyEntry> = [...getRegisteredPeople(), ...catalogEntries]
+  return all.filter((e) => e.adultOnly === true)
+}
+
+/** The set of flagged ids (fast membership for the collectors). */
+export function getAdultOnlyIds(): ReadonlySet<string> {
+  return new Set(getAdultOnlyEntries().map((e) => e.id))
+}
+
+/** Every full prompt-hint string a flagged entry can inject, lower-cased,
+ *  longest first — the backend policy strips text that contains any of them
+ *  (Layer 2), which is how flagged wording arriving inside free text (a
+ *  client-assembled seedPrompt) is caught.
+ *
+ *  `promptHint` ONLY, deliberately — `term` is analyzer/UI vocabulary
+ *  (compact-mode display), and `picker-catalogs.ts`'s composed-catalog
+ *  projection back-fills a `term` for EVERY option via `deriveTerm(label)`
+ *  when no explicit term was authored (e.g. "lounging", "cropped top",
+ *  "school uniform", "lying down"). Those short, generic derived terms are
+ *  exactly the kind of everyday word that collides with unrelated, benign
+ *  text and over-strips it. Assembled prompts and client seedPrompts are
+ *  built from HINTS, never from terms, so hints are the only strings that
+ *  can actually arrive verbatim in free text — terms don't need to be (and
+ *  must not be) swept here. */
+export function getAdultOnlyHintStrings(): ReadonlyArray<string> {
+  const out = new Set<string>()
+  for (const e of getAdultOnlyEntries()) {
+    if (e.promptHint) out.add(e.promptHint.toLowerCase())
+  }
+  return [...out].filter((s) => s.length >= 8).sort((a, b) => b.length - a.length)
+}
+
+/**
+ * Every full prompt-hint string that DESCRIBES A MINOR — the mirror of
+ * `getAdultOnlyHintStrings`, and the needle list for the TEXT signal below.
+ *
+ * Why a text signal exists at all: `isMinorAge` reads the structured picker
+ * value, and the P0 arrival path does not have one. A thin client can create a
+ * character row carrying only `{nodeId, name, projectId}` and send the picker
+ * selection as an already-assembled `seedPrompt`, so `row.person === null`
+ * while the prompt itself says "a young child around 5 years old". That client
+ * assembles the text FROM THESE HINTS, which is exactly why the catalog is the
+ * drift-proof needle list: a new minor age entry is swept the day it is added,
+ * with no second list to remember.
+ *
+ * Selection is DERIVED, never hand-listed: an `age` entry is a minor unless its
+ * id is in the `ADULT_AGE_IDS` allow-list (so a new age id is inside the floor
+ * by default — same ratchet as `isMinorAge`), plus every `type` entry named by
+ * `MINOR_IMPLYING_TYPE_IDS`. Read through the pack-composed funnel
+ * (`getRegisteredPeople()`), so a deployment pack's entries are swept too.
+ *
+ * `promptHint` ONLY — never `term` and never `label`, for the same reason
+ * `getAdultOnlyHintStrings` gives: `term` is short display vocabulary
+ * ("in their teens" as a compact chip) and the composed-catalog projection
+ * back-fills a derived `term` for every option, so terms collide with benign
+ * text. The `>= 8` filter drops `age-custom`'s empty hint (`""`), which would
+ * otherwise match every string ever written.
+ */
+let cachedMinorHints: ReadonlyArray<string> | null = null
+let cachedMinorHintSourceCount = -1
+export function getMinorAgeHintStrings(): ReadonlyArray<string> {
+  const people = getRegisteredPeople()
+  if (cachedMinorHints && cachedMinorHintSourceCount === people.length) return cachedMinorHints
+  const out = new Set<string>()
+  for (const e of people) {
+    const minorAge = e.dimension === "age" && !ADULT_AGE_IDS.has(e.id)
+    const minorType = e.dimension === "type" && MINOR_IMPLYING_TYPE_IDS.has(e.id)
+    if (!minorAge && !minorType) continue
+    if (e.promptHint) out.add(e.promptHint.toLowerCase())
+  }
+  cachedMinorHintSourceCount = people.length
+  cachedMinorHints = [...out].filter((s) => s.length >= 8).sort((a, b) => b.length - a.length)
+  return cachedMinorHints
+}
+
+function escapeReSource(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+/** One needle's regex source: the phrase's tokens — split on whitespace AND
+ *  hyphens — escaped and rejoined by `[\s-]+`, so it matches however the text
+ *  that carries it happened to be spaced or hyphenated. */
+function needleTokenSource(needle: string): string {
+  return needle
+    .trim()
+    .split(/[\s-]+/)
+    .filter((t) => t.length > 0)
+    .map(escapeReSource)
+    .join("[\\s-]+")
+}
+
+/**
+ * The word-bounded alternation SOURCE for a needle list — the one place both
+ * layers of the floor build their matcher, so they can never disagree about
+ * what "the same phrase" means.
+ *
+ * Two properties, both load-bearing:
+ *  - **Separator tolerance.** A catalog hint is authored with single spaces
+ *    ("very full bust"), but the free text that carries it is written by a
+ *    human or an LLM and arrives as "very-full bust" or "very   full    bust".
+ *    A literal alternation misses those, and a miss is a flagged phrase
+ *    reaching the provider on a minor's prompt. Each needle's tokens are
+ *    joined by `[\s-]+`, which requires AT LEAST one separator — so
+ *    "very fullbust" (no separator at all) is still not a match, and the
+ *    phrase can't silently widen into a substring rule.
+ *  - **Word boundaries.** `(?<![\w-])` / `(?![\w-])` keep a needle from
+ *    gluing onto an adjacent word's characters ("mesh tops" must survive a
+ *    "mesh top" needle).
+ *
+ * Ordering is the CALLER's: pass needles longest-first so the alternation
+ * consumes the longest match at a given position instead of leaving debris.
+ * Returns `null` when there is nothing to match (an empty list would otherwise
+ * compile to `(?:)`, which matches everywhere). Flags are the caller's too —
+ * `"i"` for a `.test()` instance, `"gi"` for one used with `String.replace`.
+ */
+export function buildNeedleAlternationSource(needles: ReadonlyArray<string>): string | null {
+  const alts = needles.map(needleTokenSource).filter((s) => s.length > 0)
+  if (alts.length === 0) return null
+  return `(?<![\\w-])(?:${alts.join("|")})(?![\\w-])`
+}
+
+/** Needle alternation over `getMinorAgeHintStrings()`, word-bounded on both
+ *  sides so a hint can only match a whole phrase. Deliberately NOT global:
+ *  this instance is only ever `.test()`ed, and a `/g` regex would carry
+ *  `lastIndex` across calls. Cached by needle count (packs are registered
+ *  before the first prompt is assembled). */
+let cachedMinorNeedleRe: RegExp | null = null
+let cachedMinorNeedleCount = -1
+function minorNeedleRegex(): RegExp | null {
+  const needles = getMinorAgeHintStrings()
+  if (cachedMinorNeedleRe && cachedMinorNeedleCount === needles.length) return cachedMinorNeedleRe
+  cachedMinorNeedleCount = needles.length
+  const src = buildNeedleAlternationSource(needles)
+  cachedMinorNeedleRe = src === null ? null : new RegExp(src, "i")
+  return cachedMinorNeedleRe
+}
+
+/**
+ * NUMBER-FIRST age shapes: the ones `buildAgeFragment` (person.ts) emits for a
+ * CUSTOM age ("N years old", "N year old", "N-year-old") and the catalog's own
+ * "2-3 years old" range (the FIRST number decides), plus the colloquial tails a
+ * human or an LLM writes instead — "12yo", "12 yo", "12 y.o.", "12 y/o",
+ * "12 yr old", "12-yr-old", "12yrs old", "12 years of age". The cut is `< 20`,
+ * the same boundary `isMinorAge` uses for `customAge` and the same one
+ * `buildAgeFragment` switches to "in their teens" at.
+ *
+ * Both boundaries are load-bearing. The LEADING one stops a match inside a
+ * larger token; the TRAILING one is what makes "a 5 year older sibling" a
+ * non-hit ("old" may not glue onto "older") and what stops "yo" from firing
+ * inside "12 young" or "12 yoga". Used via `matchAll`, which clones the regex
+ * rather than advancing this instance's `lastIndex`.
+ */
+const NUMERIC_AGE_RE =
+  /(?<![\w-])(\d{1,3})(?:\s*-\s*\d{1,3})?\s*-?\s*(?:years?\s*-?\s*old|yrs?\s*-?\s*old|y(?:\.\s*o\.?|\/o|o)|years?\s+of\s+age)(?![\w-])/gi
+
+/**
+ * AGE-FIRST shapes, where the number trails the word instead of leading it:
+ * "age 12", "aged 12", "at the age of 12". The leading boundary is what keeps
+ * "image 12" / "page 12" out (the `age` there is glued to a preceding word
+ * character), and the trailing one keeps "aged 12th" out.
+ */
+const PREFIXED_AGE_RE = /(?<![\w-])aged?\s+(?:of\s+)?(\d{1,3})(?![\w-])/gi
+
+/** Every rule that reads a NUMBER out of the text, each capturing the age in
+ *  group 1. Iterated together below so a new shape is one array entry. */
+const AGE_NUMBER_RULES: ReadonlyArray<RegExp> = [NUMERIC_AGE_RE, PREFIXED_AGE_RE]
+
+/** The one NON-numeric shape `buildAgeFragment` emits below 20 (`${n} years
+ *  old, in their teens`). Kept as its own rule rather than as a catalog term.
+ *  Separator-tolerant on the same terms as the needle alternation, so
+ *  "in  their  teens" and "in-their-teens" are the same phrase. */
+const IN_THEIR_TEENS_RE = /(?<![\w-])in[\s-]+their[\s-]+teens(?![\w-])/i
+
+/**
+ * True when free text describes a MINOR subject. Three rules, in order:
+ *   1. any minor-age / minor-implying-type prompt hint, word-bounded;
+ *   2. a numeric age below 20 in any shape `buildAgeFragment` emits;
+ *   3. the literal "in their teens".
+ *
+ * Deliberately NOT a bare-word check: "child", "teen", "kid" alone must never
+ * fire, or an adult prompt that merely MENTIONS a child ("a mother holding her
+ * child") would be floored — the spec's "adults are byte-identical" is a hard
+ * requirement, so every rule here is a full phrase or a bounded number.
+ *
+ * Pairs with `isMinorAge`, never replaces it: the structured picker value is
+ * the primary signal; this catches the same subject when only the assembled
+ * text survives.
+ */
+export function containsMinorAgeHint(text: string | null | undefined): boolean {
+  if (typeof text !== "string" || text.trim().length === 0) return false
+  const re = minorNeedleRegex()
+  if (re && re.test(text)) return true
+  for (const rule of AGE_NUMBER_RULES) {
+    for (const m of text.matchAll(rule)) {
+      const n = Number(m[1])
+      if (Number.isFinite(n) && n < 20) return true
+    }
+  }
+  return IN_THEIR_TEENS_RE.test(text)
+}
+
+/** The analyzer/import value keys the floor strips flagged ids out of:
+ *  `person` plus EVERY catalog the flag sweep reads. DERIVED, never
+ *  hand-listed — the hand-written version omitted `photo-genre` while the
+ *  sweep included it, so a minor kept `glamour-portrait`. The analyzer JSON is
+ *  keyed by picker type id (`describe-to-picker.ts`), which is the same string
+ *  as the catalog id, so this list IS the set of keys to visit. */
+export const FLOORED_PICKER_KEYS = ["person", ...ADULT_SWEPT_CATALOG_IDS] as const
+
+function stripIds(obj: Record<string, unknown>, drop: ReadonlySet<string>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "string") {
+      if (!drop.has(v)) out[k] = v
+    } else if (Array.isArray(v)) {
+      const kept = v.filter((x) => !(typeof x === "string" && drop.has(x)))
+      if (kept.length > 0) out[k] = kept
+    } else {
+      out[k] = v
+    }
+  }
+  return out
+}
+
+/** Analyzer / import post-filter: when the person value describes a minor,
+ *  remove every flagged id from the person, styling, pose and mood values.
+ *  Identity (same reference) for an adult. */
+export function applyMinorAgeFloorToPickerValues<T extends Record<string, unknown>>(values: T): T {
+  const person = values.person
+  if (!person || typeof person !== "object" || !isMinorAge(person as { age?: string; customAge?: number; type?: string })) return values
+  const drop = getAdultOnlyIds()
+  const out: Record<string, unknown> = { ...values }
+  for (const key of FLOORED_PICKER_KEYS) {
+    const v = out[key]
+    if (v && typeof v === "object" && !Array.isArray(v)) out[key] = stripIds(v as Record<string, unknown>, drop)
+  }
+  return out as T
+}

package/src/age-signal.ts

@@ -0,0 +1,36 @@
+/**
+ * LEAF MODULE — no runtime imports. person.ts and styling.ts import this;
+ * any catalog import here reopens the person → age-floor → picker-catalogs
+ * load-time cycle.
+ *
+ * `isMinorAge` is an ADULT ALLOW-LIST on purpose: a new age id added to the
+ * catalog is inside the floor until someone lists it here as adult. Custom
+ * numeric ages use the same boundary as `buildAgeFragment` in person.ts
+ * ("in their teens" below 20).
+ */
+
+export const ADULT_ONLY_FLAG = "adultOnly" as const
+
+/** Catalog age ids that describe an ADULT. Everything else is floored. */
+export const ADULT_AGE_IDS: ReadonlySet<string> = new Set([
+  "age-early-20s", "age-late-20s", "age-20s", "age-30s", "age-40s", "age-50s", "age-60s", "age-elderly",
+])
+
+/** Type entries whose hint reads as a child even with no age selected. */
+export const MINOR_IMPLYING_TYPE_IDS: ReadonlySet<string> = new Set([
+  "alice-wonderland", "dorothy-oz", "peter-pan", "magical-girl", "prince", "princess",
+])
+
+/** True when the picker value describes someone under 20, or a child-typed
+ *  subject with no age. An explicit adult age always wins. */
+export function isMinorAge(
+  value: { readonly age?: string; readonly customAge?: number; readonly type?: string } | null | undefined,
+): boolean {
+  if (!value) return false
+  const { age, customAge, type } = value
+  if (typeof age === "string" && age.length > 0) {
+    if (age === "age-custom") return !(typeof customAge === "number" && Number.isFinite(customAge) && customAge >= 20)
+    return !ADULT_AGE_IDS.has(age)
+  }
+  return typeof type === "string" && MINOR_IMPLYING_TYPE_IDS.has(type)
+}

package/src/atmosphere.ts

@@ -12,6 +12,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export interface Atmosphere {
   readonly id: string
@@ -73,7 +74,7 @@ const atmosphereById = new Map<string, Atmosphere>(ATMOSPHERES.map((a) => [a.id,
 
 export function getAtmosphere(id: string | undefined | null): Atmosphere | undefined {
   if (!id) return undefined
-  return atmosphereById.get(id)
+  return overlayEntry("atmosphere", id, atmosphereById.get(id))
 }
 
 export function getAtmosphereLabel(id: string | undefined | null, fallback?: string): string {

package/src/backdrop.ts

@@ -23,6 +23,7 @@
  */
 
 import { resolveTerm } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type BackdropCategory =
   | "solid"
@@ -105,7 +106,7 @@ const backdropById = new Map<string, Backdrop>(BACKDROPS.map((b) => [b.id, b]))
 
 export function getBackdrop(id: string | undefined | null): Backdrop | undefined {
   if (!id) return undefined
-  return backdropById.get(id)
+  return overlayEntry("backdrop", id, backdropById.get(id))
 }
 
 export function getBackdropLabel(id: string | undefined | null, fallback?: string): string {

package/src/camera-format.ts

@@ -10,6 +10,7 @@
  */
 
 import { resolveTerm } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export interface CameraFormat {
   readonly id: string
@@ -76,7 +77,7 @@ const formatById = new Map<string, CameraFormat>(CAMERA_FORMATS.map((f) => [f.id
 
 export function getCameraFormat(id: string | undefined | null): CameraFormat | undefined {
   if (!id) return undefined
-  return formatById.get(id)
+  return overlayEntry("camera-format", id, formatById.get(id))
 }
 
 export function getCameraFormatLabel(id: string | undefined | null, fallback?: string): string {

package/src/camera-motions.ts

@@ -8,6 +8,7 @@
  */
 
 import { resolveTerm, type PickerHintMode } from "./term.js"
+import { overlayEntry } from "./catalog-overlay.js"
 
 export type CameraMotionCategory =
   | "default"
@@ -605,7 +606,7 @@ const motionById = new Map<string, CameraMotion>(
 
 export function getCameraMotion(id: string | undefined | null): CameraMotion | undefined {
   if (!id) return undefined
-  return motionById.get(id)
+  return overlayEntry("camera-motions", id, motionById.get(id))
 }
 
 /** Human-readable label for the given motion id. Falls back to the id if unknown. */

package/src/catalog-id-guard.ts

@@ -0,0 +1,189 @@
+import { PICKER_CATALOGS, getPickerCatalog } from "./picker-catalogs.js"
+import { getRegisteredCatalogPacks, catalogPacksVersion } from "./catalog-packs.js"
+
+/**
+ * THE WALL: refuse work that names a catalog id this deployment does not
+ * offer.
+ *
+ * A curated deployment composes its picker catalogs from packs — entries
+ * removed, some rewritten. The browser is supposed to show only the composed
+ * catalogs and the resolvers are supposed to honor them, but neither of those
+ * is a SAFETY property: a stale tab, an imported workflow, a hand-made request
+ * or a bug in either layer can still hand the run path an id the deployment
+ * never offered. This module is what makes curation hold regardless — it is
+ * consulted at the one place every run passes (the orchestrator, after input
+ * overrides are merged), inside nested sub-workflows, and on the single-node
+ * routes that carry ids on the wire.
+ *
+ * INERT WITHOUT PACKS. A deployment that registers no catalog packs offers
+ * every base id, so there is nothing to refuse; the guard returns [] without
+ * walking. Mainline behavior is unchanged by construction.
+ *
+ * WHAT COUNTS AS AN ID FIELD. Every field a picker catalog declares — a
+ * single-dim catalog's `valueField`, a multi-dim catalog's `dimensions[].field`
+ * — plus the few resolver side-fields the catalogs do not declare (the pose
+ * sub-picks, the legacy direction keys). A field NOT in that table is never
+ * validated: `preText`, `customText`, `customAge`, free-text notes and the
+ * like are not ids and must not be refused. The table is derived from the
+ * BASE catalogs, so a field a `replace` pack dropped is still recognised as an
+ * id field and any value in it fails membership — which is the point.
+ */
+
+export interface ForeignCatalogId {
+  /** The node carrying the id (undefined for a request body). */
+  readonly nodeId?: string
+  readonly nodeType: string
+  readonly field: string
+  readonly id: string
+  readonly catalogId: string
+}
+
+/** Node-data fields that resolve against a catalog but are not declared by
+ *  it. Kept beside the guard so a new one is a one-line, reviewed addition. */
+const SIDE_FIELDS: ReadonlyArray<readonly [nodeType: string, field: string, catalogId: string]> = [
+  // pose.ts resolves all four sub-picks through getPosePromptHint
+  ["pose", "handPosition", "pose"],
+  ["pose", "bodyLean", "pose"],
+  ["pose", "headTilt", "pose"],
+  ["pose", "activity", "pose"],
+]
+
+/** Legacy `direction` wire keys still accepted by direction-registry.ts. */
+const DIRECTION_ALIASES: Readonly<Record<string, string>> = {
+  framingId: "framing",
+  framingAngleId: "framing",
+  lightingId: "lighting",
+  lensId: "lens",
+  cameraFormatId: "camera-format",
+}
+
+interface FieldTable {
+  /** nodeType → (field → catalogId) */
+  readonly byNodeType: ReadonlyMap<string, ReadonlyMap<string, string>>
+  /** field → catalogId, across every catalog (for direction/subject bodies) */
+  readonly byField: ReadonlyMap<string, string>
+}
+
+let tableMemo: FieldTable | null = null
+/** Derived from the BASE catalogs once — the field contract is code, not packs. */
+function fieldTable(): FieldTable {
+  if (tableMemo) return tableMemo
+  const byNodeType = new Map<string, Map<string, string>>()
+  const byField = new Map<string, string>()
+  const put = (nodeType: string, field: string, catalogId: string) => {
+    let m = byNodeType.get(nodeType)
+    if (!m) byNodeType.set(nodeType, (m = new Map()))
+    m.set(field, catalogId)
+    if (!byField.has(field)) byField.set(field, catalogId)
+  }
+  for (const c of PICKER_CATALOGS) {
+    if (c.valueField) put(c.nodeType, c.valueField, c.catalogId)
+    for (const d of c.dimensions ?? []) put(c.nodeType, d.field, c.catalogId)
+    for (const f of c.fields ?? []) put(c.nodeType, f, c.catalogId)
+  }
+  for (const [nodeType, field, catalogId] of SIDE_FIELDS) put(nodeType, field, catalogId)
+  for (const [alias, catalogId] of Object.entries(DIRECTION_ALIASES)) if (!byField.has(alias)) byField.set(alias, catalogId)
+  tableMemo = { byNodeType, byField }
+  return tableMemo
+}
+
+let idsMemo: { v: number; byCatalog: Map<string, ReadonlySet<string>> } | null = null
+/** Every id the COMPOSED catalog offers, across options and all dimensions. */
+function composedIds(catalogId: string): ReadonlySet<string> {
+  const v = catalogPacksVersion()
+  if (!idsMemo || idsMemo.v !== v) idsMemo = { v, byCatalog: new Map() }
+  const hit = idsMemo.byCatalog.get(catalogId)
+  if (hit) return hit
+  const cat = getPickerCatalog(catalogId)
+  const ids = new Set<string>()
+  for (const o of cat?.options ?? []) ids.add(o.id)
+  for (const d of cat?.dimensions ?? []) for (const o of d.options) ids.add(o.id)
+  idsMemo.byCatalog.set(catalogId, ids)
+  return ids
+}
+
+function values(v: unknown): string[] {
+  if (typeof v === "string") return v ? [v] : []
+  if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string" && x.length > 0)
+  return []
+}
+
+/** The guard is only meaningful once something curates. */
+export function catalogGuardActive(): boolean {
+  return getRegisteredCatalogPacks().length > 0
+}
+
+function checkRecord(
+  nodeType: string,
+  nodeId: string | undefined,
+  data: Record<string, unknown>,
+  fields: ReadonlyMap<string, string>,
+  out: ForeignCatalogId[],
+): void {
+  for (const [field, catalogId] of fields) {
+    const raw = data[field]
+    if (raw === undefined || raw === null) continue
+    const offered = composedIds(catalogId)
+    for (const id of values(raw)) {
+      if (!offered.has(id)) out.push({ nodeId, nodeType, field, id, catalogId })
+    }
+  }
+}
+
+/**
+ * Walk a graph. Parameter nodes are checked against their own catalog's
+ * fields; consumer nodes (generate-image, image-to-video, …) carry folded
+ * `direction` / `subject` records whose keys are the same field names, so
+ * those are checked against the global field table.
+ */
+export function findForeignCatalogIds(
+  nodes: ReadonlyArray<{ id?: unknown; type?: unknown; data?: unknown }> | undefined,
+): ForeignCatalogId[] {
+  if (!catalogGuardActive() || !nodes) return []
+  const table = fieldTable()
+  const out: ForeignCatalogId[] = []
+  for (const node of nodes) {
+    const type = typeof node.type === "string" ? node.type : ""
+    const nodeId = typeof node.id === "string" ? node.id : undefined
+    const data = node.data && typeof node.data === "object" ? (node.data as Record<string, unknown>) : null
+    if (!type || !data) continue
+    const own = table.byNodeType.get(type)
+    if (own) checkRecord(type, nodeId, data, own, out)
+    for (const key of ["direction", "subject"] as const) {
+      const rec = data[key]
+      if (rec && typeof rec === "object" && !Array.isArray(rec)) {
+        checkRecord(type, nodeId, rec as Record<string, unknown>, table.byField, out)
+      }
+    }
+  }
+  return out
+}
+
+/** A request body's `direction` / `subject` records (the single-node routes). */
+export function findForeignCatalogIdsInBody(
+  nodeType: string,
+  body: { direction?: unknown; subject?: unknown } | undefined,
+): ForeignCatalogId[] {
+  if (!catalogGuardActive() || !body) return []
+  const table = fieldTable()
+  const out: ForeignCatalogId[] = []
+  for (const key of ["direction", "subject"] as const) {
+    const rec = body[key]
+    if (rec && typeof rec === "object" && !Array.isArray(rec)) {
+      checkRecord(nodeType, undefined, rec as Record<string, unknown>, table.byField, out)
+    }
+  }
+  return out
+}
+
+/** One line, naming every offender — the audit trail and the user message. */
+export function foreignCatalogIdMessage(found: readonly ForeignCatalogId[]): string {
+  const parts = [...new Set(found.map((f) => `${f.field}="${f.id}"`))]
+  return `This deployment does not offer the following picker value${parts.length === 1 ? "" : "s"}: ${parts.join(", ")}. Choose from the options shown in the picker.`
+}
+
+/** Test hook. */
+export function __resetCatalogIdGuardForTests(): void {
+  tableMemo = null
+  idsMemo = null
+}