@nodaro/shared 2.3.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.3.0",
+  "version": "2.7.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__/effective-tier.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest"
+import {
+  resolveStoredTier,
+  resolveEffectiveTier,
+  isPaygRetentionActive,
+  PAYG_RETENTION_DAYS,
+} from "../effective-tier.js"
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const NOW = new Date("2026-08-12T12:00:00Z")
+const daysAgo = (n: number) => new Date(NOW.getTime() - n * DAY_MS)
+
+describe("resolveStoredTier", () => {
+  it("prefers tier, falls back to subscription_tier, then free", () => {
+    expect(resolveStoredTier({ tier: "pro", subscription_tier: "basic" })).toBe("pro")
+    expect(resolveStoredTier({ tier: null, subscription_tier: "basic" })).toBe("basic")
+    expect(resolveStoredTier({ tier: null, subscription_tier: null })).toBe("free")
+  })
+})
+
+describe("resolveEffectiveTier — the payg derivation matrix (design §9)", () => {
+  it("never-paid free user stays free", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("free user with NET lifetime > 0 derives payg — even at zero current balance", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 3300 })
+    ).toBe("payg")
+  })
+
+  it("refunded-to-zero user drops back to free (NET lifetime)", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("#489 pre-subscribe carryover fixture: topup balance without purchase stays free", () => {
+    // Cancel-path carryover moves a pre-subscribe balance into topup_credits
+    // with NO purchase — lifetime stays 0, so the user must NOT derive payg.
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("every stored paid tier passes through untouched, regardless of lifetime", () => {
+    for (const t of ["basic", "standard", "pro", "business"]) {
+      expect(
+        resolveEffectiveTier({ tier: t, subscription_tier: null, lifetime_topup_credits: 9999 })
+      ).toBe(t)
+    }
+  })
+
+  it("subscription_tier-only legacy rows resolve through the stored fallback", () => {
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: "standard", lifetime_topup_credits: 500 })
+    ).toBe("standard")
+  })
+
+  it("null-tier never-paid rows resolve free; with lifetime they derive payg", () => {
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: null, lifetime_topup_credits: 100 })
+    ).toBe("payg")
+  })
+})
+
+describe("isPaygRetentionActive — 90-day activity window boundaries", () => {
+  it("exports the 90-day constant", () => {
+    expect(PAYG_RETENTION_DAYS).toBe(90)
+  })
+
+  it("purchase activity: 89d active, 90d active (inclusive), 91d inactive", () => {
+    const base = { lifetimeTopupCredits: 100, lastSpendAt: null }
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(89) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(90) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(91) }, NOW)).toBe(false)
+  })
+
+  it("spend activity counts on its own (usage_logs MAX, not balance polls)", () => {
+    const base = { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(200) }
+    expect(isPaygRetentionActive({ ...base, lastSpendAt: daysAgo(10) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastSpendAt: daysAgo(91) }, NOW)).toBe(false)
+  })
+
+  it("either source alone is sufficient; the most recent wins", () => {
+    expect(
+      isPaygRetentionActive(
+        { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(120), lastSpendAt: daysAgo(5) },
+        NOW
+      )
+    ).toBe(true)
+  })
+
+  it("string timestamps (supabase rows) are accepted", () => {
+    expect(
+      isPaygRetentionActive(
+        { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(5).toISOString(), lastSpendAt: null },
+        NOW
+      )
+    ).toBe(true)
+  })
+
+  it("all-null activity is inactive; never-paid users are never retention-active", () => {
+    expect(
+      isPaygRetentionActive({ lifetimeTopupCredits: 100, lastTopupAt: null, lastSpendAt: null }, NOW)
+    ).toBe(false)
+    expect(
+      isPaygRetentionActive({ lifetimeTopupCredits: 0, lastTopupAt: daysAgo(1), lastSpendAt: null }, NOW)
+    ).toBe(false)
+  })
+})

