dsh-novel-write-engine 0.2.2 → 0.2.3

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 {
@@ -1401,7 +1419,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 +1435,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 +1520,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 +1536,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 +1579,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 +1590,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 +1746,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;
 }
@@ -1971,6 +2033,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 +2067,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 +2187,7 @@ declare class EngineService {
     active: string | null;
     projects: Array<RegistryEntry & {
       state: ProjectState;
+      identity_changed?: boolean;
     }>;
   }>;
   /**
@@ -2147,6 +2215,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.
@@ -2246,10 +2330,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 +2359,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,7 +2414,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 = 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. */