dsh-novel-write-engine 0.2.2 → 0.2.4

package/lib/index.d.ts

@@ -65,9 +65,13 @@ declare const ERROR_CODES: {
   readonly PROJECT_IDENTITY_MISMATCH: "ENGINE_PROJECT_IDENTITY_MISMATCH";
   readonly PROJECT_EXISTS: "ENGINE_PROJECT_EXISTS";
   readonly STAGE_ORDER: "ENGINE_STAGE_ORDER";
+  /** The exact same keyed submission already failed in the same context. */
+  readonly RETRY_UNCHANGED: "ENGINE_RETRY_UNCHANGED";
   readonly GATE_BLOCKED: "ENGINE_GATE_BLOCKED";
   readonly READING_PROOF_INVALID: "ENGINE_READING_PROOF_INVALID";
   readonly SCORE_MISMATCH: "ENGINE_SCORE_MISMATCH";
+  /** A revision tried to rewrite reviewer-owned issue fields. */
+  readonly ISSUE_IMMUTABLE: "ENGINE_ISSUE_IMMUTABLE";
   readonly DELTA_UNVERIFIED: "ENGINE_DELTA_UNVERIFIED";
   readonly RESOURCE_NEGATIVE_BALANCE: "ENGINE_RESOURCE_NEGATIVE_BALANCE";
   readonly SCHEMA_TOO_NEW: "ENGINE_SCHEMA_TOO_NEW";
@@ -464,6 +468,8 @@ interface ForeshadowsDocument {
     resolved_at: number | null;
     description: string;
     anchor?: string;
+    /** New 0.2.3 writes are distinguishable from pre-0.2.3 rows by this marker. */
+    format_version?: 1;
     advance_log: Array<{
       chapter: number;
       note: string;
@@ -786,7 +792,13 @@ interface BookReport {
     min: number;
     max: number;
     last_five: number[];
-    trend: number;
+    /** Null when there are not enough distinct chapter reviews to compare. */
+    trend: number | null;
+    trend_basis: 'last_five_vs_previous_five' | 'insufficient_samples' | 'insufficient_history';
+    /** Number of chapters represented by a final review. */
+    samples: number;
+    /** Committed review rounds for this report, including history. */
+    attempts: number;
     dimensions: Array<{
       id: string;
       average: number;
@@ -1013,6 +1025,8 @@ interface StatusReport {
   chapter: number;
   /** The chapter the pipeline is currently working on. */
   active_chapter: number;
+  /** SHA-256 of the active manuscript, or null when the stage has no draft. */
+  manuscript_hash: string | null;
   stage: Stage;
   rounds: RoundCounters;
   blocking: BlockingItem[];
@@ -1089,6 +1103,10 @@ interface AuditRow {
   /** True when no transaction started: the gate/input refused the call. */
   attempt?: boolean;
   blocking?: BlockingItem[];
+  /** Keyed operation fingerprint; lets an identical failed retry be refused. */
+  retry_key?: string;
+  /** Brief/stage/revision context for `retry_key`. */
+  retry_context?: string;
 }
 /** One diff hunk between two revisions of a chapter. */
 interface DiffReport {
@@ -1278,8 +1296,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;
@@ -1401,7 +1425,10 @@ interface PanelSnapshot {
   quality?: {
     averageScore: number;
     scores: number[];
-    trend: number;
+    trend: number | null;
+    trend_basis?: 'last_five_vs_previous_five' | 'insufficient_samples' | 'insufficient_history';
+    samples?: number;
+    attempts?: number;
   };
   health?: {
     ok: boolean;
@@ -1414,6 +1441,19 @@ interface PanelSnapshot {
     chapter: number;
     status: string;
   }>;
+  /** Unacknowledged machine advisories; never mixed into `blocking`. */
+  advisories?: Array<{
+    code: string;
+    detail: string;
+    hint?: string;
+  }>;
+  /** Number of advisory codes already acknowledged for the current check. */
+  acknowledgedAdvisories?: number;
+  /** Read-only upgrade findings; null when the project needs no explanation. */
+  legacy?: Array<{
+    code: string;
+    detail: string;
+  }>;
 }
 interface PanelBook {
   premise: string;
@@ -1486,7 +1526,10 @@ interface PanelSummaryDto {
   quality?: {
     averageScore: number;
     scores: number[];
-    trend: number;
+    trend: number | null;
+    trend_basis?: 'last_five_vs_previous_five' | 'insufficient_samples' | 'insufficient_history';
+    samples?: number;
+    attempts?: number;
   };
   health?: {
     ok: boolean;
@@ -1499,6 +1542,19 @@ interface PanelSummaryDto {
     chapter: number;
     status: string;
   }>;
+  /** Unacknowledged machine advisories; never mixed into `blocking`. */
+  advisories?: Array<{
+    code: string;
+    detail: string;
+    hint?: string;
+  }>;
+  /** Number of advisory codes already acknowledged for the current check. */
+  acknowledgedAdvisories?: number;
+  /** Read-only upgrade findings; null when the project needs no explanation. */
+  legacy?: Array<{
+    code: string;
+    detail: string;
+  }>;
 }
 interface PanelChapterRow {
   num: number;
@@ -1529,7 +1585,9 @@ interface PanelProjectOption {
   title: string;
   active: boolean;
   registered: boolean;
-  state: 'ok' | 'damaged' | 'missing' | 'unreadable';
+  state: 'ok' | 'damaged' | 'missing' | 'not-project' | 'unreadable';
+  /** The path now holds a different project identity; writes will fail closed. */
+  identity_changed?: boolean;
 }
 interface PanelSelection {
   root: string | null;
@@ -1538,8 +1596,8 @@ interface PanelSelection {
 interface PanelMissing {
   root: string;
   title: string;
-  code: 'ENGINE_PROJECT_MISSING' | 'ENGINE_PROJECT_NOT_FOUND';
-  reason: 'missing' | 'not-project' | 'damaged' | 'not_registered' | 'unreadable';
+  code: 'ENGINE_PROJECT_MISSING' | 'ENGINE_PROJECT_NOT_FOUND' | 'ENGINE_TXN_IN_PROGRESS';
+  reason: 'missing' | 'not-project' | 'damaged' | 'not_registered' | 'unreadable' | 'busy';
   hint: string;
 }
 interface PanelBundle {
@@ -1694,6 +1752,16 @@ interface BriefInput {
   chapter?: number;
   root?: string;
 }
+type BriefPayload = {
+  stage: BriefStage;
+  chapter: number;
+  digest: string;
+  title: string;
+  content: string;
+  content_hash: string;
+  fields: Record<string, unknown>;
+  context: Record<string, unknown>;
+};
 interface WorldPlanSubmission extends WorldPlanInput {
   root?: string;
 }
@@ -1746,7 +1814,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;
 }
@@ -1795,8 +1863,27 @@ 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[];
+  removed: number[];
+  volumes_added: string[];
+  volumes_updated: string[];
+  volumes_removed: string[];
+  dry_run?: boolean;
+  would_add?: number[];
+  would_update?: number[];
+  would_remove?: number[];
+}
 interface OutlineSubmission extends OutlineInput {
   root?: string;
 }
@@ -1929,13 +2016,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;
@@ -1971,6 +2053,13 @@ declare class EngineService {
    * the model only learns about the mismatch when that write aborts.
    */
   private journalBlocking;
+  /**
+   * Count review attempts per archived chapter. The journal is authoritative;
+   * history fills any per-chapter gap where it has more distinct historical
+   * reviews than committed journal rows (legacy or a truncated upgrade). A
+   * chapter can never report fewer attempts than readable current reviews.
+   */
+  private reviewAttemptsByChapter;
   /**
    * Count every committed attempt for one chapter, not just the loop since the
    * last rollback. `pipeline.rounds` is deliberately reset by rollback to keep
@@ -1998,20 +2087,18 @@ declare class EngineService {
     state_errors: StateError[];
   }>>;
   search(input: SearchInput): Promise<OpResult<SearchReport>>;
+  /**
+   * Read-only upgrade audit. It never edits a legacy document: the point is to
+   * explain why an old project's numbers look different, not to rewrite history.
+   */
+  private legacyIssues;
   doctor(input?: DoctorInput): Promise<OpResult<DoctorReport>>;
   private recoveryForSafe;
   report(input?: ReportSubmission): Promise<OpResult<BookReport>>;
   guide(input?: GuideInput): Promise<OpResult<GuideReport>>;
-  getBrief(input: BriefInput): Promise<OpResult<{
-    stage: string;
-    chapter: number;
-    digest: string;
-    title: string;
-    content: string;
-    content_hash: string;
-    fields: Record<string, unknown>;
-    context: Record<string, unknown>;
-  }>>;
+  getBrief(input: BriefInput): Promise<OpResult<BriefPayload>>;
+  private assertBriefChapter;
+  private briefPayload;
   submitWorldPlan(input: WorldPlanSubmission): Promise<OpResult<{
     chapter: number;
     stage: Stage;
@@ -2120,6 +2207,7 @@ declare class EngineService {
     active: string | null;
     projects: Array<RegistryEntry & {
       state: ProjectState;
+      identity_changed?: boolean;
     }>;
   }>;
   /**
@@ -2147,6 +2235,22 @@ declare class EngineService {
     active: string | null;
     projects: RegistryEntry[];
   }>;
+  /**
+   * Remove only registry rows whose directories are missing, not a project, or
+   * unreadable. The default is a dry run; project files and session bindings are
+   * never touched, and `--yes` is required at the command layer.
+   */
+  pruneProjects(input?: {
+    apply?: boolean;
+  }): Promise<{
+    candidates: Array<{
+      root: string;
+      title: string;
+      state: ProjectState;
+    }>;
+    removed: string[];
+    active: string | null;
+  }>;
   /**
    * Bounded workspace scan. Normal mode is read-only; `register` updates only
    * healthy, newly discovered rows, never active or session bindings.
@@ -2217,10 +2321,8 @@ 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.
+   * 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;
   /**
@@ -2246,10 +2348,10 @@ declare class EngineService {
   private bookStatus;
   private panelSnapshot;
   /**
-   * The archive stage has only one legal operation, so a status/panel that
-   * recommends it without checking the same gates as the archive creates a
-   * loop. Evaluate the real archive gates through `gateInput`, then add the
-   * machine pass and semantic evidence that archive re-checks separately.
+   * The archive stage can be left by a direct revision (the 0.2.3 workflow) or
+   * by rollback. Evaluate the same gates as archive so status/panel do not
+   * recommend an operation that will immediately fail; when the failure is
+   * prose-level, `nextStep` recommends the direct P5 revision instead.
    */
   private archivePreflight;
   private nextStep;
@@ -2275,6 +2377,7 @@ declare class EngineService {
   private stateGateBlock;
   /** Whether the stored brief still signs the current snapshot. */
   private readBriefReceipts;
+  private assertBriefReceiptsWritable;
   private briefIsCurrent;
   /** Arguments valid for the tool `STAGE_NEXT` recommends at this stage. */
   private nextArgs;
@@ -2329,12 +2432,14 @@ 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 = 4;
+declare const REMOTE_VERSION = 5;
 /** 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. */
 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";
@@ -2460,4 +2565,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 };