# 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.