package/src/__tests__/entity-image-handle.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest"
-import { resolveEffectiveSourceType, ENTITY_IMAGE_HANDLE_TYPES, sourceRefKey } from "../entity-image-handle.js"
+import { resolveEffectiveSourceType, ENTITY_IMAGE_HANDLE_TYPES, AGGREGATE_LANE_SOURCE_TYPES, sourceRefKey } from "../entity-image-handle.js"
 
 const ENTITY_REF_HANDLE: Record<string, string> = {
   character: "characterRef",
@@ -62,3 +62,35 @@ describe("sourceRefKey (handle-scoped ref key — prevents node-id collision)",
     expect(sourceRefKey("n1", undefined, "character")).toBe("n1")
   })
 })
+
+describe("resolveEffectiveSourceType (aggregate lane handle → plain producer of that type)", () => {
+  const LANE_TO_PRODUCER: Record<string, string> = {
+    "out-image": "upload-image",
+    "out-video": "upload-video",
+    "out-audio": "upload-audio",
+    "out-text": "list",
+  }
+
+  it("remaps every Collect / Group lane to the plain producer of its media type", () => {
+    for (const agg of AGGREGATE_LANE_SOURCE_TYPES) {
+      for (const [lane, producer] of Object.entries(LANE_TO_PRODUCER)) {
+        expect(resolveEffectiveSourceType(agg, lane)).toBe(producer)
+      }
+    }
+  })
+
+  it("leaves a non-lane / missing handle as the raw aggregate type", () => {
+    expect(resolveEffectiveSourceType("collect", "out")).toBe("collect")
+    expect(resolveEffectiveSourceType("collect", undefined)).toBe("collect")
+    expect(resolveEffectiveSourceType("group", null)).toBe("group")
+  })
+
+  it("does not remap lane-shaped handles on non-aggregate producers", () => {
+    expect(resolveEffectiveSourceType("generate-image", "out-image")).toBe("generate-image")
+    expect(resolveEffectiveSourceType("list", "out-text")).toBe("list")
+  })
+
+  it("AGGREGATE_LANE_SOURCE_TYPES is exactly group + collect", () => {
+    expect([...AGGREGATE_LANE_SOURCE_TYPES].sort()).toEqual(["collect", "group"])
+  })
+})

package/src/__tests__/group-aggregation.test.ts

@@ -5,7 +5,9 @@ import {
   groupHandleId,
   parseGroupHandle,
   isAggregateableType,
+  computeAggregateLanes,
   AGGREGATEABLE_TYPES,
+  type AggregationBuckets,
   type Member,
 } from "../group-aggregation.js"
 
@@ -81,3 +83,40 @@ describe("isAggregateableType", () => {
     expect(isAggregateableType(undefined)).toBe(false)
   })
 })
+
+describe("computeAggregateLanes", () => {
+  const EMPTY: AggregationBuckets = { text: [], image: [], video: [], audio: [] }
+
+  it("returns empty when nothing is wired, bucketed, or referenced", () => {
+    expect(computeAggregateLanes("c1", [], EMPTY, [])).toEqual([])
+  })
+
+  it("exposes lanes for wired types even with empty buckets (pre-run)", () => {
+    expect(computeAggregateLanes("c1", ["image", "image"], EMPTY, [])).toEqual(["image"])
+  })
+
+  it("exposes lanes for bucket contents (post-run)", () => {
+    const buckets: AggregationBuckets = { text: ["t"], image: [], video: [], audio: [] }
+    expect(computeAggregateLanes("c1", [], buckets, [])).toEqual(["text"])
+  })
+
+  it("keeps a lane alive when an outgoing edge references it", () => {
+    const edges = [{ source: "c1", sourceHandle: "out-video" }]
+    expect(computeAggregateLanes("c1", [], EMPTY, edges)).toEqual(["video"])
+  })
+
+  it("ignores outgoing edges of other nodes and non-lane handles", () => {
+    const edges = [
+      { source: "other", sourceHandle: "out-video" },
+      { source: "c1", sourceHandle: "out" },
+      { source: "c1", sourceHandle: null },
+    ]
+    expect(computeAggregateLanes("c1", [], EMPTY, edges)).toEqual([])
+  })
+
+  it("unions all three sources and orders by AGGREGATEABLE_TYPES", () => {
+    const buckets: AggregationBuckets = { text: [], image: [], video: [], audio: ["a"] }
+    const edges = [{ source: "c1", sourceHandle: "out-video" }]
+    expect(computeAggregateLanes("c1", ["text"], buckets, edges)).toEqual(["text", "video", "audio"])
+  })
+})

