Phase 21H - Book-Level Story Intelligence Import Sessions

Purpose

Phase 21H changes the Story Intelligence Experience from following one chapter run to following one book-level import session.

The implementation reuses the existing StoryIntelligenceBookPipelines table as the import-session abstraction. A session represents one project/book and owns the visualisation state across many chapter runs.

Architecture

The browser now opens the visualisation with:

/Development/StoryIntelligenceExperience?importSessionId={StoryIntelligenceBookPipelineID}

The snapshot endpoint is:

/api/story-intelligence/import-sessions/{importSessionId}/visualisation-snapshot

The older run route remains available temporarily:

/Development/StoryIntelligenceExperience?runId={runId}

and:

/api/story-intelligence/runs/{runId}/visualisation-snapshot

This preserves compatibility while moving the development selector and live visualisation to sessions.

Relationship To Chapter Runs

A session is backed by StoryIntelligenceBookPipelines.

Chapter analysis still creates normal StoryIntelligenceRuns. The session snapshot gathers all runs for the session book, orders them by chapter order, and builds one continuous visualisation. The browser does not need to know which chapter run is currently active.

Newly queued chapter runs update the book pipeline to InProgress, and historical runs are backfilled into session rows by the Phase 21H SQL migration.

Snapshot Changes

The new session snapshot:

loads the import session by StoryIntelligenceBookPipelineID
loads all chapter runs for the session book
parses scene results from every run
skips malformed scene results without blocking later valid results
selects the active run as the first non-terminal chapter run, falling back to the latest parsed run
produces one scene list across the whole book
keeps RunId only as a diagnostic/current-active-run field

Progress Calculation

Progress is now based on the aggregate book view:

scenes analysed: parsed scene results across all session runs
scenes detected: sum of detected/persisted scene counts across all session runs
chapters analysed: terminal chapter runs
chapter total: known chapter runs in the session
percentage: aggregate scenes analysed divided by aggregate scenes detected

Progress reaches 100% only when the import session is complete.

Completion Rules

Polling stops only when the import session snapshot is terminal. A completed chapter run no longer stops the visualisation. The session is terminal when all known chapter runs are terminal and the book pipeline status is Complete.

Migration Strategy

The migration backfills StoryIntelligenceBookPipelines for books that already have Story Intelligence runs. Existing chapter runs are not modified or orphaned. Current and future queue paths record the book pipeline as InProgress when a chapter run is queued.

Future Production Integration

The current implementation is still development-facing. A production version should introduce explicit user-facing import-session screens, richer chapter totals from the actual book outline, and SignalR events keyed by import session rather than chapter run.

3.2 KiB Raw Blame History