dsh-novel-write-engine 0.2.3 → 0.2.5

package/lib/index.d.ts

@@ -68,6 +68,9 @@ declare const ERROR_CODES: {
   /** The exact same keyed submission already failed in the same context. */
   readonly RETRY_UNCHANGED: "ENGINE_RETRY_UNCHANGED";
   readonly GATE_BLOCKED: "ENGINE_GATE_BLOCKED";
+  readonly CHECK_SUBMISSION_INVALID: "ENGINE_CHECK_SUBMISSION_INVALID";
+  readonly PENDING_PARTIAL: "ENGINE_PENDING_PARTIAL";
+  readonly IO_PERMISSION: "ENGINE_IO_PERMISSION";
   readonly READING_PROOF_INVALID: "ENGINE_READING_PROOF_INVALID";
   readonly SCORE_MISMATCH: "ENGINE_SCORE_MISMATCH";
   /** A revision tried to rewrite reviewer-owned issue fields. */
@@ -178,9 +181,14 @@ interface CheckDocument {
       evidence: string;
       note: string;
     }>;
+    /** 0.2.5: explain a persisted content failure; historical checks omit it. */
+    findings?: BlockingItem[];
   };
   /** Advisory codes the author has explicitly acknowledged for this content. */
   acknowledged?: string[];
+  /** 0.2.5: content failures consume the check budget; submission errors never persist. */
+  failure_class?: 'submission' | 'content';
+  counted?: boolean;
   verdict: 'pass' | 'fail';
 }
 /** Every persisted document whose damage status/panel can report. */
