dsh-novel-write-engine 0.0.0-stage → 0.1.1

package/lib/index.d.ts

@@ -0,0 +1,1345 @@
+import Schema from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+/**
+ * Public contracts of the engine. Everything else in `src/` is an implementation
+ * detail; adapters (tools, commands, panel, presets) may only import this file
+ * and the engine service.
+ */
+/** On-disk schema version for every YAML file the engine owns. */
+declare const SCHEMA_VERSION: 1;
+/** Pipeline control-flow state. This is the state machine value, not a brief id. */
+type Stage = 'idle' | 'P2' | 'P3' | 'P4' | 'P5' | 'P6' | 'ready_to_archive' | 'done';
+/** Brief (task book) ids. `P7`/`P9` are transactions and never hand out a brief. */
+type BriefStage = 'P1' | 'P2' | 'P3' | 'P4' | 'P5' | 'P6' | 'P8';
+/** The twelve supported commercial genres. */
+declare const GENRES: readonly ["玄幻修仙", "都市现代", "西方奇幻", "悬疑推理", "科幻", "游戏系统", "历史架空", "无限流", "轻小说", "军事", "末世流", "言情"];
+type Genre = (typeof GENRES)[number];
+/** Platform style profiles. */
+declare const PLATFORMS: readonly ["fanqie", "qidian", "qimao", "jinjiang"];
+type Platform = (typeof PLATFORMS)[number];
+/** Scene types used by rhythm budgets and PG-06. */
+declare const SCENE_TYPES: readonly ["战斗/动作章", "日常过渡章", "情感爆发章", "纯叙事章"];
+type SceneType = (typeof SCENE_TYPES)[number];
+/** A violation is blocking unless the rule pack declares it advisory. */
+type Severity = 'blocker' | 'advisory';
+/** All twenty-two service operations. */
+declare const OPERATIONS: readonly ["initProject", "archiveChapter", "amend", "rollback", "submitWorldPlan", "submitChapterPlan", "submitDraft", "submitReview", "submitRevision", "runCheck", "getStatus", "getBrief", "countWords", "queryState", "diff", "auditHistory", "advise", "export", "panelSummary", "panelChapters", "panelGates", "stats"];
+type Operation = (typeof OPERATIONS)[number];
+/** Structured, non-fatal note attached to a successful result. */
+interface Warning {
+  code: string;
+  message: string;
+}
+/** One reason a gate refused progress. */
+interface BlockingItem {
+  code: string;
+  scope?: string;
+  detail: string;
+  hint?: string;
+}
+/** Uniform success envelope of every service operation. */
+interface OpResult<T> {
+  data: T;
+  revision: number;
+  warnings: Warning[];
+  /** True when an idempotent retry was answered from the replay cache. */
+  replayed?: boolean;
+}
+/** A single reading-proof reference: the quoted text, its paragraph and chapter. */
+interface ReadingProofReference {
+  chapter?: number;
+  paragraph: number;
+  quote: string;
+}
+/** Three references proving the model read the chapter it claims to review. */
+interface ReadingProof {
+  opening: ReadingProofReference;
+  middle: ReadingProofReference;
+  ending: ReadingProofReference;
+}
+/** Error families map one-to-one to the three repair actions a caller can take. */
+declare const ERROR_CODES: {
+  readonly PROJECT_NOT_FOUND: "ENGINE_PROJECT_NOT_FOUND";
+  readonly PROJECT_EXISTS: "ENGINE_PROJECT_EXISTS";
+  readonly STAGE_ORDER: "ENGINE_STAGE_ORDER";
+  readonly GATE_BLOCKED: "ENGINE_GATE_BLOCKED";
+  readonly READING_PROOF_INVALID: "ENGINE_READING_PROOF_INVALID";
+  readonly SCORE_MISMATCH: "ENGINE_SCORE_MISMATCH";
+  readonly DELTA_UNVERIFIED: "ENGINE_DELTA_UNVERIFIED";
+  readonly RESOURCE_NEGATIVE_BALANCE: "ENGINE_RESOURCE_NEGATIVE_BALANCE";
+  readonly SCHEMA_TOO_NEW: "ENGINE_SCHEMA_TOO_NEW";
+  readonly SCHEMA_INVALID: "ENGINE_SCHEMA_INVALID";
+  readonly PATH_ESCAPE: "ENGINE_PATH_ESCAPE";
+  readonly LOCK_TIMEOUT: "ENGINE_LOCK_TIMEOUT";
+  readonly TXN_ABORTED: "ENGINE_TXN_ABORTED";
+  readonly RULEPACK_INVALID: "ENGINE_RULEPACK_INVALID";
+  readonly ID_EXHAUSTED: "ENGINE_ID_EXHAUSTED";
+  readonly CONFIG_INVALID: "ENGINE_CONFIG_INVALID";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/** Base class: carries a stable machine-readable code and an actionable hint. */
+declare class EngineError extends Error {
+  readonly code: string;
+  readonly hint: string | undefined;
+  constructor(code: string, message: string, hint?: string, options?: {
+    cause?: unknown;
+  });
+}
+/** Bad arguments or illegal preconditions: the model must change its call. */
+declare class EngineInputError extends EngineError {}
+/** Content did not pass a gate: the author must change the manuscript. */
+declare class EngineBlockedError extends EngineError {
+  readonly blocking: BlockingItem[];
+  constructor(code: string, message: string, blocking: BlockingItem[], hint?: string);
+}
+/** System fault: the environment or the code is wrong, not the caller. */
+declare class EngineFaultError extends EngineError {}
+/** Convenience constructor set, kept close to the classes so adapters agree. */
+declare const inputError: (code: string, message: string, hint?: string) => EngineInputError;
+declare const blockedError: (code: string, message: string, blocking: BlockingItem[], hint?: string) => EngineBlockedError;
+declare const faultError: (code: string, message: string, cause?: unknown) => EngineFaultError;
+/** One deduction inside one scoring dimension. */
+interface Deduction {
+  rule: string;
+  location: string;
+  delta: number;
+  note: string;
+}
+/** One of the fifteen scoring dimensions. */
+interface ScoreDimension {
+  id: string;
+  max: number;
+  deductions: Deduction[];
+}
+/** A review issue; blockers cannot be waived. */
+interface ReviewIssue {
+  id: string;
+  severity: Severity;
+  dimension: string;
+  location: string;
+  problem: string;
+  fix: string;
+  status: 'open' | 'fixed' | 'waived';
+  evidence?: string;
+}
+/** The persisted review document. */
+interface ReviewDocument {
+  schema_version: 1;
+  chapter: number;
+  round: number;
+  content_hash: string;
+  dimensions: ScoreDimension[];
+  issues: ReviewIssue[];
+  total: number;
+  /** The three reading proofs accepted at P4; PG-09 re-verifies them at P6. */
+  proof?: ReadingProof;
+}
+/** Structured machine finding. */
+interface Violation {
+  code: string;
+  severity: Severity;
+  location: {
+    paragraph: number;
+  };
+  detail: string;
+}
+/** Metric block produced by the machine pass. */
+interface MachineMetrics {
+  total_word_count: number;
+  non_empty_lines: number;
+  dialogue_lines: number;
+  dialogue_ratio: number;
+  paragraph_max: number;
+}
+/** The persisted check document. */
+interface CheckDocument {
+  schema_version: 1;
+  chapter: number;
+  scope: string[];
+  content_hash: string;
+  machine: {
+    violations: Violation[];
+    metrics: WordMetrics;
+  };
+  semantic: {
+    items: Array<{
+      id: string;
+      verdict: 'pass' | 'fail';
+      evidence: string;
+      note: string;
+    }>;
+  };
+  verdict: 'pass' | 'fail';
+}
+/** Word statistics with the single engine-wide counting rule. */
+interface WordMetrics {
+  total_word_count: number;
+  cjk_chars: number;
+  english_words: number;
+  numbers: number;
+  chinese_punct: number;
+  english_punct: number;
+  non_ws_chars: number;
+  total_lines: number;
+  non_empty_lines: number;
+  dialogue_lines: number;
+  dialogue_ratio: number;
+  paragraph_count: number;
+  paragraph_max_words: number;
+}
+/** Derived chapter row kept in `state/chapters.yaml`. */
+interface ChapterRecord {
+  num: number;
+  title: string;
+  file: string;
+  word_count: number;
+  dialogue_lines: number;
+  dialogue_ratio: number;
+  scene_type: SceneType;
+  narrator: string;
+  score: number;
+  status: 'draft' | 'reviewed';
+  content_hash: string;
+  summary: ChapterSummary;
+  /** 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. */
+  archive_digest?: string;
+}
+/** Summary block the model supplies with a draft and the engine persists. */
+interface ChapterSummary {
+  events: string[];
+  characters_appeared: string[];
+  foreshadows: {
+    planted: Array<{
+      key: string;
+      title: string;
+      description: string;
+    }>;
+    advanced: Array<{
+      key: string;
+      note: string;
+      new_info: boolean;
+    }>;
+    resolved: string[];
+  };
+  new_elements: {
+    locations: string[];
+    abilities: string[];
+    artifacts: string[];
+  };
+  resource_changes: Array<{
+    character: string;
+    resource: string;
+    delta: number;
+    reason: string;
+  }>;
+  opening: string;
+  continuity: {
+    opens_from: string;
+    ends_with: string;
+  };
+  hook_strength: number;
+  pleasure_points: string[];
+  plot_advancement: 'high' | 'mid' | 'low';
+}
+/** Round counters live in the pipeline and are engine-owned. */
+interface RoundCounters {
+  review: number;
+  revise: number;
+  check: number;
+}
+/** How one ledger entity changed in this chapter. */
+type DeltaAction = 'created' | 'updated' | 'no_change';
+/** One character declaration inside `state_delta.characters`. */
+interface CharacterDelta {
+  action: DeltaAction;
+  reason?: string;
+  role?: string;
+  profile?: Record<string, unknown>;
+  current_state?: Record<string, unknown>;
+  growth?: {
+    chapter: number;
+    change: string;
+    status_change: string;
+  };
+}
+/** One world entity declaration inside `state_delta.world`. */
+interface WorldDelta {
+  action: DeltaAction;
+  reason?: string;
+  kind?: 'location' | 'ability' | 'artifact' | 'faction' | 'rule';
+  description?: string;
+  layout?: string;
+  capacity?: number;
+  detail?: Record<string, unknown>;
+}
+/** One foreshadow declaration inside `state_delta.foreshadows`. */
+interface ForeshadowDelta {
+  action: DeltaAction;
+  reason?: string;
+  title?: string;
+  description?: string;
+  note?: string;
+  new_info?: boolean;
+}
+/** One timeline-event declaration; keys are `summary.events` indices. */
+interface TimelineDelta {
+  action: DeltaAction;
+  reason?: string;
+  story_time?: string;
+  description?: string;
+  location?: string;
+  characters?: string[];
+}
+/** One relationship declaration; keys are `"a|b"`. */
+interface RelationshipDelta {
+  action: DeltaAction;
+  reason?: string;
+  a?: string;
+  b?: string;
+  type?: string;
+  description?: string;
+  note?: string;
+}
+/**
+ * The archive reconciliation sheet. Every entity the chapter claims (appeared
+ * characters, new world elements, foreshadow keys, events, relationships) must
+ * appear here; omission is a hard error, never an implicit no_change.
+ */
+interface StateDelta {
+  characters: Record<string, CharacterDelta>;
+  foreshadows: Record<string, ForeshadowDelta>;
+  timeline: Record<string, TimelineDelta>;
+  world: Record<string, WorldDelta>;
+  relationships: Record<string, RelationshipDelta>;
+}
+/** Optional handoff override; omitted values are derived by the engine. */
+interface ArchiveHandoff {
+  volume?: number;
+  volume_name?: string;
+  act?: string;
+  act_progress?: string;
+}
+/** Pipeline document (`state/pipeline.yaml`). */
+interface PipelineState {
+  schema_version: 1;
+  revision: number;
+  chapter: number;
+  stage: Stage;
+  rounds: RoundCounters;
+  briefs: Record<string, {
+    issued_at: string;
+    digest: string;
+  }>;
+  blocking: BlockingItem[];
+  /** Hash of the review document last written by submitReview/submitRevision. */
+  review_digest?: string;
+  last_action: {
+    op: string;
+    at: string;
+    digest: string;
+  } | null;
+}
+/** Chapter index document (`state/chapters.yaml`). */
+interface ChaptersDocument {
+  schema_version: 1;
+  chapters: ChapterRecord[];
+}
+/** Character registry document. */
+interface CharactersDocument {
+  schema_version: 1;
+  characters: Array<{
+    name: string;
+    role: string;
+    first_appearance: number;
+    profile: Record<string, unknown>;
+    current_state: Record<string, unknown>;
+    growth: Array<{
+      chapter: number;
+      change: string;
+      status_change: string;
+    }>;
+    updated_at: number;
+  }>;
+}
+/** World registry document. */
+interface WorldDocument {
+  schema_version: 1;
+  locations: Array<{
+    name: string;
+    first_appearance: number;
+    locked: boolean;
+    description: string;
+    layout: string;
+    capacity: number;
+    changes: Array<{
+      chapter: number;
+      change: string;
+      reason: string;
+    }>;
+  }>;
+  abilities: unknown[];
+  artifacts: unknown[];
+  factions: unknown[];
+  rules: unknown[];
+}
+/** Locked first-appearance snapshots. */
+interface LocksDocument {
+  schema_version: 1;
+  locked_at_chapter: number;
+  characters: Record<string, {
+    first_appearance: number;
+    locked_at: number;
+    appearance: string;
+  }>;
+  locations: Record<string, {
+    first_appearance: number;
+    locked_at: number;
+    layout: string;
+    capacity: number;
+  }>;
+}
+/** Foreshadow ledger document. */
+interface ForeshadowsDocument {
+  schema_version: 1;
+  next_seq: number;
+  items: Array<{
+    id: string;
+    title: string;
+    planted: number;
+    last_touched: number;
+    status: 'planted' | 'dormant' | 'advanced' | 'resolved';
+    resolved_at: number | null;
+    description: string;
+    advance_log: Array<{
+      chapter: number;
+      note: string;
+      new_info: boolean;
+    }>;
+  }>;
+}
+/** Timeline ledger document. */
+interface TimelineDocument {
+  schema_version: 1;
+  next_seq: number;
+  items: Array<{
+    id: string;
+    chapter: number;
+    story_time: string;
+    description: string;
+    location: string;
+    characters: string[];
+  }>;
+}
+/** Relationship ledger document. */
+interface RelationshipsDocument {
+  schema_version: 1;
+  next_seq: number;
+  items: Array<{
+    id: string;
+    a: string;
+    b: string;
+    type: string;
+    since: number;
+    description: string;
+    evolution: Array<{
+      chapter: number;
+      note: string;
+    }>;
+  }>;
+}
+/** Handoff document (`state/handoff.yaml`). */
+interface HandoffDocument {
+  schema_version: 1;
+  current_chapter: number;
+  volume: number;
+  volume_name: string;
+  act: string;
+  act_progress: string;
+  next_chapter: number;
+  last_summary: string;
+  open_hooks: Array<{
+    id: string;
+    title: string;
+  }>;
+  updated_at: string;
+}
+/** Project definition (`novel.yaml`). */
+interface NovelProject {
+  schema_version: 1;
+  title: string;
+  genre: Genre;
+  platform: Platform;
+  author: string;
+  description: string;
+  created_at: string;
+  targets: {
+    words_per_chapter: [number, number];
+    total_chapters: number | null;
+    dialogue_ratio: [number, number];
+  };
+}
+/** World plan (`plans/chNNN.world.yaml`). */
+interface WorldPlanInput {
+  chapter: number;
+  objective: string;
+  constraints: string[];
+  characters: Array<{
+    name: string;
+    role: string;
+    current_state: string;
+  }>;
+  locations: Array<{
+    name: string;
+    layout: string;
+    capacity: number;
+  }>;
+  continuity_notes: string[];
+}
+/** Chapter plan (`plans/chNNN.chapter.yaml`). */
+interface ChapterPlanInput {
+  chapter: number;
+  title: string;
+  scene_type: SceneType;
+  narrator: string;
+  beats: string[];
+  opening: string;
+  ending: string;
+  target_words: [number, number];
+}
+/** Draft submission payload. */
+interface DraftInput {
+  chapter: number;
+  content: string;
+  chapter_title: string;
+  scene_type: SceneType;
+  narrator: string;
+  summary: ChapterSummary;
+}
+/** Review submission payload. */
+interface ReviewInput {
+  chapter: number;
+  dimensions: ScoreDimension[];
+  issues: ReviewIssue[];
+  /** The model's claimed headline score; checked against 150 - Σdelta. */
+  total: number;
+  proof: ReadingProof;
+}
+/** Revision submission payload. */
+interface RevisionInput {
+  chapter: number;
+  content: string;
+  summary: ChapterSummary;
+}
+/** Semantic check items supplied by the model. */
+interface SemanticItem {
+  id: string;
+  verdict: 'pass' | 'fail';
+  evidence: string;
+  note: string;
+}
+/** Everything a gate evaluation needs, gathered by the engine before writing. */
+interface GateInput {
+  operation: Operation;
+  stage: Stage;
+  text: string;
+  chapter: number;
+  project: NovelProject;
+  pipeline: PipelineState;
+  chapters: ChaptersDocument;
+  briefDigest: string | null;
+  briefStage: BriefStage | null;
+  draftTitle: string | null;
+  sceneType: SceneType | null;
+  summary: ChapterSummary | null;
+  /** P5 may omit `summary`; when omitted, the previous plan summary is reused. */
+  summaryProvided?: boolean;
+  review: ReviewDocument | null;
+  check: CheckDocument | null;
+  semantic: SemanticItem[];
+  proof: ReadingProof | null;
+  rounds: RoundCounters;
+  /** Facts PG-12 checks before the archive transaction starts. */
+  archive: {
+    chapterExists: boolean;
+    checkPassed: boolean;
+    hashMatches: boolean;
+  } | null;
+  evidence: {
+    characters: CharactersDocument | null;
+    foreshadows: ForeshadowsDocument | null;
+    timeline: TimelineDocument | null;
+    relationships: RelationshipsDocument | null;
+    world: WorldDocument | null;
+    locks: LocksDocument | null;
+  };
+  previousText: string | null;
+  /** The three preceding chapters, newest first, for the duplicate rule. */
+  previousTexts: string[];
+  priorSceneTypes: SceneType[];
+}
+/** Gate evaluation outcome. */
+interface GateResult {
+  passed: boolean;
+  blocking: BlockingItem[];
+}
+/** A chapter row projected to the panel and status output. */
+interface ChapterStatusRow {
+  num: number;
+  title: string;
+  word_count: number;
+  score: number;
+  stage: Stage;
+  passed: boolean;
+}
+/** The `getStatus` payload. */
+interface StatusReport {
+  project: {
+    title: string;
+    genre: Genre;
+    platform: Platform;
+    root: string;
+  };
+  /** The chapter requested for metrics; may be historical. */
+  chapter: number;
+  /** The chapter the pipeline is currently working on. */
+  active_chapter: number;
+  stage: Stage;
+  rounds: RoundCounters;
+  blocking: BlockingItem[];
+  metrics: WordMetrics | null;
+  next: {
+    tool: string;
+    args: Record<string, unknown>;
+    reason: string;
+  };
+}
+/** `advise` answer: which tool to call next and why. */
+interface AdviceReport {
+  stage: Stage;
+  chapter: number;
+  tool: string;
+  args: Record<string, unknown>;
+  reason: string;
+  blocking: BlockingItem[];
+}
+/** One history row derived from the journal. */
+interface AuditRow {
+  at: string;
+  op: string;
+  chapter: number;
+  revision: number;
+  txid: string;
+  status: 'committed' | 'aborted';
+  files: string[];
+}
+/** One diff hunk between two revisions of a chapter. */
+interface DiffReport {
+  chapter: number;
+  before: string;
+  after: string;
+  added: number;
+  removed: number;
+  hunks: Array<{
+    kind: 'add' | 'remove' | 'same';
+    line: string;
+  }>;
+}
+/** Export capabilities. */
+type ExportKind = 'md' | 'txt' | 'epub';
+/** One blacklisted word. */
+interface TermEntry {
+  term: string;
+  note?: string;
+  /** Allow the term inside a dialogue-dominant paragraph (character voice). */
+  dialogueExempt?: boolean;
+}
+/** A soft-limit word, optionally relaxed for some genres. */
+interface LimitEntry {
+  term: string;
+  limit: number;
+  genres?: Genre[];
+}
+/** Structured rule pack: all taste lives here, never in code. */
+interface Rulepack {
+  schema_version: 1;
+  name: string;
+  version: string;
+  lexicon: {
+    zero_tolerance: TermEntry[];
+    soft: LimitEntry[];
+    contextual: LimitEntry[];
+    meta_narration: TermEntry[];
+    reader_intrusion: Array<{
+      pattern: string;
+    }>;
+    god_view: Array<{
+      pattern: string;
+    }>;
+    conclusion_first: {
+      verbs: string[];
+      causals: string[];
+    };
+  };
+  format: {
+    paragraph_max_words: number;
+    forbid_markdown: boolean;
+    forbid_semicolon: boolean;
+    forbid_english_ellipsis: boolean;
+    title: {
+      pattern: string;
+      min_chars: number;
+      max_chars: number;
+    };
+    system_labels: string[];
+    scene_separators: string[];
+    markdown_markers: string[];
+  };
+  punctuation: {
+    dash: {
+      base: Record<SceneType, number>;
+      scale_words: number;
+      token: string;
+    };
+    period_density: {
+      min: number;
+      max: number;
+    };
+    ellipsis_run: {
+      max: number;
+      token: string;
+    };
+    uniform_sentence: {
+      min_sentences: number;
+      ratio: number;
+    };
+    consecutive_le: {
+      max: number;
+      char: string;
+    };
+    /** Paragraphs at or above this quoted-character share skip rhythm checks. */
+    dialogue_dominant_ratio: number;
+  };
+  semantics: {
+    adjective_density: {
+      max: number;
+      adjectives: string[];
+    };
+    pleasure_density: {
+      min: number;
+      keywords: string[];
+      window: number;
+    };
+    sensory_density: {
+      min: number;
+      senses: string[];
+      window: number;
+    };
+    water_words: {
+      window: number;
+      threshold: number;
+      scene_thresholds?: Partial<Record<SceneType, number>>;
+      terms: string[];
+    };
+  };
+  /** Platform style profiles; `initProject` uses these when the caller omits targets. */
+  platform: Record<Platform, {
+    words_per_chapter: [number, number];
+    dialogue_ratio: [number, number];
+  }>;
+  /** Genre guides injected into the task-book context; no threshold branches on them. */
+  genres: Record<Genre, {
+    note: string;
+  }>;
+  crosschapter: {
+    duplicate_similarity: number;
+    duplicate_advisory: number;
+    /** Paragraphs shorter than this many non-whitespace chars are not duplicate candidates. */
+    duplicate_min_chars: number;
+    foreshadow_min_dormancy: number;
+    foreshadow_dormant_after: number;
+    check_time: boolean;
+    lock_similarity: number;
+  };
+  quality: {
+    dimensions: Array<{
+      id: string;
+      max: number;
+    }>;
+  };
+  exclusions: Array<{
+    pair: [string, string];
+    family: string;
+  }>;
+  exemptions: string[];
+}
+/** Every persisted document the engine knows how to load. */
+type DocKind = 'project' | 'pipeline' | 'chapters' | 'characters' | 'world' | 'locks' | 'foreshadows' | 'timeline' | 'relationships' | 'handoff' | 'review' | 'check' | 'worldPlan' | 'chapterPlan';
+/** One project row in the cross-project registry. */
+interface RegistryEntry {
+  root: string;
+  title: string;
+  updated_at: string;
+}
+/** One rendered task book. */
+interface BriefDocument {
+  stage: BriefStage;
+  title: string;
+  content: string;
+  /** sha256 of the source file, so a task book change is visible to callers. */
+  contentHash: string;
+}
+/**
+ * Task books live on disk (`briefs/*.md`), never in code: changing writing
+ * guidance must not require a release.
+ */
+declare class BriefLibrary {
+  private readonly overrideDirectory;
+  private readonly bundledDirectory;
+  constructor(directory?: string);
+  /** Absolute path of the override when configured, otherwise the bundled one. */
+  pathFor(stage: BriefStage): string;
+  load(stage: BriefStage): BriefDocument;
+  /** Replace `{{name}}` placeholders; unknown placeholders are left visible. */
+  render(stage: BriefStage, variables: Record<string, string | number>): BriefDocument;
+}
+/** Gate identifiers in fixed evaluation order. */
+declare const GATES: {
+  readonly 'PG-01': "BRIEF_REQUIRED";
+  readonly 'PG-02': "STAGE_ORDER";
+  readonly 'PG-03': "WORD_COUNT";
+  readonly 'PG-04': "FORMAT";
+  readonly 'PG-05': "SUMMARY_SCHEMA";
+  readonly 'PG-06': "SCENE_TYPE";
+  readonly 'PG-07': "SCORE";
+  readonly 'PG-08': "ISSUES_CLEARED";
+  readonly 'PG-09': "READING_PROOF";
+  readonly 'PG-10': "CONSISTENCY";
+  readonly 'PG-11': "ROUNDS";
+  readonly 'PG-12': "ARCHIVE_ATOMIC";
+};
+type GateId = keyof typeof GATES;
+/** Everything gate evaluation needs beyond the input: taste comes from the pack. */
+interface GateOptions {
+  rulepack: Rulepack;
+  minScore: number;
+}
+/** Parse "第 12 段" into 12; null when the location is not a paragraph reference. */
+declare function parseParagraphLocation(location: string): number | null;
+/** Verify one reading-proof reference against the manuscript. */
+declare function verifyReference(text: string, reference: ReadingProofReference): string | null;
+/** Evaluate all twelve gates and return every blocking item, in canonical order. */
+declare function evaluateGates(input: GateInput, options: GateOptions): GateResult;
+/**
+ * Which gates apply to an operation. A gate that does not apply must not run:
+ * judging word count on a world plan would block every plan.
+ */
+declare function applicableGates(input: GateInput): GateId[];
+/** Human-facing label of a gate id, used by status and the panel. */
+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'];
+/** The shared read model: everything the panel, status and commands render. */
+interface PanelDraft {
+  num: number;
+  title: string;
+  wordCount: number;
+  score: number;
+  status: 'draft' | 'blocked';
+  details: string;
+}
+interface PanelSnapshot {
+  root: string;
+  title: string;
+  genre: string;
+  platform: string;
+  chapter: number;
+  stage: Stage;
+  revision: number;
+  rounds: {
+    review: number;
+    revise: number;
+    check: number;
+  };
+  blocking: BlockingItem[];
+  /** Recommended next action; lets the panel explain a stage with no blockers. */
+  next?: StatusReport['next'];
+  /** True only when the configured total chapter target has been reached. */
+  finished?: boolean;
+  chapters: ChapterRecord[];
+  /** The active, not-yet-archived chapter; archived rows come from `chapters`. */
+  draft?: PanelDraft | null;
+  /** Total words across the index, for the header. */
+  totalWords: number;
+  /** The nine-phase strip state, derived from the pipeline stage. */
+  phases: Array<{
+    id: string;
+    done: boolean;
+    active: boolean;
+  }>;
+}
+interface PanelSummaryDto {
+  schemaVersion: number;
+  panelId: string;
+  title: string;
+  genre: string;
+  platform: string;
+  chapter: number;
+  stage: Stage;
+  revision: number;
+  totalWords: number;
+  totalChapters: number;
+  phases: Array<{
+    id: string;
+    done: boolean;
+    active: boolean;
+  }>;
+  blocking: BlockingItem[];
+  next?: {
+    tool: string;
+    reason: string;
+  };
+  /** Absent for older payloads; false means the current chapter cycle is done. */
+  finished?: boolean;
+}
+interface PanelChapterRow {
+  num: number;
+  title: string;
+  wordCount: number;
+  score: number;
+  stage: Stage;
+  status: 'passed' | 'blocked' | 'draft';
+  /** One-line summary shown when the row is expanded. */
+  details: string;
+}
+interface PanelChaptersDto {
+  schemaVersion: number;
+  panelId: string;
+  rows: PanelChapterRow[];
+}
+interface PanelGatesDto {
+  schemaVersion: number;
+  panelId: string;
+  stage: Stage;
+  blocking: BlockingItem[];
+  /** Human-facing one-liner per blocking item. */
+  explanations: string[];
+}
+/** The nine-phase progress strip: phases before the active one are done. */
+declare function phaseStrip(stage: Stage, finished?: boolean): Array<{
+  id: string;
+  done: boolean;
+  active: boolean;
+}>;
+/** Project a chapter row for the table; a reviewed chapter without blockers reads as passed. */
+declare function projectChapter(record: ChapterRecord): PanelChapterRow;
+declare function projectSummary(snapshot: PanelSnapshot): PanelSummaryDto;
+declare function projectChapters(snapshot: PanelSnapshot): PanelChaptersDto;
+declare function projectGates(snapshot: PanelSnapshot): PanelGatesDto;
+/** Plugin configuration, mapped from `Config` in `src/index.ts`. */
+interface EngineConfig {
+  projectRoot: string;
+  /** Where the multi-project registry lives; never inside a project. */
+  stateDir: string;
+  tools: {
+    mode: 'all' | 'core';
+  };
+  quality: {
+    minScore: number;
+  };
+  briefs: {
+    overrides: string;
+  };
+  storage: {
+    backupRetention: number;
+  };
+}
+/** Events other plugins may subscribe to; payloads never contain manuscript text. */
+type EngineEvent = {
+  name: 'novel/archived';
+  payload: {
+    schemaVersion: 1;
+    projectRoot: string;
+    chapter: number;
+    score: number;
+    words: number;
+  };
+} | {
+  name: 'novel/blocked';
+  payload: {
+    schemaVersion: 1;
+    projectRoot: string;
+    operation: string;
+    blocking: number;
+  };
+} | {
+  name: 'novel/amended';
+  payload: {
+    schemaVersion: 1;
+    projectRoot: string;
+    path: string;
+    reason: string;
+  };
+};
+interface InitProjectInput {
+  title: string;
+  genre: NovelProject['genre'];
+  platform: NovelProject['platform'];
+  author?: string;
+  description?: string;
+  words_per_chapter?: [number, number];
+  total_chapters?: number | null;
+  dialogue_ratio?: [number, number];
+  root?: string;
+}
+interface StatusInput {
+  chapter?: number;
+  root?: string;
+}
+interface BriefInput {
+  stage: BriefStage;
+  chapter?: number;
+  root?: string;
+}
+interface WorldPlanSubmission extends WorldPlanInput {
+  root?: string;
+}
+interface ChapterPlanSubmission extends ChapterPlanInput {
+  root?: string;
+}
+interface DraftSubmission {
+  chapter: number;
+  content: string;
+  chapter_title: string;
+  scene_type: SceneType;
+  narrator: string;
+  summary: ChapterSummary;
+  root?: string;
+}
+interface ReviewSubmission extends ReviewInput {
+  root?: string;
+}
+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;
+  root?: string;
+}
+interface CheckSubmission {
+  chapter: number;
+  /** The four P6 semantic items; omission is a failed check, never a pass. */
+  semantic: SemanticItem[];
+  scope?: string[];
+  root?: string;
+}
+interface ArchiveSubmission {
+  chapter: number;
+  /** Mandatory reconciliation sheet for the five derived ledgers. */
+  state_delta: StateDelta;
+  /** Optional volume/act override; omitted values are derived by the engine. */
+  handoff?: ArchiveHandoff;
+  root?: string;
+}
+interface AmendSubmission {
+  path: string;
+  content: Record<string, unknown>;
+  reason: string;
+  root?: string;
+}
+interface RollbackSubmission {
+  chapter: number;
+  toStage: 'P1' | 'P2' | 'P3' | 'P4' | 'P5' | 'P6';
+  reason?: string;
+  root?: string;
+}
+interface DiffInput {
+  chapter: number;
+  before?: string;
+  after?: string;
+  root?: string;
+}
+interface AuditInput {
+  limit?: number;
+  root?: string;
+}
+interface ExportInput {
+  kind: ExportKind;
+  chapter?: number;
+  root?: string;
+}
+interface StateQueryInput {
+  kind: DocKind | 'novel' | 'planWorld' | 'planChapter';
+  chapter?: number;
+  root?: string;
+}
+interface WordCountInput {
+  text?: string;
+  chapter?: number;
+  root?: string;
+}
+/**
+ * The single write authority. Tools, commands, the panel and task books never
+ * touch a file; every mutation is one of these operations.
+ */
+declare class EngineService {
+  private readonly config;
+  private readonly stores;
+  private readonly mutex;
+  private readonly replay;
+  private readonly briefs;
+  private readonly now;
+  /** The project this process last touched; the panel follows it without a workspace hint. */
+  private lastRoot;
+  constructor(config: EngineConfig, rulepack: Rulepack | (() => Rulepack), options?: {
+    briefs?: BriefLibrary;
+    now?: () => Date;
+    onEvent?: (event: EngineEvent) => void;
+  });
+  /** Compiled on first use so `apply()` performs no IO. */
+  private readonly rulepackSource;
+  private compiled;
+  private disposed;
+  /**
+   * Release in-process caches on host teardown. The engine owns no file
+   * handles, so this is deliberately synchronous and idempotent; it prevents a
+   * disposed instance from keeping project stores and replay results alive.
+   */
+  dispose(): void;
+  private get rulepack();
+  private readonly onEvent;
+  private readonly signalContext;
+  /** Bind the host cancellation signal to the engine work of one tool call. */
+  withSignal<T>(signal: AbortSignal | undefined, task: () => Promise<T>): Promise<T>;
+  /** The configured default project root. */
+  defaultRoot(): string;
+  /**
+   * Resolve an omitted root through the cross-project registry. The registry is
+   * convenience state, so a corrupt or unreadable registry falls back to the
+   * configured root instead of making every call fail.
+   */
+  private resolveRoot;
+  private storeFor;
+  initProject(input: InitProjectInput): Promise<OpResult<{
+    root: string;
+    title: string;
+    chapter: number;
+    stage: Stage;
+  }>>;
+  getStatus(input?: StatusInput): Promise<OpResult<StatusReport>>;
+  countWords(input?: WordCountInput): Promise<OpResult<WordMetrics>>;
+  queryState(input: StateQueryInput): Promise<OpResult<unknown>>;
+  advise(input?: {
+    root?: string;
+  }): Promise<OpResult<{
+    stage: Stage;
+    chapter: number;
+    tool: string;
+    args: Record<string, unknown>;
+    reason: string;
+    blocking: BlockingItem[];
+  }>>;
+  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>;
+  }>>;
+  submitWorldPlan(input: WorldPlanSubmission): Promise<OpResult<{
+    chapter: number;
+    stage: Stage;
+    plan_file: string;
+  }>>;
+  submitChapterPlan(input: ChapterPlanSubmission): Promise<OpResult<{
+    chapter: number;
+    stage: Stage;
+    plan_file: string;
+  }>>;
+  submitDraft(input: DraftSubmission): Promise<OpResult<{
+    chapter: number;
+    stage: Stage;
+    metrics: WordMetrics;
+    warnings: Warning[];
+  }>>;
+  submitReview(input: ReviewSubmission): Promise<OpResult<{
+    chapter: number;
+    round: number;
+    total: number;
+    open_blockers: number;
+    next_stage: Stage;
+  }>>;
+  submitRevision(input: RevisionSubmission): Promise<OpResult<{
+    chapter: number;
+    stage: Stage;
+    metrics: WordMetrics;
+  }>>;
+  runCheck(input: CheckSubmission): Promise<OpResult<{
+    chapter: number;
+    verdict: 'pass' | 'fail';
+    violations: number;
+    metrics: WordMetrics;
+    stage: Stage;
+  }>>;
+  archiveChapter(input: ArchiveSubmission): Promise<OpResult<{
+    chapter: number;
+    assigned_ids: Record<string, string>;
+    metrics: WordMetrics;
+    score: number;
+  }>>;
+  amend(input: AmendSubmission): Promise<OpResult<{
+    path: string;
+    revision: number;
+  }>>;
+  rollback(input: RollbackSubmission): Promise<OpResult<{
+    chapter: number;
+    stage: Stage;
+  }>>;
+  diff(input: DiffInput): Promise<OpResult<DiffReport>>;
+  auditHistory(input?: AuditInput): Promise<OpResult<AuditRow[]>>;
+  export(input: ExportInput): Promise<OpResult<{
+    kind: ExportKind;
+    files: string[];
+  }>>;
+  panelSummary(input?: {
+    root?: string;
+  }): Promise<PanelSummaryDto>;
+  panelChapters(input?: {
+    root?: string;
+  }): Promise<PanelChaptersDto>;
+  panelGates(input?: {
+    root?: string;
+  }): Promise<PanelGatesDto>;
+  /** One snapshot, three projections: the panel never mixes revisions. */
+  panelBundle(input?: {
+    root?: string;
+  }): Promise<{
+    summary: PanelSummaryDto;
+    chapters: PanelChaptersDto;
+    gates: PanelGatesDto;
+  }>;
+  stats(input?: {
+    root?: string;
+  }): Promise<{
+    totalWords: number;
+    chapters: number;
+    revision: number;
+    rulepack: string;
+    averageScore: number;
+    lastScore: number;
+    openForeshadows: number;
+  }>;
+  private registry;
+  /** List known projects (convenience only; a project opens without a row). */
+  listProjects(): Promise<{
+    active: string | null;
+    projects: RegistryEntry[];
+  }>;
+  /** Record the current project in the registry. */
+  registerProject(input?: {
+    root?: string;
+  }): Promise<{
+    active: string | null;
+    projects: RegistryEntry[];
+  }>;
+  /** Choose the default project for future convenience calls. */
+  setActiveProject(input: {
+    root: string;
+  }): Promise<{
+    active: string | null;
+  }>;
+  /** Forget a registry row; the project directory is never touched. */
+  forgetProject(input: {
+    root: string;
+  }): Promise<{
+    active: string | null;
+    projects: RegistryEntry[];
+  }>;
+  /**
+   * Import one ledger from a settings pack. Always previews with a diff; a
+   * dry run never writes, and an apply is a normal transaction.
+   */
+  importPack(input: {
+    kind: 'characters' | 'world' | 'foreshadows' | 'relationships' | 'timeline';
+    content: unknown;
+    dryRun?: boolean;
+    root?: string;
+  }): Promise<OpResult<{
+    kind: string;
+    preview: string;
+    applied: boolean;
+  }>>;
+  private panelSnapshot;
+  private nextStep;
+  /** A computed blocker for the retry budget the next operation would consume. */
+  private roundsLimitBlock;
+  /** Pipeline blockers plus budget exhaustion, so status/panel cannot say "all clear". */
+  private effectiveBlocking;
+  /** Whether the stored brief still signs the current snapshot. */
+  private briefIsCurrent;
+  /** Arguments valid for the tool `STAGE_NEXT` recommends at this stage. */
+  private nextArgs;
+  private metricsFor;
+  private readChapter;
+  private latestBackup;
+  private chaptersForExport;
+  private machine;
+  private briefContextFor;
+  private briefDigest;
+  private briefVariables;
+  private assertGates;
+  private assertChapterParameter;
+  private assertChapter;
+  private load;
+  private mutate;
+  private invalidateReplay;
+  private emptySnapshot;
+}
+/** Read, compile and freeze a pack. Runtime callers always use the bundled default. */
+declare function loadRulepack(path?: string): Rulepack;
+/** One rendered chapter, assembled by the engine before rendering. */
+interface ExportChapter {
+  num: number;
+  title: string;
+  text: string;
+}
+/** `第 N 章 标题` — the title stored in the index never carries the prefix. */
+declare function chapterHeading(chapter: Pick<ChapterRecord, 'num' | 'title'>): string;
+/** Markdown export: one heading per chapter, body unchanged (it is plain text). */
+declare function renderMarkdown(project: NovelProject, chapters: readonly ExportChapter[]): string;
+/** Plain-text export: no markdown syntax, no BOM. */
+declare function renderPlainText(project: NovelProject, chapters: readonly ExportChapter[]): string;
+/** Blurb built from the project record; deterministic, no model call. */
+declare function renderBlurb(project: NovelProject): string;
+/** Cover as a standalone SVG string; text is escaped, palette is theme-neutral. */
+declare function renderCover(project: NovelProject): string;
+/** XHTML chapter document for the EPUB package. */
+declare function renderEpubChapter(chapter: ExportChapter): string;
+declare const name = "dsh-novel-write-engine";
+declare const inject: string[];
+/** Plugin configuration. Every value is also readable in `--dump-config`. */
+interface Config {
+  projectRoot: string;
+  minScore: number;
+  /** `all` or `core`; validated in `apply`, so the schema stays a plain string. */
+  toolsMode: string;
+  /** Optional directory with user task-book overrides; empty uses the bundled set. */
+  briefsOverrides: string;
+  /** How many archived-chapter backups to keep. */
+  backupRetention: number;
+  /** Directory for cross-project bookkeeping; never inside a project. */
+  stateDir: string;
+}
+declare const Config: Schema<Config>;
+/**
+ * Assemble the engine and its four thin adapters. No IO happens here: the rule
+ * pack compiles on first use, task books load on demand, and the store is
+ * created lazily per project root.
+ */
+declare function apply(ctx: Context, config: Config): void;
+export { AdviceReport, ArchiveHandoff, AuditRow, BlockingItem, BriefDocument, BriefLibrary, BriefStage, ChapterPlanInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, Deduction, DeltaAction, DiffReport, DraftInput, ERROR_CODES, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, HandoffDocument, LocksDocument, MachineMetrics, NovelProject, OPERATIONS, OpResult, Operation, PLATFORMS, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ReviewDocument, ReviewInput, ReviewIssue, RevisionInput, RoundCounters, SCENE_TYPES, SCHEMA_VERSION, SceneType, ScoreDimension, SemanticItem, Severity, Stage, StateDelta, StatusReport, TimelineDelta, TimelineDocument, Violation, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, applicableGates, apply, blockedError, briefStageFor, chapterHeading, evaluateGates, faultError, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, verifyReference };