@nodaro/shared 2.21.1 → 2.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.21.1",
+  "version": "2.23.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/index.ts

@@ -3,6 +3,7 @@ export type {
   GenericEdge,
   CharacterDef,
   ConnectedReference,
+  DescribedReference,
   IdentityFidelity,
   IdentityMeta,
   ReferenceSource,
@@ -112,6 +113,7 @@ export {
   checkRefVideoDurations,
   VIDEO_PROVIDERS_REQUIRING_IMAGE,
   videoProviderRequiresImage,
+  videoProviderFoldsLoneEndFrame,
   VIDEO_MODE_ALIASES,
   VIDEO_GEN_COLLAPSED_T2V_IDS,
   resolveVideoProviderForMode,

package/src/model-constants.ts

@@ -2105,6 +2105,29 @@ export function videoProviderRequiresImage(provider: string | undefined): boolea
   return !!provider && VIDEO_PROVIDERS_REQUIRING_IMAGE.has(provider)
 }
 
+/**
+ * True when the provider's image-to-video path FOLDS a lone closing frame into
+ * its reference images — i.e. an end frame with no start frame is a reference
+ * the model actually receives, not a half-formed frame pair.
+ *
+ * The Seedance 2.x, MiniMax Hailuo 3 and Wan 3 families all assemble their KIE
+ * input through the shared `resolveSeedance2Inputs` (`@nodaro/prompts`), whose
+ * reference mode takes a lone last frame as the sole reference image plus a
+ * closing-frame prompt hint. NOTHING else does: VEO ships `[imageUrl,
+ * endFrameUrl]` verbatim (a lone end frame would reach KIE as `[null, url]`),
+ * the Gemini Omni branch drops the frame when there is no start frame, and the
+ * generic KIE path sends `end_frame` with no image param at all. So the
+ * exemption is keyed to the FOLD, not to "carries image references" — the
+ * catalog has no capability for it, and these three family predicates are the
+ * same membership the provider layer itself branches on (the backend's
+ * `kie/video.ts::applySeedance2Params` / `applyMinimaxH3Params` / `runWan3`).
+ * A ref-capable provider that grows the fold gets the exemption by joining a
+ * family here; one that does not keeps the honest `image_required` 400.
+ */
+export function videoProviderFoldsLoneEndFrame(provider: string): boolean {
+  return isSeedance2Provider(provider) || isMinimaxH3Provider(provider) || isWan3Provider(provider)
+}
+
 /**
  * Video models where enabling audio/sound incurs an additional cost.
  * The audio addon is expressed as a separate composite identifier suffix.

package/src/types.ts

@@ -214,6 +214,49 @@ export interface ConnectedReference {
    * The single new structured-shape field for external (API/MCP/SDK) parity.
    */
   readonly identityLock?: { enabled: boolean; text?: string }
+  /**
+   * PER-USE identity description for this reference — what the caller wants the
+   * model told about this subject THIS TIME, overriding whatever the entity's
+   * library record says. Wherever a reference's identity description already
+   * renders (the legacy identity bullet's `— <desc>` part, a `{image:N:label}`
+   * directive's descriptor) it WINS over `characterCanonicalDescription` /
+   * `locationCanonicalDescription` / `description`; where the HYBRID format
+   * renders no description at all, it adds one trailing `<binding> — <override>.`
+   * line instead.
+   *
+   * The two formats are deliberately ASYMMETRIC where a reference renders no
+   * directive at all — a plain upload (`manual` / `wired-image`, non-extra) that
+   * is neither `@`-mentioned nor `{image:N}`-covered: the LEGACY format stays
+   * silent, and the override is not surfaced there (a bullet would force a
+   * fidelity verb onto an opaque image); the HYBRID format — the production
+   * default — adds the trailing line above for it.
+   *
+   * DISTINCT from `description`, which stays the reference's own label slot (the
+   * free text an extra-ref row / an upstream node carries) — a caller that edits
+   * the wording for ONE use writes it here, so the label is untouched and
+   * dropping the override falls back to the library wording. Absent →
+   * byte-identical to a caller that never sent it.
+   */
+  readonly descriptionOverride?: string
+}
+
+/**
+ * A reference the caller can NAME and DESCRIBE but has no media for — a cast
+ * role no entity has been bound to yet, an analysis slot, a character the author
+ * has only written down. It carries no `url`, so it attaches no reference image
+ * and claims no `@image_N` seat; it reaches the model purely as prose
+ * (`<Name> — <description>.`), rendered in ONE place per lane by
+ * `@nodaro/prompts`' `renderDescribedReferenceLines`.
+ *
+ * Correlation with the prompt body is BY NAME: the caller leaves the name in the
+ * prose (never an indexed `@slug:N` mention — that grammar is url-gated) and the
+ * described line tells the model who that name is.
+ */
+export interface DescribedReference {
+  /** Display name exactly as it appears in the prompt prose (e.g. "Natalie"). */
+  readonly name: string
+  /** What the model should picture when it reads that name. */
+  readonly description: string
 }
 
 /** Default label per source — used by `@` autocomplete and inventory fallback. */