package/src/__tests__/infer-music-video.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest"
+import { inferMusicVideo, videoAnalysisResultSchema, VIDEO_ANALYSIS_TIMES_OF_DAY, VIDEO_ANALYSIS_STORY_JUMPS } from "../video-analysis"
+
+/**
+ * The inference decides whether a recast takes the original soundtrack AS-IS
+ * (no stem separation). Server (recast route mode derivation) and client
+ * (prep pricing + the generate-time mode-mismatch guard) both call THIS
+ * function, so its exact boundary behaviour is contract, not detail.
+ */
+
+const music = (content: string) => ({ mode: "music" as const, content })
+const scene = (audio: Array<{ mode: string; content: string }>) => ({ audio })
+const vocalScenes = (n: number) => Array.from({ length: n }, () => scene([music("upbeat pop track with sung lyrics")]))
+
+describe("inferMusicVideo", () => {
+  it("true when ≥80% of ≥4 scenes carry music and vocals are evidenced", () => {
+    expect(inferMusicVideo({ scenes: vocalScenes(5) })).toBe(true)
+    // 4 of 5 with music (80% exactly), one vocal layer
+    expect(inferMusicVideo({ scenes: [...vocalScenes(4), scene([])] })).toBe(true)
+  })
+
+  it("quoted lyric text inside a music layer is vocal evidence on its own", () => {
+    const scenes = Array.from({ length: 4 }, () => scene([music('gentle track, "la la la, choosing you tonight"')]))
+    expect(inferMusicVideo({ scenes })).toBe(true)
+  })
+
+  it("false below the coverage bar, the scene floor, or with no vocal evidence", () => {
+    expect(inferMusicVideo({ scenes: [...vocalScenes(3), scene([]), scene([])] })).toBe(false) // 60%
+    expect(inferMusicVideo({ scenes: vocalScenes(3) })).toBe(false) // < 4 scenes
+    const instrumentalOnly = Array.from({ length: 5 }, () => scene([music("sweeping orchestral score")]))
+    expect(inferMusicVideo({ scenes: instrumentalOnly })).toBe(false)
+  })
+
+  it("negated vocals ('instrumental', 'no vocals') are not evidence; sfx/speech layers never are", () => {
+    const negated = Array.from({ length: 5 }, () => scene([music("instrumental version of the song, no vocals")]))
+    expect(inferMusicVideo({ scenes: negated })).toBe(false)
+    const speechy = Array.from({ length: 5 }, () => scene([{ mode: "speech", content: "she sings later" }, music("soft bed")]))
+    expect(inferMusicVideo({ scenes: speechy })).toBe(false)
+  })
+
+  it("bare 'song'/'music' descriptions are NOT vocal evidence (instrumental beds are described as songs)", () => {
+    const bare = Array.from({ length: 5 }, () => scene([music("upbeat pop song under the action")]))
+    expect(inferMusicVideo({ scenes: bare })).toBe(false)
+  })
+
+  it("throw-proof on malformed or absent input", () => {
+    expect(inferMusicVideo(undefined)).toBe(false)
+    expect(inferMusicVideo(null)).toBe(false)
+    expect(inferMusicVideo({})).toBe(false)
+    expect(inferMusicVideo({ scenes: [{}, { audio: [{}] }, {}, {}] } as never)).toBe(false)
+  })
+})
+
+describe("chronicle-time fields (2.6.0)", () => {
+  const base = {
+    startSec: 0, endSec: 2, label: "l", shotType: "Wide", camera: "static",
+    visual: "a scene", audio: [], sceneNumber: 1, visualResolved: "a scene", slotRefs: [],
+  }
+  const result = (sceneOver: Record<string, unknown>) => ({
+    meta: { durationSec: 2, width: 10, height: 10, aspectRatio: "1:1" },
+    slots: [],
+    scenes: [{ ...base, ...sceneOver }],
+  })
+
+  it("are optional (pre-2.6.0 analyses parse unchanged) and enum-validated when present", () => {
+    expect(videoAnalysisResultSchema.safeParse(result({})).success).toBe(true)
+    expect(videoAnalysisResultSchema.safeParse(result({ timeOfDay: "dusk", storyJump: "years-later" })).success).toBe(true)
+    expect(videoAnalysisResultSchema.safeParse(result({ timeOfDay: "noon" })).success).toBe(false)
+    expect(videoAnalysisResultSchema.safeParse(result({ storyJump: "later" })).success).toBe(false)
+  })
+
+  it("the enums stay congruence-safe for the window decode grammar (no ints, no maxItems)", () => {
+    expect(VIDEO_ANALYSIS_TIMES_OF_DAY).toContain("ambiguous")
+    expect(VIDEO_ANALYSIS_STORY_JUMPS).toContain("years-later")
+  })
+})

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

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

