@agentproto/corpus 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/ports/index.d.ts

@@ -1,3 +1,5 @@
+export { b as FsLockHandle, F as FsPort, a as FsStat } from '../fs.port-BHzctsoT.js';
+
 /**
  * ClockPort — abstracted time source.
  *
@@ -14,65 +16,6 @@ interface ClockPort {
 /** Real-time implementation. The local CLI host wires this in. */
 declare const systemClock: ClockPort;
 
-/**
- * FsPort — filesystem boundary the corpus kit consumes.
- *
- * Structural interface, NOT a nominal one — any object exposing this
- * shape satisfies it. Matches the existing Guilde `WorkspaceFsLike`
- * convention (projects/guilde/packages/core/src/services/role-source/
- * workspace.ts:38-47) so cloud and local topologies share the same
- * minimal contract.
- *
- * Paths are relative to the workspace root (no leading slash). The
- * concrete implementation (MastraFilesystem in cloud, local-fs in CLI,
- * mcp-filesystem for hybrid topologies) does the resolution.
- */
-interface FsStat {
-    readonly kind: "file" | "directory";
-    readonly bytes?: number;
-    readonly modifiedAt?: Date;
-}
-interface FsPort {
-    /** True if a file or directory exists at `path`. */
-    exists(path: string): Promise<boolean>;
-    /** Read a file as UTF-8 text. Throws on missing path. */
-    readFile(path: string): Promise<string>;
-    /**
-     * Write a file atomically — caller assumes content is persisted on
-     * resolve. Implementations are expected to write to a temp file +
-     * rename so partial writes never become visible.
-     */
-    writeFile(path: string, content: string): Promise<void>;
-    /**
-     * Append to a file. MUST be atomic against concurrent appends to the
-     * same path — used by the event emitter for _log.md. If the file
-     * does not exist, create it.
-     */
-    appendFile(path: string, content: string): Promise<void>;
-    /**
-     * List immediate children of a directory. Returns names only (NOT
-     * full paths). Throws if `path` is not a directory.
-     */
-    readdir(path: string): Promise<readonly string[]>;
-    /**
-     * Recursive directory listing — returns workspace-relative paths of
-     * every file under `path`. Skips directories starting with `.`.
-     */
-    walk(path: string): Promise<readonly string[]>;
-    /** File metadata. Returns null if the path doesn't exist. */
-    stat(path: string): Promise<FsStat | null>;
-    /**
-     * Acquire a cross-process advisory lock on `path`. Used by the
-     * writer for atomic multi-file transactions (entry write + _index
-     * regen + _log append). Implementations MAY no-op for single-process
-     * topologies (local CLI), but cloud hosts MUST enforce real locking.
-     */
-    lock(path: string): Promise<FsLockHandle>;
-}
-interface FsLockHandle {
-    release(): Promise<void>;
-}
-
 /**
  * IdentityPort — resolves who is currently acting on the corpus.
  *
@@ -202,4 +145,4 @@ interface EvaluatorPort {
     evaluate(input: EvalInputPort): Promise<EvalResultPort>;
 }
 
-export { type CallerIdentity, type ClockPort, type EvalContextPort, type EvalInputPort, type EvalResultPort, type EvalRubricPort, type EvaluatorPort, type FetchedSource, type FetchedSourceKind, type FetcherPort, type FsLockHandle, type FsPort, type FsStat, type IdentityPort, systemClock };
+export { type CallerIdentity, type ClockPort, type EvalContextPort, type EvalInputPort, type EvalResultPort, type EvalRubricPort, type EvaluatorPort, type FetchedSource, type FetchedSourceKind, type FetcherPort, type IdentityPort, systemClock };

package/dist/report/index.d.ts

@@ -0,0 +1,526 @@
+import { F as FsPort } from '../fs.port-BHzctsoT.js';
+import { z } from 'zod';
+
+/**
+ * ReportConfig — the single source of truth for a long-form report rendered
+ * from a corpus dataset. Superset of the two pre-existing shapes (the Claude
+ * bible toolkit's `bible.config.json` + the AIP `bibleConfigSchema`); the
+ * authoring reference is `.claude/skills/deep-research/bible/config.schema.md`.
+ *
+ * Validated with zod (NOT AJV — avoids corpus-cli's findSpecsRoot). Unknown
+ * keys pass through so presentation/render fields the engine doesn't read
+ * (covers, header/footer, parts) survive a parse round-trip untouched.
+ */
+
+/** A key/value fact rendered on a branded cover (`facts[]`). */
+declare const reportCoverFactSchema: z.ZodObject<{
+    k: z.ZodString;
+    v: z.ZodString;
+}, z.core.$loose>;
+/** One extra full-bleed cover (front or back). Data → one shared template. */
+declare const reportCoverPageSchema: z.ZodObject<{
+    kicker: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    align: z.ZodOptional<z.ZodString>;
+    facts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        k: z.ZodString;
+        v: z.ZodString;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+/** The title cover (1re de couverture). */
+declare const reportCoverSchema: z.ZodObject<{
+    brand: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodString>;
+    brandLetterSpacing: z.ZodOptional<z.ZodString>;
+    brandFontSize: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** A part grouping that drives stitch ordering. */
+declare const reportPartSchema: z.ZodObject<{
+    heading: z.ZodString;
+    chapters: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+/**
+ * One report unit. Carries BOTH write fields (words/src/cover) and
+ * pack-routing fields (facets/kw/cap). `id` doubles as the view filename
+ * and the `<id>.md` chapter source.
+ */
+declare const reportChapterSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    words: z.ZodOptional<z.ZodString>;
+    src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cover: z.ZodOptional<z.ZodString>;
+    facets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    kw: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cap: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+declare const reportConfigSchema: z.ZodObject<{
+    workspace: z.ZodOptional<z.ZodString>;
+    dataset: z.ZodOptional<z.ZodString>;
+    corpora: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    profile: z.ZodOptional<z.ZodString>;
+    bibMax: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
+    cover: z.ZodOptional<z.ZodObject<{
+        brand: z.ZodOptional<z.ZodString>;
+        subtitle: z.ZodOptional<z.ZodString>;
+        tag: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodString>;
+        brandLetterSpacing: z.ZodOptional<z.ZodString>;
+        brandFontSize: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    frontCovers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kicker: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodString>;
+        tag: z.ZodOptional<z.ZodString>;
+        align: z.ZodOptional<z.ZodString>;
+        facts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            k: z.ZodString;
+            v: z.ZodString;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+    backCovers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kicker: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodString>;
+        tag: z.ZodOptional<z.ZodString>;
+        align: z.ZodOptional<z.ZodString>;
+        facts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            k: z.ZodString;
+            v: z.ZodString;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>;
+    runningHeader: z.ZodOptional<z.ZodString>;
+    runningFooter: z.ZodOptional<z.ZodString>;
+    frontFile: z.ZodOptional<z.ZodString>;
+    annexesFile: z.ZodOptional<z.ZodString>;
+    parts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        heading: z.ZodString;
+        chapters: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>>;
+    rulesText: z.ZodOptional<z.ZodString>;
+    factsText: z.ZodOptional<z.ZodString>;
+    briefText: z.ZodOptional<z.ZodString>;
+    chapters: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        words: z.ZodOptional<z.ZodString>;
+        src: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cover: z.ZodOptional<z.ZodString>;
+        facets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        kw: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cap: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type ReportCoverFact = z.infer<typeof reportCoverFactSchema>;
+type ReportCoverPage = z.infer<typeof reportCoverPageSchema>;
+type ReportCover = z.infer<typeof reportCoverSchema>;
+type ReportPart = z.infer<typeof reportPartSchema>;
+type ReportChapter = z.infer<typeof reportChapterSchema>;
+type ReportConfig = z.infer<typeof reportConfigSchema>;
+
+/**
+ * buildPacks — materialize a corpus dataset into per-chapter knowledge views
+ * (the L2 "marts" of the pipeline) + a global citation bibliography.
+ *
+ * PURE: reads the dataset through an injected read-only `FsPort` and RETURNS
+ * the files to write — it never writes. The frontend (CLI / AIP tool) owns
+ * the report-rooted writer, so the dataset stays read-only to this module
+ * (invariant 1). This is the single source of truth that both the Claude
+ * `build-packs.mjs` and the AIP `corpus.report-packs` tool delegate to,
+ * porting the skill's semantics (the authoritative reference).
+ *
+ * Global [n] citation numbering: every source in the dataset gets one stable
+ * number (facet-ordered, then title); each distilled entry cites its sources
+ * by those numbers. Chapter routing = facet match + keyword needles + cap.
+ */
+
+interface PackFile {
+    /** Path relative to the report root (e.g. `views/_bibliography.json`). */
+    readonly path: string;
+    readonly content: string;
+}
+interface BuildPacksResult {
+    /** All files to write under the report root, in deterministic order. */
+    readonly files: readonly PackFile[];
+    /** Number of sources in the global bibliography. */
+    readonly bibliography: number;
+    /** Per-chapter view summary. */
+    readonly chapters: ReadonlyArray<{
+        readonly id: string;
+        readonly title: string;
+        readonly entryCount: number;
+    }>;
+}
+interface BuildPacksOptions {
+    /** Read-only view of the dataset (sources/ + entries/). */
+    readonly dataset: FsPort;
+    readonly config: ReportConfig;
+    /**
+     * Subdir under the report root for the views + bibliography. Default
+     * `views`; the parity path against the legacy on-disk corpora passes
+     * `packs`. Also embedded in each view's "Also read" pointer text.
+     */
+    readonly viewsDir?: string;
+}
+declare function buildPacks(opts: BuildPacksOptions): Promise<BuildPacksResult>;
+
+/**
+ * Citation helpers shared across the report glue. A citation is `[n]` or
+ * `[n, m, …]` referencing the global bibliography index.
+ */
+/** Every citation number referenced in a string (flattening `[a, b]`). */
+declare function citesOf(s: string): number[];
+/** Citation numbers in `s` outside the valid `[1, bibMax]` range. */
+declare function outOfRangeCites(s: string, bibMax: number): number[];
+
+/**
+ * assembleChapters — turn the write step's raw per-chapter drafts into clean
+ * chapter files. Pure: in-memory drafts → files to write (the caller owns the
+ * report-rooted writer). Mechanical only — strips agent preambles, normalizes
+ * `[a→b]` cross-refs to `[b]`, collapses blank runs; no model calls.
+ */
+
+interface ChapterDraft {
+    /** Chapter id (= `<chaptersDir>/<ch>.md`). */
+    readonly ch: string;
+    readonly draft: string;
+}
+interface AssembleResult {
+    readonly files: readonly PackFile[];
+    readonly stats: {
+        readonly chapters: number;
+        readonly preamblesStripped: number;
+        readonly withOutOfRangeCites: number;
+        readonly outOfRange: ReadonlyArray<{
+            ch: string;
+            cites: number[];
+        }>;
+    };
+}
+interface AssembleOptions {
+    readonly chapters: readonly ChapterDraft[];
+    /** Highest valid citation [n]; cites above it are flagged (not dropped). */
+    readonly bibMax: number;
+    /** Subdir under the report root for chapter files. Default `chapters`. */
+    readonly chaptersDir?: string;
+}
+/** Drop any leading agent chatter before the first "## " and tidy whitespace. */
+declare function cleanDraft(draft: string | undefined): string;
+declare function assembleChapters(opts: AssembleOptions): AssembleResult;
+
+/**
+ * ReportContent — the ONE medium-agnostic shape of a finished report.
+ *
+ * `buildReportContent` reads the report root (config + chapters/ + the
+ * bibliography view) and RETURNS the structured content: an ordered list of
+ * sections (each raw markdown) plus the structured bibliography and document
+ * metadata. It is PURE and port-injected like the rest of the engine — it
+ * never touches the dataset and never renders HTML/PDF (no Chrome here).
+ *
+ * Every render medium is an AIP `render.*` tool whose input is a
+ * `ReportContent`; the canvakit driver (in `@canvakit/report`) is the only
+ * place HTML/PDF lives. The markdown medium is reconstructed losslessly by
+ * `reportContentToMarkdown` — which is exactly what `stitchReport` emits, so
+ * REPORT.md byte-parity is preserved (the two share `collectReportSections`).
+ */
+
+/** What role a section plays in the document. */
+declare const reportSectionKindSchema: z.ZodEnum<{
+    sources: "sources";
+    front: "front";
+    part: "part";
+    chapter: "chapter";
+    annexes: "annexes";
+}>;
+/** One contiguous unit of a report (front, a part divider, a chapter, …). */
+declare const reportSectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    markdown: z.ZodString;
+    kind: z.ZodEnum<{
+        sources: "sources";
+        front: "front";
+        part: "part";
+        chapter: "chapter";
+        annexes: "annexes";
+    }>;
+}, z.core.$strip>;
+/** One global citation source (mirrors `views/_bibliography.json`). */
+declare const bibEntrySchema: z.ZodObject<{
+    n: z.ZodNumber;
+    id: z.ZodString;
+    title: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The medium-agnostic content a `render.*` tool consumes — the single source
+ * of truth for "what a report's content is". Zod so the render tool schemas
+ * can embed it directly (one definition across the engine and every renderer).
+ */
+declare const reportContentSchema: z.ZodObject<{
+    title: z.ZodString;
+    sections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        markdown: z.ZodString;
+        kind: z.ZodEnum<{
+            sources: "sources";
+            front: "front";
+            part: "part";
+            chapter: "chapter";
+            annexes: "annexes";
+        }>;
+    }, z.core.$strip>>;
+    bibliography: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodLiteral<"numbered">;
+        entries: z.ZodArray<z.ZodObject<{
+            n: z.ZodNumber;
+            id: z.ZodString;
+            title: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+type ReportSection = z.infer<typeof reportSectionSchema>;
+type BibEntry = z.infer<typeof bibEntrySchema>;
+type ReportContent = z.infer<typeof reportContentSchema>;
+interface CollectSectionsOptions {
+    readonly config: ReportConfig;
+    /** Read-side view of the report root (chapters/ + views/ + front/annexes). */
+    readonly report: FsPort;
+    /** Subdir holding the written chapter files. Default `chapters`. */
+    readonly chaptersDir?: string;
+    /** Subdir holding the bibliography. Default `views`. */
+    readonly viewsDir?: string;
+}
+/**
+ * Collect a report's ordered sections from the report root. This is the
+ * single read path shared by `stitchReport` (markdown medium) and
+ * `buildReportContent` (every other medium), so the section boundaries — and
+ * therefore REPORT.md — are identical regardless of the consumer.
+ *
+ * Order: front? · (parts ? part-heading + its chapters : chapters in config
+ * order) · annexes? · Sources (from the bibliography). Mirrors the legacy
+ * stitch exactly; all reads are report-side (the dataset is never touched).
+ */
+declare function collectReportSections(opts: CollectSectionsOptions): Promise<ReportSection[]>;
+/**
+ * Reconstruct the canonical REPORT.md from collected sections. Byte-identical
+ * to the legacy stitch output (`out.join("\n\n") + "\n"`).
+ */
+declare function reportContentToMarkdown(sections: readonly ReportSection[]): string;
+type BuildReportContentOptions = CollectSectionsOptions;
+/**
+ * Build the medium-agnostic {@link ReportContent} for a report. Pure: reads
+ * the report root through the injected FsPort and returns structured content —
+ * the single input every `render.*` tool consumes.
+ */
+declare function buildReportContent(opts: BuildReportContentOptions): Promise<ReportContent>;
+
+/**
+ * stitchReport — assemble the final REPORT.md = front + part dividers +
+ * chapters + annexes + a Sources section (from the global bibliography), per
+ * the config's `parts[]`. Pure: reads report-side files through an injected
+ * FsPort and RETURNS the document string (the caller writes REPORT.md).
+ *
+ * It is the markdown render medium: `stitchReport === reportContentToMarkdown
+ * ∘ collectReportSections`. The shared section collection guarantees the
+ * markdown medium and every `render.*` tool see the exact same boundaries.
+ *
+ * All reads are report-side (chapters + views) — the dataset is not touched.
+ */
+
+type StitchOptions = CollectSectionsOptions;
+interface StitchResult {
+    readonly content: string;
+    readonly wordCount: number;
+}
+declare function stitchReport(opts: StitchOptions): Promise<StitchResult>;
+
+/**
+ * applyEdits — apply {find, replace, reason} edits (from the fix step) to
+ * chapter files by EXACT match. An edit lands only if `find` occurs exactly
+ * once AND `replace` adds no out-of-range [n]; everything else is reported,
+ * not forced. A chapter is written only if at least one edit applied and the
+ * post-check passes (still starts at "## ", no out-of-range cites).
+ *
+ * Reads chapter files through an injected FsPort; RETURNS the writes + a
+ * human-readable apply report (the caller owns the writer).
+ */
+
+interface ChapterEdit {
+    readonly find?: string;
+    readonly replace?: string;
+    readonly reason?: string;
+}
+interface ChapterEditSet {
+    readonly id: string;
+    readonly edits?: readonly ChapterEdit[];
+}
+interface ApplyEditsResult {
+    /** Chapter files to (over)write — already post-checked. */
+    readonly files: readonly PackFile[];
+    /** The fix-apply report markdown. */
+    readonly report: string;
+    readonly stats: {
+        readonly filesChanged: number;
+        readonly applied: number;
+        readonly skipped: number;
+    };
+}
+interface ApplyEditsOptions {
+    readonly results: readonly ChapterEditSet[];
+    readonly bibMax: number;
+    /** Read-side view of the report root. */
+    readonly report: FsPort;
+    /** Subdir holding chapter files. Default `chapters`. */
+    readonly chaptersDir?: string;
+}
+declare function applyEdits(opts: ApplyEditsOptions): Promise<ApplyEditsResult>;
+
+/**
+ * ReportModelPort — the minimal model seam the report's model steps consume.
+ *
+ * Structural, not nominal: the AIP `ModelPort` (`complete({system?, prompt}) →
+ * {result}`) satisfies it as-is, so the same engine runs under any registered
+ * model. The single-pass functions here ARE the "model driver" tier; the
+ * higher-fidelity claude-code path (Phase C) reuses the same prompt-builders
+ * but swaps the executor for file-reading sub-agents.
+ */
+interface ReportModelInput {
+    readonly system?: string;
+    readonly prompt: string;
+}
+interface ReportModelOutput {
+    /** Completion payload — string for text, or a structured object. */
+    readonly result: string | unknown;
+}
+interface ReportModelPort {
+    complete(input: ReportModelInput): Promise<ReportModelOutput>;
+}
+/** Run a prompt and coerce the completion to text. */
+declare function runModel(model: ReportModelPort, input: ReportModelInput): Promise<string>;
+
+/**
+ * analyze — synthesize the distilled entries of each facet into a structured
+ * markdown analysis doc (`sources.<facet>.md`), the deeper context the chapter
+ * writer reads. A report-side step (invariant 3): it READS the dataset's
+ * entries and RETURNS report-rooted files; it never writes the dataset.
+ */
+
+interface AnalyzeFacetInput {
+    readonly facet: string;
+    /** Pre-rendered entries block (title/kind/confidence + body per entry). */
+    readonly entriesText: string;
+}
+/** The prompt for one facet's analysis doc — pure, driver-reusable. */
+declare function buildFacetAnalysisPrompt(input: AnalyzeFacetInput): ReportModelInput;
+interface AnalyzeDatasetOptions {
+    /** Read-only view of the dataset (entries/). */
+    readonly dataset: FsPort;
+    readonly facets: readonly string[];
+    readonly model: ReportModelPort;
+}
+interface AnalyzeDatasetResult {
+    /** `sources.<facet>.md` files to write at the report root. */
+    readonly files: readonly PackFile[];
+    readonly analyzed: number;
+    /** Facets skipped because they resolved to zero entries. */
+    readonly skipped: readonly string[];
+}
+declare function analyzeDataset(opts: AnalyzeDatasetOptions): Promise<AnalyzeDatasetResult>;
+
+/**
+ * write — the single-pass chapter writer (the "model driver" tier). Given a
+ * chapter's view (distilled claims + [n] cites), the per-facet analysis, and
+ * the bibliography, produce a cited markdown draft.
+ *
+ * `buildChapterWritePrompt` is pure and exported so the higher-fidelity
+ * claude-code driver (Phase C) reuses the identical prompt while swapping the
+ * executor for a file-reading sub-agent. `writeChapter` is the model-driver
+ * executor. Output is a raw DRAFT — `assembleChapters` then cleans it.
+ */
+
+interface ChapterWriteContext {
+    readonly chapter: Pick<ReportChapter, "id" | "title" | "words">;
+    /** Report/document title for framing. */
+    readonly title: string;
+    /** The chapter's view content (distilled claims with [n]). */
+    readonly packContent: string;
+    /** Concatenated per-facet analysis docs (optional deeper context). */
+    readonly analysisContext?: string;
+    /** The global bibliography markdown (for citation verification). */
+    readonly bibliography?: string;
+}
+declare function buildChapterWritePrompt(ctx: ChapterWriteContext): ReportModelInput;
+/** Single-pass chapter write → a `{ ch, draft }` ready for assembleChapters. */
+declare function writeChapter(ctx: ChapterWriteContext, model: ReportModelPort): Promise<{
+    ch: string;
+    draft: string;
+}>;
+
+/**
+ * review — the single-pass chapter reviewer (the "model driver" tier of the
+ * quality loop). Given a chapter's current prose, its per-facet analysis, and
+ * the bibliography, the model returns a set of EXACT-MATCH `{find, replace,
+ * reason}` edits that `applyEdits` can land verbatim (fact/citation fixes,
+ * overstatement trims). It never rewrites the chapter — only proposes targeted,
+ * verifiable edits, so the fix step stays deterministic.
+ *
+ * `buildReviewPrompt` is pure + exported so the claude-code driver reuses it.
+ */
+
+interface ChapterReviewContext {
+    readonly chapter: {
+        readonly id: string;
+        readonly title: string;
+    };
+    /** The chapter's current markdown (what gets reviewed). */
+    readonly chapterText: string;
+    /** Concatenated per-facet analysis docs (the ground truth to check against). */
+    readonly analysisContext?: string;
+    /** The global bibliography markdown (citation range + targets). */
+    readonly bibliography?: string;
+    /** Highest valid citation [n] — replacements must not exceed it. */
+    readonly bibMax: number;
+}
+declare function buildReviewPrompt(ctx: ChapterReviewContext): ReportModelInput;
+/**
+ * Single-pass chapter review → a {@link ChapterEditSet} ready for
+ * `applyEdits`. Tolerant: a malformed completion yields no edits (the chapter
+ * is left untouched) rather than throwing — review is an enhancement, not a gate.
+ */
+declare function reviewChapter(ctx: ChapterReviewContext, model: ReportModelPort): Promise<ChapterEditSet>;
+
+/**
+ * plan — the auto-outliner. Turns (brief + dataset facets + profile) into a
+ * chapter outline, so a report can run from a topic with NO hand-authored
+ * config. Model-driven; the returned chapters are zod-validated and carry the
+ * routing fields (facets/kw/cap) the pack builder needs.
+ */
+
+interface PlanOutlineOptions {
+    /** The research brief / framing (what the report should cover). */
+    readonly brief: string;
+    /** Facets discovered in the dataset (the tags chapters route against). */
+    readonly facets: readonly string[];
+    /** Profile preset that shapes the unit (bible | brief | memo | deck). */
+    readonly profile?: string;
+    /** Target chapter count (a hint, not a hard cap). */
+    readonly targetChapters?: number;
+    readonly model: ReportModelPort;
+}
+interface PlanOutlineResult {
+    readonly title?: string;
+    readonly chapters: readonly ReportChapter[];
+}
+declare function planOutline(opts: PlanOutlineOptions): Promise<PlanOutlineResult>;
+
+export { type AnalyzeDatasetOptions, type AnalyzeDatasetResult, type AnalyzeFacetInput, type ApplyEditsOptions, type ApplyEditsResult, type AssembleOptions, type AssembleResult, type BibEntry, type BuildPacksOptions, type BuildPacksResult, type BuildReportContentOptions, type ChapterDraft, type ChapterEdit, type ChapterEditSet, type ChapterReviewContext, type ChapterWriteContext, type CollectSectionsOptions, type PackFile, type PlanOutlineOptions, type PlanOutlineResult, type ReportChapter, type ReportConfig, type ReportContent, type ReportCover, type ReportCoverFact, type ReportCoverPage, type ReportModelInput, type ReportModelOutput, type ReportModelPort, type ReportPart, type ReportSection, type StitchOptions, type StitchResult, analyzeDataset, applyEdits, assembleChapters, bibEntrySchema, buildChapterWritePrompt, buildFacetAnalysisPrompt, buildPacks, buildReportContent, buildReviewPrompt, citesOf, cleanDraft, collectReportSections, outOfRangeCites, planOutline, reportChapterSchema, reportConfigSchema, reportContentSchema, reportContentToMarkdown, reportCoverFactSchema, reportCoverPageSchema, reportCoverSchema, reportPartSchema, reportSectionKindSchema, reportSectionSchema, reviewChapter, runModel, stitchReport, writeChapter };