llm-wiki-compiler 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -0,0 +1,1010 @@
+/**
+ * Type definitions for the wiki schema layer.
+ *
+ * The schema layer turns llmwiki from a flat compiler pipeline into a shaped
+ * knowledge system. It declares the kinds of pages a project supports
+ * (`concept`, `entity`, `comparison`, `overview`) and the cross-link
+ * expectations that lint and review enforce per kind.
+ *
+ * Types live in their own module so that compile, lint, CLI, and tests can
+ * depend on the schema vocabulary without pulling in YAML/JSON loaders.
+ */
+/** All page kinds the schema layer recognises. */
+type PageKind = "concept" | "entity" | "comparison" | "overview";
+
+/**
+ * Type definitions for the wiki linter.
+ * Defines the shape of lint results, summaries, and rule functions
+ * used across all lint rules and the orchestrator.
+ */
+interface LintResult {
+    rule: string;
+    severity: "error" | "warning" | "info";
+    file: string;
+    message: string;
+    line?: number;
+}
+interface LintSummary {
+    errors: number;
+    warnings: number;
+    info: number;
+    results: LintResult[];
+}
+
+/**
+ * Lifecycle state of a concept or page's provenance.
+ * - `extracted`: drawn directly from a source document.
+ * - `merged`: synthesised from multiple sources during compilation.
+ * - `inferred`: produced by the model from context, not directly cited.
+ * - `ambiguous`: sources disagree or evidence is conflicting.
+ */
+type ProvenanceState = "extracted" | "merged" | "inferred" | "ambiguous";
+/**
+ * Reference to another concept that contradicts the current one.
+ * The slug points to the contradicting wiki page.
+ */
+interface ContradictionRef {
+    slug: string;
+    reason?: string;
+}
+/** Structured result returned by the compile pipeline. */
+interface CompileResult {
+    compiled: number;
+    skipped: number;
+    deleted: number;
+    concepts: string[];
+    pages: string[];
+    errors: string[];
+    /** Candidate IDs created when the pipeline runs in --review mode. */
+    candidates?: string[];
+}
+/** A single chunk citation surfaced as part of a query result. */
+interface ChunkCitation {
+    slug: string;
+    title: string;
+    chunkIndex: number;
+    score: number;
+    text: string;
+}
+/** Diagnostic snapshot of how the retrieval pipeline picked context. */
+interface RetrievalDebug {
+    /** Pages selected after collapsing chunks to their parent slugs. */
+    pages: Array<{
+        slug: string;
+        score: number;
+    }>;
+    /** Top-ranked chunks before the page-collapse step. */
+    chunks: ChunkCitation[];
+    /** True when chunk-level entries drove the selection (vs. page-level fallback). */
+    usedChunks: boolean;
+    /** True when reranking reordered the initial semantic ranking. */
+    reranked: boolean;
+}
+/** Structured result returned by the query pipeline. */
+interface QueryResult {
+    answer: string;
+    selectedPages: string[];
+    reasoning: string;
+    saved?: string;
+    /** Populated when the query was run in debug mode. */
+    debug?: RetrievalDebug;
+}
+/** Source type tag persisted in frontmatter to describe the ingest origin. */
+type SourceType = "web" | "file" | "image" | "pdf" | "transcript";
+/** Outcome of a source write: a new file, a content change, or a no-op. */
+type WriteStatus = "created" | "updated" | "unchanged";
+/** Structured result returned by the ingest pipeline. */
+interface IngestResult {
+    filename: string;
+    charCount: number;
+    truncated: boolean;
+    source: string;
+    /** Detected source type; undefined for legacy results produced before this field was added. */
+    sourceType?: SourceType;
+    /** Whether the source file was created, updated (content changed), or unchanged (no-op). */
+    writeStatus: WriteStatus;
+}
+
+/**
+ * Provenance helpers for `llmwiki context`.
+ *
+ * Slice 4 ships two related pieces of work:
+ *   1. Flatten `ViewerPage.citations` (`ClaimCitation[]`, each with one
+ *      or more `SourceSpan` entries) into the documented
+ *      `ContextPrimary.citations[]` shape: one object per span,
+ *      `file`/`start`/`end` lifted from `span.lines` when present,
+ *      paragraph-only citations omit `start`/`end`, de-duped by
+ *      `(file, start, end)`, preserved in first-seen document order
+ *      (plan §Provenance And Source Windows).
+ *   2. Materialize bounded `ContextSourceWindow[]` for `--include-sources`
+ *      by reading short line ranges out of `sources/`. Path-confined:
+ *      traversal, absolute paths, and symlink escapes are rejected.
+ *      Only claim-level spans (`lines` populated) become windows;
+ *      paragraph-only citations are intentionally skipped because the
+ *      caller asked for SPECIFIC line context, not whole files.
+ *
+ * Citation flattening is the inner contract for `primary[].citations`;
+ * source-window materialization is the outer guard rail for
+ * `--include-sources` per-pack and per-window caps.
+ */
+
+/**
+ * Flat citation shape consumed by `ContextPrimary.citations[]` AND by
+ * the JSON export's `ExportPage.citations[]`. Exported so both
+ * surfaces share one normalized shape rather than drifting — consumers
+ * can reuse the same flattening rule across `llmwiki context` and
+ * `llmwiki export`.
+ */
+interface FlatCitation {
+    file: string;
+    start?: number;
+    end?: number;
+}
+
+/**
+ * Types for the computed source-freshness layer.
+ *
+ * Freshness is derived on demand from the filesystem + state.json and is never
+ * persisted. `FreshnessSnapshot` is built once per command/viewer snapshot and
+ * shared by every consumer (lint, export, MCP, context, viewer).
+ */
+/** A page's computed freshness on the source-derived axis. */
+type FreshnessStatus = "fresh" | "stale" | "orphaned" | "unverified";
+
+/**
+ * Shared types for the llmwiki export subsystem.
+ *
+ * ExportPage is the normalised in-memory representation of a wiki page used
+ * by every export format. It is derived from the page's YAML frontmatter plus
+ * the wikilink graph extracted from the body.
+ *
+ * Trust-adjacent fields (`advisoryConfidence`, `provenanceState`,
+ * `contradictedBy`) are surfaced as **advisory metadata only** — once the
+ * export crosses into any downstream storage (Atomic Memory or otherwise),
+ * those fields become mutable and lose their cryptographic tie to this
+ * export. Consumers should treat them as the compiler's estimate at
+ * export time, not as runtime guarantees.
+ */
+
+/**
+ * Flat citation shape exported alongside each page. Identical to the
+ * normalized `FlatCitation` used by `llmwiki context` so adapters that
+ * consume both surfaces share one shape. Paragraph-only citations omit
+ * `start` and `end`; claim-level citations carry the parsed line range.
+ */
+type ExportCitation = FlatCitation;
+/**
+ * Which wiki/ subdirectory a page lives in.
+ *
+ * Intentionally distinct from the schema layer's `PageKind`
+ * (concept/entity/comparison/overview) — this is a filesystem location, not
+ * a semantic typology. Renaming avoids field collision when JSON export and
+ * schema metadata are consumed by the same downstream tooling.
+ */
+type PageDirectory = "concepts" | "queries";
+/** A fully-resolved wiki page ready for export serialisation. */
+interface ExportPage {
+    /** Human-readable page title (from frontmatter). */
+    title: string;
+    /** Filesystem slug (filename without .md). */
+    slug: string;
+    /** Whether this page came from wiki/concepts or wiki/queries. */
+    pageDirectory: PageDirectory;
+    /**
+     * Project-relative path to the source markdown file, e.g.
+     * `wiki/concepts/retrieval.md`. Surfaced for the bridge so downstream
+     * adapters can deep-link without reconstructing the path themselves.
+     */
+    path: string;
+    /** One-line page summary (from frontmatter). */
+    summary: string;
+    /** Source filenames cited in the page body. */
+    sources: string[];
+    /** Taxonomy tags (from frontmatter). */
+    tags: string[];
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 last-updated timestamp. */
+    updatedAt: string;
+    /** Slugs of other pages this page links to via [[wikilinks]]. */
+    links: string[];
+    /** Full markdown body (without frontmatter). */
+    body: string;
+    /**
+     * Optional typed page kind from frontmatter. Defaults to "concept" in
+     * downstream consumers when absent — the export omits the field if no
+     * `kind` was set on the wiki page rather than fabricating a default.
+     */
+    kind?: PageKind;
+    /**
+     * Compiler's confidence estimate at export time. Advisory only —
+     * once imported into any downstream store this field is mutable and
+     * not cryptographically bound to the export.
+     */
+    advisoryConfidence?: number;
+    /** Lifecycle state from the compiler's provenance metadata. Advisory only. */
+    provenanceState?: ProvenanceState;
+    /** Other pages flagged as contradicting this one. Advisory only. */
+    contradictedBy?: ContradictionRef[];
+    /**
+     * Claim citations from the page body, flattened to the shared bridge
+     * shape. One entry per `^[file:start-end]` span. Multi-source markers
+     * (`^[a.md, b.md]`) expand into multiple entries. Paragraph-only
+     * citations carry no line range.
+     */
+    citations: ExportCitation[];
+    /**
+     * Prior external IDs this page was known by (e.g. before a slug
+     * rename). Downstream importers treat any matching alias as an
+     * upsert target so renamed pages do not orphan their prior memory
+     * record.
+     */
+    aliases?: string[];
+    /**
+     * Advisory per-page source-freshness, computed at export time from
+     * `.llmwiki/state.json` + the current `sources/`. A snapshot, not a
+     * guarantee. The export is active-page-only, so this is `fresh`, `stale`,
+     * or `unverified` — never `orphaned` (orphaned pages are dropped from the
+     * export and surfaced by lint/the viewer instead).
+     */
+    freshnessStatus: FreshnessStatus;
+    /** True when the page is disputed by another page (`contradictedBy` non-empty). */
+    contradicted: boolean;
+    /** True when the page is explicitly archived (`archived: true` frontmatter). */
+    archived: boolean;
+    /**
+     * Deterministic SHA-256 (hex) of {@link ExportPage.body}. Lets a
+     * downstream auditor (export provenance) detect content drift and verify that an
+     * imported page still matches what the compiler exported, without
+     * re-reading the markdown. Stable for identical bodies.
+     */
+    contentHash: string;
+    /**
+     * SHA-256 hashes of the source files this page derived from — the same
+     * per-source digests the compiler records in `.llmwiki/state.json` for
+     * change detection. Resolved from the page's `sources` list; ordered and
+     * de-duplicated. Empty when a page has no recorded sources (e.g. seed
+     * pages). Lets an auditor tie a page back to exact source bytes.
+     */
+    sourceHashes: string[];
+    /**
+     * Model id that produced this page's current content, stamped into the
+     * page's frontmatter at compile time (export provenance). Unlike an export-time env
+     * read, this is true per-page lineage: a page compiled by model A keeps
+     * `modelId: A` even if the exporter's env later points at model B. Absent
+     * for pages compiled before provenance stamping shipped.
+     */
+    modelId?: string;
+    /**
+     * Named prompt-contract version the page was compiled under (export provenance),
+     * stamped at compile time. Absent for pre-provenance pages.
+     */
+    promptVersion?: string;
+}
+
+/**
+ * Path-safe page access primitives for the llmwiki in-process SDK.
+ *
+ * Exposes two public functions:
+ *   - `getPage(root, ref)` — fetch a single page by directory + slug; returns
+ *     the full `Page` shape (body included) or null when the file is absent.
+ *   - `listPages(root, options)` — scan both page directories, read each page's
+ *     body so wikilinks can be extracted, apply archive/orphan filters, sort,
+ *     and return a cursor-paged slice.
+ *
+ * Design notes:
+ *   - `links` are derived from the Markdown **body** via `extractWikilinkSlugs`,
+ *     NOT from frontmatter.
+ *   - `archived` and `orphaned` are boolean **frontmatter** flags.
+ *   - `scanWikiPages` returns `{ slug, meta }` only (no body), so `listPages`
+ *     always re-reads each file to extract body links even when `includeBody`
+ *     is false.
+ *   - Path safety is enforced at `getPage` entry via `assertSafeSlug`; symlink
+ *     confinement is handled at a lower level by `scanWikiPages`.
+ */
+
+/** A reference to a specific page by its directory and slug. */
+interface PageRef {
+    pageDirectory: PageDirectory;
+    slug: string;
+}
+/** A fully-resolved in-memory representation of a single wiki page. */
+interface Page {
+    slug: string;
+    pageDirectory: PageDirectory;
+    title: string;
+    summary: string;
+    tags: string[];
+    /** Slugs of pages linked via `[[wikilinks]]` in the body. */
+    links: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    /** True when frontmatter contains `orphaned: true`. */
+    orphaned: boolean;
+    /** True when frontmatter contains `archived: true`. */
+    archived: boolean;
+    /** Full markdown body, present only when `includeBody` is true or via `getPage`. */
+    body?: string;
+}
+/** Options for filtering and paginating `listPages`. */
+interface ListPagesOptions {
+    cursor?: string;
+    limit?: number;
+    includeBody?: boolean;
+    includeArchived?: boolean;
+    includeOrphaned?: boolean;
+}
+/** Result returned by `listPages`. */
+interface ListPagesResult {
+    pages: Page[];
+    /** Opaque cursor for the next page; absent when the listing is exhausted. */
+    cursor?: string;
+}
+
+/**
+ * JSON export format writer.
+ *
+ * Produces a structured JSON document containing all wiki pages and their
+ * metadata. The schema is intentionally simple and human-readable so it can
+ * be consumed directly by scripts, agents, or downstream pipelines without
+ * additional transformation.
+ *
+ * Schema:
+ *   { schemaVersion, exportedAt, pageCount, projectId?, pages: ExportPage[] }
+ *
+ * W4 provenance lives PER PAGE (`ExportPage.modelId` / `promptVersion` plus
+ * `contentHash` / `sourceHashes`), stamped into each page at compile time.
+ * It is deliberately not summarized at the envelope level: a single
+ * export-time model id would misattribute pages compiled under a different
+ * model, which is exactly the lineage bug this avoids.
+ *
+ * `schemaVersion` lets downstream consumers (e.g. the rule importer) pin to a known
+ * contract. Increment when a breaking field change lands; additive fields
+ * do not require a bump.
+ *
+ * `projectId` is the optional bridge identifier. When present it pins the
+ * on-disk export to a stable identity that downstream consumers (the
+ * Atomic Memory adapter especially) use to derive deterministic external
+ * IDs. Validation happens at the CLI/programmatic boundary, not here —
+ * by the time we serialize, the value has been checked.
+ */
+
+/** Top-level shape of the JSON export file. */
+interface JsonExportDocument {
+    /**
+     * Contract version for downstream consumers. Start at 1; increment only on
+     * breaking envelope changes so consumers can pin a supported range.
+     */
+    schemaVersion: number;
+    exportedAt: string;
+    pageCount: number;
+    /** Optional bridge identifier. See `src/export/project-id.ts` for the validation rule. */
+    projectId?: string;
+    pages: ExportPage[];
+}
+/** Options accepted by {@link buildJsonExportDocument}. */
+interface BuildJsonExportOptions {
+    /**
+     * Optional project identifier. Validated against the bridge contract
+     * regex; throws if invalid so a malformed value never reaches disk.
+     */
+    projectId?: string;
+}
+
+/**
+ * Single provider-credential guard shared by every entry point that
+ * needs an LLM call (CLI compile/query/watch, MCP tools, the upcoming
+ * `quickstart` command).
+ *
+ * The guard throws on failure instead of calling `process.exit(1)`,
+ * which lets every caller decide how to surface the failure:
+ *
+ *  - CLI verbs catch the throw and print the message + exit 1.
+ *  - MCP tools let the throw propagate as a tool error.
+ *  - `quickstart` catches the throw and translates it into the
+ *    `compile.error = { code: "provider_unavailable", ... }` shape
+ *    documented in the next-quickstart implementation plan.
+ *
+ * Error messages mirror the rich CLI form (with `Set it with: export X=...`
+ * hints) so the user always sees actionable guidance no matter which
+ * surface fired the guard.
+ */
+/** Thrown when the active provider has no usable credentials. */
+declare class ProviderUnavailableError extends Error {
+    readonly provider: string;
+    readonly missing: string[];
+    readonly code: "provider_unavailable";
+    constructor(provider: string, missing: string[], message: string);
+}
+/** Thrown when LLMWIKI_PROVIDER names an unsupported provider. */
+declare class UnknownProviderError extends Error {
+    readonly provider: string;
+    readonly supported: string[];
+    readonly code: "unknown_provider";
+    constructor(provider: string, supported: string[], message: string);
+}
+
+/**
+ * Commander action for `llmwiki ingest <source>`.
+ *
+ * Detects the source type (URL, image, PDF, transcript, or generic file),
+ * delegates to the appropriate ingestion module, and saves the result as a
+ * markdown file with YAML frontmatter in the sources/ directory.
+ *
+ * Source type is persisted in frontmatter under the `sourceType` key for
+ * downstream tooling and human readers.
+ */
+
+/** Input shape for raw-text ingestion. */
+interface IngestTextInput {
+    title: string;
+    text: string;
+    source?: string;
+}
+
+/**
+ * Shared types for the local web viewer.
+ *
+ * `ViewerPage` is the in-memory page record consumed by the HTTP server's
+ * `/api/page/:directory/:slug` endpoint. `ViewerSnapshot` is the immutable
+ * project-wide state captured once at viewer startup and served from for
+ * every request — v1 deliberately does not live-watch the filesystem.
+ *
+ * `ViewerWarning` is the only warning surface; the underlying wiki layer
+ * (`src/wiki/collect.ts`) returns structural `parseStatus` flags, and the
+ * viewer decorator (`src/viewer/collect.ts`) maps those into stable
+ * `code`/`message` pairs the UI renders.
+ */
+
+/**
+ * Canonical page identifier: `concepts/<slug>` or `queries/<slug>`. Bare
+ * slugs collide between the two directories, so every viewer surface uses
+ * the namespaced form.
+ */
+type PageId = `${PageDirectory}/${string}`;
+
+/**
+ * Pure recommendation rules for `llmwiki next`.
+ *
+ * Classifies a {@link ProjectState} snapshot into exactly one of seven
+ * primary states and produces a primary {@link RecommendedAction} plus
+ * the per-state `otherActions` table from the implementation plan.
+ *
+ * Actions with user-supplied input (a source path, a question, a
+ * candidate id) are templates: the display `command` carries a
+ * `<placeholder>` and `executable.placeholders` lists the slots. Agents
+ * must populate placeholders themselves; the contract never returns a
+ * shell-ready command line.
+ */
+
+/** Single recommended action; `command` is for display, `executable` is for agents. */
+interface RecommendedAction {
+    command: string | null;
+    reason: string;
+    executable: ExecutableSpec | null;
+}
+/** Structured form of an executable command. Placeholders are slot names, not literals. */
+interface ExecutableSpec {
+    binary: "llmwiki";
+    args: string[];
+    placeholders?: string[];
+}
+
+/**
+ * Stable v1 JSON contract for `llmwiki context` and the future
+ * `get_context_pack` MCP tool.
+ *
+ * Every top-level field and every documented nested key is present from
+ * Slice 1 onward, even when later-slice features have not populated
+ * them yet (see `localdocs/context-graph-packs-implementation-plan.md`
+ * §JSON Contract). Unpopulated list fields are empty arrays; absent
+ * object fields are `null`. Slices may fill data into these fields,
+ * but must NEVER add or remove top-level keys without bumping
+ * `version`.
+ */
+
+/** Closed v1 enum for why a page landed in `primary[]`. */
+type PrimaryReason = "semantic-chunk" | "title-match" | "body-match" | "exact-slug" | "exact-title" | "graph-neighbor";
+/** Closed v1 enum for the edge label used in `neighbors[]`. */
+type NeighborReason = "wikilink";
+/** Closed v1 enum for top-level `warnings[]` codes. */
+type ContextWarningCode = "embedding-store-missing" | "query-embedding-unavailable" | "semantic-retrieval-error" | "lint-errors" | "pending-candidates" | "source-window-unavailable" | "truncated-prompt";
+/** Closed v1 enum for `gaps[]` codes. */
+type ContextGapCode = "dangling-link" | "page-warning";
+/**
+ * Budget envelope. `estimatedTokens` uses a tokens ≈ chars/4 heuristic in v1.
+ * Because `estimatedTokens` is itself serialized inside the measured JSON, the
+ * reported value may differ from `estimatePackTokens(returnedPack)` by at most
+ * one token of digit-count drift.
+ */
+interface ContextBudget {
+    requestedTokens: number;
+    estimatedTokens: number;
+    truncated: boolean;
+    /** Section keys (`primary`, `neighbors`, `sourceWindows`, `chunks`) that lost data. */
+    trimmedSections: string[];
+}
+/**
+ * Cached lint summary surfaced inside `project.lint`. Matches
+ * `LintCacheEntry` in `src/linter/cache.ts` but typed locally so the
+ * context contract does not depend on the linter's internal shape.
+ */
+interface ContextLintSummary {
+    warnings: number;
+    errors: number;
+    at: string;
+}
+/** Project block. `root` is set to `null` when `--omit-root` is supplied. */
+interface ContextProject {
+    root: string | null;
+    pages: number;
+    pendingCandidates: number;
+    lint: ContextLintSummary | null;
+}
+/** One semantic chunk surfaced for a primary page. Slice 2 populates it. */
+interface ContextChunk {
+    text: string;
+    score: number;
+    contentHash?: string;
+}
+/**
+ * Flattened citation. Produced by lifting `ClaimCitation.spans` into one
+ * object per span. Paragraph-only citations omit `start` and `end`.
+ */
+interface ContextCitation {
+    file: string;
+    start?: number;
+    end?: number;
+}
+/** Source line window emitted only when `--include-sources` is set in Slice 4. */
+interface ContextSourceWindow {
+    file: string;
+    start: number;
+    end: number;
+    text: string;
+}
+/** Page-local warning surfaced from the viewer collector. */
+interface ContextPageWarning {
+    code: string;
+    message: string;
+}
+/** One primary page entry. `reasons` is sorted alphabetically for stable output. */
+interface ContextPrimary {
+    id: PageId;
+    title: string;
+    pageDirectory: PageDirectory;
+    score: number;
+    reasons: PrimaryReason[];
+    summary: string;
+    chunks: ContextChunk[];
+    citations: ContextCitation[];
+    sourceWindows: ContextSourceWindow[];
+    warnings: ContextPageWarning[];
+    /** Computed source-freshness of this page (advisory snapshot, not a guarantee). */
+    freshnessStatus: FreshnessStatus;
+    /** Disputed by another page (`contradictedBy` non-empty). */
+    contradicted: boolean;
+    /** Explicitly archived (`archived: true` frontmatter). */
+    archived: boolean;
+}
+/** One graph neighbor edge. `distance` is 1 for direct, 2 for second-hop. */
+interface ContextNeighbor {
+    from: PageId;
+    to: PageId;
+    direction: "outgoing" | "incoming";
+    distance: number;
+    score: number;
+    reason: NeighborReason;
+}
+/** Top-level context-pack state warning. */
+interface ContextWarning {
+    code: ContextWarningCode;
+    message: string;
+}
+/**
+ * Missing-knowledge gap. `pageId` is required in v1; every documented
+ * gap code (`dangling-link`, `page-warning`) is tied to a specific
+ * page. A future project-wide gap would either bump `version` or
+ * introduce a new sibling field rather than retrofitting nullability
+ * onto this one.
+ */
+interface ContextGap {
+    code: ContextGapCode;
+    message: string;
+    pageId: PageId;
+}
+/** Top-level v1 envelope. */
+interface ContextPack {
+    version: 1;
+    prompt: string;
+    budget: ContextBudget;
+    project: ContextProject;
+    primary: ContextPrimary[];
+    neighbors: ContextNeighbor[];
+    warnings: ContextWarning[];
+    gaps: ContextGap[];
+    suggestedActions: RecommendedAction[];
+}
+
+/**
+ * Type definitions for the llmwiki eval harness.
+ *
+ * Four metric families:
+ *  - HealthResult: aggregated lint score (0–100)
+ *  - CitationCoverageResult: prose paragraph citation rate + precision
+ *  - CitationSupportResult: LLM-judged citation support quality (full suite only)
+ *  - StatsResult: corpus size snapshot appended to history.jsonl
+ *
+ * EvalReport bundles all four plus regression deltas and CI threshold violations.
+ */
+interface HealthRuleResult {
+    rule: string;
+    count: number;
+    severity: "error" | "warning" | "info";
+    deduction: number;
+}
+interface HealthResult {
+    score: number;
+    maxScore: 100;
+    rules: HealthRuleResult[];
+}
+interface CitationPageResult {
+    slug: string;
+    proseParagraphs: number;
+    citedParagraphs: number;
+}
+interface CitationCoverageResult {
+    totalProseParagraphs: number;
+    citedParagraphs: number;
+    coveragePercent: number;
+    totalCitations: number;
+    validCitations: number;
+    precisionPercent: number;
+    perPage: CitationPageResult[];
+}
+/** Per-source citation detail emitted by source-utilization eval. */
+interface SourceUtilizationEntry {
+    sourceFile: string;
+    citingPageCount: number;
+    citingPages: string[];
+}
+interface SourceUtilizationResult {
+    totalSources: number;
+    citedSources: number;
+    uncitedSources: number;
+    /** 0.0-1.0, or null when totalSources is 0 (not measured). */
+    utilizationRate: number | null;
+    /** Non-fatal issues encountered during evaluation (e.g. unreadable files). */
+    warnings: string[];
+    /** Sorted by citingPageCount descending. */
+    perSource: SourceUtilizationEntry[];
+}
+/** Citation depth metrics — how precise are the wiki's citations. */
+interface CitationDepthResult {
+    totalCitations: number;
+    preciseCitations: number;
+    vagueCitations: number;
+    /** 0.0-1.0 fraction of citations that include a line range. */
+    claimLevelRate: number;
+    /** Average number of citation markers per prose paragraph. */
+    avgCitationsPerParagraph: number;
+}
+interface CitationJudgement {
+    /** First 16 hex chars of SHA-256(claimText + spanText) — stable cache key. */
+    claimHash: string;
+    pageSlug: string;
+    citedFile: string;
+    lineStart: number;
+    lineEnd: number;
+    claimText: string;
+    spanText: string;
+    score: 0 | 1 | 2;
+    reason: string;
+    model: string;
+    timestamp: string;
+}
+interface CitationSupportResult {
+    sampledCount: number;
+    /** Ordered list of claimHash values evaluated in this run. Persisted so subsequent runs can retain the same sample as the corpus grows. */
+    sampledHashes: string[];
+    totalCitations: number;
+    meanScore: number;
+    fullySupported: number;
+    partiallySupported: number;
+    unsupported: number;
+    /** Number of judge calls that threw (credentials failure, network error, parse error). */
+    judgeErrors: number;
+    judgements: CitationJudgement[];
+}
+interface StatsResult {
+    timestamp: string;
+    sourceCount: number;
+    pageCount: number;
+    totalWikiChars: number;
+    embeddingCount: number;
+    chunkEmbeddingCount: number;
+    avgPageLengthChars: number;
+}
+interface EvalDelta {
+    healthScore?: number;
+    citationCoveragePercent?: number;
+    citationPrecisionPercent?: number;
+    citationSupportMean?: number;
+}
+interface EvalReport {
+    suite: "fast" | "full";
+    timestamp: string;
+    health: HealthResult;
+    citationCoverage: CitationCoverageResult;
+    sourceUtilization: SourceUtilizationResult;
+    citationDepth: CitationDepthResult;
+    citationSupport?: CitationSupportResult;
+    stats: StatsResult;
+    delta?: EvalDelta;
+    thresholdViolations: string[];
+}
+
+/** Shape returned by `collectStatus` and surfaced by the `wiki_status` tool. */
+interface WikiStatus {
+    pages: {
+        concepts: number;
+        queries: number;
+        total: number;
+    };
+    sources: number;
+    lastCompiledAt: string | null;
+    /**
+     * Concept slugs whose source changed or partially disappeared since compile.
+     * Capped at MAX_STATUS_LIST (sorted ascending); see staleCount for the true total.
+     */
+    stalePages: string[];
+    /** True total of stale pages (may exceed stalePages.length when capped). */
+    staleCount: number;
+    /**
+     * Concept slugs whose every owning source was deleted, or frontmatter-flagged orphaned.
+     * Capped at MAX_STATUS_LIST (sorted ascending); see orphanedCount for the true total.
+     */
+    orphanedPages: string[];
+    /** True total of orphaned pages (may exceed orphanedPages.length when capped). */
+    orphanedCount: number;
+    /** Readability of .llmwiki/state.json — surfaced so corrupt state is never silent. */
+    stateStatus: "ok" | "missing" | "corrupt";
+    /** Number of compile candidates awaiting human review. */
+    pendingCandidates: number;
+    /**
+     * Source files with changes since last compile (new/changed/deleted).
+     * Capped at MAX_STATUS_LIST (sorted by file); see pendingChangesCount for the true total.
+     */
+    pendingChanges: Array<{
+        file: string;
+        status: string;
+    }>;
+    /** True total of pending changes (may exceed pendingChanges.length when capped). */
+    pendingChangesCount: number;
+}
+
+/**
+ * Page-reading utilities for llmwiki.
+ *
+ * Exposes `readPageRecord`, which locates a wiki page by slug across the
+ * priority-ordered page directories (concepts first, then queries), parses
+ * its frontmatter, and returns a structured `PageRecord`. Orphaned pages are
+ * silently skipped to match the query pipeline's behaviour.
+ *
+ * This module is shared between the MCP tool layer and the in-process SDK so
+ * both consumers work from identical read semantics.
+ */
+/** Shape returned by readPageRecord and search_pages for each matching page. */
+interface PageRecord {
+    slug: string;
+    title: string;
+    summary: string;
+    body: string;
+}
+
+/** A single source file under `sources/`, with frontmatter metadata. */
+interface SourceRecord {
+    id: string;
+    title: string;
+    source: string;
+    sourceType: string;
+    ingestedAt?: string;
+    body?: string;
+}
+/** Options for paginating `listSources` and opting into source bodies. */
+interface ListSourcesOptions {
+    cursor?: string;
+    limit?: number;
+    includeBody?: boolean;
+}
+/** Result returned by `listSources`. */
+interface ListSourcesResult {
+    sources: SourceRecord[];
+    cursor?: string;
+}
+
+/**
+ * @file src/sdk/types.ts
+ * @description Public type surface for the llmwiki in-process SDK.
+ *
+ * Defines the `Wiki` interface returned by `createWiki`, plus the
+ * option shapes that callers pass to each method. All concrete result
+ * types are imported directly from their owning modules so consumers
+ * who need deeper access can follow the same import path.
+ */
+
+/** Options for `createWiki`. */
+interface CreateWikiOptions {
+    /** Absolute or relative path to the project root. Normalized once inside `createWiki`. */
+    root: string;
+}
+/** Compile options exposed through the SDK. Mirrors the core CompileOptions shape. */
+interface SdkCompileOptions {
+    /** Write generated pages as candidates for review instead of mutating wiki/. */
+    review?: boolean;
+}
+/** Options for `getContextPack`. Maps onto the subset of BuildContextPackOptions needed externally. */
+interface ContextPackOptions {
+    /** Free-text prompt the agent supplied. */
+    prompt: string;
+    /** Token budget (tokens ≈ chars/4). */
+    budget?: number;
+    /** Graph traversal depth (0–2). */
+    depth?: number;
+    /** Maximum primary pages to include. */
+    topPages?: number;
+    /** Maximum semantic chunks to include. */
+    topChunks?: number;
+}
+/**
+ * The facade object returned by `createWiki`. Every method runs silently
+ * (no console output) and normalizes all paths against the project root
+ * supplied at construction time.
+ */
+interface Wiki {
+    /**
+     * Ingest a file path or URL as a new source document. Requires no LLM credentials.
+     *
+     * **Trust boundary (SSRF + local-file-read primitive):** this method fetches any URL
+     * or reads any local file path the caller supplies — server-side — and writes the
+     * resulting content into the wiki. Treat `source` as **trusted input only**. Do not
+     * pass user-supplied or otherwise untrusted strings here. For untrusted content, use
+     * `ingestText` instead (it accepts pre-extracted `{title, text}` with no fetch or
+     * file-read step).
+     *
+     * **Prompt-injection surface:** ingested content is later processed by an LLM during
+     * `compile`. Untrusted or adversarially crafted content in sources is therefore a
+     * prompt-injection vector into page generation.
+     */
+    ingest(input: {
+        source: string;
+    }): Promise<IngestResult>;
+    /**
+     * Ingest raw text as a new source document. Requires no LLM credentials.
+     *
+     * Safe path for untrusted content: no network fetch or local file read is performed.
+     * The caller supplies the text directly, so there is no SSRF or path-traversal risk
+     * at ingest time (prompt-injection into `compile` still applies if the text itself is
+     * adversarial).
+     */
+    ingestText(input: IngestTextInput): Promise<IngestResult>;
+    /**
+     * Compile all pending sources into wiki pages. Requires LLM credentials.
+     *
+     * **Data egress:** source content is sent to the configured LLM provider during
+     * compilation. Do not compile wikis that contain confidential data unless the
+     * provider's data-handling policies are acceptable for that content.
+     *
+     * **Silent operation:** progress output is suppressed by the SDK facade. There is no
+     * progress callback in v1; structured `onLog` event delivery is planned for v1.x.
+     * For long corpora this call may take several minutes with no intermediate feedback.
+     */
+    compile(options?: SdkCompileOptions): Promise<CompileResult>;
+    /**
+     * Pick and hydrate the most relevant pages for a question. Requires LLM credentials.
+     *
+     * **Data egress:** the question (and embedding request) is sent to the configured LLM
+     * provider. Wiki page content may also be sent during retrieval scoring.
+     */
+    search(question: string): Promise<PageRecord[]>;
+    /**
+     * Generate a grounded answer from the wiki. Requires LLM credentials.
+     *
+     * **Data egress:** the question and relevant wiki page content are sent to the
+     * configured LLM provider to produce the answer.
+     *
+     * Streaming token delivery (`onToken`) is intentionally NOT exposed by the
+     * facade in v1 — only `save` and `debug` are surfaced. Callers needing
+     * per-token streaming should use `generateAnswer` directly.
+     */
+    query(question: string, options?: {
+        save?: boolean;
+        debug?: boolean;
+    }): Promise<QueryResult>;
+    /** Fetch a single page by directory and slug. No LLM required. */
+    getPage(ref: PageRef): Promise<Page | null>;
+    /** List wiki pages with optional filters and cursor-based pagination. No LLM required. */
+    listPages(options?: ListPagesOptions): Promise<ListPagesResult>;
+    /** List source files under `sources/` with optional cursor pagination. Bodies are opt-in via `includeBody`. No LLM required. */
+    listSources(options?: ListSourcesOptions): Promise<ListSourcesResult>;
+    /** Fetch a single source record by its basename id (e.g. "note.md"); returns null if absent. Always includes body. No LLM required. */
+    getSource(id: string): Promise<SourceRecord | null>;
+    /** Delete the source file for the given id (the id is the `IngestResult.filename`, e.g. "note.md").
+     *  Returns true if deleted, false if not found. The compiled page in `wiki/` is NOT removed
+     *  immediately — reconciliation happens on the next `compile()`. No LLM required. */
+    deleteSource(id: string): Promise<boolean>;
+    /**
+     * Collect a read-only status snapshot of the wiki. No LLM required.
+     *
+     * **Per-call cost:** each call hashes and reads the full source corpus —
+     * O(total source bytes) — with no cross-call caching. Avoid calling this in a
+     * hot loop; an mtime-keyed cache is planned for v1.x.
+     */
+    status(): Promise<WikiStatus>;
+    /**
+     * Run all lint rules and return a severity-counted summary. No LLM required.
+     *
+     * **Per-call cost:** each call hashes and reads the full source corpus —
+     * O(total source bytes) — with no cross-call caching. Avoid calling this in a
+     * hot loop; an mtime-keyed cache is planned for v1.x.
+     */
+    lint(): Promise<LintSummary>;
+    /**
+     * Build a v1 context pack for agent consumption. Lexical retrieval works
+     * credential-free; semantic retrieval is opportunistic (skipped when no
+     * embeddings are available).
+     */
+    getContextPack(options: ContextPackOptions): Promise<ContextPack>;
+    /**
+     * Export the wiki as a structured JSON document. No LLM required.
+     *
+     * **Per-call cost:** each call hashes and reads the full source corpus —
+     * O(total source bytes) — with no cross-call caching. Avoid calling this in a
+     * hot loop; an mtime-keyed cache is planned for v1.x.
+     */
+    exportJson(options?: BuildJsonExportOptions): Promise<JsonExportDocument>;
+    /**
+     * Run the eval harness. "fast" mode is credential-free; "full" mode
+     * requires LLM credentials for citation-support judging.
+     *
+     * **Silent operation:** the SDK suppresses all progress output. There is no
+     * progress callback in v1; structured `onLog` event delivery is planned for v1.x.
+     */
+    runEval(options: {
+        mode: "fast" | "full";
+        record?: boolean;
+    }): Promise<EvalReport>;
+}
+
+/**
+ * @file src/sdk/wiki.ts
+ * @description In-process SDK facade for llmwiki.
+ *
+ * `createWiki(options)` returns a `Wiki` object that delegates every
+ * method to the SDK-safe core functions built across Tasks 1–9. All
+ * methods run silently (no console output) by scoping quiet mode to the
+ * async call tree via AsyncLocalStorage, so concurrent calls are fully
+ * isolated — no global flag is mutated, eliminating the concurrency caveat
+ * described in earlier design drafts.
+ *
+ * Provider-gating rules:
+ *   - `compile`, `search`, `query` — always guard (throw ProviderUnavailableError if no creds)
+ *   - `runEval({ mode: "full" })` — guards only when mode is "full"
+ *   - All other methods — no credential check; safe to call without an LLM provider
+ *
+ * Root-path validation: `createWiki` normalizes the root once via `path.resolve`.
+ * A non-existent root is accepted — `ingest`/`ingestText` create `sources/` via
+ * recursive `mkdir` on first write. If the path already exists but is NOT a
+ * directory (e.g. a regular file was passed by mistake), construction throws
+ * immediately with a clear error message.
+ */
+
+/**
+ * Create an in-process wiki facade bound to the given project root.
+ *
+ * @param options - `{ root }` — path to the wiki project directory.
+ * @returns A `Wiki` facade whose methods delegate to the SDK-safe core.
+ */
+declare function createWiki(options: CreateWikiOptions): Wiki;
+
+export { type CompileResult, type ContextPack, type ContextPackOptions, type CreateWikiOptions, type EvalReport, type IngestResult, type IngestTextInput, type JsonExportDocument, type LintSummary, type ListPagesOptions, type ListPagesResult, type ListSourcesOptions, type ListSourcesResult, type Page, type PageDirectory, type PageRecord, type PageRef, ProviderUnavailableError, type QueryResult, type SdkCompileOptions, type SourceRecord, UnknownProviderError, type Wiki, type WikiStatus, type WriteStatus, createWiki };