@nodaro/shared 1.4.1

package/src/pipeline-events.ts

@@ -0,0 +1,162 @@
+import { z } from "zod"
+import type { EntityStatus, EntityType } from "./entity-approval-types.js"
+import type {
+  EntityStateChangeEvent,
+  EntityStaleEvent,
+  PipelineForkedEvent,
+  PipelineDriftSummary,
+  PipelineCompletedEvent,
+  StageAwaitingSubGateEvent,
+  PipelineMusicReadyEvent,
+  PipelineEditorDecisionsReadyEvent,
+} from "./pipeline-state-types.js"
+// Phase 1D.2b — Guided-mode chat. Type-only import to keep this file at the
+// root of the import graph (pipeline-chat.ts imports PipelineStageName from
+// here, so a value import would be circular).
+import type { ProposedChange } from "./pipeline-chat.js"
+
+/**
+ * Canonical pipeline stage order — Phase 1A→1C topology. The engine's
+ * `runPipeline` walks this list in sequence; tests, the SSE event router,
+ * and the admin-side stage timeline all consume this same tuple as the
+ * source of truth for "which stages exist + in what order".
+ */
+export const PIPELINE_STAGE_NAMES = [
+  "script",
+  "characters",
+  "objects",
+  "locations",
+  "shot_list",
+  "scene_images",
+  "animate_audio_edit",
+  "post_merge",
+] as const
+export const PipelineStageNameSchema = z.enum(PIPELINE_STAGE_NAMES)
+export type PipelineStageName = (typeof PIPELINE_STAGE_NAMES)[number]
+
+export const PipelineStatusSchema = z.enum([
+  "queued",
+  "running",
+  "awaiting_approval",
+  "completed",
+  "failed",
+  "cancelled",
+  "forked",
+])
+export type PipelineStatus = z.infer<typeof PipelineStatusSchema>
+
+export const PipelineStageStatusSchema = z.enum([
+  "pending",
+  "running",
+  "awaiting_approval",
+  "approved",
+  "rejected",
+  "failed",
+  "cancelled",
+])
+export type PipelineStageStatus = z.infer<typeof PipelineStageStatusSchema>
+
+export type PipelineEvent =
+  | { type: "pipeline:status"; pipelineId: string; status: PipelineStatus }
+  | {
+      type: "stage:status"
+      pipelineId: string
+      stageName: PipelineStageName
+      status: PipelineStageStatus
+      output?: unknown
+      criticFeedback?: unknown
+    }
+  | {
+      type: "pipeline:warning"
+      pipelineId: string
+      code: string
+      message: string
+    }
+  | { type: "pipeline:done"; pipelineId: string }
+  | {
+      type: "entity:status"
+      pipelineId: string
+      entityId: string
+      entityType: EntityType
+      entityKey: string
+      status: EntityStatus
+      mainAssetUrl?: string
+    }
+  | {
+      type: "entity:variant:added"
+      pipelineId: string
+      entityId: string
+      variantKey: string
+      assetUrl: string
+    }
+  | {
+      type: "scene:status"
+      pipelineId: string
+      sceneEntityId: string
+      sceneIndex: number
+      status: EntityStatus
+      shotCount?: number
+    }
+  // Phase 1B.4 lifecycle events — see pipeline-state-types.ts for full JSDoc
+  // on when each fires. SSE forwarders in routes/pipelines.ts are
+  // event-type-agnostic and pass all of these through unchanged.
+  | EntityStateChangeEvent
+  | EntityStaleEvent
+  | PipelineForkedEvent
+  | PipelineDriftSummary
+  // Phase 1C.1 — final-MP4 ready event carries the merged asset id + URL.
+  | PipelineCompletedEvent
+  // Phase 1C.2 — Stage 7 sub-gate pause, music ready, editor decisions ready.
+  | StageAwaitingSubGateEvent
+  | PipelineMusicReadyEvent
+  | PipelineEditorDecisionsReadyEvent
+  // Phase 1D.2b — Guided-mode chat. `chat:turn` fires after each LLM round-
+  // trip (user prompt → assistant reply with optional proposed_change). The
+  // event carries the full turn record so the frontend chat history can
+  // render it without an extra GET /chat roundtrip. `chat:proposal_applied`
+  // fires when the user accepts a proposed_change — the turnId + attemptId
+  // let the UI mark the source turn as applied and link to the resulting
+  // stage attempt (re-run output) it produced.
+  | {
+      type: "chat:turn"
+      pipelineId: string
+      stageName: PipelineStageName
+      turn: {
+        id: string
+        turn_n: number
+        role: "user" | "assistant"
+        content: string
+        proposed_change: ProposedChange | null
+      }
+    }
+  | {
+      type: "chat:proposal_applied"
+      pipelineId: string
+      stageName: PipelineStageName
+      turnId: string
+      attemptId: string
+    }
+  // Phase 1D.2c-b-ii — per-shot status emitted by the Stage 7 Video Critic
+  // retry loop. Fires once per shot after the critic finalises (pass or
+  // cap-exhausted fail). The frontend per-shot UI subscribes to update each
+  // shot's badge/banner without re-reading the scene entity.
+  | {
+      type: "shot:status"
+      pipelineId: string
+      sceneId: string
+      shotId: string
+      status: "approved" | "failed"
+    }
+  // LLM-stream narrative progress, emitted by callLLM when a caller passes
+  // an `onProgress` callback. Currently used by the Stage 1 Showrunner so the
+  // pipeline panel can show a live "Drafting plan…" banner instead of a 2-
+  // minute spinner. The `message` is human-readable; `bytesSoFar` is a coarse
+  // proxy for stream progress (cumulative tool-use JSON delta bytes) that the
+  // frontend may format into a percent or just ignore.
+  | {
+      type: "stage:progress"
+      pipelineId: string
+      stageName: PipelineStageName
+      message: string
+      bytesSoFar?: number
+    }

