@nodaro/prompts 1.7.3 → 1.8.0

package/src/parameter-prompt-hint.ts

@@ -21,14 +21,14 @@ export type { HintNodeLike, HintEdgeLike, HintGraphContext }
 
 import { buildFramingHints } from "./framing.js"
 import { buildLightingHints } from "./lighting.js"
-import { getLensPromptHint } from "./lens.js"
-import { getCameraFormatPromptHint } from "./camera-format.js"
-import { getColorLookPromptHint } from "./color-look.js"
+import { getLensPromptHint, getLensTerm } from "./lens.js"
+import { getCameraFormatPromptHint, getCameraFormatTerm } from "./camera-format.js"
+import { getColorLookPromptHint, getColorLookTerm } from "./color-look.js"
 import { buildAtmosphereHints } from "./atmosphere.js"
 import { buildActionFxHints } from "./action-fx.js"
-import { getStylePromptHint } from "./style.js"
-import { getSettingPromptHint } from "./setting.js"
-import { getLoopSubjectPromptHint } from "./loop-subject.js"
+import { getStylePromptHint, getStyleTerm } from "./style.js"
+import { getSettingPromptHint, getSettingTerm } from "./setting.js"
+import { getLoopSubjectPromptHint, getLoopSubjectTerm } from "./loop-subject.js"
 import { buildPersonHints } from "./person.js"
 import { buildMoodHints } from "./mood.js"
 import { buildPoseHints } from "./pose.js"
@@ -42,21 +42,23 @@ import { getAnimal } from "@nodaro/shared"
 import { getVehicle } from "@nodaro/shared"
 import { getWeapon } from "@nodaro/shared"
 import { getFurniture } from "@nodaro/shared"
-import { getPhotoGenrePromptHint } from "./photo-genre.js"
-import { getBackdropPromptHint } from "./backdrop.js"
+import { getPhotoGenrePromptHint, getPhotoGenreTerm } from "./photo-genre.js"
+import { getBackdropPromptHint, getBackdropTerm } from "./backdrop.js"
 import { buildHeldPropHints } from "./held-prop.js"
 import { buildPhotographerHints } from "./photographer.js"
 import { buildAestheticHints } from "./aesthetic.js"
-import { getEraPromptHint } from "./era.js"
+import { getEraPromptHint, getEraTerm } from "./era.js"
 import { buildExposureHints } from "./exposure-settings.js"
-import { getRenderQualityPromptHint } from "./render-quality.js"
-import { getCompositionEffectPromptHint } from "./composition-effects.js"
+import { getRenderQualityPromptHint, getRenderQualityTerm } from "./render-quality.js"
+import { getCompositionEffectPromptHint, getCompositionEffectTerm } from "./composition-effects.js"
 import { buildPostProcessHints } from "./post-process-effects.js"
 import { buildMusicGenreHints } from "./music-genre.js"
 import { buildMusicMoodHints } from "./music-mood.js"
 import { buildInstrumentationHints } from "./instrumentation.js"
 import { buildVoiceCharacterHints } from "./voice-character.js"
 import { buildVoiceDeliveryHints } from "./voice-delivery.js"
+import { getPickerCatalog } from "./picker-catalogs.js"
+import { deriveTerm, resolveTerm, type PickerHintMode } from "./term.js"
 
 
 function asStr(v: unknown): string {
@@ -88,21 +90,87 @@ function withCustomText(data: Record<string, unknown>, mainHint: string): string
   return fragments.join(", ")
 }
 
