dsh-novel-write-engine 0.2.4 → 0.2.6

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,13 +181,18 @@ 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. */
-type StateErrorCode = 'PROJECT_UNREADABLE' | 'PLAN_UNREADABLE' | 'WORLD_PLAN_UNREADABLE' | 'REVIEW_UNREADABLE' | 'CHECK_UNREADABLE' | 'CHAPTERS_UNREADABLE' | 'CHARACTERS_UNREADABLE' | 'WORLD_UNREADABLE' | 'LOCKS_UNREADABLE' | 'TIMELINE_UNREADABLE' | 'FORESHADOWS_UNREADABLE' | 'RELATIONSHIPS_UNREADABLE' | 'HANDOFF_UNREADABLE' | 'OUTLINE_UNREADABLE' | 'WORLDBOOK_UNREADABLE';
+type StateErrorCode = 'PROJECT_UNREADABLE' | 'PIPELINE_UNREADABLE' | 'PLAN_UNREADABLE' | 'WORLD_PLAN_UNREADABLE' | 'REVIEW_UNREADABLE' | 'CHECK_UNREADABLE' | 'CHAPTERS_UNREADABLE' | 'CHARACTERS_UNREADABLE' | 'WORLD_UNREADABLE' | 'LOCKS_UNREADABLE' | 'TIMELINE_UNREADABLE' | 'FORESHADOWS_UNREADABLE' | 'RELATIONSHIPS_UNREADABLE' | 'HANDOFF_UNREADABLE' | 'OUTLINE_UNREADABLE' | 'WORLDBOOK_UNREADABLE';
 /** A state document that exists but cannot be read safely. */
 interface StateError {
   path: string;
@@ -255,6 +263,12 @@ interface ChapterSummary {
     abilities: string[];
     artifacts: string[];
   };
+  /** Optional P3/P5 verbatim manuscript anchors for readable entity names. */
+  new_element_anchors?: {
+    locations?: Record<string, string[]>;
+    abilities?: Record<string, string[]>;
+    artifacts?: Record<string, string[]>;
+  };
   resource_changes: Array<{
     character: string;
     resource: string;
@@ -423,6 +437,8 @@ interface WorldDocument {
   schema_version: 1;
   locations: Array<{
     name: string;
+    /** 0.2.6 additive: readable-name anchors; old ledgers omit this. */
+    anchors?: string[];
     first_appearance: number;
     locked: boolean;
     description: string;
@@ -785,6 +801,12 @@ interface BookReport {
     glossary: number;
     backstory: number;
     facts?: number;
+    /** 0.2.6 persisted world-ledger anchors, capped for report payloads. */
+    anchors?: Array<{
+      name: string;
+      kind: string;
+      anchors: string[];
+    }>;
   };
   quality: {
     average: number;
@@ -953,6 +975,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 +1056,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 +1150,39 @@ 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';
+type SemanticConflictKind = 'duplicate' | 'same_sentence' | 'interval_overlap';
+interface SemanticConflict {
+  kind: SemanticConflictKind;
+  other_id: string;
+  /** Only for interval_overlap; a verbatim excerpt, capped at 120 characters. */
+  overlap_text?: string;
+  overlap_chars?: number;
+  /** overlap_chars / min(quoteA, quoteB), 0..1. */
+  overlap_ratio?: number;
+  paragraphs?: number[];
+  /** Only for same_sentence. */
+  sentence?: {
+    id: number;
+    text: string;
+    paragraph: number;
+  };
+}
+interface SemanticNearest {
+  paragraph: number;
+  quote: string;
+  score: number;
+}
+interface SemanticItemResult {
+  id: string;
+  state: SemanticItemState;
+  quote?: string;
+  detail?: string;
+  nearest?: SemanticNearest;
+  /** Kept for older adapters; the full pair is in `conflicts`. */
+  conflict_with?: string;
+  conflicts?: SemanticConflict[];
+}
 /** One blacklisted word. */
 interface TermEntry {
   term: string;
@@ -1376,6 +1437,130 @@ declare function applicableGates(input: GateInput): GateId[];
 declare function gateName(id: GateId): string;
 /** Which brief stage an operation requires; `null` means no brief gate. */
 declare function briefStageFor(operation: GateInput['operation'], stage: Stage): GateInput['briefStage'];
+/** v6 read-only book data. All windows are explicit in the field names. */
+interface PanelCardData {
+  num: number;
+  title: string;
+  scene_type: string;
+  goal: string;
+  conflict: string;
+  hook: string;
+  cast: string[];
+  target_words: [number, number];
+  status: 'planned' | 'archived';
+}
+interface PanelWorldEntry {
+  name: string;
+  description: string;
+  anchors?: string[];
+}
+interface PanelBookData {
+  identity: {
+    author: string;
+    description: string;
+    created_at: string;
+    targets: {
+      words_per_chapter: [number, number];
+      total_chapters: number | null;
+      dialogue_ratio: [number, number];
+    };
+  };
+  blueprint: {
+    premise: string;
+    logline: string;
+    themes: string[];
+    tone: string;
+    pov: string;
+    audience: string;
+    selling_points: string[];
+    ending: string;
+  };
+  progress: {
+    archived: number;
+    target: number | null;
+    words_archived: number;
+    words_with_draft: number;
+    average_words: number;
+    remaining_words: number | null;
+    remaining_words_basis: 'actual_average' | 'minimum_target' | 'none';
+    percent: number;
+  };
+  current: {
+    card: PanelCardData | null;
+    chapter: number;
+    stage: Stage;
+    rounds: {
+      review: number;
+      revise: number;
+      check: number;
+    };
+    manuscript_hash: string | null;
+    metrics: WordMetrics | null;
+  };
+  worldbook: {
+    counts: Omit<BookReport['worldbook'], 'anchors'>;
+    locations: PanelWorldEntry[];
+    factions: PanelWorldEntry[];
+    rules: PanelWorldEntry[];
+    facts: Array<{
+      alias: string;
+      value: number;
+      unit: string;
+    }>;
+  };
+  cast: {
+    total: number;
+    top: Array<{
+      name: string;
+      role: string;
+      appearances: number;
+      last_seen: number;
+    }>;
+  };
+  relationships: {
+    total: number;
+    types: Record<string, number>;
+  };
+  foreshadows: BookReport['foreshadows'];
+  timeline: BookReport['timeline'];
+  outline: {
+    drift: BookReport['outline']['drift'];
+  };
+  quality: {
+    average: number;
+    median: number;
+    min: number;
+    max: number;
+    last_ten_average: number;
+    trend: number | null;
+    trend_basis: BookReport['quality']['trend_basis'];
+    samples: number;
+    attempts: number;
+    dimensions: BookReport['quality']['dimensions'];
+  };
+  pacing: BookReport['pacing'];
+  effort: BookReport['effort'];
+  health: {
+    state_errors: Array<{
+      path: string;
+      code: string;
+      message: string;
+    }>;
+    outline: {
+      present: boolean;
+      error: string | null;
+    };
+    worldbook: {
+      present: boolean;
+      error: string | null;
+    };
+    pending: {
+      state: string;
+      txid: string;
+      detail: string;
+    } | null;
+  };
+}
 /** The shared read model: everything the panel, status and commands render. */
 interface PanelDraft {
   num: number;
@@ -1434,6 +1619,7 @@ interface PanelSnapshot {
     ok: boolean;
     blocking: number;
     stateErrors: number;
+    pending?: boolean;
   };
   activity?: Array<{
     at: string;
@@ -1454,6 +1640,14 @@ interface PanelSnapshot {
     code: string;
     detail: string;
   }>;
+  /** Crash-left pending transaction; complete/untouched are warnings. */
+  pending?: {
+    state: string;
+    txid: string;
+    detail: string;
+  };
+  /** v6 read-only book data; v5 payloads omit it. */
+  bookData?: PanelBookData;
 }
 interface PanelBook {
   premise: string;
@@ -1535,6 +1729,7 @@ interface PanelSummaryDto {
     ok: boolean;
     blocking: number;
     stateErrors: number;
+    pending?: boolean;
   };
   activity?: Array<{
     at: string;
@@ -1555,6 +1750,14 @@ interface PanelSummaryDto {
     code: string;
     detail: string;
   }>;
+  /** Crash-left pending transaction; complete/untouched are warnings. */
+  pending?: {
+    state: string;
+    txid: string;
+    detail: string;
+  };
+  /** v6 read-only book data; v5 payloads omit it. */
+  bookData?: PanelBookData;
 }
 interface PanelChapterRow {
   num: number;
@@ -1565,6 +1768,15 @@ interface PanelChapterRow {
   status: 'passed' | 'blocked' | 'draft';
   /** One-line summary shown when the row is expanded. */
   details: string;
+  sceneType?: string;
+  dialogueRatio?: number;
+  hookStrength?: number;
+  finalCheck?: 'pass' | 'fail' | null;
+  reviews?: number;
+  revisions?: number;
+  checks?: number;
+  rollbacks?: number;
+  archivedAt?: string | null;
 }
 interface PanelChaptersDto {
   schemaVersion: number;
@@ -1784,8 +1996,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 {
@@ -1875,6 +2087,7 @@ interface OutlineMutationResult {
   volumes: number;
   added: number[];
   updated: number[];
+  reindexed: number[];
   removed: number[];
   volumes_added: string[];
   volumes_updated: string[];
@@ -1882,6 +2095,7 @@ interface OutlineMutationResult {
   dry_run?: boolean;
   would_add?: number[];
   would_update?: number[];
+  would_reindex?: number[];
   would_remove?: number[];
 }
 interface OutlineSubmission extends OutlineInput {
@@ -1931,8 +2145,12 @@ 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;
+  /** The 15s panel poll reuses the heavy book projection until revision/damage changes. */
+  private readonly panelCache;
   private readonly briefs;
   private readonly now;
   private readonly metadataMutex;
@@ -2126,6 +2344,8 @@ declare class EngineService {
     chapter: number;
     stage: Stage;
     metrics: WordMetrics;
+    summary_only?: boolean;
+    rounds_consumed?: 0 | 1;
   }>>;
   runCheck(input: CheckSubmission): Promise<OpResult<{
     chapter: number;
@@ -2136,12 +2356,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;
@@ -2320,6 +2554,12 @@ declare class EngineService {
    * could not read.
    */
   private assertPlanningDocumentReadable;
+  /**
+   * `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.
@@ -2432,7 +2672,7 @@ declare const PLUGIN_NAME = "dsh-novel-write-engine";
 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 = 5;
+declare const REMOTE_VERSION = 6;
 /** 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. */