dsh-novel-write-engine 0.2.0 → 0.2.1

package/lib/index.d.ts

@@ -23,7 +23,7 @@ type SceneType = (typeof SCENE_TYPES)[number];
 /** A violation is blocking unless the rule pack declares it advisory. */
 type Severity = 'blocker' | 'advisory';
 /** All thirty-one service operations (22 inherited from 0.1.x, 9 book-level). */
-declare const OPERATIONS: readonly ["initProject", "archiveChapter", "amend", "rollback", "reopenChapter", "submitWorldPlan", "submitChapterPlan", "submitDraft", "submitReview", "submitRevision", "runCheck", "submitBookPlan", "submitOutline", "importOutline", "submitWorldbook", "getStatus", "getBrief", "countWords", "queryState", "diff", "auditHistory", "advise", "search", "doctor", "report", "guide", "export", "panelSummary", "panelChapters", "panelGates", "stats"];
+declare const OPERATIONS: readonly ["initProject", "archiveChapter", "amend", "rollback", "reopenChapter", "submitWorldPlan", "submitChapterPlan", "submitDraft", "submitReview", "submitRevision", "runCheck", "submitBookPlan", "submitOutline", "importOutline", "submitWorldbook", "getStatus", "getBrief", "countWords", "queryState", "diff", "auditHistory", "advise", "search", "doctor", "report", "guide", "export", "panelSummary", "panelChapters", "panelGates", "stats", "restoreBackup"];
 type Operation = (typeof OPERATIONS)[number];
 /** Structured, non-fatal note attached to a successful result. */
 interface Warning {
@@ -161,6 +161,7 @@ interface CheckDocument {
   content_hash: string;
   machine: {
     violations: Violation[];
+    advisories?: Violation[];
     metrics: WordMetrics;
   };
   semantic: {
@@ -171,6 +172,8 @@ interface CheckDocument {
       note: string;
     }>;
   };
+  /** Advisory codes the author has explicitly acknowledged for this content. */
+  acknowledged?: string[];
   verdict: 'pass' | 'fail';
 }
 /** Every persisted document whose damage status/panel can report. */
@@ -189,6 +192,8 @@ interface WordMetrics {
   numbers: number;
   chinese_punct: number;
   english_punct: number;
+  /** All punctuation counted by the engine; total = cjk + words + numbers + punctuation. */
+  punctuation_chars: number;
   non_ws_chars: number;
   total_lines: number;
   non_empty_lines: number;
@@ -211,6 +216,10 @@ interface ChapterRecord {
   status: 'draft' | 'reviewed';
   content_hash: string;
   summary: ChapterSummary;
+  /** How hard this chapter was before it was archived. */
+  rounds?: RoundCounters;
+  final_check?: 'pass' | 'fail';
+  archived_at?: string;
   /** Keys allocated by the archive transaction; lets a cross-process retry replay. */
   assigned_ids?: Record<string, string>;
   /** Digest of the archive request that produced this row. */
@@ -225,6 +234,7 @@ interface ChapterSummary {
       key: string;
       title: string;
       description: string;
+      anchor?: string;
     }>;
     advanced: Array<{
       key: string;
@@ -258,6 +268,8 @@ interface RoundCounters {
   review: number;
   revise: number;
   check: number;
+  /** Lifetime rollback count on a chapter record; never stored in the live pipeline. */
+  rollbacks?: number;
 }
 /** How one ledger entity changed in this chapter. */
 type DeltaAction = 'created' | 'updated' | 'no_change';
@@ -289,6 +301,8 @@ interface ForeshadowDelta {
   action: DeltaAction;
   reason?: string;
   title?: string;
+  /** Verbatim manuscript quote used for verification; title stays a readable label. */
+  anchor?: string;
   description?: string;
   note?: string;
   new_info?: boolean;
@@ -331,6 +345,28 @@ interface ArchiveHandoff {
   act?: string;
   act_progress?: string;
 }
+/** One issued task-book receipt; the brief itself is rendered on demand. */
+interface BriefReceipt {
+  chapter: number;
+  stage: BriefStage;
+  digest: string;
+  issued_at: string;
+}
+/** `state/briefs.yaml`: append-only task-book evidence outside content transactions. */
+interface BriefReceiptsDocument {
+  schema_version: 1;
+  receipts: BriefReceipt[];
+}
+/** The active draft's own metadata; P2 plan stays immutable after submission. */
+interface DraftState {
+  chapter: number;
+  title: string;
+  scene_type: SceneType;
+  narrator: string;
+  summary: ChapterSummary;
+  content_hash: string;
+  updated_at: string;
+}
 /** Pipeline document (`state/pipeline.yaml`). */
 interface PipelineState {
   schema_version: 1;
@@ -343,6 +379,8 @@ interface PipelineState {
     digest: string;
   }>;
   blocking: BlockingItem[];
+  /** Current draft summary/title; never written into the P2 plan file. */
+  draft?: DraftState;
   /** Hash of the review document last written by submitReview/submitRevision. */
   review_digest?: string;
   last_action: {
@@ -422,6 +460,7 @@ interface ForeshadowsDocument {
     status: 'planted' | 'dormant' | 'advanced' | 'resolved';
     resolved_at: number | null;
     description: string;
+    anchor?: string;
     advance_log: Array<{
       chapter: number;
       note: string;
@@ -614,6 +653,14 @@ interface WorldbookBackstory {
   time: string;
   event: string;
 }
+/** One declared numeric canon, checked against the manuscript on request. */
+interface WorldbookFact {
+  alias: string;
+  value: number;
+  unit: string;
+  tolerance?: number;
+  note?: string;
+}
 /** Worldbuilding plan, persisted in `outline/worldbook.yaml`. */
 interface WorldbookDocument {
   schema_version: 1;
@@ -626,6 +673,8 @@ interface WorldbookDocument {
   characters: WorldbookCharacter[];
   glossary: WorldbookGlossary[];
   backstory: WorldbookBackstory[];
+  /** Optional numeric canon; old documents omit it. */
+  facts?: WorldbookFact[];
   themes: string[];
 }
 /** One hit from `novel_search`; the scope names the source family. */
@@ -663,6 +712,22 @@ interface DoctorReport {
     infos: number;
   };
 }
+/** One canonical outline-progress calculation shared by every adapter. */
+interface OutlineProgress {
+  present: boolean;
+  target: number | null;
+  total: number;
+  planned: number;
+  archived: number;
+  missingCards: number;
+  plannedCoverage: number | null;
+  archivedCoverage: number | null;
+  /** Compatibility alias: planned coverage when a target exists, otherwise card coverage. */
+  coverage: number;
+  /** Fraction of archived chapters that have a matching archived card. */
+  cardCoverage: number;
+  volumes: number;
+}
 /** Book-wide quality, outline, cast and pacing aggregates. */
 interface BookReport {
   progress: {
@@ -672,13 +737,22 @@ interface BookReport {
     average_words: number;
     percent: number;
     remaining_words: number | null;
+    remaining_words_min: number | null;
+    remaining_words_average: number | null;
+    remaining_words_basis: 'actual_average' | 'minimum_target' | 'none';
   };
   outline: {
     present: boolean;
     strict: boolean;
+    target: number | null;
+    total: number;
     planned: number;
     archived: number;
+    missing_cards: number;
+    planned_coverage: number | null;
+    archived_coverage: number | null;
     coverage: number;
+    card_coverage: number;
     volumes: Array<{
       title: string;
       start: number;
@@ -701,6 +775,7 @@ interface BookReport {
     rules: number;
     glossary: number;
     backstory: number;
+    facts?: number;
   };
   quality: {
     average: number;
@@ -715,6 +790,22 @@ interface BookReport {
       samples: number;
     }>;
   };
+  /** Per-chapter effort survives archive (pipeline rounds are reset). */
+  effort: {
+    reviews: number;
+    revisions: number;
+    checks: number;
+    rollbacks: number;
+    chapters: Array<{
+      num: number;
+      reviews: number;
+      revisions: number;
+      checks: number;
+      rollbacks: number;
+      final_check: 'pass' | 'fail' | null;
+      archived_at: string | null;
+    }>;
+  };
   pacing: {
     scene_types: Record<string, number>;
     hook_strength: Record<string, number>;
@@ -805,10 +896,23 @@ interface ReviewInput {
   total: number;
   proof: ReadingProof;
 }
+/** One exact, unique replacement used by patch-mode revisions. */
+interface RevisionEdit {
+  old_text: string;
+  new_text: string;
+  /** 1-based occurrence; defaults to requiring exactly one match. */
+  occurrence?: number;
+}
+/** Patch-mode revision; content and patch are mutually exclusive. */
+interface RevisionPatch {
+  expected_hash: string;
+  edits: RevisionEdit[];
+}
 /** Revision submission payload. */
 interface RevisionInput {
   chapter: number;
-  content: string;
+  content?: string;
+  patch?: RevisionPatch;
   summary: ChapterSummary;
 }
 /** Semantic check items supplied by the model. */
@@ -910,10 +1014,15 @@ interface StatusReport {
     strict: boolean;
     outline: {
       present: boolean;
+      target: number | null;
       total: number;
       planned: number;
       archived: number;
+      missing_cards: number;
+      planned_coverage: number | null;
+      archived_coverage: number | null;
       coverage: number;
+      card_coverage: number;
       volumes: number;
       current: OutlineChapter | null;
     };
@@ -925,6 +1034,7 @@ interface StatusReport {
       rules: number;
       glossary: number;
       backstory: number;
+      facts?: number;
     };
   };
   next: {
@@ -945,6 +1055,8 @@ interface AdviceReport {
 }
 /** One history row derived from the journal. */
 interface AuditRow {
+  /** Stable chronological cursor; absent only on hand-built test rows. */
+  seq?: number;
   at: string;
   op: string;
   chapter: number;
@@ -952,6 +1064,14 @@ interface AuditRow {
   txid: string;
   status: 'committed' | 'aborted';
   files: string[];
+  /** Machine code and human reason for a refused attempt. */
+  code?: string;
+  reason?: string;
+  hint?: string;
+  stage?: string;
+  /** True when no transaction started: the gate/input refused the call. */
+  attempt?: boolean;
+  blocking?: BlockingItem[];
 }
 /** One diff hunk between two revisions of a chapter. */
 interface DiffReport {
@@ -1151,6 +1271,7 @@ interface WorldbookPatch {
   characters?: WorldbookCharacter[];
   glossary?: WorldbookGlossary[];
   backstory?: WorldbookBackstory[];
+  facts?: WorldbookFact[];
   themes?: string[];
 }
 /** One rendered task book. */
@@ -1282,10 +1403,15 @@ interface PanelBook {
   target: number | null;
   outline: {
     present: boolean;
+    target: number | null;
     total: number;
     planned: number;
     archived: number;
+    missing_cards: number;
+    planned_coverage: number | null;
+    archived_coverage: number | null;
     coverage: number;
+    card_coverage: number;
     volumes: Array<{
       title: string;
       start: number;
@@ -1302,6 +1428,7 @@ interface PanelBook {
     rules: number;
     glossary: number;
     backstory: number;
+    facts?: number;
   };
 }
 interface PanelSummaryDto {
@@ -1447,6 +1574,15 @@ type EngineEvent = {
     chapter: number;
     restore_txid: string;
   };
+} | {
+  name: 'novel/restored';
+  payload: {
+    schemaVersion: 1;
+    projectRoot: string;
+    txid: string;
+    chapter: number;
+    paths: string[];
+  };
 } | {
   name: 'novel/exported';
   payload: {
@@ -1518,6 +1654,8 @@ interface CheckSubmission {
   /** The five P6 semantic items; omission is a failed check, never a pass. */
   semantic: SemanticItem[];
   scope?: string[];
+  /** Advisory codes the author has read and accepts; blockers cannot be acknowledged. */
+  acknowledge?: string[];
   root?: string;
 }
 interface ArchiveSubmission {
@@ -1534,6 +1672,13 @@ interface AmendSubmission {
   reason: string;
   root?: string;
 }
+interface RestoreSubmission {
+  txid: string;
+  chapter?: number;
+  /** Restrict to these project-relative files; omitted restores every chapter file in the snapshot. */
+  paths?: string[];
+  root?: string;
+}
 interface RollbackSubmission {
   chapter: number;
   toStage: 'P1' | 'P2' | 'P3' | 'P4' | 'P5' | 'P6';
@@ -1548,6 +1693,12 @@ interface DiffInput {
 }
 interface AuditInput {
   limit?: number;
+  cursor?: number;
+  chapter?: number;
+  op?: string;
+  status?: 'committed' | 'aborted';
+  since?: string;
+  until?: string;
   root?: string;
 }
 interface ExportInput {
@@ -1556,8 +1707,10 @@ interface ExportInput {
   root?: string;
 }
 interface StateQueryInput {
-  kind: DocKind | 'novel' | 'planWorld' | 'planChapter';
+  kind: DocKind | 'novel' | 'planWorld' | 'planChapter' | 'history' | 'backups' | 'briefs';
   chapter?: number;
+  /** Select one historical revision instead of listing history. */
+  revision?: number;
   /** Chapter index defaults to a compact read; opt in to the full summaries. */
   include_summary?: boolean;
   /** Inclusive chapter range for the `chapters` index. */
@@ -1689,12 +1842,28 @@ declare class EngineService {
     stage: Stage;
     restore_txid: string;
   }>>;
+  /**
+   * Restore one active chapter from a backup transaction. Archived chapters
+   * are refused: their manuscript hash is bound by the index, so restoring
+   * behind the index would corrupt the project. Reopen first, then restore.
+   */
+  restoreBackup(input: RestoreSubmission): Promise<OpResult<{
+    txid: string;
+    chapter: number;
+    restored: string[];
+  }>>;
   /**
    * Read-only paths must surface a committed-journal mismatch. The write path
    * already fails closed; without this, status recommends the next write and
    * the model only learns about the mismatch when that write aborts.
    */
   private journalBlocking;
+  /**
+   * Count every committed attempt for one chapter, not just the loop since the
+   * last rollback. `pipeline.rounds` is deliberately reset by rollback to keep
+   * the retry budget fair; it is not the chapter's lifetime effort.
+   */
+  private lifetimeRounds;
   getStatus(input?: StatusInput): Promise<OpResult<StatusReport>>;
   countWords(input?: WordCountInput): Promise<OpResult<WordMetrics>>;
   queryState(input: StateQueryInput): Promise<OpResult<unknown>>;
@@ -1756,6 +1925,9 @@ declare class EngineService {
     chapter: number;
     verdict: 'pass' | 'fail';
     violations: number;
+    advisories: number;
+    advisory_codes: string[];
+    acknowledged: string[];
     metrics: WordMetrics;
     stage: Stage;
   }>>;
@@ -1807,7 +1979,10 @@ declare class EngineService {
     lastScore: number;
     openForeshadows: number;
     plannedChapters: number;
-    outlineCoverage: number;
+    totalCards: number;
+    outlineCoverage: number | null;
+    archivedCoverage: number | null;
+    missingCards: number;
     blueprintReady: boolean;
     worldbookEntries: number;
     strictOutline: boolean;
@@ -1924,6 +2099,7 @@ declare class EngineService {
   /** State damage that makes this operation unsafe to start. */
   private stateGateBlock;
   /** Whether the stored brief still signs the current snapshot. */
+  private readBriefReceipts;
   private briefIsCurrent;
   /** Arguments valid for the tool `STAGE_NEXT` recommends at this stage. */
   private nextArgs;
@@ -2013,4 +2189,4 @@ declare const Config: Schema<Config>;
  * created lazily per project root.
  */
 declare function apply(ctx: Context, config: Config): void;
-export { AdviceReport, ArchiveHandoff, AuditRow, BlockingItem, BookPlan, BookReport, BriefDocument, BriefLibrary, BriefStage, ChapterCastMember, ChapterPlanInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, Deduction, DeltaAction, DiffReport, DoctorCheck, DoctorReport, DraftInput, ERROR_CODES, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, GuideReport, GuideStep, HandoffDocument, LocksDocument, MachineMetrics, NovelProject, OPERATIONS, OpResult, Operation, OutlineChapter, OutlineDocument, OutlineVolume, PLATFORMS, PanelBook, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ReviewDocument, ReviewInput, ReviewIssue, RevisionInput, RoundCounters, SCENE_TYPES, SCHEMA_VERSION, SceneType, ScoreDimension, SearchReport, SearchResultItem, SemanticItem, Severity, Stage, StateDelta, StateError, StateErrorCode, StatusReport, TimelineDelta, TimelineDocument, Violation, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, WorldbookBackstory, WorldbookCharacter, WorldbookDocument, WorldbookFaction, WorldbookGlossary, WorldbookLocation, WorldbookRule, applicableGates, apply, blockedError, briefStageFor, chapterHeading, evaluateGates, faultError, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, renderProposal, verifyReference };
+export { AdviceReport, ArchiveHandoff, AuditRow, BlockingItem, BookPlan, BookReport, BriefDocument, BriefLibrary, BriefReceipt, BriefReceiptsDocument, BriefStage, ChapterCastMember, ChapterPlanInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, Deduction, DeltaAction, DiffReport, DoctorCheck, DoctorReport, DraftInput, DraftState, ERROR_CODES, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, GuideReport, GuideStep, HandoffDocument, LocksDocument, MachineMetrics, NovelProject, OPERATIONS, OpResult, Operation, OutlineChapter, OutlineDocument, OutlineProgress, OutlineVolume, PLATFORMS, PanelBook, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ReviewDocument, ReviewInput, ReviewIssue, RevisionEdit, RevisionInput, RevisionPatch, RoundCounters, SCENE_TYPES, SCHEMA_VERSION, SceneType, ScoreDimension, SearchReport, SearchResultItem, SemanticItem, Severity, Stage, StateDelta, StateError, StateErrorCode, StatusReport, TimelineDelta, TimelineDocument, Violation, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, WorldbookBackstory, WorldbookCharacter, WorldbookDocument, WorldbookFact, WorldbookFaction, WorldbookGlossary, WorldbookLocation, WorldbookRule, applicableGates, apply, blockedError, briefStageFor, chapterHeading, evaluateGates, faultError, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, renderProposal, verifyReference };