dsh-novel-write-engine 0.2.0 → 0.2.2

package/lib/index.d.ts

@@ -22,8 +22,8 @@ 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 thirty-one service operations (22 inherited from 0.1.x, 9 book-level). */
-declare const OPERATIONS: readonly ["initProject", "archiveChapter", "amend", "rollback", "reopenChapter", "submitWorldPlan", "submitChapterPlan", "submitDraft", "submitReview", "submitRevision", "runCheck", "submitBookPlan", "submitOutline", "importOutline", "submitWorldbook", "getStatus", "getBrief", "countWords", "queryState", "diff", "auditHistory", "advise", "search", "doctor", "report", "guide", "export", "panelSummary", "panelChapters", "panelGates", "stats"];
+/** All thirty-two service operations (22 inherited + 9 book-level + restoreBackup). */
+declare const OPERATIONS: readonly ["initProject", "archiveChapter", "amend", "rollback", "reopenChapter", "submitWorldPlan", "submitChapterPlan", "submitDraft", "submitReview", "submitRevision", "runCheck", "submitBookPlan", "submitOutline", "importOutline", "submitWorldbook", "getStatus", "getBrief", "countWords", "queryState", "diff", "auditHistory", "advise", "search", "doctor", "report", "guide", "export", "panelSummary", "panelChapters", "panelGates", "stats", "restoreBackup"];
 type Operation = (typeof OPERATIONS)[number];
 /** Structured, non-fatal note attached to a successful result. */
 interface Warning {
@@ -60,6 +60,9 @@ interface ReadingProof {
 /** 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_AMBIGUOUS: "ENGINE_PROJECT_AMBIGUOUS";
+  readonly PROJECT_MISSING: "ENGINE_PROJECT_MISSING";
+  readonly PROJECT_IDENTITY_MISMATCH: "ENGINE_PROJECT_IDENTITY_MISMATCH";
   readonly PROJECT_EXISTS: "ENGINE_PROJECT_EXISTS";
   readonly STAGE_ORDER: "ENGINE_STAGE_ORDER";
   readonly GATE_BLOCKED: "ENGINE_GATE_BLOCKED";
@@ -161,6 +164,7 @@ interface CheckDocument {
   content_hash: string;
   machine: {
     violations: Violation[];
+    advisories?: Violation[];
     metrics: WordMetrics;
   };
   semantic: {
@@ -171,6 +175,8 @@ interface CheckDocument {
       note: string;
     }>;
   };
+  /** Advisory codes the author has explicitly acknowledged for this content. */
+  acknowledged?: string[];
   verdict: 'pass' | 'fail';
 }
 /** Every persisted document whose damage status/panel can report. */
@@ -189,6 +195,8 @@ interface WordMetrics {
   numbers: number;
   chinese_punct: number;
   english_punct: number;
+  /** All punctuation counted by the engine; total = cjk + words + numbers + punctuation. */
+  punctuation_chars: number;
   non_ws_chars: number;
   total_lines: number;
   non_empty_lines: number;
@@ -211,6 +219,10 @@ interface ChapterRecord {
   status: 'draft' | 'reviewed';
   content_hash: string;
   summary: ChapterSummary;
+  /** How hard this chapter was before it was archived. */
+  rounds?: RoundCounters;
+  final_check?: 'pass' | 'fail';
+  archived_at?: string;
   /** 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. */
@@ -225,6 +237,7 @@ interface ChapterSummary {
       key: string;
       title: string;
       description: string;
+      anchor?: string;
     }>;
     advanced: Array<{
       key: string;
@@ -258,6 +271,8 @@ interface RoundCounters {
   review: number;
   revise: number;
   check: number;
+  /** Lifetime rollback count on a chapter record; never stored in the live pipeline. */
+  rollbacks?: number;
 }
 /** How one ledger entity changed in this chapter. */
 type DeltaAction = 'created' | 'updated' | 'no_change';
@@ -289,6 +304,8 @@ interface ForeshadowDelta {
   action: DeltaAction;
   reason?: string;
   title?: string;
+  /** Verbatim manuscript quote used for verification; title stays a readable label. */
+  anchor?: string;
   description?: string;
   note?: string;
   new_info?: boolean;
@@ -331,6 +348,28 @@ interface ArchiveHandoff {
   act?: string;
   act_progress?: string;
 }
+/** One issued task-book receipt; the brief itself is rendered on demand. */
+interface BriefReceipt {
+  chapter: number;
+  stage: BriefStage;
+  digest: string;
+  issued_at: string;
+}
+/** `state/briefs.yaml`: append-only task-book evidence outside content transactions. */
+interface BriefReceiptsDocument {
+  schema_version: 1;
+  receipts: BriefReceipt[];
+}
+/** The active draft's own metadata; P2 plan stays immutable after submission. */
+interface DraftState {
+  chapter: number;
+  title: string;
+  scene_type: SceneType;
+  narrator: string;
+  summary: ChapterSummary;
+  content_hash: string;
+  updated_at: string;
+}
 /** Pipeline document (`state/pipeline.yaml`). */
 interface PipelineState {
   schema_version: 1;
@@ -343,6 +382,8 @@ interface PipelineState {
     digest: string;
   }>;
   blocking: BlockingItem[];
+  /** Current draft summary/title; never written into the P2 plan file. */
+  draft?: DraftState;
   /** Hash of the review document last written by submitReview/submitRevision. */
   review_digest?: string;
   last_action: {
@@ -422,6 +463,7 @@ interface ForeshadowsDocument {
     status: 'planted' | 'dormant' | 'advanced' | 'resolved';
     resolved_at: number | null;
     description: string;
+    anchor?: string;
     advance_log: Array<{
       chapter: number;
       note: string;
@@ -614,6 +656,14 @@ interface WorldbookBackstory {
   time: string;
   event: string;
 }
+/** One declared numeric canon, checked against the manuscript on request. */
+interface WorldbookFact {
+  alias: string;
+  value: number;
+  unit: string;
+  tolerance?: number;
+  note?: string;
+}
 /** Worldbuilding plan, persisted in `outline/worldbook.yaml`. */
 interface WorldbookDocument {
   schema_version: 1;
@@ -626,6 +676,8 @@ interface WorldbookDocument {
   characters: WorldbookCharacter[];
   glossary: WorldbookGlossary[];
   backstory: WorldbookBackstory[];
+  /** Optional numeric canon; old documents omit it. */
+  facts?: WorldbookFact[];
   themes: string[];
 }
 /** One hit from `novel_search`; the scope names the source family. */
@@ -663,6 +715,22 @@ interface DoctorReport {
     infos: number;
   };
 }
+/** One canonical outline-progress calculation shared by every adapter. */
+interface OutlineProgress {
+  present: boolean;
+  target: number | null;
+  total: number;
+  planned: number;
+  archived: number;
+  missingCards: number;
+  plannedCoverage: number | null;
+  archivedCoverage: number | null;
+  /** Compatibility alias: planned coverage when a target exists, otherwise card coverage. */
+  coverage: number;
+  /** Fraction of archived chapters that have a matching archived card. */
+  cardCoverage: number;
+  volumes: number;
+}
 /** Book-wide quality, outline, cast and pacing aggregates. */
 interface BookReport {
   progress: {
@@ -672,13 +740,22 @@ interface BookReport {
     average_words: number;
     percent: number;
     remaining_words: number | null;
+    remaining_words_min: number | null;
+    remaining_words_average: number | null;
+    remaining_words_basis: 'actual_average' | 'minimum_target' | 'none';
   };
   outline: {
     present: boolean;
     strict: boolean;
+    target: number | null;
+    total: number;
     planned: number;
     archived: number;
+    missing_cards: number;
+    planned_coverage: number | null;
+    archived_coverage: number | null;
     coverage: number;
+    card_coverage: number;
     volumes: Array<{
       title: string;
       start: number;
@@ -701,6 +778,7 @@ interface BookReport {
     rules: number;
     glossary: number;
     backstory: number;
+    facts?: number;
   };
   quality: {
     average: number;
@@ -715,6 +793,22 @@ interface BookReport {
       samples: number;
     }>;
   };
+  /** Per-chapter effort survives archive (pipeline rounds are reset). */
+  effort: {
+    reviews: number;
+    revisions: number;
+    checks: number;
+    rollbacks: number;
+    chapters: Array<{
+      num: number;
+      reviews: number;
+      revisions: number;
+      checks: number;
+      rollbacks: number;
+      final_check: 'pass' | 'fail' | null;
+      archived_at: string | null;
+    }>;
+  };
   pacing: {
     scene_types: Record<string, number>;
     hook_strength: Record<string, number>;
@@ -805,10 +899,23 @@ interface ReviewInput {
   total: number;
   proof: ReadingProof;
 }
+/** One exact, unique replacement used by patch-mode revisions. */
+interface RevisionEdit {
+  old_text: string;
+  new_text: string;
+  /** 1-based occurrence; defaults to requiring exactly one match. */
+  occurrence?: number;
+}
+/** Patch-mode revision; content and patch are mutually exclusive. */
+interface RevisionPatch {
+  expected_hash: string;
+  edits: RevisionEdit[];
+}
 /** Revision submission payload. */
 interface RevisionInput {
   chapter: number;
-  content: string;
+  content?: string;
+  patch?: RevisionPatch;
   summary: ChapterSummary;
 }
 /** Semantic check items supplied by the model. */
@@ -880,6 +987,15 @@ interface ChapterStatusRow {
   stage: Stage;
   passed: boolean;
 }
+/** Where an omitted project root came from. */
+type SelectionSource = 'explicit' | 'session' | 'workspace' | 'active' | 'config' | 'single';
+/** One resolved project choice, before the project is loaded. */
+interface Selection {
+  root: string;
+  source: SelectionSource;
+  title?: string;
+  created_at?: string;
+}
 /** The `getStatus` payload. */
 interface StatusReport {
   project: {
@@ -888,6 +1004,11 @@ interface StatusReport {
     platform: Platform;
     root: string;
   };
+  /** Why this project was chosen; lets the model notice a wrong book. */
+  selection?: {
+    source: SelectionSource;
+    root: string;
+  };
   /** The chapter requested for metrics; may be historical. */
   chapter: number;
   /** The chapter the pipeline is currently working on. */
@@ -910,10 +1031,15 @@ interface StatusReport {
     strict: boolean;
     outline: {
       present: boolean;
+      target: number | null;
       total: number;
       planned: number;
       archived: number;
+      missing_cards: number;
+      planned_coverage: number | null;
+      archived_coverage: number | null;
       coverage: number;
+      card_coverage: number;
       volumes: number;
       current: OutlineChapter | null;
     };
@@ -925,6 +1051,7 @@ interface StatusReport {
       rules: number;
       glossary: number;
       backstory: number;
+      facts?: number;
     };
   };
   next: {
@@ -945,6 +1072,8 @@ interface AdviceReport {
 }
 /** One history row derived from the journal. */
 interface AuditRow {
+  /** Stable chronological cursor; absent only on hand-built test rows. */
+  seq?: number;
   at: string;
   op: string;
   chapter: number;
@@ -952,6 +1081,14 @@ interface AuditRow {
   txid: string;
   status: 'committed' | 'aborted';
   files: string[];
+  /** Machine code and human reason for a refused attempt. */
+  code?: string;
+  reason?: string;
+  hint?: string;
+  stage?: string;
+  /** True when no transaction started: the gate/input refused the call. */
+  attempt?: boolean;
+  blocking?: BlockingItem[];
 }
 /** One diff hunk between two revisions of a chapter. */
 interface DiffReport {
@@ -1099,6 +1236,8 @@ type DocKind = 'project' | 'pipeline' | 'chapters' | 'characters' | 'world' | 'l
 interface RegistryEntry {
   root: string;
   title: string;
+  /** Project identity; absent on registries written by 0.2.1 and earlier. */
+  created_at?: string;
   updated_at: string;
 }
 interface BookPatch {
@@ -1151,6 +1290,7 @@ interface WorldbookPatch {
   characters?: WorldbookCharacter[];
   glossary?: WorldbookGlossary[];
   backstory?: WorldbookBackstory[];
+  facts?: WorldbookFact[];
   themes?: string[];
 }
 /** One rendered task book. */
@@ -1282,10 +1422,15 @@ interface PanelBook {
   target: number | null;
   outline: {
     present: boolean;
+    target: number | null;
     total: number;
     planned: number;
     archived: number;
+    missing_cards: number;
+    planned_coverage: number | null;
+    archived_coverage: number | null;
     coverage: number;
+    card_coverage: number;
     volumes: Array<{
       title: string;
       start: number;
@@ -1302,11 +1447,14 @@ interface PanelBook {
     rules: number;
     glossary: number;
     backstory: number;
+    facts?: number;
   };
 }
 interface PanelSummaryDto {
   schemaVersion: number;
   panelId: string;
+  /** Absolute project root, so a stale title cannot hide a wrong book. */
+  root: string;
   title: string;
   genre: string;
   platform: string;
@@ -1375,6 +1523,47 @@ interface PanelGatesDto {
   /** Human-facing one-liner per blocking item. */
   explanations: string[];
 }
+/** One selectable project in the panel; state is cheap, not a full load. */
+interface PanelProjectOption {
+  root: string;
+  title: string;
+  active: boolean;
+  registered: boolean;
+  state: 'ok' | 'damaged' | 'missing' | 'unreadable';
+}
+interface PanelSelection {
+  root: string | null;
+  source: 'query' | 'active' | 'single' | 'config' | 'none';
+}
+interface PanelMissing {
+  root: string;
+  title: string;
+  code: 'ENGINE_PROJECT_MISSING' | 'ENGINE_PROJECT_NOT_FOUND';
+  reason: 'missing' | 'not-project' | 'damaged' | 'not_registered' | 'unreadable';
+  hint: string;
+}
+interface PanelBundle {
+  projects: PanelProjectOption[];
+  selection: PanelSelection;
+  summary?: PanelSummaryDto;
+  chapters?: PanelChaptersDto;
+  gates?: PanelGatesDto;
+  resume?: {
+    text: string;
+  };
+  missing?: PanelMissing;
+  empty?: true;
+  error?: string;
+}
+interface ResumePromptInput {
+  title: string;
+  root: string;
+  chapter: number | string;
+  stage: string;
+  nextTool: string;
+}
+/** One shared prompt template for `/novel resume` and the panel copy button. */
+declare function formatResumePrompt(input: ResumePromptInput): string;
 /** The nine-phase progress strip: phases before the active one are done. */
 declare function phaseStrip(stage: Stage, finished?: boolean): Array<{
   id: string;
@@ -1386,6 +1575,15 @@ declare function projectChapter(record: ChapterRecord): PanelChapterRow;
 declare function projectSummary(snapshot: PanelSnapshot): PanelSummaryDto;
 declare function projectChapters(snapshot: PanelSnapshot): PanelChaptersDto;
 declare function projectGates(snapshot: PanelSnapshot): PanelGatesDto;
+/** How much of a candidate project can be inspected without loading a snapshot. */
+type ProjectState = 'ok' | 'damaged' | 'not-project' | 'missing' | 'unreadable';
+interface ProjectInspection {
+  root: string;
+  state: ProjectState;
+  title: string;
+  created_at?: string;
+  error?: string;
+}
 /** Plugin configuration, mapped from `Config` in `src/index.ts`. */
 interface EngineConfig {
   projectRoot: string;
@@ -1447,6 +1645,15 @@ type EngineEvent = {
     chapter: number;
     restore_txid: string;
   };
+} | {
+  name: 'novel/restored';
+  payload: {
+    schemaVersion: 1;
+    projectRoot: string;
+    txid: string;
+    chapter: number;
+    paths: string[];
+  };
 } | {
   name: 'novel/exported';
   payload: {
@@ -1518,6 +1725,8 @@ interface CheckSubmission {
   /** The five P6 semantic items; omission is a failed check, never a pass. */
   semantic: SemanticItem[];
   scope?: string[];
+  /** Advisory codes the author has read and accepts; blockers cannot be acknowledged. */
+  acknowledge?: string[];
   root?: string;
 }
 interface ArchiveSubmission {
@@ -1534,6 +1743,13 @@ interface AmendSubmission {
   reason: string;
   root?: string;
 }
+interface RestoreSubmission {
+  txid: string;
+  chapter?: number;
+  /** Restrict to these project-relative files; omitted restores every chapter file in the snapshot. */
+  paths?: string[];
+  root?: string;
+}
 interface RollbackSubmission {
   chapter: number;
   toStage: 'P1' | 'P2' | 'P3' | 'P4' | 'P5' | 'P6';
@@ -1548,6 +1764,12 @@ interface DiffInput {
 }
 interface AuditInput {
   limit?: number;
+  cursor?: number;
+  chapter?: number;
+  op?: string;
+  status?: 'committed' | 'aborted';
+  since?: string;
+  until?: string;
   root?: string;
 }
 interface ExportInput {
@@ -1556,8 +1778,10 @@ interface ExportInput {
   root?: string;
 }
 interface StateQueryInput {
-  kind: DocKind | 'novel' | 'planWorld' | 'planChapter';
+  kind: DocKind | 'novel' | 'planWorld' | 'planChapter' | 'history' | 'backups' | 'briefs';
   chapter?: number;
+  /** Select one historical revision instead of listing history. */
+  revision?: number;
   /** Chapter index defaults to a compact read; opt in to the full summaries. */
   include_summary?: boolean;
   /** Inclusive chapter range for the `chapters` index. */
@@ -1606,6 +1830,11 @@ interface ReportSubmission {
 interface GuideInput {
   root?: string;
 }
+/** Session/workspace context of one tool or command call. */
+interface EngineCaller {
+  sessionId?: string;
+  cwd?: string;
+}
 /**
  * The single write authority. Tools, commands, the panel and task books never
  * touch a file; every mutation is one of these operations.
@@ -1619,8 +1848,8 @@ declare class EngineService {
   private readonly briefContextCache;
   private readonly briefs;
   private readonly now;
-  /** The project this process last touched; the panel follows it without a workspace hint. */
-  private lastRoot;
+  private readonly metadataMutex;
+  private readonly callerContext;
   constructor(config: EngineConfig, rulepack: Rulepack | (() => Rulepack), options?: {
     briefs?: BriefLibrary;
     now?: () => Date;
@@ -1641,15 +1870,52 @@ declare class EngineService {
   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>;
+  /** Bind the calling Agent session and cwd to every engine operation in `task`. */
+  withCaller<T>(caller: EngineCaller | undefined, task: () => Promise<T>): Promise<T>;
+  private caller;
   /** The configured default project root. */
   defaultRoot(): string;
+  /** Resolve a caller-supplied root against the session cwd, like /novel use. */
+  private resolveProjectPath;
+  /** The resolved metadata directory; resolves relative config once per call. */
+  private stateRoot;
+  private stateStore;
+  private bindings;
+  /**
+   * Serialize metadata read-modify-write across sessions and processes. The
+   * project manuscript lock is a different lock; a slow write never blocks a
+   * registry update.
+   */
+  withMetadataLock<T>(task: () => Promise<T>): Promise<T>;
+  private inspectConfigRoot;
   /**
-   * 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.
+   * Resolve the four-layer choice: explicit, session binding, bounded workspace
+   * discovery, then registry/config defaults. There is deliberately no
+   * process-global "last project" layer.
    */
+  /** Doctor/guide may run before any project exists; that is not a failure. */
+  private resolveRootForInspection;
   private resolveRoot;
   private storeFor;
+  /** Persist one explicit choice for this DSH session. */
+  private bindSelection;
+  /**
+   * Best-effort discovery bookkeeping. A metadata failure must never turn a
+   * successful project read/write into a failure; the registry is convenience.
+   */
+  private autoRegister;
+  /** Record the session binding/registration implied by a successful selection. */
+  private recordSelection;
+  /**
+   * Read paths may record convenience metadata, but a corrupt or read-only
+   * state directory must not turn a successful explicit-root read into a
+   * failure. Resolution without an explicit root still reads the binding
+   * fail-closed; writes use recordSelection directly and report a committed
+   * mutation with a warning if its metadata update fails.
+   */
+  private recordSelectionBestEffort;
+  /** Registration/activation/use need a readable project identity. */
+  private assertProjectHealthy;
   initProject(input: InitProjectInput): Promise<OpResult<{
     root: string;
     title: string;
@@ -1689,13 +1955,35 @@ declare class EngineService {
     stage: Stage;
     restore_txid: string;
   }>>;
+  /**
+   * Restore one active chapter from a backup transaction. Archived chapters
+   * are refused: their manuscript hash is bound by the index, so restoring
+   * behind the index would corrupt the project. Reopen first, then restore.
+   */
+  restoreBackup(input: RestoreSubmission): Promise<OpResult<{
+    txid: string;
+    chapter: number;
+    restored: string[];
+  }>>;
   /**
    * Read-only paths must surface a committed-journal mismatch. The write path
    * already fails closed; without this, status recommends the next write and
    * the model only learns about the mismatch when that write aborts.
    */
   private journalBlocking;
+  /**
+   * Count every committed attempt for one chapter, not just the loop since the
+   * last rollback. `pipeline.rounds` is deliberately reset by rollback to keep
+   * the retry budget fair; it is not the chapter's lifetime effort.
+   */
+  private lifetimeRounds;
   getStatus(input?: StatusInput): Promise<OpResult<StatusReport>>;
+  /**
+   * Build a status report from an already-loaded snapshot. This deliberately
+   * has no selection side effect: read-only callers such as /novel resume must
+   * not register or bind the project just by reading it.
+   */
+  private statusFor;
   countWords(input?: WordCountInput): Promise<OpResult<WordMetrics>>;
   queryState(input: StateQueryInput): Promise<OpResult<unknown>>;
   advise(input?: {
@@ -1756,6 +2044,9 @@ declare class EngineService {
     chapter: number;
     verdict: 'pass' | 'fail';
     violations: number;
+    advisories: number;
+    advisory_codes: string[];
+    acknowledged: string[];
     metrics: WordMetrics;
     stage: Stage;
   }>>;
@@ -1788,14 +2079,21 @@ declare class EngineService {
   panelGates(input?: {
     root?: string;
   }): Promise<PanelGatesDto>;
-  /** One snapshot, three projections: the panel never mixes revisions. */
+  /**
+   * Build the read-only panel payload. The query root is accepted only when it
+   * is registered, active or the configured root; arbitrary paths never reach
+   * the filesystem from the panel route.
+   */
   panelBundle(input?: {
     root?: string;
-  }): Promise<{
-    summary: PanelSummaryDto;
-    chapters: PanelChaptersDto;
-    gates: PanelGatesDto;
-  }>;
+  }): Promise<PanelBundle>;
+  /** Read-only resume text shared with the panel copy button. */
+  resumePrompt(input?: {
+    root?: string;
+  }): Promise<OpResult<{
+    text: string | null;
+    selection: StatusReport['selection'];
+  }>>;
   stats(input?: {
     root?: string;
   }): Promise<{
@@ -1807,38 +2105,90 @@ declare class EngineService {
     lastScore: number;
     openForeshadows: number;
     plannedChapters: number;
-    outlineCoverage: number;
+    totalCards: number;
+    outlineCoverage: number | null;
+    archivedCoverage: number | null;
+    missingCards: number;
     blueprintReady: boolean;
     worldbookEntries: number;
     strictOutline: boolean;
     targetChapters: number | null;
   }>;
   private registry;
-  /** List known projects (convenience only; a project opens without a row). */
+  /** List known projects with a cheap directory state for the panel/command. */
   listProjects(): Promise<{
     active: string | null;
-    projects: RegistryEntry[];
+    projects: Array<RegistryEntry & {
+      state: ProjectState;
+    }>;
   }>;
-  /** Record the current project in the registry. */
+  /**
+   * Record an explicit project row. An unchanged duplicate is a no-op; a path
+   * reused by another project updates the row and reports `replaced`.
+   */
   registerProject(input?: {
     root?: string;
   }): Promise<{
     active: string | null;
     projects: RegistryEntry[];
+    replaced: boolean;
   }>;
-  /** Choose the default project for future convenience calls. */
+  /** Choose the panel/default project. This never binds the current session. */
   setActiveProject(input: {
     root: string;
   }): Promise<{
     active: string | null;
+    replaced: boolean;
   }>;
-  /** Forget a registry row; the project directory is never touched. */
+  /** Forget a registry row; the project directory and bindings are never touched. */
   forgetProject(input: {
     root: string;
   }): Promise<{
     active: string | null;
     projects: RegistryEntry[];
   }>;
+  /**
+   * Bounded workspace scan. Normal mode is read-only; `register` updates only
+   * healthy, newly discovered rows, never active or session bindings.
+   */
+  scanProjects(input: {
+    cwd: string;
+    register?: boolean;
+  }): Promise<{
+    cwd: string;
+    candidates: Array<ProjectInspection & {
+      registered: boolean;
+      identity_changed?: boolean;
+      reason?: string;
+    }>;
+    truncated: boolean;
+    added: string[];
+    already: string[];
+    skipped: Array<{
+      root: string;
+      reason: string;
+    }>;
+    identity_changed: string[];
+  }>;
+  /** Current session binding, or the inferred fallback when none is set. */
+  currentProject(): Promise<{
+    selection: Selection | null;
+    bound: boolean;
+    state?: ProjectState;
+    error?: string;
+  }>;
+  /** Explicitly switch this session; failure leaves the old binding untouched. */
+  useProject(input: {
+    target: string;
+  }): Promise<{
+    selection: Selection;
+    title: string;
+    created_at: string;
+  }>;
+  /** Clear only this session's choice; never touches a project or registry row. */
+  unbindProject(): Promise<{
+    cleared: boolean;
+  }>;
   /**
    * Import one ledger from a settings pack. Always previews with a diff; a
    * dry run never writes, and an apply is a normal transaction.
@@ -1924,6 +2274,7 @@ declare class EngineService {
   /** State damage that makes this operation unsafe to start. */
   private stateGateBlock;
   /** Whether the stored brief still signs the current snapshot. */
+  private readBriefReceipts;
   private briefIsCurrent;
   /** Arguments valid for the tool `STAGE_NEXT` recommends at this stage. */
   private nextArgs;
@@ -1956,11 +2307,13 @@ declare class EngineService {
   private assertGates;
   private assertChapterParameter;
   private assertChapter;
-  /** True when anything survives in the project directory besides novel.yaml. */
-  private projectStateExists;
   /** A live writer lock makes a read-only snapshot potentially torn. */
   private lockIsLive;
+  /** Resolve a selection, load it, then persist the explicit choice (best effort). */
   private load;
+  /** Load exactly one already-resolved selection; never writes a binding. */
+  private movedProjectHint;
+  private loadAt;
   /** A repair may bypass the journal hash only when the document is unreadable. */
   private stateDocIsUnreadable;
   /** Read a review/check without letting one corrupt file wedge every read. */
@@ -1971,6 +2324,100 @@ declare class EngineService {
 }
 /** Read, compile and freeze a pack. Runtime callers always use the bundled default. */
 declare function loadRulepack(path?: string): Rulepack;
+/** Panel and session identifiers. */
+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;
+/** 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";
+declare const WORLDBOOK_FILE = "outline/worldbook.yaml";
+declare const STATE_DIR = "state";
+declare const CHAPTERS_DIR = "chapters";
+declare const PLAN_DIR = "plans";
+declare const REVIEW_DIR = "reviews";
+declare const CHECK_DIR = "checks";
+declare const EXPORT_DIR = "exports";
+declare const BACKUP_DIR = "backups";
+declare const HISTORY_DIR = "history";
+/** Brief receipts are append-only evidence, separate from content transactions. */
+declare const BRIEF_RECEIPTS_FILE = "state/briefs.yaml";
+declare const OUTLINE_DIR = "outline";
+declare const LOCK_FILE = ".engine.lock";
+declare const STAGING_DIR = ".staging";
+declare const REGISTRY_FILE = "projects.yaml";
+declare const SESSION_BINDINGS_FILE = "session-bindings.yaml";
+declare const METADATA_LOCK_FILE = ".metadata.lock";
+declare const ARCHIVE_DIGESTS_FILE = "state/archive-digests.json";
+/** Files owned by the engine under `state/`. */
+declare const STATE_FILES: {
+  readonly pipeline: "pipeline.yaml";
+  readonly chapters: "chapters.yaml";
+  readonly characters: "characters.yaml";
+  readonly world: "world.yaml";
+  readonly locks: "locks.yaml";
+  readonly timeline: "timeline.yaml";
+  readonly foreshadows: "foreshadows.yaml";
+  readonly relationships: "relationships.yaml";
+  readonly handoff: "handoff.yaml";
+  readonly journal: "journal.jsonl";
+};
+/** Chapter file name, zero padded to three digits. */
+declare const chapterFile: (chapter: number) => string;
+/** Kept for reference when a rollback discards the current draft. */
+declare const deprecatedChapterFile: (chapter: number) => string;
+declare const planWorldFile: (chapter: number) => string;
+declare const planChapterFile: (chapter: number) => string;
+declare const reviewFile: (chapter: number) => string;
+declare const checkFile: (chapter: number) => string;
+declare const reviewHistoryFile: (chapter: number, revision: number) => string;
+declare const checkHistoryFile: (chapter: number, revision: number) => string;
+declare const chapterHistoryFile: (chapter: number, revision: number) => string;
+declare const deprecatedHistoryFile: (chapter: number, revision: number) => string;
+declare const planHistoryFile: (chapter: number, revision: number) => string;
+declare const HISTORY_KINDS: readonly ["reviews", "checks", "chapters", "deprecated", "plans"];
+type HistoryKind = (typeof HISTORY_KINDS)[number];
+/** Limits that are structural, not taste. */
+declare const LIMITS: {
+  /** P4 <-> P5/P6 retries before a forced rollback. */
+  maxRounds: number;
+  /** Lock staleness in milliseconds. */
+  lockStaleMs: number;
+  /** How long a writer waits for the keyed mutex before failing. */
+  lockWaitMs: number;
+  /** Reading proofs shorter than this cannot be verified. */
+  minQuoteChars: number;
+  /** World-plan text fields are protected context, so they need a hard bound. */
+  maxWorldPlanItems: number;
+  maxWorldPlanTextChars: number;
+  maxWorldPlanObjectiveChars: number;
+  /** Cast plus summary may exceed eight, but not without a bound. */
+  maxActiveCast: number;
+  /** Outline and worldbook are protected context, so they need hard bounds. */
+  maxOutlineChapters: number;
+  maxOutlineVolumes: number;
+  maxOutlineTextFieldChars: number;
+  maxOutlineNotesChars: number;
+  maxWorldbookEntries: number;
+  maxWorldbookTextChars: number;
+  maxSearchQueryChars: number;
+};
+/** Re-exported enums make adapter code readable without importing types twice. */
+declare const SCENE_TYPE_DEFAULT: SceneType;
+declare const DEFAULT_GENRE: Genre;
+declare const DEFAULT_PLATFORM: Platform;
+declare const INITIAL_STAGE: Stage;
+/** The order used to render the nine-phase progress strip. */
+declare const PHASE_STRIP: readonly ["P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9"];
+/** Tool names, kept here so the arch test can assert one namespace. */
+declare const TOOL_NAMES: readonly ["novel_init", "novel_status", "novel_brief", "novel_plan_world", "novel_plan_chapter", "novel_write_draft", "novel_review", "novel_revise", "novel_check", "novel_archive", "novel_word_count", "novel_state", "novel_amend", "novel_rollback", "novel_diff", "novel_export", "novel_audit", "novel_pipeline", "novel_blueprint", "novel_outline", "novel_outline_import", "novel_worldbook", "novel_search", "novel_doctor", "novel_report", "novel_guide", "novel_reopen", "novel_restore"];
+type ToolName = (typeof TOOL_NAMES)[number];
+/** The ten high-frequency tools kept when `tools.mode = core`. */
+declare const CORE_TOOLS: readonly ToolName[];
 /** One rendered chapter, assembled by the engine before rendering. */
 interface ExportChapter {
   num: number;
@@ -2013,4 +2460,4 @@ declare const Config: Schema<Config>;
  * created lazily per project root.
  */
 declare function apply(ctx: Context, config: Config): void;
-export { AdviceReport, ArchiveHandoff, AuditRow, BlockingItem, BookPlan, BookReport, BriefDocument, BriefLibrary, BriefStage, ChapterCastMember, ChapterPlanInput, ChapterRecord, ChapterStatusRow, ChapterSummary, ChaptersDocument, CharacterDelta, CharactersDocument, CheckDocument, Config, Deduction, DeltaAction, DiffReport, DoctorCheck, DoctorReport, DraftInput, ERROR_CODES, EngineBlockedError, EngineError, EngineFaultError, EngineInputError, EngineService, ErrorCode, ExportChapter, ExportKind, ForeshadowDelta, ForeshadowsDocument, GENRES, GateInput, GateOptions, GateResult, Genre, GuideReport, GuideStep, HandoffDocument, LocksDocument, MachineMetrics, NovelProject, OPERATIONS, OpResult, Operation, OutlineChapter, OutlineDocument, OutlineVolume, PLATFORMS, PanelBook, PanelChapterRow, PanelChaptersDto, PanelDraft, PanelGatesDto, PanelSnapshot, PanelSummaryDto, PipelineState, Platform, ReadingProof, ReadingProofReference, RelationshipDelta, RelationshipsDocument, ReviewDocument, ReviewInput, ReviewIssue, RevisionInput, RoundCounters, SCENE_TYPES, SCHEMA_VERSION, SceneType, ScoreDimension, SearchReport, SearchResultItem, SemanticItem, Severity, Stage, StateDelta, StateError, StateErrorCode, StatusReport, TimelineDelta, TimelineDocument, Violation, Warning, WordMetrics, WorldDelta, WorldDocument, WorldPlanInput, WorldbookBackstory, WorldbookCharacter, WorldbookDocument, WorldbookFaction, WorldbookGlossary, WorldbookLocation, WorldbookRule, applicableGates, apply, blockedError, briefStageFor, chapterHeading, evaluateGates, faultError, gateName, inject, inputError, loadRulepack, name, parseParagraphLocation, phaseStrip, projectChapter, projectChapters, projectGates, projectSummary, renderBlurb, renderCover, renderEpubChapter, renderMarkdown, renderPlainText, renderProposal, 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_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 };