dsh-novel-write-engine 0.2.7 → 0.2.9

package/lib/index.d.ts

@@ -217,6 +217,18 @@ interface WordMetrics {
   paragraph_count: number;
   paragraph_max_words: number;
 }
+/** Protected evidence copied from the archived outline card at archive time. */
+interface ArchivedCardSnapshot {
+  title: string;
+  scene_type: SceneType;
+  target_words: [number, number];
+  cast: string[];
+  goal: string;
+  conflict: string;
+  hook: string;
+  notes: string;
+  archived_at: string | null;
+}
 /** Derived chapter row kept in `state/chapters.yaml`. */
 interface ChapterRecord {
   num: number;
@@ -239,6 +251,10 @@ interface ChapterRecord {
   assigned_ids?: Record<string, string>;
   /** Digest of the archive request that produced this row. */
   archive_digest?: string;
+  /** Immutable card fields written by the archive transaction, not by amend. */
+  archive_card?: ArchivedCardSnapshot;
+  /** Canonical digest of archive_card; v1-prefixed like archive_digest. */
+  archive_card_digest?: string;
 }
 /** Summary block the model supplies with a draft and the engine persists. */
 interface ChapterSummary {
@@ -301,8 +317,8 @@ interface CharacterDelta {
   role?: string;
   profile?: Record<string, unknown>;
   current_state?: Record<string, unknown>;
+  /** Chapter is engine-assigned from the archive transaction, not caller-supplied. */
   growth?: {
-    chapter: number;
     change: string;
     status_change: string;
   };
@@ -760,7 +776,7 @@ interface BookReport {
     target: number | null;
     words: number;
     average_words: number;
-    percent: number;
+    percent: number | null;
     remaining_words: number | null;
     remaining_words_min: number | null;
     remaining_words_average: number | null;
@@ -825,6 +841,7 @@ interface BookReport {
       id: string;
       average: number;
       samples: number;
+      max: number;
     }>;
   };
   /** Per-chapter effort survives archive (pipeline rounds are reset). */
@@ -972,6 +989,8 @@ interface GateInput {
   briefStage: BriefStage | null;
   draftTitle: string | null;
   sceneType: SceneType | null;
+  /** The submitted/active plan narrator; PG-05 uses it before a draft exists. */
+  narrator?: string | null;
   summary: ChapterSummary | null;
   /** P5 may omit `summary`; when omitted, the previous plan summary is reused. */
   summaryProvided?: boolean;
@@ -1034,6 +1053,36 @@ interface Selection {
   title?: string;
   created_at?: string;
 }
+/**
+ * One human-readable projection of the pipeline's chapter boundary.
+ *
+ * `pipeline.chapter`/`stage` are protocol values: after archiving chapter N the
+ * pipeline points at N+1 and still says `done` because `done` describes the
+ * chapter that was just archived. This projection is the only place that turns
+ * those values into "chapter N archived; chapter N+1 starts at P1".
+ */
+interface ChapterProgress {
+  active_chapter: number;
+  stage: Stage;
+  /** The chapter currently being written; null while `stage === 'done'`. */
+  current: {
+    chapter: number;
+    stage: Stage;
+  } | null;
+  /** Highest archived chapter, or null before the first archive. */
+  last_archived: number | null;
+  /** Next chapter to start at P1; null while writing or after the book is finished. */
+  next: {
+    chapter: number;
+    stage: 'P1';
+  } | null;
+  /** True only when the configured target has been reached at `stage === 'done'`. */
+  finished: boolean;
+  /** One line for status cards, commands and the panel. */
+  label: string;
+  /** Sentence used by the resume prompt instead of "当前第 N 章，阶段 done". */
+  resume: string;
+}
 /** The `getStatus` payload. */
 interface StatusReport {
   project: {
@@ -1054,6 +1103,8 @@ interface StatusReport {
   /** SHA-256 of the active manuscript, or null when the stage has no draft. */
   manuscript_hash: string | null;
   stage: Stage;
+  /** Chapter-boundary projection shared by every human-readable surface. */
+  progress?: ChapterProgress;
   rounds: RoundCounters;
   blocking: BlockingItem[];
   /** Non-blocking recovery notes, e.g. a recoverable pending transaction. */
@@ -1106,6 +1157,8 @@ interface StatusReport {
 interface AdviceReport {
   stage: Stage;
   chapter: number;
+  /** Same chapter-boundary projection as getStatus. */
+  progress?: ChapterProgress;
   tool: string;
   args: Record<string, unknown>;
   reason: string;
@@ -1283,9 +1336,17 @@ interface Rulepack {
     words_per_chapter: [number, number];
     dialogue_ratio: [number, number];
   }>;
-  /** Genre guides injected into the task-book context; no threshold branches on them. */
+  /** Genre guides plus optional advisory-only threshold profiles. */
   genres: Record<Genre, {
     note: string;
+    profile?: {
+      period_density?: {
+        min: number;
+        max: number;
+      };
+      water_words?: number;
+      pleasure_density?: number;
+    };
   }>;
   crosschapter: {
     duplicate_similarity: number;
@@ -1483,7 +1544,7 @@ interface PanelBookData {
     average_words: number;
     remaining_words: number | null;
     remaining_words_basis: 'actual_average' | 'minimum_target' | 'none';
-    percent: number;
+    percent: number | null;
   };
   current: {
     card: PanelCardData | null;
@@ -1531,7 +1592,7 @@ interface PanelBookData {
     median: number;
     min: number;
     max: number;
-    last_ten_average: number;
+    last_ten_average: number | null;
     trend: number | null;
     trend_basis: BookReport['quality']['trend_basis'];
     samples: number;
@@ -1566,7 +1627,7 @@ interface PanelDraft {
   num: number;
   title: string;
   wordCount: number;
-  score: number;
+  score: number | null;
   status: 'draft' | 'blocked';
   details: string;
 }
@@ -1577,6 +1638,8 @@ interface PanelSnapshot {
   platform: string;
   chapter: number;
   stage: Stage;
+  /** Chapter-boundary projection; `chapter`/`stage` stay as the protocol pair. */
+  progress?: ChapterProgress;
   revision: number;
   rounds: {
     review: number;
@@ -1595,8 +1658,12 @@ interface PanelSnapshot {
   chapters: ChapterRecord[];
   /** The active, not-yet-archived chapter; archived rows come from `chapters`. */
   draft?: PanelDraft | null;
-  /** Total words across the index, for the header. */
+  /** Archived words plus the active draft; the header shows this total. */
   totalWords: number;
+  /** Words in archived chapters only. */
+  archivedWords?: number;
+  /** Active draft words, zero when no draft exists. */
+  draftWords?: number;
   /** Book-wide archived average, not just the panel's capped rows. */
   averageScore?: number;
   /** The nine-phase strip state, derived from the pipeline stage. */
@@ -1609,6 +1676,7 @@ interface PanelSnapshot {
   book?: PanelBook;
   quality?: {
     averageScore: number;
+    last_ten_average?: number | null;
     scores: number[];
     trend: number | null;
     trend_basis?: 'last_five_vs_previous_five' | 'insufficient_samples' | 'insufficient_history';
@@ -1694,8 +1762,14 @@ interface PanelSummaryDto {
   platform: string;
   chapter: number;
   stage: Stage;
+  /** Chapter-boundary projection; absent on older payloads. */
+  progress?: ChapterProgress;
   revision: number;
   totalWords: number;
+  /** Words in archived chapters only; `totalWords` also counts the active draft. */
+  archivedWords?: number;
+  /** Active draft words, zero when no draft exists. */
+  draftWords?: number;
   totalChapters: number;
   /** Book-wide archived average; absent on older payloads. */
   averageScore?: number;
@@ -1719,6 +1793,7 @@ interface PanelSummaryDto {
   book?: PanelBook;
   quality?: {
     averageScore: number;
+    last_ten_average?: number | null;
     scores: number[];
     trend: number | null;
     trend_basis?: 'last_five_vs_previous_five' | 'insufficient_samples' | 'insufficient_history';
@@ -1763,7 +1838,7 @@ interface PanelChapterRow {
   num: number;
   title: string;
   wordCount: number;
-  score: number;
+  score: number | null;
   stage: Stage;
   status: 'passed' | 'blocked' | 'draft';
   /** One-line summary shown when the row is expanded. */
@@ -1812,12 +1887,25 @@ interface PanelMissing {
   reason: 'missing' | 'not-project' | 'damaged' | 'not_registered' | 'unreadable' | 'busy';
   hint: string;
 }
+/** Additive v7 sections; the v6 bundle stays unchanged for old tabs. */
+type PanelSectionName = 'overview' | 'chapters' | 'characters' | 'foreshadows' | 'timeline' | 'relationships' | 'worldbook' | 'quality' | 'quality_detail' | 'health' | 'chapter_detail';
+interface PanelSectionMeta {
+  payload_version: 7;
+  section: PanelSectionName;
+  items: unknown;
+  total: number;
+  returned: number;
+  truncated: boolean;
+  next_cursor: string | null;
+  updated_at: string;
+  etag: string;
+}
 interface PanelBundle {
   projects: PanelProjectOption[];
   selection: PanelSelection;
   summary?: PanelSummaryDto;
   chapters?: PanelChaptersDto;
-  gates?: PanelGatesDto;
+  etag?: string;
   resume?: {
     text: string;
   };
@@ -1825,12 +1913,27 @@ interface PanelBundle {
   empty?: true;
   error?: string;
 }
+interface ChapterProgressInput {
+  activeChapter: number;
+  stage: Stage;
+  archived: readonly number[];
+  target: number | null;
+}
+/**
+ * Turn the protocol pair (`chapter` + `stage`) into the only human-readable
+ * chapter boundary. After archiving chapter N the protocol intentionally keeps
+ * `stage: 'done'` and advances `chapter` to N+1; `done` describes chapter N,
+ * not the chapter the pipeline now points at.
+ */
+declare function projectChapterProgress(input: ChapterProgressInput): ChapterProgress;
 interface ResumePromptInput {
   title: string;
   root: string;
   chapter: number | string;
   stage: string;
   nextTool: string;
+  /** When supplied, replaces the protocol pair with the chapter boundary text. */
+  progress?: ChapterProgress;
 }
 /** One shared prompt template for `/novel resume` and the panel copy button. */
 declare function formatResumePrompt(input: ResumePromptInput): string;
@@ -1933,6 +2036,15 @@ type EngineEvent = {
     files: number;
   };
 };
+interface PanelSectionQuery {
+  search?: string;
+  status?: string;
+  scene?: string;
+  sort?: string;
+  cursor?: string;
+  limit?: number;
+  chapter?: number;
+}
 interface InitProjectInput {
   title: string;
   genre: NovelProject['genre'];
@@ -2151,6 +2263,10 @@ declare class EngineService {
   private readonly briefContextCache;
   /** The 15s panel poll reuses the heavy book projection until revision/damage changes. */
   private readonly panelCache;
+  /** Section-level cache; writes bump revision, so a stale entry cannot survive a commit. */
+  private readonly sectionCache;
+  private readonly journalCache;
+  private readonly reviewKeyCache;
   private readonly briefs;
   private readonly now;
   private readonly metadataMutex;
@@ -2298,6 +2414,7 @@ declare class EngineService {
   }): Promise<OpResult<{
     stage: Stage;
     chapter: number;
+    progress: ChapterProgress;
     tool: string;
     args: Record<string, unknown>;
     reason: string;
@@ -2400,6 +2517,21 @@ declare class EngineService {
   panelGates(input?: {
     root?: string;
   }): Promise<PanelGatesDto>;
+  /**
+   * Additive v7 section read model. Catalog sections reuse the Snapshot; only
+   * the quality section reads archived reviews, and only chapter/quality
+   * detail reads manuscripts or check files. Every section is byte-capped.
+   */
+  panelSection(input?: {
+    root?: string;
+    section: PanelSectionName;
+    query?: PanelSectionQuery;
+  }): Promise<PanelSectionMeta>;
+  private panelSectionPage;
+  private panelSectionReturned;
+  /** WP3.7 free-text caps before the byte budget; both report truncation. */
+  private panelSectionClip;
+  private panelSectionBudget;
   /**
    * Build the read-only panel payload. The query root is accepted only when it
    * is registered, active or the configured root; arbitrary paths never reach
@@ -2407,6 +2539,7 @@ declare class EngineService {
    */
   panelBundle(input?: {
     root?: string;
+    lean?: boolean;
   }): Promise<PanelBundle>;
   /** Read-only resume text shared with the panel copy button. */
   resumePrompt(input?: {
@@ -2419,6 +2552,8 @@ declare class EngineService {
     root?: string;
   }): Promise<{
     totalWords: number;
+    archivedWords: number;
+    draftWords: number;
     chapters: number;
     revision: number;
     rulepack: string;
@@ -2434,6 +2569,8 @@ declare class EngineService {
     worldbookEntries: number;
     strictOutline: boolean;
     targetChapters: number | null;
+    state_errors: StateError[];
+    partial: boolean;
   }>;
   private registry;
   /** List known projects with a cheap directory state for the panel/command. */
@@ -2586,6 +2723,8 @@ declare class EngineService {
    */
   private assertArchiveIndexReadable;
   private bookStatus;
+  private panelReviewKey;
+  private panelJournalIdentity;
   private panelSnapshot;
   /**
    * The archive stage can be left by a direct revision (the 0.2.3 workflow) or
@@ -2673,6 +2812,8 @@ declare const PANEL_ID = "novel-workshop";
 declare const PANEL_ROUTE = "/api/novel-write-engine/panel";
 declare const SKILL_NAME = "novel-write-engine";
 declare const REMOTE_VERSION = 6;
+/** User-visible panel/tutorial version; keep in sync with package.json. */
+declare const PANEL_VERSION = "0.2.9";
 /** The panel is a recent-history view; the wire payload and UI use one cap. */
 declare const PANEL_CHAPTER_LIMIT = 30;
 /** Project-relative locations. Every write goes through these constants. */
@@ -2805,4 +2946,4 @@ declare const Config: Schema<Config>;
  * created lazily per project root.
  */
 declare function apply(ctx: Context, config: Config): void;
-export { ARCHIVE_DIGESTS_FILE, AdviceReport, ArchiveHandoff, AuditRow, BACKUP_DIR, BRIEF_RECEIPTS_FILE, BlockingItem, BookPlan, BookReport, BriefDocument, BriefLibrary, BriefReceipt, BriefReceiptsDocument, BriefStage, CHAPTERS_DIR, CHECK_DIR, CORE_TOOLS, ChapterCastMember, ChapterPlanInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, DEFAULT_GENRE, DEFAULT_PLATFORM, Deduction, DeltaAction, DiffReport, DoctorCheck, DoctorReport, DraftInput, DraftState, ERROR_CODES, EXPORT_DIR, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, GuideReport, GuideStep, HISTORY_DIR, HISTORY_KINDS, HandoffDocument, HistoryKind, INITIAL_STAGE, LIMITS, LOCK_FILE, LocksDocument, METADATA_LOCK_FILE, MachineMetrics, NovelProject, OPERATIONS, OUTLINE_DEPRECATED_FILE, OUTLINE_DIR, OUTLINE_FILE, OpResult, Operation, OutlineChapter, OutlineDocument, OutlineProgress, OutlineVolume, PANEL_CHAPTER_LIMIT, PANEL_ID, PANEL_ROUTE, PHASE_STRIP, PLAN_DIR, PLATFORMS, PLUGIN_NAME, PROJECT_FILE, PanelBook, PanelBundle, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelMissing, PanelProjectOption, PanelSelection, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, REGISTRY_FILE, REMOTE_VERSION, REVIEW_DIR, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ResumePromptInput, ReviewDocument, ReviewInput, ReviewIssue, RevisionEdit, RevisionInput, RevisionPatch, RoundCounters, SCENE_TYPES, SCENE_TYPE_DEFAULT, SCHEMA_VERSION, SESSION_BINDINGS_FILE, SKILL_NAME, STAGING_DIR, STATE_DIR, STATE_FILES, SceneType, ScoreDimension, SearchReport, SearchResultItem, Selection, SelectionSource, SemanticItem, Severity, Stage, StateDelta, StateError, StateErrorCode, StatusReport, TOOL_NAMES, TimelineDelta, TimelineDocument, ToolName, Violation, WORLDBOOK_FILE, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, WorldbookBackstory, WorldbookCharacter, WorldbookDocument, WorldbookFact, WorldbookFaction, WorldbookGlossary, WorldbookLocation, WorldbookRule, applicableGates, apply, blockedError, briefStageFor, chapterFile, chapterHeading, chapterHistoryFile, checkFile, checkHistoryFile, deprecatedChapterFile, deprecatedHistoryFile, evaluateGates, faultError, formatResumePrompt, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, planChapterFile, planHistoryFile, planWorldFile, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, renderProposal, reviewFile, reviewHistoryFile, verifyReference };
+export { ARCHIVE_DIGESTS_FILE, AdviceReport, ArchiveHandoff, ArchivedCardSnapshot, AuditRow, BACKUP_DIR, BRIEF_RECEIPTS_FILE, BlockingItem, BookPlan, BookReport, BriefDocument, BriefLibrary, BriefReceipt, BriefReceiptsDocument, BriefStage, CHAPTERS_DIR, CHECK_DIR, CORE_TOOLS, ChapterCastMember, ChapterPlanInput, ChapterProgress, ChapterProgressInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, DEFAULT_GENRE, DEFAULT_PLATFORM, Deduction, DeltaAction, DiffReport, DoctorCheck, DoctorReport, DraftInput, DraftState, ERROR_CODES, EXPORT_DIR, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, GuideReport, GuideStep, HISTORY_DIR, HISTORY_KINDS, HandoffDocument, HistoryKind, INITIAL_STAGE, LIMITS, LOCK_FILE, LocksDocument, METADATA_LOCK_FILE, MachineMetrics, NovelProject, OPERATIONS, OUTLINE_DEPRECATED_FILE, OUTLINE_DIR, OUTLINE_FILE, OpResult, Operation, OutlineChapter, OutlineDocument, OutlineProgress, OutlineVolume, PANEL_CHAPTER_LIMIT, PANEL_ID, PANEL_ROUTE, PANEL_VERSION, PHASE_STRIP, PLAN_DIR, PLATFORMS, PLUGIN_NAME, PROJECT_FILE, PanelBook, PanelBundle, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelMissing, PanelProjectOption, PanelSectionMeta, PanelSectionName, PanelSelection, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, REGISTRY_FILE, REMOTE_VERSION, REVIEW_DIR, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ResumePromptInput, ReviewDocument, ReviewInput, ReviewIssue, RevisionEdit, RevisionInput, RevisionPatch, RoundCounters, SCENE_TYPES, SCENE_TYPE_DEFAULT, SCHEMA_VERSION, SESSION_BINDINGS_FILE, SKILL_NAME, STAGING_DIR, STATE_DIR, STATE_FILES, SceneType, ScoreDimension, SearchReport, SearchResultItem, Selection, SelectionSource, SemanticItem, Severity, Stage, StateDelta, StateError, StateErrorCode, StatusReport, TOOL_NAMES, TimelineDelta, TimelineDocument, ToolName, Violation, WORLDBOOK_FILE, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, WorldbookBackstory, WorldbookCharacter, WorldbookDocument, WorldbookFact, WorldbookFaction, WorldbookGlossary, WorldbookLocation, WorldbookRule, applicableGates, apply, blockedError, briefStageFor, chapterFile, chapterHeading, chapterHistoryFile, checkFile, checkHistoryFile, deprecatedChapterFile, deprecatedHistoryFile, evaluateGates, faultError, formatResumePrompt, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, planChapterFile, planHistoryFile, planWorldFile, projectChapter, projectChapterProgress, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, renderProposal, reviewFile, reviewHistoryFile, verifyReference };