package/src/__tests__/seedance-2-5-catalog.test.ts

@@ -23,10 +23,14 @@ const ID = "seedance-2-5"
  * api.kie.ai on 2026-08-08, NOT by the published schema — KIE's docs advertise
  * a wider surface than the proxy actually accepts. These tests pin the probed
  * reality so a future "the spec sheet says 4K/180s" edit has to re-probe first.
+ *
+ * Re-probed 2026-08-17 (KIE "Seedance 2.5 now supports 1080P" release):
+ * 1080p passes resolution validation; 1440p/2k/4k are still rejected with
+ * "not within the range of allowed options", and duration 31 is still refused.
  */
-describe("seedance-2-5 catalog (probe-verified 2026-08-08)", () => {
-  it("is 480p/720p ONLY — KIE rejects 1080p/4k/2k the same way it rejects a nonsense value", () => {
-    expect(MODEL_CATALOG[ID].resolutions).toEqual(["480p", "720p"])
+describe("seedance-2-5 catalog (probe-verified 2026-08-08, re-probed 2026-08-17)", () => {
+  it("is 480p/720p/1080p — KIE still rejects 4k/2k/1440p the same way it rejects a nonsense value", () => {
+    expect(MODEL_CATALOG[ID].resolutions).toEqual(["480p", "720p", "1080p"])
   })
 
   it("runs 4-30s contiguously — 30 is the probed ceiling (31 was rejected)", () => {
@@ -101,9 +105,13 @@ describe("seedance-2-5 pricing identifiers", () => {
     }
   })
 
+  it("prices 1080p at its own tier — a supported resolution must never clamp away", () => {
+    expect(build(8, "1080p")).toBe("seedance-2-5:8s:1080p")
+    expect(build(30, "1080p")).toBe("seedance-2-5:30s:1080p")
+  })
+
   it("clamps an unsupported resolution to the top real tier so the id is always seeded", () => {
-    expect(build(8, "1080p")).toBe("seedance-2-5:8s:720p")
-    expect(build(8, "4k")).toBe("seedance-2-5:8s:720p")
+    expect(build(8, "4k")).toBe("seedance-2-5:8s:1080p")
   })
 
   it("selects the cheaper -ref ladder when a reference video is wired", () => {
@@ -114,7 +122,7 @@ describe("seedance-2-5 pricing identifiers", () => {
   it("resolves every catalog duration x resolution x ref-mode to a distinct tier", () => {
     const seen = new Set<string>()
     for (const d of MODEL_CATALOG[ID].durations!) {
-      for (const res of ["480p", "720p"]) {
+      for (const res of ["480p", "720p", "1080p"]) {
         for (const ref of [false, true]) {
           const identifier = build(d, res, ref)
           expect(identifier).toBe(`${ID}:${d}s:${res}${ref ? "-ref" : ""}`)
@@ -122,7 +130,7 @@ describe("seedance-2-5 pricing identifiers", () => {
         }
       }
     }
-    // 27 durations x 2 resolutions x 2 ref-modes, none collapsing onto another.
-    expect(seen.size).toBe(108)
+    // 27 durations x 3 resolutions x 2 ref-modes, none collapsing onto another.
+    expect(seen.size).toBe(162)
   })
 })

package/src/effective-tier.ts

@@ -0,0 +1,72 @@
+/**
+ * Effective-tier resolution — the payg derivation.
+ *
+ * "payg" is a DERIVED tier, never stored: a user whose stored tier resolves
+ * to "free" but who has NET lifetime top-up credits (granted − refunded,
+ * clamped ≥ 0 by every SQL writer) is treated as "payg" by entitlement
+ * checks. Stored tier stays untouched, so subscription webhooks never learn
+ * about payg and a cancel→free transition re-derives it automatically.
+ *
+ * Lives in @nodaro/shared because the pipeline tier maps already do, and
+ * both backend (credit gates, workers) and read surfaces need one source.
+ *
+ * The profile fields are REQUIRED (non-optional) on purpose: a call site
+ * whose SELECT forgot to fetch `lifetime_topup_credits` becomes a compile
+ * error instead of a silent `?? 0` that quietly deactivates payg — that is
+ * the failure mode this shape exists to prevent.
+ */
+
+/** Stored-tier resolution — mirrors SQL COALESCE(tier, subscription_tier, 'free'). */
+export function resolveStoredTier(p: {
+  tier: string | null
+  subscription_tier: string | null
+}): string {
+  return p.tier ?? p.subscription_tier ?? "free"
+}
+
+/**
+ * Effective tier: stored "free" with NET lifetime top-ups > 0 derives "payg".
+ * Every other stored tier passes through untouched.
+ */
+export function resolveEffectiveTier(p: {
+  tier: string | null
+  subscription_tier: string | null
+  lifetime_topup_credits: number
+}): string {
+  const stored = resolveStoredTier(p)
+  if (stored === "free" && p.lifetime_topup_credits > 0) return "payg"
+  return stored
+}
+
+/** Media-retention activity window for payg users (design 2026-07-05 §4.6). */
+export const PAYG_RETENTION_DAYS = 90
+
+/**
+ * Is this payg user inside their retention-activity window?
+ *
+ * Activity = credit SPEND (callers supply MAX(usage_logs.created_at) — never
+ * `last_daily_reset`, which read-only balance polls bump) OR a top-up
+ * PURCHASE (`last_topup_at`). Within PAYG_RETENTION_DAYS of either → the
+ * nightly reaper leaves their media alone; past it, the standard free-tier
+ * reaper rules apply. A user with no lifetime purchases is never
+ * retention-active (they are not payg).
+ */
+export function isPaygRetentionActive(
+  p: {
+    lifetimeTopupCredits: number
+    lastTopupAt: string | Date | null
+    lastSpendAt: string | Date | null
+  },
+  now: Date
+): boolean {
+  if (p.lifetimeTopupCredits <= 0) return false
+  const cutoff = now.getTime() - PAYG_RETENTION_DAYS * 24 * 60 * 60 * 1000
+  const at = (v: string | Date | null): number | null => {
+    if (v === null) return null
+    const t = v instanceof Date ? v.getTime() : new Date(v).getTime()
+    return Number.isFinite(t) ? t : null
+  }
+  const topup = at(p.lastTopupAt)
+  const spend = at(p.lastSpendAt)
+  return (topup !== null && topup >= cutoff) || (spend !== null && spend >= cutoff)
+}

package/src/entity-image-handle.ts

@@ -19,11 +19,41 @@ export const ENTITY_IMAGE_HANDLE_TYPES: ReadonlySet<string> = new Set([
   "creature",
 ])
 
+/**
+ * Aggregate node types (Group / Collect) whose source handles are typed LANES
+ * — `out-text` / `out-image` / `out-video` / `out-audio` — each emitting that
+ * media type. Like an entity's `image` handle, a wire leaving a lane is a plain
+ * producer of that lane's type, so it must reach the typed inputs of every
+ * consumer (Image Collage, Combine Videos, Merge Lists, prompts, …) exactly as
+ * an upload node of that type would. Neither node type is in any producer set
+ * itself: the NODE emits nothing, its LANES do.
+ */
+export const AGGREGATE_LANE_SOURCE_TYPES: ReadonlySet<string> = new Set(["group", "collect"])
+
+/**
+ * The plain producer each aggregate lane behaves as. `upload-*` are the
+ * canonical single-media producers present in every typed accepts set
+ * (IMAGE/VIDEO/AUDIO_PRODUCER_TYPES). `out-text` maps to `list`, not
+ * `text-prompt`: the lane is a LIST of texts, so it must reach both prompt
+ * inputs (TEXT_PRODUCER_TYPES) and the list consumers (Merge Lists / Sort /
+ * Dedup / Selector — LIST_PRODUCER_TYPES), exactly like a List text column.
+ * (`list` is also a DYNAMIC producer, so the text lane is admitted at media
+ * inputs too — the same latitude a List column already has on canvas.)
+ */
+const AGGREGATE_LANE_EFFECTIVE_TYPE: Readonly<Record<string, string>> = {
+  "out-image": "upload-image",
+  "out-video": "upload-video",
+  "out-audio": "upload-audio",
+  "out-text": "list",
+}
+
 /**
  * The effective output TYPE a given source handle emits. Returns the raw node
- * type for every `(type, handle)` pair EXCEPT an entity `image` handle, which
- * resolves to `"upload-image"` (a plain image producer). Pure — safe for both
- * frontend and backend.
+ * type for every `(type, handle)` pair EXCEPT:
+ *   - an entity `image` handle → `"upload-image"` (a plain image producer);
+ *   - an aggregate (group / collect) lane handle → the plain producer of that
+ *     lane's media type (see AGGREGATE_LANE_EFFECTIVE_TYPE).
+ * Pure — safe for both frontend and backend.
  */
 export function resolveEffectiveSourceType(
   rawSourceType: string | undefined | null,
@@ -32,6 +62,10 @@ export function resolveEffectiveSourceType(
   if (sourceHandleId === "image" && ENTITY_IMAGE_HANDLE_TYPES.has(rawSourceType ?? "")) {
     return "upload-image"
   }
+  if (AGGREGATE_LANE_SOURCE_TYPES.has(rawSourceType ?? "")) {
+    const effective = AGGREGATE_LANE_EFFECTIVE_TYPE[sourceHandleId ?? ""]
+    if (effective) return effective
+  }
   return rawSourceType ?? ""
 }
 

package/src/group-aggregation.ts

@@ -73,3 +73,35 @@ export function buildChildrenByParent<N extends { id: string; parentId?: string
 export function isCollectInEdge(e: { targetHandle?: string | null }): boolean {
   return (e.targetHandle ?? COLLECT_IN_HANDLE) === COLLECT_IN_HANDLE
 }
+
+/**
+ * The source-pip lanes an aggregate node (Group / Collect) must EXPOSE.
+ *
+ * Bucket contents alone are not enough: buckets are computed from upstream
+ * RESULTS, so before anything ran the node rendered zero source handles — a
+ * pre-authored edge out of the node (MCP-written JSON, import, paste) pointed
+ * at a handle that did not exist and React Flow silently hid it ("connected
+ * in the panel, invisible on canvas"), and there was no pip to drag outward
+ * from. A lane therefore exists when ANY of these hold:
+ *   (a) a wired member / input of that aggregateable type exists (pre-run),
+ *   (b) the bucket for that type has values (post-run),
+ *   (c) an existing outgoing edge references the lane's handle — so an edge
+ *       can never point at a missing handle, whatever state authored it
+ *       (also covers results being cleared after wiring downstream).
+ * Ordered by AGGREGATEABLE_TYPES so the handle layout is stable.
+ */
+export function computeAggregateLanes(
+  nodeId: string,
+  wiredTypes: Iterable<AggregateableType>,
+  buckets: AggregationBuckets,
+  edges: ReadonlyArray<{ source: string; sourceHandle?: string | null }>,
+): AggregateableType[] {
+  const present = new Set<AggregateableType>(wiredTypes)
+  for (const t of presentTypes(buckets)) present.add(t)
+  for (const e of edges) {
+    if (e.source !== nodeId) continue
+    const lane = parseGroupHandle(e.sourceHandle)
+    if (lane) present.add(lane)
+  }
+  return AGGREGATEABLE_TYPES.filter((t) => present.has(t))
+}

package/src/index.ts

@@ -62,6 +62,7 @@ export {
   IMAGE_GEN_PROVIDERS,
   IMAGE_I2I_PROVIDERS,
   IMAGE_EDIT_PROVIDERS,
+  TASK_CHAINED_EDIT_PROVIDERS,
   IMAGE_TO_VIDEO_PROVIDERS,
   TEXT_TO_VIDEO_PROVIDERS,
   VIDEO_GEN_PROVIDERS,
@@ -270,6 +271,7 @@ export {
   parseGroupHandle,
   isCollectInEdge,
   buildChildrenByParent,
+  computeAggregateLanes,
   type AggregateableType,
   type Member,
   type AggregationBuckets,
@@ -540,6 +542,13 @@ export type {
   SharedListing,
 } from "./community.js"
 
+export {
+  resolveStoredTier,
+  resolveEffectiveTier,
+  isPaygRetentionActive,
+  PAYG_RETENTION_DAYS,
+} from "./effective-tier.js"
+
 export {
   NODE_DEFAULT_TYPES,
   validateProviderForNodeType,

package/src/llm-models.ts

@@ -423,6 +423,10 @@ export type LlmFeature =
   | "generate-script"
   | "translate"
   | "image-critic"
+  // Choose Best (reduce) — the pick-best-llm strategy's judge. Its own
+  // feature (not ai-writer, which it used to piggyback on) so the model
+  // default and the tiered credit ids are the strategy's own.
+  | "pick-best-llm"
 
 /** Engine-dependent LlmFeature for the motion-graphics node (design §8: every credit-id site must branch on engine). */
 export function motionGraphicsFeature(engine?: string): LlmFeature {
@@ -446,6 +450,7 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
   "generate-script": "gemini-3.6-flash",
   "translate": "gemini-3.6-flash",
   "image-critic": "claude-sonnet-4.6",
+  "pick-best-llm": "claude-sonnet-4.6",
 }
 
 /**

package/src/model-catalog.ts

@@ -872,6 +872,47 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
     useCases: ["upscale"],
     pricing: [{ identifier: "grok-upscale", credits: 25 }],
   },
+  // Grok Imagine Image 2.0 — t2i plus task-chained region editing. The edit
+  // and segment-map endpoints take a PRIOR grok-2 generation's task id (the
+  // job's `kieTaskId` output), not an image URL — same contract as
+  // grok-upscale (see TASK_CHAINED_EDIT_PROVIDERS in model-constants).
+  "grok-2": {
+    id: "grok-2",
+    kind: "image",
+    modes: ["t2i"] as const,
+    family: "xAI",
+    label: "Grok Imagine 2",
+    series: "Grok",
+    description:
+      "Grok Imagine Image 2.0 — expressive, high-contrast t2i. Generations chain into grok-2-segment (free named region masks) and grok-2-edit (region-targeted edits).",
+    useCases: ["stylized", "expressive", "general"],
+    aspectRatios: GROK_RATIOS,
+    pricing: [{ identifier: "grok-2", credits: 10 }],
+  },
+  "grok-2-edit": {
+    id: "grok-2-edit",
+    kind: "image",
+    modes: ["edit"] as const,
+    family: "xAI",
+    label: "Grok Imagine 2 Edit",
+    series: "Grok",
+    description:
+      "Prompt-edit a prior grok-2 generation by task id. Optional mask indexes (from grok-2-segment) restrict the edit to named regions.",
+    useCases: ["edit", "region-edit"],
+    pricing: [{ identifier: "grok-2-edit", credits: 10 }],
+  },
+  "grok-2-segment": {
+    id: "grok-2-segment",
+    kind: "image",
+    modes: ["edit"] as const,
+    family: "xAI",
+    label: "Grok Imagine 2 Segment Map",
+    series: "Grok",
+    description:
+      "FREE semantic segment map of a prior grok-2 generation — named region masks whose indexes feed grok-2-edit's region targeting.",
+    useCases: ["segmentation", "region-edit"],
+    pricing: [{ identifier: "grok-2-segment", credits: 0, note: "free" }],
+  },
 
   // ── Utilities ──
   "recraft-remove-bg": {
@@ -1354,7 +1395,8 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   },
   // Seedance 2.5 — the next Seedance generation, not a tier of the 2.0 ladder.
   // Two levers differ from every 2.0 SKU and drive its own entries throughout:
-  // durations run to 30s (2.0 caps at 15s) and there is NO 1080p/4K tier.
+  // durations run to 30s (2.0 caps at 15s) and there is NO 4K tier (1080p
+  // arrived on KIE 2026-08-17 — probe-verified; 4k/2k/1440p still rejected).
   // Reference caps are also wider (30 images / 10 videos / 10 audio) — see
   // SEEDANCE_2_5_REF_LIMITS in model-constants.
   "seedance-2-5": {
@@ -1364,20 +1406,23 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     family: "Bytedance",
     label: "Seedance 2.5",
     series: "Seedance",
-    description: "Seedance 2.5 — up to 30s in one shot, native audio, wide multimodal references. 480p/720p.",
+    description: "Seedance 2.5 — up to 30s in one shot, native audio, wide multimodal references. 480p/720p/1080p.",
     useCases: ["premium", "narrative", "long-form"],
     features: ["end-frame", "audio", "reference-image", "video-reference"],
     aspectRatios: VIDEO_RATIOS_SEEDANCE_2,
     durations: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30],
-    resolutions: ["480p", "720p"],
+    resolutions: ["480p", "720p", "1080p"],
     pricing: [
       { identifier: "seedance-2-5", credits: 1260, note: "default 8s 720p — see :Ns:res variants for exact" },
       { identifier: "seedance-2-5:8s:480p", credits: 560, note: "8s 480p" },
       { identifier: "seedance-2-5:8s:720p", credits: 1260, note: "8s 720p" },
+      { identifier: "seedance-2-5:8s:1080p", credits: 2280, note: "8s 1080p" },
       { identifier: "seedance-2-5:8s:480p-ref", credits: 340, note: "8s 480p with reference video" },
       { identifier: "seedance-2-5:8s:720p-ref", credits: 760, note: "8s 720p with reference video" },
+      { identifier: "seedance-2-5:8s:1080p-ref", credits: 1370, note: "8s 1080p with reference video" },
       { identifier: "seedance-2-5:30s:480p", credits: 2100, note: "30s 480p (max)" },
       { identifier: "seedance-2-5:30s:720p", credits: 4730, note: "30s 720p (max)" },
+      { identifier: "seedance-2-5:30s:1080p", credits: 8550, note: "30s 1080p (max)" },
     ],
   },