package/src/pipeline-state-types.ts

@@ -0,0 +1,196 @@
+import { z } from "zod"
+
+/**
+ * Phase 1B.4 — pipeline_state lifecycle + drift event types.
+ *
+ * `pipeline_state` lives on `pipeline_entity_nodes.pipeline_state` (migration
+ * 131). Mirrors the four-value CHECK constraint there.
+ *
+ * `pipeline_owned_running`           — node belongs to the pipeline, work in flight
+ * `pipeline_owned_awaiting_approval` — node belongs to the pipeline, user is the gate
+ * `pipeline_owned_approved`          — node belongs to the pipeline, work locked in
+ * `pipeline_orphaned`                — pipeline released ownership (cancel / fork / fail);
+ *                                      node survives so the user keeps the work
+ */
+export const PipelineStateSchema = z.enum([
+  "pipeline_owned_running",
+  "pipeline_owned_awaiting_approval",
+  "pipeline_owned_approved",
+  "pipeline_orphaned",
+])
+export type PipelineState = z.infer<typeof PipelineStateSchema>
+
+/**
+ * Emitted when a pipeline_entity_nodes row transitions to a new
+ * `pipeline_state`. Fires on:
+ *   - stage transitioning to 'awaiting_approval' (per-entity batch)
+ *   - approveEntity success
+ *   - rejectEntity regenerate path
+ *   - force-stop / fork orphaning (every entity at once)
+ *
+ * Frontend swaps node visuals (running glow → awaiting frame → approved chip)
+ * based on the new state.
+ */
+export const EntityStateChangeEventSchema = z.object({
+  type: z.literal("entity:state_change"),
+  pipelineId: z.string(),
+  pipelineEntityId: z.string(),
+  newState: PipelineStateSchema,
+})
+export type EntityStateChangeEvent = z.infer<typeof EntityStateChangeEventSchema>
+
+/**
+ * Emitted when a `pipeline_entities.is_stale` flag flips to true via the
+ * cascade staleness trigger (migration 131). Triggered after a `main_asset_id`
+ * update on an upstream entity; the trigger marks every transitive dependent
+ * stale, and the engine emits one event per dependent.
+ *
+ * Frontend overlays a "Stale — needs regenerate" warning on the affected
+ * canvas nodes.
+ */
+export const EntityStaleEventSchema = z.object({
+  type: z.literal("entity:stale"),
+  pipelineId: z.string(),
+  pipelineEntityId: z.string(),
+  reason: z.enum(["upstream_changed", "user_edit", "manual"]).optional(),
+})
+export type EntityStaleEvent = z.infer<typeof EntityStaleEventSchema>
+
+/**
+ * Emitted when a pipeline is force-stopped / forked. Carries the prior status
+ * (`forked_status`) so the UI can render "Forked from approval" vs "Forked
+ * mid-Stage-5" copy. The companion `entity:state_change` flurry that orphans
+ * every node lands in the same SSE batch.
+ */
+export const PipelineForkedEventSchema = z.object({
+  type: z.literal("pipeline:forked"),
+  pipelineId: z.string(),
+  forkedAt: z.string(), // ISO timestamp
+  forkedStatus: z.string(),
+  forkReason: z.string().optional(),
+})
+export type PipelineForkedEvent = z.infer<typeof PipelineForkedEventSchema>
+
+/**
+ * Section H drift summary — when the engine pauses a stage at
+ * 'awaiting_approval' because user edits on the canvas diverged from the
+ * pipeline's recorded state, this payload is attached to the
+ * `pipeline_stages.awaiting_reason='canvas_drift'` row so the UI can render
+ * the DriftBanner with actionable diffs.
+ *
+ * Carried inside a `stage:status` event (or a future dedicated event); kept
+ * as a standalone schema so callers can validate the drift payload
+ * independently.
+ */
+export const PipelineDriftSummarySchema = z.object({
+  type: z.literal("pipeline:drift"),
+  pipelineId: z.string(),
+  stageName: z.string(),
+  driftedEntityIds: z.array(z.string()),
+  summary: z.string().optional(),
+})
+export type PipelineDriftSummary = z.infer<typeof PipelineDriftSummarySchema>
+
+/**
+ * Phase 1C.1 — emitted by Stage 8 (post_merge) when the pipeline reaches the
+ * `completed` terminal state. Carries the final merged-MP4 asset id + URL so
+ * the SSE consumer can render the player without an extra round-trip.
+ *
+ * Distinct from the legacy `pipeline:done` lifecycle event (which carries no
+ * payload). SSE forwarders close on either type.
+ */
+export const PipelineCompletedEventSchema = z.object({
+  type: z.literal("pipeline:completed"),
+  pipelineId: z.string(),
+  finalOutputAssetId: z.string().uuid().nullable(),
+  finalOutputUrl: z.string(),
+})
+export type PipelineCompletedEvent = z.infer<typeof PipelineCompletedEventSchema>
+
+/**
+ * Phase 1C.2 — Sub-gate names. Stage 7 (animate_audio_edit) and Stage 6
+ * (scene_images) can pause at one of these mid-stage gates before resuming
+ * the rest of the stage; the gate name is persisted on
+ * `pipeline_stages.output.current_sub_gate` (JSONB) so a resumed orchestrator
+ * picks up at the right step.
+ *
+ *   `silent_cut_preview`       — Stage 7: Editor LLM has emitted cut_decisions;
+ *                                user reviews the preview reel before the
+ *                                per-shot trims commit.
+ *   `dialogue_recheck`         — Stage 7: A re-recorded dialogue line shifted
+ *                                the dialogue_no_cut_zone; user confirms the
+ *                                new cuts still respect the zone.
+ *   `match_cut_break_pending`  — Stage 6: MatchCutCritic found one or more
+ *                                match-cut shot pairs with `match_strength =
+ *                                "break"`. User must accept each break (sets
+ *                                `accepted_match_cut_break=true` on the shot)
+ *                                before Stage 7 can animate those pairs.
+ */
+export const SubGateNameSchema = z.enum([
+  "silent_cut_preview",
+  "dialogue_recheck",
+  "match_cut_break_pending",
+])
+export type SubGateName = z.infer<typeof SubGateNameSchema>
+
+/**
+ * Phase 1C.2 — emitted when Stage 6 (scene_images) or Stage 7
+ * (animate_audio_edit) pauses at a sub-gate. Carries an optional `payload`
+ * (JSONB-shaped) for whatever the gate needs to render — e.g. the preview
+ * reel URL, the affected shot ids, or the pending-break list.
+ *
+ * Distinct from `stage:status awaiting_approval` (which is the top-level
+ * stage gate). Sub-gates stash `current_sub_gate` on the stage output AND
+ * flip `status = "awaiting_approval"` so the pipeline engine waits.
+ */
+export const StageAwaitingSubGateEventSchema = z.object({
+  type: z.literal("stage:awaiting_sub_gate"),
+  pipelineId: z.string().uuid(),
+  stageName: z.enum(["animate_audio_edit", "scene_images"]),
+  subGate: SubGateNameSchema,
+  payload: z.record(z.unknown()).optional(),
+})
+export type StageAwaitingSubGateEvent = z.infer<typeof StageAwaitingSubGateEventSchema>
+
+/**
+ * Phase 1C.2 — emitted when the music_timeline build step (Stage 7 sibling)
+ * has produced the merged music track + beat grid. The SSE consumer can
+ * render the music waveform + beat markers without an extra round-trip.
+ */
+export const PipelineMusicReadyEventSchema = z.object({
+  type: z.literal("pipeline:music_ready"),
+  pipelineId: z.string().uuid(),
+  musicAssetUrl: z.string().url(),
+  beatGridLength: z.number(),
+})
+export type PipelineMusicReadyEvent = z.infer<typeof PipelineMusicReadyEventSchema>
+
+/**
+ * Phase 1C.2 — emitted when the Editor LLM has produced cut_decisions for
+ * every shot in the pipeline. Frontend can render the silent-cut-preview UI
+ * (timeline + accept/reject) once this fires. Payload is intentionally
+ * minimal — the decisions are persisted on the shots' `cut_decision` field
+ * and the `editor_decisions` audit table.
+ */
+export const PipelineEditorDecisionsReadyEventSchema = z.object({
+  type: z.literal("pipeline:editor_decisions_ready"),
+  pipelineId: z.string().uuid(),
+})
+export type PipelineEditorDecisionsReadyEvent = z.infer<
+  typeof PipelineEditorDecisionsReadyEventSchema
+>
+
+/**
+ * Union of the Phase 1B.4 + 1C.1 + 1C.2 lifecycle event payloads. The broader
+ * `PipelineEvent` union in `pipeline-events.ts` extends this so SSE
+ * forwarders accept all of them transparently.
+ */
+export type PipelineLifecycleEvent =
+  | EntityStateChangeEvent
+  | EntityStaleEvent
+  | PipelineForkedEvent
+  | PipelineDriftSummary
+  | PipelineCompletedEvent
+  | StageAwaitingSubGateEvent
+  | PipelineMusicReadyEvent
+  | PipelineEditorDecisionsReadyEvent