@@ -953,6 +961,10 @@ interface GateInput {
   summary: ChapterSummary | null;
   /** P5 may omit `summary`; when omitted, the previous plan summary is reused. */
   summaryProvided?: boolean;
+  /** Summary-only repair: no manuscript change, no P4/P6 proof requirement. */
+  summaryOnly?: boolean;
+  /** The last write was a summary-only repair; P6 may continue without a new brief. */
+  summaryOnlyRevision?: boolean;
   review: ReviewDocument | null;
   check: CheckDocument | null;
   /** When set, result-bearing gates run only the named check scopes. */
@@ -1030,6 +1042,8 @@ interface StatusReport {
   stage: Stage;
   rounds: RoundCounters;
   blocking: BlockingItem[];
+  /** Non-blocking recovery notes, e.g. a recoverable pending transaction. */
+  warnings?: Warning[];
   /** plan/review/check/ledger files that exist but cannot be read safely. */
   state_errors: StateError[];
   metrics: WordMetrics | null;
@@ -1122,6 +1136,20 @@ interface DiffReport {
 }
 /** Export capabilities; the last three are book-planning deliverables. */
 type ExportKind = 'md' | 'txt' | 'epub' | 'outline' | 'worldbook' | 'proposal';
+type SemanticItemState = 'pass' | 'fail' | 'missing' | 'invalid' | 'not_found' | 'too_short' | 'duplicate' | 'overlap' | 'same_sentence' | 'boundary';
+interface SemanticNearest {
+  paragraph: number;
+  quote: string;
+  score: number;
+}
+interface SemanticItemResult {
+  id: string;
+  state: SemanticItemState;
+  quote?: string;
+  detail?: string;
+  nearest?: SemanticNearest;
+  conflict_with?: string;
+}
 /** One blacklisted word. */
 interface TermEntry {
   term: string;
@@ -1296,8 +1324,14 @@ interface OutlineChapterInput {
 interface OutlineInput {
   book?: BookPatch;
   volumes?: VolumeInput[];
-  chapters: OutlineChapterInput[];
+  chapters?: OutlineChapterInput[];
   strict?: boolean;
+  /** Explicit deletion list; omitted cards are preserved. */
+  remove?: number[];
+  /** Explicit volume deletion list, keyed by title. */
+  remove_volumes?: string[];
+  /** Preview changes without writing or journaling. */
+  dry_run?: boolean;
 }
 interface WorldbookPatch {
   premise?: string;
@@ -1448,6 +1482,12 @@ interface PanelSnapshot {
     code: string;
     detail: string;
   }>;
+  /** Crash-left pending transaction; complete/untouched are warnings. */
+  pending?: {
+    state: string;
+    txid: string;
+    detail: string;
+  };
 }
 interface PanelBook {
   premise: string;
@@ -1549,6 +1589,12 @@ interface PanelSummaryDto {
     code: string;
     detail: string;
   }>;
+  /** Crash-left pending transaction; complete/untouched are warnings. */
+  pending?: {
+    state: string;
+    txid: string;
+    detail: string;
+  };
 }
 interface PanelChapterRow {
   num: number;
@@ -1778,8 +1824,8 @@ interface RevisionSubmission extends Omit<RevisionInput, 'summary'> {
   summary?: ChapterSummary;
   /** Updated issue statuses/evidence; the review document is patched in place. */
   issues?: ReviewDocument['issues'];
-  /** Proof that the revised text was read; PG-09 verifies it against the new text. */
-  proof: ReadingProof;
+  /** Proof that the revised text was read; required for content/patch revisions. */
+  proof?: ReadingProof;
   root?: string;
 }
 interface CheckSubmission {
@@ -1808,7 +1854,7 @@ interface AmendSubmission {
 interface RestoreSubmission {
   txid: string;
   chapter?: number;
-  /** Restrict to these project-relative files; omitted restores every chapter file in the snapshot. */
+  /** Restrict to chapter files, or exactly [outline/outline.yaml] to restore the plan. */
   paths?: string[];
   root?: string;
 }
@@ -1857,8 +1903,29 @@ interface WordCountInput {
 }
 interface BookPlanSubmission extends BookPatch {
   volumes?: VolumeInput[];
+  /** Explicit confirmation when a volume-list replacement drops a volume. */
+  confirm_remove?: boolean;
   root?: string;
 }
+interface OutlineMutationResult {
+  planned: number;
+  archived: number;
+  total: number;
+  strict: boolean;
+  volumes: number;
+  added: number[];
+  updated: number[];
+  reindexed: number[];
+  removed: number[];
+  volumes_added: string[];
+  volumes_updated: string[];
+  volumes_removed: string[];
+  dry_run?: boolean;
+  would_add?: number[];
+  would_update?: number[];
+  would_reindex?: number[];
+  would_remove?: number[];
+}
 interface OutlineSubmission extends OutlineInput {
   root?: string;
 }
@@ -1906,6 +1973,8 @@ declare class EngineService {
   private readonly stores;
   private readonly mutex;
   private readonly replay;
+  /** Bumped when an export artifact disappeared; makes the replay key miss. */
+  private readonly exportArtifactEpoch;
   /** Status, panel and gates ask for the same stage context repeatedly. */
   private readonly briefContextCache;
   private readonly briefs;
@@ -1991,13 +2060,8 @@ declare class EngineService {
     volumes: number;
     chapters: number;
   }>>;
-  submitOutline(input: OutlineSubmission): Promise<OpResult<{
-    planned: number;
-    archived: number;
-    total: number;
-    strict: boolean;
-    volumes: number;
-  }>>;
+  private outlinePlanChange;
+  submitOutline(input: OutlineSubmission): Promise<OpResult<OutlineMutationResult>>;
   importOutline(input: OutlineImportSubmission): Promise<OpResult<{
     format: string;
     planned: number;
@@ -2106,6 +2170,8 @@ declare class EngineService {
     chapter: number;
     stage: Stage;
     metrics: WordMetrics;
+    summary_only?: boolean;
+    rounds_consumed?: 0 | 1;
   }>>;
   runCheck(input: CheckSubmission): Promise<OpResult<{
     chapter: number;
@@ -2116,12 +2182,26 @@ declare class EngineService {
     acknowledged: string[];
     metrics: WordMetrics;
     stage: Stage;
+    semantic: {
+      items: SemanticItemResult[];
+      findings: BlockingItem[];
+    };
+    rounds: {
+      check: number;
+    };
+    counted: boolean;
   }>>;
   archiveChapter(input: ArchiveSubmission): Promise<OpResult<{
     chapter: number;
     assigned_ids: Record<string, string>;
     metrics: WordMetrics;
     score: number;
+    delta_warnings?: Warning[];
+    normalized_world?: Record<string, {
+      from: 'created' | 'updated' | 'no_change';
+      to: 'created' | 'updated' | 'no_change';
+      reason: 'existing-created-as-updated' | 'missing-updated-as-created' | 'missing-no-change-as-created';
+    }>;
   }>>;
   amend(input: AmendSubmission): Promise<OpResult<{
     path: string;
@@ -2301,10 +2381,14 @@ declare class EngineService {
    */
   private assertPlanningDocumentReadable;
   /**
-   * A strict outline cannot silently lose the active chapter's card while the
-   * chapter is still being written. Otherwise a late replacement turns a
-   * strict project non-strict in effect and archive would auto-create the card
-   * the author was required to provide.
+   * `strict_explicit` is an internal provenance bit, not an author choice.
+   * Exposing it lets a caller forge "the author chose strict:false" without
+   * going through the strict option. Stored documents may still contain it.
+   */
+  private assertPublicBookHasNoStrictExplicit;
+  /**
+   * An import is a full replacement, unlike novel_outline's keyed upsert. It
+   * must not silently lose the active card while strict mode still requires it.
    */
   private assertActiveCardPreserved;
   /**
@@ -2420,6 +2504,8 @@ declare const PANEL_CHAPTER_LIMIT = 30;
 /** Project-relative locations. Every write goes through these constants. */
 declare const PROJECT_FILE = "novel.yaml";
 declare const OUTLINE_FILE = "outline/outline.yaml";
+/** Last outline replaced by a normal planning write; one level is enough for repair. */
+declare const OUTLINE_DEPRECATED_FILE = "outline/outline.deprecated.yaml";
 declare const WORLDBOOK_FILE = "outline/worldbook.yaml";
 declare const STATE_DIR = "state";
 declare const CHAPTERS_DIR = "chapters";
@@ -2545,4 +2631,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_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, 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 };