@nodaro/shared 2.8.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.8.0",
+  "version": "2.11.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

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

@@ -0,0 +1,14 @@
+import { describe, it, expectTypeOf } from "vitest"
+import type { ProjectedCatalog } from "../catalog-projection.js"
+
+describe("ProjectedCatalog wire shape (Apache boundary)", () => {
+  it("is tag-free and policy-free (the deferred CatalogPolicy never crosses the wire)", () => {
+    // @ts-expect-error — no `tags` field may exist on the projection shape
+    const _t: ProjectedCatalog["tags"] = undefined
+    // @ts-expect-error — no policy field may exist either
+    const _p: ProjectedCatalog["policy"] = undefined
+    void _t
+    void _p
+    expectTypeOf<ProjectedCatalog>().toHaveProperty("catalogId")
+  })
+})

package/src/__tests__/default-video-provider.test.ts

@@ -23,7 +23,7 @@ describe("DEFAULT_VIDEO_PROVIDER", () => {
   })
 
   it("nothing-specified request resolves to the cheapest seeded composite", () => {
-    const sel = applyDefaultVideoSelection({})
+    const sel = applyDefaultVideoSelection<number>({})
     const id = buildVideoCreditModelIdentifier(
       sel.provider, sel.duration, undefined, "image-to-video", undefined, undefined, false,
     )

package/src/__tests__/llm-models.test.ts

@@ -392,10 +392,11 @@ describe("LLM_FEATURE_DEFAULTS", () => {
     "translate",
     "image-critic",
     "pick-best-llm",
+    "workflow-copilot",
   ]
 
-  it("has entries for all 16 features", () => {
-    expect(Object.keys(LLM_FEATURE_DEFAULTS)).toHaveLength(16)
+  it("has entries for all 17 features", () => {
+    expect(Object.keys(LLM_FEATURE_DEFAULTS)).toHaveLength(17)
     for (const feature of ALL_FEATURES) {
       expect(LLM_FEATURE_DEFAULTS).toHaveProperty(feature)
     }

package/src/__tests__/organizations-types.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest"
+import {
+  ACCESS_LEVELS,
+  COLLABORATOR_ROLES,
+  MEMBER_STATUSES,
+  ORG_ERROR_CODES,
+  ORG_KINDS,
+  ORG_ROLES,
+  OrgSettingsSchema,
+  PRESET_SETTING_KEYS,
+  PresetSettingsSchema,
+  WORKSPACE_ROLES,
+  WorkspaceSettingsSchema,
+} from "../organizations/index.js"
+
+describe("organizations wire contract — enums", () => {
+  it("every enum is non-empty and duplicate-free", () => {
+    for (const list of [ORG_KINDS, ORG_ROLES, WORKSPACE_ROLES, MEMBER_STATUSES, COLLABORATOR_ROLES, ACCESS_LEVELS, ORG_ERROR_CODES]) {
+      expect(list.length).toBeGreaterThan(0)
+      expect(new Set(list).size).toBe(list.length)
+    }
+  })
+
+  it("error codes are snake_case identifiers", () => {
+    for (const code of ORG_ERROR_CODES) expect(code).toMatch(/^[a-z][a-z_]*[a-z]$/)
+  })
+})
+
+describe("organizations wire contract — settings request schemas", () => {
+  it("the preset shape has exactly the nine resolvable keys", () => {
+    expect([...PRESET_SETTING_KEYS].sort()).toEqual(
+      [
+        "admin_access",
+        "collaborators_can_invite",
+        "default_workflow_visibility",
+        "member_access_to_shared",
+        "member_caps_enabled",
+        "members_can_create_projects",
+        "personal_space_enabled",
+        "policy_survives_suspension",
+        "workspace_admins_can_invite",
+      ].sort(),
+    )
+    expect(PresetSettingsSchema.safeParse({}).success).toBe(false)
+  })
+
+  it("workspace settings are a partial of the preset; unknown keys are stripped; bad values rejected", () => {
+    expect(WorkspaceSettingsSchema.parse({ admin_access: "edit", rogue: 1 })).toEqual({ admin_access: "edit" })
+    expect(WorkspaceSettingsSchema.safeParse({}).success).toBe(true)
+    expect(WorkspaceSettingsSchema.safeParse({ admin_access: "owner" }).success).toBe(false)
+    expect(WorkspaceSettingsSchema.safeParse({ member_caps_enabled: "yes" }).success).toBe(false)
+  })
+
+  it("org settings accept lower-case domains only and string vocabulary overrides", () => {
+    expect(OrgSettingsSchema.safeParse({ allowed_email_domains: ["school.edu", "sub.school.ac.il"] }).success).toBe(true)
+    expect(OrgSettingsSchema.safeParse({ allowed_email_domains: ["School.edu"] }).success).toBe(false)
+    expect(OrgSettingsSchema.safeParse({ allowed_email_domains: ["not a domain"] }).success).toBe(false)
+    expect(OrgSettingsSchema.safeParse({ vocabulary_overrides: { workspace: "Cohort" } }).success).toBe(true)
+    expect(OrgSettingsSchema.safeParse({ vocabulary_overrides: { workspace: 3 } }).success).toBe(false)
+  })
+})

package/src/__tests__/pack-sidecar-localization.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect, afterEach } from "vitest"
+import { registerCatalogSidecars, resetCatalogSidecars, resolveLabel, entryMatchesQuery } from "../index.js"
+
+afterEach(() => resetCatalogSidecars())
+
+describe("pack sidecars resolve through the shared localizer (G10)", () => {
+  it("resolveLabel returns a pack-registered localized label", () => {
+    // English fallback before registration
+    expect(resolveLabel("person", "attire-x", "Modest Suit", "he")).toBe("Modest Suit")
+    registerCatalogSidecars("person", { he: { "attire-x": { label: "חליפה צנועה" } } })
+    expect(resolveLabel("person", "attire-x", "Modest Suit", "he")).toBe("חליפה צנועה")
+  })
+  it("english locale ignores sidecars", () => {
+    registerCatalogSidecars("person", { he: { "attire-x": { label: "חליפה צנועה" } } })
+    expect(resolveLabel("person", "attire-x", "Modest Suit", "en")).toBe("Modest Suit")
+  })
+  it("search matches the localized pack label", () => {
+    registerCatalogSidecars("person", { he: { "attire-x": { label: "חליפה צנועה" } } })
+    expect(entryMatchesQuery("person", "attire-x", "Modest Suit", "d", "he", "חליפה")).toBe(true)
+  })
+})

package/src/__tests__/parameter-node-value.test.ts

@@ -1,8 +1,9 @@
-import { describe, it, expect } from "vitest"
+import { describe, it, expect, afterEach } from "vitest"
 import {
   PARAMETER_NODE_TYPES,
   getParameterValue,
 } from "../parameter-node-value.js"
+import { setRegisteredPersonPackFields } from "../index.js"
 
 describe("PARAMETER_NODE_TYPES", () => {
   it("includes the existing parameter node types", () => {
@@ -135,3 +136,19 @@ describe("parameter-node-value — furniture", () => {
     expect(getParameterValue({}, "furniture")).toBeUndefined()
   })
 })
+
+describe("getParameterValue person pack-dimension fallback (G4)", () => {
+  afterEach(() => setRegisteredPersonPackFields([]))
+
+  it("returns undefined for an unregistered pack field", () => {
+    expect(getParameterValue({ sectorAttire: "attire-modest-suit" }, "person")).toBeUndefined()
+  })
+  it("resolves a registered pack field when no base dimension is set", () => {
+    setRegisteredPersonPackFields(["sectorAttire"])
+    expect(getParameterValue({ sectorAttire: "attire-modest-suit" }, "person")).toBe("attire-modest-suit")
+  })
+  it("base dimensions still win over pack fields", () => {
+    setRegisteredPersonPackFields(["sectorAttire"])
+    expect(getParameterValue({ type: "man", sectorAttire: "attire-modest-suit" }, "person")).toBe("man")
+  })
+})

package/src/__tests__/producer-types.test.ts

@@ -23,6 +23,17 @@ describe("producer-types", () => {
     DYNAMIC_PRODUCER_TYPES,
   } as const
 
+  // still-to-video (still image + audio → MP4 via local FFmpeg) has a video
+  // OUTPUT handle — absent from this set, every downstream video input would
+  // hard-reject its edges (the "cannot connect the outputs" bug class).
+  it("registers still-to-video as a video producer", () => {
+    expect(VIDEO_PRODUCER_TYPES.has("still-to-video")).toBe(true)
+  })
+
+  it("registers slideshow as a video producer (still-to-video's N-image companion)", () => {
+    expect(VIDEO_PRODUCER_TYPES.has("slideshow")).toBe(true)
+  })
+
   it("registers voice-changer-pro as an audio producer (its default output)", () => {
     expect(AUDIO_PRODUCER_TYPES.has("voice-changer-pro")).toBe(true)
   })

package/src/__tests__/prompt-length-limits.test.ts

@@ -102,9 +102,13 @@ describe("per-model prompt length limits", () => {
   })
 
   describe("Suno per-version caps", () => {
-    it("prompt: 500 non-custom; 3000 V4 custom; 5000 V4.5+/V5 custom", () => {
-      expect(getMaxSunoPromptChars("V4", false)).toBe(500)
-      expect(getMaxSunoPromptChars("V5", false)).toBe(500)
+    // Non-custom was 500 until 2026-08-19 — six times under the provider's
+    // documented 3000, and the route truncates rather than rejects, so a
+    // 950-char recast score brief reached Suno cut to exactly 500 mid-word.
+    it("prompt: 3000 non-custom (all models); 3000 V4 custom; 5000 V4.5+/V5 custom", () => {
+      expect(getMaxSunoPromptChars("V4", false)).toBe(3000)
+      expect(getMaxSunoPromptChars("V5", false)).toBe(3000)
+      expect(getMaxSunoPromptChars("V5_5", false)).toBe(3000)
       expect(getMaxSunoPromptChars("V4", true)).toBe(3000)
       expect(getMaxSunoPromptChars("V4_5", true)).toBe(5000)
       expect(getMaxSunoPromptChars("V5", true)).toBe(5000)

package/src/__tests__/resolve-pipeline-model.test.ts

@@ -28,8 +28,8 @@ describe("resolvePipelineModel", () => {
   })
 
   it("returns the global script_llm for the script_llm stage", () => {
-    const config: Partial<PipelineConfig> = { script_llm: "claude-opus-4-6" }
-    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-6")
+    const config: Partial<PipelineConfig> = { script_llm: "claude-opus-4-7" }
+    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-7")
   })
 
   it("per-stage override beats the matching global field", () => {
@@ -52,12 +52,12 @@ describe("resolvePipelineModel", () => {
       stage_models: {
         scene_keyframes_image: "gpt-image",
         shots_video: "veo3",
-        script_llm: "claude-opus-4-6",
+        script_llm: "claude-opus-4-7",
       },
     }
     expect(resolvePipelineModel(config, "scene_keyframes_image")).toBe("gpt-image")
     expect(resolvePipelineModel(config, "shots_video")).toBe("veo3")
-    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-6")
+    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-7")
     // Entity image stages keep the global pick.
     expect(resolvePipelineModel(config, "characters_image")).toBe("flux")
   })

package/src/__tests__/seedance2-continuation-ref.test.ts

@@ -11,9 +11,8 @@ import {
  *  job dbf95612 — the original 1.0s tails made every generate-video-pro
  *  continuation segment fail deterministically). Everything this platform
  *  sends as a Seedance-2 video reference cuts SEEDANCE_2_CONTINUATION_REF_SEC
- *  seconds; do NOT "optimize" it back below the floor. The private-plugin
- *  twin constants (nodaro-cloud-plugins chain.ts TAIL_SEC / bridge-math.ts
- *  MIN_REF) are guarded by that repo's r2v-ref-floor.test.ts — keep in sync. */
+ *  seconds; do NOT "optimize" it back below the floor. The plugin repo
+ *  carries twin constants guarded by its own tests — keep the two in sync. */
 describe("seedance-2 continuation-reference floor (do not regress)", () => {
   it("the platform's continuation-ref length clears KIE's r2v minimum", () => {
     expect(SEEDANCE_2_CONTINUATION_REF_SEC).toBeGreaterThanOrEqual(SEEDANCE_2_R2V_MIN_REF_VIDEO_SEC)

package/src/__tests__/video-analysis-catalog-sync.test.ts

@@ -157,7 +157,7 @@ describe("bare video-analysis node-type credit id", () => {
     // 24 and the schedule regenerated ~47% lower at the ceiling bucket, and 300
     // wrote 2064: the V1 hybrid-smart reprice (task A3) moved `smart` to a
     // multi-roll plan (native skeleton + donor rolls, always refined) and
-    // trued up every tier's judge/refine terms from staging measurement).
+    // trued up every tier's judge/refine terms).
     expect(ceiling).toBe(2064)
   })
 

package/src/__tests__/video-analysis-pricing.test.ts

@@ -15,7 +15,7 @@ import {
 
 // The measured-rate constants and the $-derived `videoAnalysisBucketCredits`
 // formula are PRIVATE, in @nodaroai/cloud-plugins
-// (src/plugins/video-analysis/cost.ts) — its tests (the worked-example
+// (in the plugin repo) — its tests (the worked-example
 // bucket-credit values and the cross-check against VIDEO_ANALYSIS_BUCKET_CREDITS
 // below) live in that private package's __tests__/cost.test.ts. This file
 // covers only the NON-monetary duration-bucketing, window-batching, and
@@ -121,7 +121,7 @@ describe("video-analysis-pricing", () => {
   })
 
   // Full drift-detection against the live $-formula lives in the PRIVATE
-  // plugin repo (src/plugins/video-analysis/__tests__/cost.test.ts) — the
+  // plugin repo — the
   // formula moved there in 2026-07 and the app-side test was deleted with it,
   // so nothing in THIS repo can recompute these numbers. This is a lightweight
   // shape check that the precomputed table covers every legal id.

package/src/__tests__/video-mode-for-inputs.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest"
+import {
+  VIDEO_MODE_ALIASES,
+  VIDEO_REF_LIMITS_BY_PROVIDER,
+  resolveVideoModeForInputs,
+  resolveVideoProviderForMode,
+} from "../model-constants.js"
+
+/**
+ * #861 — reference images wired to Grok Imagine 1 without a start frame were
+ * silently dropped: the run resolved to text-to-video, the t2v twin (`grok`)
+ * has no image parameter, and nothing said so. The mode must follow what the
+ * model can CARRY, derived from the catalog's reference caps — not a name.
+ */
+const I2V = "image-to-video"
+const T2V = "text-to-video"
+
+describe("resolveVideoModeForInputs", () => {
+  it("a start frame is image-to-video for every provider", () => {
+    for (const id of ["grok-i2v", "grok", "seedance-2", "kling", "veo3", "wan-i2v", undefined]) {
+      expect(resolveVideoModeForInputs(id, { hasStartFrame: true, hasImageRefs: false })).toBe(I2V)
+      expect(resolveVideoModeForInputs(id, { hasStartFrame: true, hasImageRefs: true })).toBe(I2V)
+    }
+  })
+
+  it("nothing wired is text-to-video", () => {
+    expect(resolveVideoModeForInputs("grok-i2v", { hasStartFrame: false, hasImageRefs: false })).toBe(T2V)
+    expect(resolveVideoModeForInputs(undefined, { hasStartFrame: false, hasImageRefs: true })).toBe(T2V)
+  })
+
+  it("refs alone route Grok Imagine 1 to its i2v twin — the only one that can carry them (#861)", () => {
+    // Whichever member id the node stored (base/i2v/t2v all appear in old workflows).
+    for (const id of ["grok-i2v", "grok"]) {
+      expect(resolveVideoModeForInputs(id, { hasStartFrame: false, hasImageRefs: true })).toBe(I2V)
+    }
+    // The premise, pinned: i2v carries refs, t2v does not.
+    expect(VIDEO_REF_LIMITS_BY_PROVIDER["grok-i2v"]?.images).toBeGreaterThan(0)
+    expect(VIDEO_REF_LIMITS_BY_PROVIDER["grok"]).toBeUndefined()
+  })
+
+  it("single-id models are untouched: the same id serves both modes, so there is nothing to re-route", () => {
+    // seedance-2 / gemini-omni-video / veo forward refs on their t2v path
+    // (generate-video.md mode table). kling-3-omni is i2v-only and keeps its
+    // documented orchestrator behavior (image_required on the t2v path) —
+    // whether refs alone should satisfy it is a separate question from #861.
+    for (const id of ["seedance-2", "gemini-omni-video", "veo3.1", "kling-3-omni"]) {
+      expect(resolveVideoModeForInputs(id, { hasStartFrame: false, hasImageRefs: true })).toBe(T2V)
+    }
+  })
+
+  it("a split-id model with no ref support on either twin is unaffected (wan, happyhorse)", () => {
+    for (const id of ["wan-i2v", "wan-2.7-i2v", "happyhorse-i2v"]) {
+      expect(resolveVideoModeForInputs(id, { hasStartFrame: false, hasImageRefs: true })).toBe(T2V)
+    }
+  })
+
+  it("every alias group is classified — a new split-id model lands in one of the two pinned outcomes", () => {
+    // Explicit per-group expectations (not a re-derivation of the formula):
+    // grok is the one group whose twins differ on ref support today.
+    const expectedByBase: Record<string, "image-to-video" | "text-to-video"> = {
+      "grok-i2v": I2V,
+      "wan-i2v": T2V,
+      "wan-2.7-i2v": T2V,
+      "happyhorse-i2v": T2V,
+    }
+    expect(VIDEO_MODE_ALIASES.map((g) => g.base).sort()).toEqual(Object.keys(expectedByBase).sort())
+    for (const g of VIDEO_MODE_ALIASES) {
+      const expected = expectedByBase[g.base]!
+      expect(resolveVideoModeForInputs(g.base, { hasStartFrame: false, hasImageRefs: true }), g.base).toBe(expected)
+      // The mode it picks resolves to the twin that can actually run it.
+      if (expected === I2V) expect(resolveVideoProviderForMode(g.base, expected)).toBe(g.i2v)
+    }
+  })
+})

package/src/animals.ts

@@ -30,6 +30,16 @@ export interface Animal {
   readonly label: string
   readonly subcategory: AnimalSubcategory
   readonly description: string
+  /**
+   * Optional authored compact term — the short phrase a professional would
+   * write in a prompt, as opposed to the user-facing `label` (see the `term`
+   * convention in `@nodaro/prompts`'s `term.ts`). Authored ONLY where the
+   * lowercased label is not that phrase — a UI compound naming two things at
+   * once ("Airship / Dirigible" -> "airship", "Plasma Sword / Lightsaber" ->
+   * "plasma sword"). Everywhere else the lowercased label IS the term for a
+   * concrete object ("golden retriever", "katana"), so nothing is authored.
+   */
+  readonly term?: string
 }
 
 export const ANIMALS: ReadonlyArray<Animal> = [

package/src/catalog-projection.ts

@@ -0,0 +1,48 @@
+/**
+ * Tag-free, policy-free wire shape for the `GET /v1/catalogs` projection — the
+ * server-driven, pack-composed catalog view thin clients render their own
+ * pickers from. This is the ONLY catalog-related type in `@nodaro/shared`
+ * (Apache): catalog DATA stays in `@nodaro/prompts` (FSL), and the deferred
+ * `CatalogPolicy` (tags / deny-by-tag / per-read-kind filter) is deliberately
+ * NOT represented here — nothing tag- or policy-shaped may cross this boundary.
+ */
+export interface ProjectedCatalogOption {
+  id: string
+  label: string
+  description?: string
+  category?: string
+  /** The prompt fragment this id injects downstream. Present only when detail="full". */
+  promptHint?: string
+  /**
+   * Short professional term injected by compact hint mode; `label` is for
+   * display. Present at BOTH detail levels — a thin client renders `label`
+   * and injects `term`. Empty for a no-op ("auto"/"none") entry that injects
+   * nothing.
+   */
+  term?: string
+  icon?: string
+}
+
+export interface ProjectedCatalogDimension {
+  field: string
+  label: string
+  options: ProjectedCatalogOption[]
+}
+
+export interface ProjectedCatalog {
+  nodeType: string
+  label: string
+  catalogId: string
+  kind: "single" | "multi"
+  /** single only — the node-data field the chosen id writes to. */
+  valueField?: string
+  defaultValue?: string
+  categoryOrder?: readonly string[]
+  categoryLabels?: Readonly<Record<string, string>>
+  detail: "compact" | "full"
+  /** single-dim catalogs. */
+  options?: ProjectedCatalogOption[]
+  /** multi-dim catalogs. */
+  fields?: readonly string[]
+  dimensions?: ProjectedCatalogDimension[]
+}

package/src/combine-transitions.ts

@@ -480,3 +480,41 @@ export function resolveXfadeName(id: string): string | null {
   }
   return entry.xfade
 }
+
+/**
+ * Map a `transition` PARAMETER-NODE pick (the @nodaro/prompts creative
+ * catalog — prose-hint transitions for AI video prompts) onto the ffmpeg
+ * xfade vocabulary above. The two vocabularies are deliberately different
+ * (the picker describes shots, this table describes blends); only the
+ * visually-faithful subset maps — everything else falls back to `cut`.
+ *
+ * Consumed by the slideshow node (its transition TYPE comes from a wired
+ * transition parameter node; unwired defaults to cut). Kept here — not in
+ * @nodaro/prompts — because the dependency points prompts → shared, and the
+ * ids are plain strings on both sides.
+ */
+export const PICKER_TO_COMBINE_TRANSITION: Readonly<Record<string, string>> = {
+  "none": "cut",
+  "auto": "dissolve", // an explicitly wired "auto" wants A blend — the classic slideshow default
+  "cross-dissolve": "dissolve",
+  "fade-to-black": "dip-to-black",
+  "fade-to-white": "dip-to-white",
+  "iris": "circle-open",
+  "wipe": "wipe-left",
+  "pixelate-reform": "pixelize",
+  "dissolve-to-mist": "hblur",
+  "match-cut": "cut",
+  "smash-cut": "cut",
+  "freeze-frame-jump": "cut",
+}
+
+/**
+ * Resolve ANY transition string a slideshow may receive — a combine id
+ * (already valid), a picker id (mapped), or anything else (→ cut).
+ */
+export function resolveSlideshowTransition(value: string | undefined | null): string {
+  if (!value) return "cut"
+  if (COMBINE_TRANSITION_IDS.includes(value)) return value
+  return PICKER_TO_COMBINE_TRANSITION[value] ?? "cut"
+}
+

package/src/credit-estimators/video-utils.ts

@@ -155,7 +155,7 @@ export function estimateLoopTrimAddonCredits(
          Math.ceil(frames / VIDEO_UTIL_PRICING.FRAMES_PER_CREDIT)
 }
 
-/** BASE credits (at-cost) for assemble-narrated-video: 3 flat + 1 per 6
+/** BASE credits for assemble-narrated-video: 3 flat + 1 per 6
  *  blocks. 6→4, 24→7, 60→13. Single source of truth shared by the backend
  *  route/creditGuard (`backend/src/providers/video/narrated-block-fit.ts`
  *  re-exports this) and the frontend pre-run estimate

package/src/entity-node-fields.ts

@@ -0,0 +1,147 @@
+/**
+ * Which DB columns of a saved entity land on its canvas node, per kind.
+ *
+ * Four surfaces copy an entity row onto a node: the browser's load-time
+ * hydrator, the browser's library picker, the backend's run-time hydration, and
+ * (indirectly) anything that reads a node expecting those fields to be there.
+ * They used to be four hand-written lists, and they drifted exactly as you would
+ * expect — the load-time hydrator covers `character` and nothing else, so an
+ * object node bound by an agent stays media-less until someone rebinds it by
+ * hand.
+ *
+ * This is the field NAMES only — the structural vocabulary. Merge behaviour
+ * (defaults, `prev` fallbacks, type narrowing) stays with each caller, because
+ * a browser node and a server row disagree about nulls and it is not worth
+ * pretending otherwise.
+ */
+
+/**
+ * Every entity kind, in the order surfaces present them.
+ *
+ * The list is the invariant: `Record<EntityNodeKind, …>` makes the compiler
+ * find every table below, every per-kind UI row in the `@` picker, and the
+ * picker’s kind→query map. What the compiler cannot see — that the MCP read
+ * tools for a kind exist and are reachable — is pinned by a test instead.
+ *
+ * Tool names are derivable from it too: `list_<kind>s` / `get_<kind>`.
+ */
+export const ENTITY_NODE_KINDS = ["character", "object", "creature", "location"] as const
+
+export type EntityNodeKind = (typeof ENTITY_NODE_KINDS)[number]
+
+/** The `data.*DbId` field that binds each entity node to its row. */
+export const ENTITY_DB_ID_FIELD: Record<EntityNodeKind, string> = {
+  character: "characterDbId",
+  object: "objectDbId",
+  creature: "creatureDbId",
+  location: "locationDbId",
+}
+
+/** The `data.*Name` field each kind stores its display name under. */
+export const ENTITY_NAME_FIELD: Record<EntityNodeKind, string> = {
+  character: "characterName",
+  object: "objectName",
+  creature: "creatureName",
+  location: "locationName",
+}
+
+/** Postgres table per kind. */
+export const ENTITY_TABLE: Record<EntityNodeKind, string> = {
+  character: "characters",
+  object: "objects",
+  creature: "creatures",
+  location: "locations",
+}
+
+/**
+ * `{name,url}[]` buckets per kind, as `[db_column, nodeField]`.
+ *
+ * These are what a generation actually consumes — the variant a prompt
+ * `@mentions`, the extra references a user attaches. A node missing them is not
+ * visibly broken; it just quietly generates the wrong picture.
+ */
+export const ENTITY_BUCKET_FIELDS: Record<EntityNodeKind, ReadonlyArray<readonly [string, string]>> = {
+  character: [
+    ["expressions", "expressions"],
+    ["poses", "poses"],
+    ["motions", "motions"],
+    ["angles", "angles"],
+    ["body_angles", "bodyAngles"],
+    ["lighting_variations", "lightingVariations"],
+    ["outfit_variations", "outfitVariations"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+  object: [
+    ["angles", "angles"],
+    ["materials", "materials"],
+    ["variations", "variations"],
+    ["motion_clips", "motionClips"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+  creature: [
+    ["angles", "angles"],
+    ["poses", "poses"],
+    ["variations", "variations"],
+    ["motion_clips", "motionClips"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+  location: [
+    ["time_of_day", "timeOfDay"],
+    ["weather", "weather"],
+    ["angles", "angles"],
+    ["lighting", "lighting"],
+    ["seasons", "seasons"],
+    ["atmosphere_motions", "atmosphereMotions"],
+    ["detail_closeups", "detailCloseups"],
+    ["sheets", "sheets"],
+  ],
+}
+
+/**
+ * Scalars every kind shares, as `[db_column, nodeField]`.
+ *
+ * `source_image_url` is the load-bearing one: the run engine reads
+ * `defaultAssetUrl || sourceImageUrl` and SKIPS the reference entirely when
+ * both are empty — no error, no warning, just a generation of the wrong
+ * person. A node with an id but no image is the shape an agent produces.
+ */
+export const ENTITY_SCALAR_FIELDS: ReadonlyArray<readonly [string, string]> = [
+  ["name", "__name"], // routed to the kind's own name field by the caller
+  ["description", "description"],
+  ["canonical_description", "canonicalDescription"],
+  ["source_image_url", "sourceImageUrl"],
+]
+
+/**
+ * Scalars only SOME kinds have.
+ *
+ * `style_lock` looks shared and is not: characters never grew the column,
+ * because a character's likeness is the lock. Selecting it from `characters`
+ * anyway is a PostgREST error, which the run-time hydrator swallows by design
+ * — so the whole kind would quietly stop hydrating and every test that mocks
+ * the database would still pass. That is why the column lists are checked
+ * against the migrations by `entity-hydration-columns.test.ts`.
+ */
+export const ENTITY_KIND_SCALAR_FIELDS: Record<EntityNodeKind, ReadonlyArray<readonly [string, string]>> = {
+  character: [],
+  object: [["style_lock", "styleLock"]],
+  creature: [["style_lock", "styleLock"]],
+  location: [["style_lock", "styleLock"]],
+}
+
+/** Every DB column a full hydration of `kind` reads. */
+export function entityHydrationColumns(kind: EntityNodeKind): string[] {
+  return [
+    "id",
+    ...entityScalarFields(kind).map(([column]) => column),
+    ...ENTITY_BUCKET_FIELDS[kind].map(([column]) => column),
+  ]
+}
+
+/** Every scalar `kind` actually has, shared plus its own. */
+export function entityScalarFields(kind: EntityNodeKind): ReadonlyArray<readonly [string, string]> {
+  return [...ENTITY_SCALAR_FIELDS, ...ENTITY_KIND_SCALAR_FIELDS[kind]]
+}

package/src/featured-entities.ts

@@ -1,5 +1,5 @@
 /**
- * Featured entity starter catalog (north-star §6 ③ — the "Featured" tab of each
+ * Featured entity starter catalog (the "Featured" tab of each
  * entity Library).
  *
  * These are app-provided starter presets: a curated visual description per

package/src/furniture.ts

@@ -26,6 +26,16 @@ export interface Furniture {
   readonly label: string
   readonly subcategory: FurnitureSubcategory
   readonly description: string
+  /**
+   * Optional authored compact term — the short phrase a professional would
+   * write in a prompt, as opposed to the user-facing `label` (see the `term`
+   * convention in `@nodaro/prompts`'s `term.ts`). Authored ONLY where the
+   * lowercased label is not that phrase — a UI compound naming two things at
+   * once ("Airship / Dirigible" -> "airship", "Plasma Sword / Lightsaber" ->
+   * "plasma sword"). Everywhere else the lowercased label IS the term for a
+   * concrete object ("golden retriever", "katana"), so nothing is authored.
+   */
+  readonly term?: string
 }
 
 export const FURNITURE: ReadonlyArray<Furniture> = [