+/**
+ * The node-level hint mode a picker declares via `data.hintMode`.
+ *
+ * Only the two documented values count; anything else (a stale value, a typo,
+ * a non-string) is treated as UNDECLARED and falls back — to the inherited
+ * mode when the node is resolved as an upstream input, and to `"full"`
+ * otherwise. Compact is opt-in, so an unrecognized value can never silently
+ * shorten a prompt.
+ */
+function readHintMode(data: Record<string, unknown>): PickerHintMode | undefined {
+  const raw = data.hintMode
+  return raw === "compact" || raw === "full" ? raw : undefined
+}
+
+/** Pick the full-hint or the compact-term getter for the active mode. */
+function byMode<T>(mode: PickerHintMode, full: T, compact: T): T {
+  return mode === "compact" ? compact : full
+}
+
+/**
+ * The compact fragment for an OBJECT-entity entry (animal / vehicle / weapon /
+ * furniture). Those catalogs carry no `promptHint` of their own — the full
+ * fragment is synthesized as "featuring a {label}, {description}" — so the
+ * compact form is the authored `term` when there is one and the derived label
+ * otherwise (a concrete object's label IS its trade term). The framing verb
+ * ("featuring a", "with a") belongs to the HINT; a term drops bare into
+ * whatever sentence the consumer is building, and "the object is in the scene"
+ * is precisely what these four nodes mean.
+ *
+ * The fallback MUST be `deriveTerm` and not a bare `toLowerCase()`: it is the
+ * same fallback `objectOptions` uses to build the `/v1/catalogs` projection,
+ * so a parenthetical label ("Rifle (bolt-action)") must strip identically here
+ * or the injected fragment and the projected term would disagree.
+ *
+ * `term` is read structurally because it is being added to the shared entity
+ * interfaces separately; this stays correct before and after that lands.
+ */
+function objectEntityTerm(entry: { readonly label: string }): string {
+  return (entry as { term?: string }).term ?? deriveTerm(entry.label)
+}
+
 /**
  * Dispatch by parameter-node type to its prompt-hint string. For camera-motion,
  * pass `ctx` to include the composed start/end clauses; otherwise only the
  * bare motion description is returned.
+ *
+ * VERBOSITY — a picker node may set `data.hintMode` to `"compact"` to inject
+ * its short professional `term` ("whip pan left", "hard cut") instead of the
+ * long `promptHint`. Absent, or any unrecognized value, means `"full"`, whose
+ * output is byte-identical to what this function returned before hint modes
+ * existed. ONLY the base catalog fragment swaps: `preText`/`postText`, the
+ * transition / camera-motion / character-fx timing and start-state/end-state
+ * clauses, multi-pick joining and multi-dimension composition are emitted the
+ * same way in both modes.
  */
 export function getParameterPromptHint(
   node: HintNodeLike | undefined,
   ctx?: HintGraphContext,
+): string {
+  return resolveParameterHint(node, ctx)
+}
+
+/**
+ * The dispatch body. `inherited` carries the mode DOWN into the nodes wired to
+ * a composer's `startState` / `endState` handles, so a compact transition
+ * composes compact start/end clauses rather than mixing a term with two
+ * paragraphs. A node that declares its own `hintMode` still wins over what it
+ * inherits.
+ */
+function resolveParameterHint(
+  node: HintNodeLike | undefined,
+  ctx?: HintGraphContext,
+  inherited?: PickerHintMode,
 ): string {
   if (!node?.type) return ""
   const data = (node.data ?? {}) as Record<string, unknown>
+  const mode: PickerHintMode = readHintMode(data) ?? inherited ?? "full"
 
   if (node.type === "camera-motion") {
     const motionId = asStr(data.cameraMotion) || undefined
-    if (!ctx) return withCustomText(data, composeCameraMotionHintFromConnections(motionId, [], []))
+    if (!ctx) return withCustomText(data, composeCameraMotionHintFromConnections(motionId, [], [], mode))
     const startHints: string[] = []
     const endHints: string[] = []
     for (const edge of ctx.edges) {
@@ -111,13 +179,14 @@ export function getParameterPromptHint(
       if (!src) continue
       // Pass no ctx for nested resolution: startState/endState inputs are
       // themselves parameter nodes (framing/tone/etc.) that don't need graph
-      // context, and avoiding recursion keeps the walk cycle-safe.
-      const hint = getParameterPromptHint(src)
+      // context, and avoiding recursion keeps the walk cycle-safe. The mode
+      // rides down so the composed clause stays at one level of detail.
+      const hint = resolveParameterHint(src, undefined, mode)
       if (!hint) continue
       if (edge.targetHandle === "startState") startHints.push(hint)
       else if (edge.targetHandle === "endState") endHints.push(hint)
     }
-    return withCustomText(data, composeCameraMotionHintFromConnections(motionId, startHints, endHints))
+    return withCustomText(data, composeCameraMotionHintFromConnections(motionId, startHints, endHints, mode))
   }
 
   if (node.type === "transition") {
@@ -132,7 +201,7 @@ export function getParameterPromptHint(
       intensity: asStr(data.intensity) as TransitionIntensity | undefined,
     }
     if (!ctx) {
-      return withCustomText(data, composeTransitionHintFromConnections(transitionId, [], [], timing))
+      return withCustomText(data, composeTransitionHintFromConnections(transitionId, [], [], timing, mode))
     }
     const startHints: string[] = []
     const endHints: string[] = []
@@ -140,12 +209,12 @@ export function getParameterPromptHint(
       if (edge.target !== node.id) continue
       const src = ctx.nodes.find((n) => n.id === edge.source)
       if (!src) continue
-      const hint = getParameterPromptHint(src) // no ctx — cycle-safe
+      const hint = resolveParameterHint(src, undefined, mode) // no ctx — cycle-safe
       if (!hint) continue
       if      (edge.targetHandle === "startState") startHints.push(hint)
       else if (edge.targetHandle === "endState")   endHints.push(hint)
     }
-    return withCustomText(data, composeTransitionHintFromConnections(transitionId, startHints, endHints, timing))
+    return withCustomText(data, composeTransitionHintFromConnections(transitionId, startHints, endHints, timing, mode))
   }
 
   if (node.type === "character-fx") {
@@ -160,7 +229,7 @@ export function getParameterPromptHint(
       intensity: asStr(data.intensity) as CharacterFxIntensity | undefined,
     }
     if (!ctx) {
-      return withCustomText(data, composeCharacterFxHintFromConnections(effectId, [], timing))
+      return withCustomText(data, composeCharacterFxHintFromConnections(effectId, [], timing, mode))
     }
     const targetNames: string[] = []
     for (const edge of ctx.edges) {
@@ -171,106 +240,149 @@ export function getParameterPromptHint(
       const name = extractCharacterRefName(src)
       if (name) targetNames.push(name)
     }
-    return withCustomText(data, composeCharacterFxHintFromConnections(effectId, targetNames, timing))
+    return withCustomText(data, composeCharacterFxHintFromConnections(effectId, targetNames, timing, mode))
   }
 
-  switch (node.type) {
+  const base = resolveBaseHint(node.type, data, mode)
+  if (base) return base
+  // Pack-extend fallback: a single-dim pack entry the per-catalog getter (which
+  // reads the frozen base array) can't resolve. Resolve it against the
+  // registered (pack-composed) catalog's options. Composition already resolved
+  // `PickerOption.term`; `resolveTerm` is idempotent over a resolved option and
+  // is called anyway so a pack option that reached this array by some other
+  // route still injects SOMETHING in compact mode rather than `undefined`.
+  const cat = getPickerCatalog(node.type)
+  if (cat?.kind === "single" && cat.valueField) {
+    const id = typeof data[cat.valueField] === "string" ? (data[cat.valueField] as string) : ""
+    const opt = cat.options?.find((o) => o.id === id)
+    if (opt) return byMode(mode, opt.promptHint, resolveTerm(opt))
+  }
+  return base
+}
+
+/**
+ * Base (upstream) hint dispatch by node type — the per-catalog getters read the
+ * frozen base arrays. Pack-added single-dim ids are resolved by the caller
+ * against the registered (pack-composed) catalog.
+ *
+ * `mode` selects the base fragment only: the compact `get<Name>Term` getter /
+ * `build<Name>Terms` builder instead of the verbose one. The `withCustomText`
+ * wrapper, the builders' own pre/post composition, and the free-text node
+ * types (tone / style-guide / text-prompt — user prose, not catalog copy) are
+ * identical in both modes.
+ */
+function resolveBaseHint(
+  type: string,
+  data: Record<string, unknown>,
+  mode: PickerHintMode = "full",
+): string {
+  switch (type) {
     case "framing":
-      return withCustomText(data, buildFramingHints(data).join(", "))
+      return withCustomText(data, buildFramingHints(data, false, mode).join(", "))
     case "lighting":
-      return withCustomText(data, buildLightingHints(data).join(", "))
+      return withCustomText(data, buildLightingHints(data, mode).join(", "))
     case "lens":
-      return withCustomText(data, getLensPromptHint(asStr(data.lens)))
+      return withCustomText(data, byMode(mode, getLensPromptHint, getLensTerm)(asStr(data.lens)))
     case "camera-format":
-      return withCustomText(data, getCameraFormatPromptHint(asStr(data.cameraFormat)))
+      return withCustomText(data, byMode(mode, getCameraFormatPromptHint, getCameraFormatTerm)(asStr(data.cameraFormat)))
     case "color-look":
-      return withCustomText(data, getColorLookPromptHint(asStr(data.colorLook)))
+      return withCustomText(data, byMode(mode, getColorLookPromptHint, getColorLookTerm)(asStr(data.colorLook)))
 
     // build*Hints in music-* / voice-* / mood / person / etc. compose
     // preText/postText internally — bypass the wrapper to avoid double-
     // composition.
     case "music-genre":
-      return buildMusicGenreHints((data ?? {}) as Parameters<typeof buildMusicGenreHints>[0])
+      return buildMusicGenreHints((data ?? {}) as Parameters<typeof buildMusicGenreHints>[0], mode)
     case "music-mood":
-      return buildMusicMoodHints((data ?? {}) as Parameters<typeof buildMusicMoodHints>[0])
+      return buildMusicMoodHints((data ?? {}) as Parameters<typeof buildMusicMoodHints>[0], mode)
     case "instrumentation":
-      return buildInstrumentationHints((data ?? {}) as Parameters<typeof buildInstrumentationHints>[0])
+      return buildInstrumentationHints((data ?? {}) as Parameters<typeof buildInstrumentationHints>[0], mode)
     case "voice-character":
-      return buildVoiceCharacterHints((data ?? {}) as Parameters<typeof buildVoiceCharacterHints>[0])
+      return buildVoiceCharacterHints((data ?? {}) as Parameters<typeof buildVoiceCharacterHints>[0], mode)
     case "voice-delivery":
-      return buildVoiceDeliveryHints((data ?? {}) as Parameters<typeof buildVoiceDeliveryHints>[0])
+      return buildVoiceDeliveryHints((data ?? {}) as Parameters<typeof buildVoiceDeliveryHints>[0], mode)
     case "person":
-      return buildPersonHints(data).join(", ")
+      return buildPersonHints(data, mode).join(", ")
     case "mood":
-      return buildMoodHints(data).join(", ")
+      return buildMoodHints(data, mode).join(", ")
     case "pose":
-      return buildPoseHints(data).join(", ")
+      return buildPoseHints(data, mode).join(", ")
     case "styling":
-      return buildStylingHints(data).join(", ")
+      return buildStylingHints(data, mode).join(", ")
 
     case "atmosphere":
-      return withCustomText(data, buildAtmosphereHints(data.atmosphere).join(", "))
+      return withCustomText(data, buildAtmosphereHints(data.atmosphere, mode).join(", "))
     case "action-fx":
-      return withCustomText(data, buildActionFxHints(data.actionFx).join(", "))
+      return withCustomText(data, buildActionFxHints(data.actionFx, mode).join(", "))
     case "style":
-      return withCustomText(data, getStylePromptHint(asStr(data.style)))
+      return withCustomText(data, byMode(mode, getStylePromptHint, getStyleTerm)(asStr(data.style)))
     case "setting":
-      return withCustomText(data, getSettingPromptHint(asStr(data.setting)))
+      return withCustomText(data, byMode(mode, getSettingPromptHint, getSettingTerm)(asStr(data.setting)))
     case "loop-subject":
-      return withCustomText(data, getLoopSubjectPromptHint(asStr(data.loopSubject)))
+      return withCustomText(data, byMode(mode, getLoopSubjectPromptHint, getLoopSubjectTerm)(asStr(data.loopSubject)))
     case "material":
-      return withCustomText(data, buildMaterialHints(data.material))
+      return withCustomText(data, buildMaterialHints(data.material, mode))
     case "animal": {
       const animal = getAnimal(asStr(data.animal))
       return withCustomText(
         data,
-        animal ? `featuring a ${animal.label.toLowerCase()}, ${animal.description}` : "",
+        animal
+          ? byMode(mode, `featuring a ${animal.label.toLowerCase()}, ${animal.description}`, objectEntityTerm(animal))
+          : "",
       )
     }
     case "vehicle": {
       const vehicle = getVehicle(asStr(data.vehicle))
       return withCustomText(
         data,
-        vehicle ? `featuring a ${vehicle.label.toLowerCase()}, ${vehicle.description}` : "",
+        vehicle
+          ? byMode(mode, `featuring a ${vehicle.label.toLowerCase()}, ${vehicle.description}`, objectEntityTerm(vehicle))
+          : "",
       )
     }
     case "weapon": {
       const weapon = getWeapon(asStr(data.weapon))
       return withCustomText(
         data,
-        weapon ? `with a ${weapon.label.toLowerCase()}, ${weapon.description}` : "",
+        weapon
+          ? byMode(mode, `with a ${weapon.label.toLowerCase()}, ${weapon.description}`, objectEntityTerm(weapon))
+          : "",
       )
     }
     case "furniture": {
       const furniture = getFurniture(asStr(data.furniture))
       return withCustomText(
         data,
-        furniture ? `including a ${furniture.label.toLowerCase()}, ${furniture.description}` : "",
+        furniture
+          ? byMode(mode, `including a ${furniture.label.toLowerCase()}, ${furniture.description}`, objectEntityTerm(furniture))
+          : "",
       )
     }
     case "photo-genre":
-      return withCustomText(data, getPhotoGenrePromptHint(asStr(data.photoGenre)))
+      return withCustomText(data, byMode(mode, getPhotoGenrePromptHint, getPhotoGenreTerm)(asStr(data.photoGenre)))
     case "backdrop":
-      return withCustomText(data, getBackdropPromptHint(asStr(data.backdrop)))
+      return withCustomText(data, byMode(mode, getBackdropPromptHint, getBackdropTerm)(asStr(data.backdrop)))
     case "held-prop":
-      return withCustomText(data, buildHeldPropHints(data.heldProp).join(", "))
+      return withCustomText(data, buildHeldPropHints(data.heldProp, mode).join(", "))
     case "photographer":
-      return withCustomText(data, buildPhotographerHints(data.photographer))
+      return withCustomText(data, buildPhotographerHints(data.photographer, mode))
     case "aesthetic":
-      return withCustomText(data, buildAestheticHints(data.aesthetic))
+      return withCustomText(data, buildAestheticHints(data.aesthetic, mode))
     case "era":
-      return withCustomText(data, getEraPromptHint(asStr(data.era)))
+      return withCustomText(data, byMode(mode, getEraPromptHint, getEraTerm)(asStr(data.era)))
     case "temporal":
-      return withCustomText(data, buildTemporalHints(data).join(", "))
+      return withCustomText(data, buildTemporalHints(data, mode).join(", "))
     case "exposure-settings":
-      return withCustomText(data, buildExposureHints(data).join(", "))
+      return withCustomText(data, buildExposureHints(data, mode).join(", "))
     case "render-quality":
-      return withCustomText(data, getRenderQualityPromptHint(asStr(data.renderQuality)))
+      return withCustomText(data, byMode(mode, getRenderQualityPromptHint, getRenderQualityTerm)(asStr(data.renderQuality)))
     case "composition-effects":
-      return withCustomText(data, getCompositionEffectPromptHint(asStr(data.compositionEffect)))
+      return withCustomText(data, byMode(mode, getCompositionEffectPromptHint, getCompositionEffectTerm)(asStr(data.compositionEffect)))
     case "post-process-effects":
-      return withCustomText(data, buildPostProcessHints(data.postProcess).join(", "))
+      return withCustomText(data, buildPostProcessHints(data.postProcess, mode).join(", "))
 
+    // Free text authored by the user, not catalog copy — there is no shorter
+    // professional form to swap in, so these are identical in both modes.
     case "tone":
       return asStr(data.tone).trim()
     case "style-guide":

package/src/person-packs.ts

@@ -0,0 +1,182 @@
+import {
+  PEOPLE,
+  PERSON_DIMENSION_ORDER,
+  PERSON_DIMENSION_LABELS,
+  PERSON_FIELD_BY_DIMENSION,
+  type Person,
+} from "./person.js"
+import { registerCatalogPack, getRegisteredCatalogPacks } from "./catalog-packs.js"
+import type { PickerDimension, PickerOption } from "./picker-catalogs.js"
+import { resolveTerm } from "./term.js"
+import { setRegisteredPersonPackFields } from "@nodaro/shared"
+
+/**
+ * A person-pack entry. Pack dimensions are new keys OUTSIDE the closed
+ * `PersonDimension` union, so `dimension` is widened to `string`.
+ */
+export type RegisteredPersonEntry = Omit<Person, "dimension"> & { dimension: string }
+
+export interface PersonPack {
+  readonly id: string
+  readonly entries: readonly RegisteredPersonEntry[]
+  // Pack dimensions are single-select in Phase 0: the selection limit still
+  // comes from `getPersonDimensionLimit`, which only knows the base
+  // `PersonDimension` union (a pack key resolves to 1), so a per-dimension
+  // `maxSelected` would be silently ignored. Omitted rather than accepted-and-
+  // dropped; add it here AND in the limit lookup together when multi-select
+  // pack dimensions are wired.
+  readonly dimensions?: readonly { dimension: string; field: string; label: string }[]
+  readonly sidecars?: Parameters<typeof registerCatalogPack>[0]["sidecars"]
+  readonly exemptSidecarLocales?: Parameters<typeof registerCatalogPack>[0]["exemptSidecarLocales"]
+}
+
+let personPacks: PersonPack[] = []
+let version = 0
+
+/**
+ * Push the aggregate of every registered person pack's dimension data-field
+ * names into `@nodaro/shared`'s content-free registry, so
+ * `getParameterValue(data, "person")` resolves a pack dimension in the
+ * `{PersonLabel}` field-mapping fallback (G4). shared never imports prompts —
+ * the field list is pushed in here. Empty aggregate ⇒ mainline identity.
+ */
+function syncPersonPackFields(): void {
+  setRegisteredPersonPackFields(
+    personPacks.flatMap((p) => (p.dimensions ?? []).map((d) => d.field)),
+  )
+}
+
+export function registerPersonPack(pack: PersonPack): void {
+  if (personPacks.some((p) => p.id === pack.id)) throw new Error(`duplicate person pack id "${pack.id}"`)
+  personPacks = [...personPacks, pack]
+  version++
+  // Fan out to the generic catalog seam so enumeration/projection/localization
+  // reflect the person pack too. Build one PickerDimension per new field.
+  const dimByKey = new Map((pack.dimensions ?? []).map((d) => [d.dimension, d]))
+  const byField = new Map<string, { field: string; label: string; options: PickerOption[] }>()
+  for (const e of pack.entries) {
+    const dim = dimByKey.get(e.dimension)
+    if (!dim) throw new Error(`person pack "${pack.id}" entry "${e.id}" references undeclared dimension "${e.dimension}"`)
+    const opt: PickerOption = {
+      id: e.id,
+      label: e.label,
+      description: e.description,
+      category: e.group,
+      promptHint: e.promptHint,
+      term: resolveTerm(e),
+    }
+    const existing = byField.get(dim.field)
+    if (existing) existing.options.push(opt)
+    else byField.set(dim.field, { field: dim.field, label: dim.label, options: [opt] })
+  }
+  registerCatalogPack({
+    id: pack.id,
+    catalogId: "person",
+    mode: "extend",
+    dimensions: [...byField.values()] as PickerDimension[],
+    sidecars: pack.sidecars,
+    exemptSidecarLocales: pack.exemptSidecarLocales,
+  })
+  syncPersonPackFields()
+}
+
+export function resetPersonPacks(): void {
+  personPacks = []
+  version++
+  syncPersonPackFields()
+}
+export function personPacksVersion(): number {
+  return version
+}
+
+/** Reverse of the registered dimension→field map, for reconstructing entries
+ *  from a projected (field-keyed) catalog pack back into Person shape. */
+function dimensionByField(): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {}
+  const map = getRegisteredPersonFieldByDimension()
+  for (const dim of Object.keys(map)) out[map[dim]] = dim
+  return out
+}
+
+/** Best-effort reconstruction of Person entries from a pack's projected
+ *  (PickerDimension) list. `shortLabel`/swatches are absent in the projection
+ *  and fall back at render time; the safety-critical id-set is exact. */
+function personEntriesFromDims(
+  dims: ReadonlyArray<{
+    field: string
+    options: ReadonlyArray<{
+      id: string
+      label: string
+      description?: string
+      category?: string
+      promptHint: string
+    }>
+  }>,
+): RegisteredPersonEntry[] {
+  const byField = dimensionByField()
+  const out: RegisteredPersonEntry[] = []
+  for (const d of dims) {
+    const dimension = byField[d.field] ?? d.field
+    for (const o of d.options) {
+      out.push({
+        id: o.id,
+        label: o.label,
+        description: o.description ?? "",
+        group: o.category,
+        promptHint: o.promptHint,
+        dimension,
+      } as RegisteredPersonEntry)
+    }
+  }
+  return out
+}
+
+/**
+ * The registered/composed person taxonomy: base `PEOPLE` folded with every
+ * `catalogId:"person"` CatalogPack in registration order (the SAME registry
+ * `composePickerCatalogs` folds for `/v1/catalogs` + MCP). `extend` appends the
+ * pack's full Person entries, `deny` removes `denyIds`, `replace` swaps to a
+ * reconstruction of the vendored catalog. This is the single funnel the
+ * picker-ui grids read, so a deploy's deny/replace curation hides base entries
+ * in the picker exactly as it hides them in the catalogs projection.
+ */
+export function getRegisteredPeople(): readonly RegisteredPersonEntry[] {
+  const personCatalogPacks = getRegisteredCatalogPacks().filter((p) => p.catalogId === "person")
+  // Mainline identity on the empty path, matching every sibling getter below
+  // (`extra.length === 0 ? BASE : [...]`): with no person packs registered this
+  // returns the base PEOPLE reference ITSELF, not a copy — the overlay
+  // boot-smoke pins "inert boot" on exactly that identity, and an
+  // unconditional copy here is what broke the combined tree after two
+  // separately-green merges.
+  if (personCatalogPacks.length === 0) return PEOPLE
+  let people: RegisteredPersonEntry[] = [...PEOPLE]
+  const packsById = new Map(personPacks.map((p) => [p.id, p]))
+  for (const pack of personCatalogPacks) {
+    if (pack.mode === "extend") {
+      // Prefer full Person entries from the source person-pack; fall back to
+      // reconstructing from the projected dimensions for a direct extend pack.
+      const src = packsById.get(pack.id)
+      people = src
+        ? [...people, ...src.entries]
+        : [...people, ...personEntriesFromDims(pack.dimensions ?? [])]
+    } else if (pack.mode === "deny") {
+      const deny = new Set(pack.denyIds ?? [])
+      people = people.filter((e) => !deny.has(e.id))
+    } else if (pack.mode === "replace" && pack.catalog) {
+      people = personEntriesFromDims(pack.catalog.dimensions ?? [])
+    }
+  }
+  return people
+}
+export function getRegisteredPersonDimensionOrder(): readonly string[] {
+  const extra = personPacks.flatMap((p) => (p.dimensions ?? []).map((d) => d.dimension))
+  return extra.length === 0 ? PERSON_DIMENSION_ORDER : [...PERSON_DIMENSION_ORDER, ...extra]
+}
+export function getRegisteredPersonFieldByDimension(): Readonly<Record<string, string>> {
+  const extra = personPacks.flatMap((p) => (p.dimensions ?? []).map((d) => [d.dimension, d.field] as const))
+  return extra.length === 0 ? PERSON_FIELD_BY_DIMENSION : { ...PERSON_FIELD_BY_DIMENSION, ...Object.fromEntries(extra) }
+}
+export function getRegisteredPersonDimensionLabels(): Readonly<Record<string, string>> {
+  const extra = personPacks.flatMap((p) => (p.dimensions ?? []).map((d) => [d.dimension, d.label] as const))
+  return extra.length === 0 ? PERSON_DIMENSION_LABELS : { ...PERSON_DIMENSION_LABELS, ...Object.fromEntries(extra) }
+}