@copperbox/why 1.0.0

package/dist/blame.js

@@ -0,0 +1,294 @@
+// `why blame` (static, DESIGN.md §7): match anchors to a target span via the
+// anchor index, expand one hop along typed edges, render the story. Blame
+// trusts anchors as written — no re-resolution — but a `lost` anchor is a
+// claim that no longer holds, so it never matches: anchors are live or lost,
+// never silently wrong.
+import { deriveTitle, extractCitations } from "@copperbox/okf-mcp";
+import { buildAnchorIndex, indexedConcept, lookupAnchors, parseLineRange, } from "./anchors.js";
+export { parseLineRange } from "./anchors.js";
+/** The target spec was malformed — a usage error, not an operational one. */
+export class BlameTargetError extends Error {
+}
+/** Parse `<path>[:line[-line]]`; a non-numeric suffix is part of the path. */
+export function parseBlameTarget(spec) {
+    const match = /^(.+):(\d+)(?:-(\d+))?$/.exec(spec);
+    if (!match)
+        return { path: normalizePath(spec) };
+    const start = Number(match[2]);
+    const end = match[3] === undefined ? start : Number(match[3]);
+    if (start < 1 || end < start) {
+        throw new BlameTargetError(`"${spec}": line ranges are 1-based low-high, like src/lock.rs:41-58`);
+    }
+    return { path: normalizePath(match[1]), lines: { start, end } };
+}
+export function normalizePath(path) {
+    return path.replace(/^\.\//, "");
+}
+export function formatTarget(target) {
+    if (!target.lines)
+        return target.path;
+    const { start, end } = target.lines;
+    return `${target.path}:${start}${end === start ? "" : `-${end}`}`;
+}
+/** Major version of the story payload — see docs/ui-contract.md for the policy. */
+export const STORY_SCHEMA_VERSION = 1;
+function newestFirst(a, b) {
+    const byDate = (b.why.happened_on ?? "").localeCompare(a.why.happened_on ?? "");
+    return byDate !== 0 ? byDate : a.id.localeCompare(b.id);
+}
+function edgeFrom(bundle, link) {
+    const neighbor = link.resolvedId ? bundle.concepts.get(link.resolvedId) : undefined;
+    if (!neighbor)
+        return { title: link.text };
+    const edge = { title: deriveTitle(neighbor), id: neighbor.id, type: neighbor.frontmatter.type };
+    if (neighbor.why.status !== undefined)
+        edge.status = neighbor.why.status;
+    return edge;
+}
+function edgesIn(bundle, concept, section) {
+    return concept.links
+        .filter((link) => link.section?.toLowerCase() === section)
+        .map((link) => edgeFrom(bundle, link));
+}
+function citationsOf(bundle, concept) {
+    const { citations } = extractCitations(concept.body, concept.path, (id) => bundle.concepts.has(id));
+    return citations.map((c) => ({ label: c.text, url: c.target }));
+}
+/** `PR #212: replace striped locks…` reads as `PR #212` on one evidence line. */
+function evidenceLabels(citations) {
+    const labels = citations.map((c) => c.label.split(":")[0].trim()).filter((label) => label !== "");
+    return [...new Set(labels)];
+}
+/**
+ * Hedging is engine logic, precomputed into the payload: anything below
+ * `corroborated` hedges, and an unstated confidence hedges hardest — the data
+ * may never hedge less than the evidence supports. Questions carry no
+ * rationale to hedge.
+ */
+function hedgePrefix(type, confidence) {
+    if (type === "question")
+        return "";
+    switch (confidence) {
+        case "recorded":
+        case "corroborated":
+            return "";
+        case "inferred":
+            return "likely — ";
+        default:
+            return "speculation, thin evidence — ";
+    }
+}
+function isExpiredConstraint(type, status) {
+    return type === "constraint" && status === "expired";
+}
+function toBlock(bundle, concept, anchors) {
+    const type = concept.frontmatter.type;
+    const description = oneLiner(concept);
+    const hedge = hedgePrefix(type, concept.why.confidence);
+    const citations = citationsOf(bundle, concept);
+    const block = {
+        id: concept.id,
+        title: deriveTitle(concept),
+        type,
+        description,
+        hedged: hedge !== "",
+        renderedRationale: description === "" ? "" : `${hedge}${description}`,
+        anchors,
+        edges: {
+            becauseOf: edgesIn(bundle, concept, "because of"),
+            insteadOf: edgesIn(bundle, concept, "instead of"),
+            supersededBy: edgesIn(bundle, concept, "superseded by"),
+        },
+        citations,
+        evidence: evidenceLabels(citations),
+        downstream: [],
+    };
+    if (concept.why.status !== undefined)
+        block.status = concept.why.status;
+    if (concept.why.happened_on !== undefined)
+        block.happened_on = concept.why.happened_on;
+    if (concept.why.expired_on !== undefined)
+        block.expired_on = concept.why.expired_on;
+    if (concept.why.confidence !== undefined)
+        block.confidence = concept.why.confidence;
+    if (isExpiredConstraint(block.type, block.status)) {
+        // The §5 payoff: what downstream shape may now be scar tissue.
+        block.downstream = edgesIn(bundle, concept, "led to").filter((edge) => edge.type === "decision" && edge.status === "active");
+    }
+    return block;
+}
+function oneLiner(concept) {
+    if (concept.frontmatter.description)
+        return concept.frontmatter.description;
+    const firstProse = concept.sections.find((s) => s.content !== "")?.content ?? "";
+    return firstProse.split("\n")[0] ?? "";
+}
+function dirOf(path) {
+    const segments = path.split("/");
+    segments.pop();
+    return segments;
+}
+function dirDistance(a, b) {
+    let shared = 0;
+    while (shared < a.length && shared < b.length && a[shared] === b[shared])
+        shared++;
+    return a.length - shared + (b.length - shared);
+}
+const NEARBY_LIMIT = 5;
+function nearestAnchored(bundle, target) {
+    const targetDir = dirOf(target.path);
+    const ranked = [];
+    for (const concept of bundle.concepts.values()) {
+        let best;
+        for (const anchor of concept.why.anchors) {
+            if (anchor.state === "lost")
+                continue;
+            const distance = dirDistance(targetDir, dirOf(anchor.path));
+            if (!best || distance < best.distance)
+                best = { distance, anchor };
+        }
+        if (!best)
+            continue;
+        const entry = {
+            id: concept.id,
+            title: deriveTitle(concept),
+            type: concept.frontmatter.type,
+            anchor: best.anchor,
+        };
+        if (concept.why.status !== undefined)
+            entry.status = concept.why.status;
+        ranked.push({ distance: best.distance, entry });
+    }
+    ranked.sort((a, b) => a.distance - b.distance || a.entry.title.localeCompare(b.entry.title));
+    return ranked.slice(0, NEARBY_LIMIT).map((r) => r.entry);
+}
+/** The narrowest covering span, README-style: `src/lock.rs:41-58 · acquire_shared`. */
+function spanOf(anchors) {
+    let best;
+    for (const anchor of anchors) {
+        const range = anchor.lines === undefined ? undefined : parseLineRange(anchor.lines);
+        const width = range ? range.end - range.start : Number.POSITIVE_INFINITY;
+        if (!best || width < best.width)
+            best = { anchor, width };
+    }
+    if (!best)
+        return undefined;
+    const { anchor } = best;
+    const lines = anchor.lines === undefined ? "" : `:${anchor.lines}`;
+    const symbol = anchor.symbol === undefined ? "" : ` · ${anchor.symbol}`;
+    return `${anchor.path}${lines}${symbol}`;
+}
+export function buildBlameReport(bundle, target, index = buildAnchorIndex(bundle)) {
+    const hitsByConcept = new Map();
+    for (const hit of lookupAnchors(index, target)) {
+        const hits = hitsByConcept.get(hit.conceptId);
+        if (hits)
+            hits.push(hit);
+        else
+            hitsByConcept.set(hit.conceptId, [hit]);
+    }
+    const matched = [...hitsByConcept.entries()].map(([id, hits]) => {
+        const concept = indexedConcept(bundle, id);
+        hits.sort((a, b) => a.anchorIndex - b.anchorIndex); // anchors in written order
+        return { concept, anchors: hits.map((hit) => hit.anchor) };
+    });
+    matched.sort((a, b) => newestFirst(a.concept, b.concept));
+    const hits = matched.map(({ concept, anchors }) => toBlock(bundle, concept, anchors));
+    const matchedIds = new Set(hits.map((block) => block.id));
+    const warnings = [...bundle.concepts.values()]
+        .filter((concept) => isExpiredConstraint(concept.frontmatter.type, concept.why.status) && !matchedIds.has(concept.id))
+        .sort(newestFirst)
+        .map((concept) => toBlock(bundle, concept, []));
+    const report = { schemaVersion: STORY_SCHEMA_VERSION, target, hits, warnings, nearby: [] };
+    const span = spanOf(matched.flatMap((m) => m.anchors));
+    if (span !== undefined)
+        report.span = span;
+    if (hits.length === 0)
+        report.nearby = nearestAnchored(bundle, target);
+    return report;
+}
+// --- Rendering ---------------------------------------------------------------
+const TITLE_COLUMN = 40;
+export function glyphFor(type, status) {
+    if (type === "question")
+        return "?";
+    if (status === "expired" || status === "superseded")
+        return "⚠";
+    return "●";
+}
+function metaLine(block) {
+    const parts = [block.type];
+    if (isExpiredConstraint(block.type, block.status)) {
+        parts.push(`EXPIRED ${block.expired_on ?? "(date unknown)"}`);
+        return parts.join(" · ");
+    }
+    if (block.happened_on !== undefined)
+        parts.push(block.happened_on);
+    if (block.type === "question") {
+        if (block.status !== undefined)
+            parts.push(block.status);
+    }
+    else if (block.confidence !== undefined) {
+        parts.push(block.confidence);
+    }
+    return parts.join(" · ");
+}
+function edgeText(edge, withStatus) {
+    if (edge.type === undefined)
+        return edge.title;
+    const status = withStatus && edge.status !== undefined ? ` — ${edge.status}` : "";
+    return `${edge.title} (${edge.type}${status})`;
+}
+function renderBlock(block) {
+    const lines = [];
+    const head = `${glyphFor(block.type, block.status)} ${block.title}`;
+    lines.push(`  ${head.padEnd(TITLE_COLUMN)} ${metaLine(block)}`);
+    // The hedge is already baked into renderedRationale — display it verbatim.
+    if (block.renderedRationale !== "")
+        lines.push(`    ${block.renderedRationale}`);
+    const edgeLines = [];
+    for (const edge of block.edges.becauseOf)
+        edgeLines.push(["because of", edgeText(edge, false)]);
+    for (const edge of block.edges.insteadOf)
+        edgeLines.push(["instead of", edgeText(edge, true)]);
+    for (const edge of block.edges.supersededBy)
+        edgeLines.push(["superseded by", edgeText(edge, false)]);
+    if (block.evidence.length > 0)
+        edgeLines.push(["evidence", block.evidence.join(", ")]);
+    const labelWidth = Math.max(10, ...edgeLines.map(([label]) => label.length));
+    for (const [label, text] of edgeLines)
+        lines.push(`    ${label.padEnd(labelWidth)} ▸ ${text}`);
+    for (const edge of block.downstream) {
+        lines.push(`    → downstream decision "${edge.title}" may now be scar tissue.`);
+    }
+    return lines;
+}
+/** `path[:lines]` — also the span format `why anchor` and `why doctor` print. */
+export function anchorSpan(anchor) {
+    return anchor.lines === undefined ? anchor.path : `${anchor.path}:${anchor.lines}`;
+}
+export function renderBlameReport(report) {
+    const lines = [];
+    if (report.hits.length > 0) {
+        if (report.span !== undefined)
+            lines.push(report.span);
+        for (const block of report.hits)
+            lines.push("", ...renderBlock(block));
+    }
+    else {
+        lines.push(`No concepts anchor ${formatTarget(report.target)}.`);
+        if (report.nearby.length > 0) {
+            lines.push("", "Anchored concepts nearby (nearest first):");
+            for (const near of report.nearby) {
+                const head = `${glyphFor(near.type, near.status)} ${near.title}`;
+                lines.push(`  ${head.padEnd(TITLE_COLUMN)} ${near.type} · ${anchorSpan(near.anchor)}`);
+            }
+        }
+        else {
+            lines.push("", "This bundle has no anchored concepts yet — add why.anchors frontmatter to place its story in the code.");
+        }
+    }
+    for (const block of report.warnings)
+        lines.push("", ...renderBlock(block));
+    return lines;
+}

package/dist/bundle.d.ts

@@ -0,0 +1,78 @@
+import type { BodySection, ConceptFrontmatter, ConceptLink, LoadedBundle } from "@copperbox/okf-mcp";
+export declare const CONCEPT_TYPES: readonly ["decision", "constraint", "attempt", "incident", "question"];
+export type ConceptType = (typeof CONCEPT_TYPES)[number];
+/** Per-type `status` vocabulary (DESIGN.md §2 field table). */
+export declare const STATUS_VOCAB: Record<ConceptType, readonly string[]>;
+/** The confidence ladder (DESIGN.md §2), strongest first. */
+export declare const CONFIDENCE_LEVELS: readonly ["recorded", "corroborated", "inferred", "speculative"];
+export type Confidence = (typeof CONFIDENCE_LEVELS)[number];
+export declare const ANCHOR_STATES: readonly ["live", "lost"];
+export type AnchorState = (typeof ANCHOR_STATES)[number];
+/** An anchor is a claim: at commit `as_of`, this concept was about this span. */
+export interface Anchor {
+    path: string;
+    symbol?: string;
+    /** Line span as written (`"41-58"` or `"31"`); absent = whole file. */
+    lines?: string;
+    as_of?: string;
+    state?: AnchorState;
+}
+export declare const VERIFY_METHODS: readonly ["check", "ask", "review-by"];
+export type VerifyMethod = (typeof VERIFY_METHODS)[number];
+/** A constraint's falsifiability contract (DESIGN.md §5). */
+export interface VerifySpec {
+    method: VerifyMethod;
+    check?: string;
+    ask?: string;
+    review_by?: string;
+}
+/**
+ * The typed `why:` extension map. Invalid values are dropped to undefined
+ * with a diagnostic — in particular an unrecognized `confidence` must never
+ * survive into the typed view, or rendering could hedge less than the
+ * evidence supports.
+ */
+export interface WhyMeta {
+    status?: string;
+    happened_on?: string;
+    expired_on?: string;
+    confidence?: Confidence;
+    anchors: Anchor[];
+    verify?: VerifySpec;
+}
+/** One problem with a concept's `why:` data, addressed for `why lint`. */
+export interface Diagnostic {
+    /** Bundle-relative file path. */
+    path: string;
+    /** Dotted field the problem is about, e.g. `why.anchors[1].path`. */
+    field: string;
+    message: string;
+}
+/** A body link plus the heading of the section it appears under (DESIGN.md §3). */
+export interface SectionedLink extends ConceptLink {
+    section?: string;
+}
+export interface WhyConcept {
+    id: string;
+    /** Bundle-relative file path. */
+    path: string;
+    frontmatter: ConceptFrontmatter;
+    why: WhyMeta;
+    body: string;
+    sections: BodySection[];
+    links: SectionedLink[];
+}
+export interface WhyBundle {
+    /** Absolute path to the bundle root. */
+    root: string;
+    concepts: Map<string, WhyConcept>;
+    /** `why:` schema problems, per concept. */
+    diagnostics: Diagnostic[];
+    /** The underlying okf-mcp bundle — OKF-level problems and validation live there. */
+    okf: LoadedBundle;
+}
+export declare function isPlainMap(value: unknown): value is Record<string, unknown>;
+/** Vocabulary membership as a type guard, so callers narrow instead of casting. */
+export declare function isOneOf<T extends string>(vocab: readonly T[], value: unknown): value is T;
+/** Load a `.why/` bundle from disk into the typed view. Never throws on content. */
+export declare function loadBundle(root: string): Promise<WhyBundle>;

package/dist/bundle.js

@@ -0,0 +1,188 @@
+// Schema-aware bundle loading: okf-mcp parses the OKF layer (frontmatter,
+// links, sections); this module types the `why:` extension map on top
+// (DESIGN.md §2) and tags each link with the section it appears in (§3).
+// Loading is permissive in the OKF spirit: malformed `why:` data becomes a
+// diagnostic, never an exception — `why lint` renders the diagnostics.
+import { loadBundle as loadOkfBundle, sectionAt, splitSections, } from "@copperbox/okf-mcp";
+export const CONCEPT_TYPES = ["decision", "constraint", "attempt", "incident", "question"];
+/** Per-type `status` vocabulary (DESIGN.md §2 field table). */
+export const STATUS_VOCAB = {
+    decision: ["active", "superseded", "reversed"],
+    constraint: ["active", "expired", "unknown"],
+    attempt: ["failed", "abandoned", "partial"],
+    incident: ["resolved", "recurring"],
+    question: ["open", "answered"],
+};
+/** The confidence ladder (DESIGN.md §2), strongest first. */
+export const CONFIDENCE_LEVELS = ["recorded", "corroborated", "inferred", "speculative"];
+export const ANCHOR_STATES = ["live", "lost"];
+export const VERIFY_METHODS = ["check", "ask", "review-by"];
+const WHY_KEYS = new Set(["status", "happened_on", "expired_on", "confidence", "anchors", "verify"]);
+export function isPlainMap(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Vocabulary membership as a type guard, so callers narrow instead of casting. */
+export function isOneOf(vocab, value) {
+    return vocab.includes(value);
+}
+/** YAML reads a bare `31` or all-digit sha as a number; both mean the string. */
+function asStringy(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    return undefined;
+}
+function list(values) {
+    return values.join(", ");
+}
+function readAnchors(value, push) {
+    if (!Array.isArray(value)) {
+        push("why.anchors", "must be a list of anchor maps");
+        return [];
+    }
+    const anchors = [];
+    value.forEach((entry, i) => {
+        const at = `why.anchors[${i}]`;
+        if (!isPlainMap(entry)) {
+            push(at, "must be a map with at least a path");
+            return;
+        }
+        const path = asStringy(entry.path);
+        if (path === undefined) {
+            push(`${at}.path`, "is required and must be a string");
+            return;
+        }
+        const anchor = { path };
+        if (entry.symbol !== undefined) {
+            const symbol = asStringy(entry.symbol);
+            if (symbol === undefined)
+                push(`${at}.symbol`, "must be a string");
+            else
+                anchor.symbol = symbol;
+        }
+        if (entry.lines !== undefined) {
+            const lines = asStringy(entry.lines);
+            if (lines === undefined)
+                push(`${at}.lines`, 'must be a line or range like "41-58"');
+            else
+                anchor.lines = lines;
+        }
+        if (entry.as_of !== undefined) {
+            const asOf = asStringy(entry.as_of);
+            if (asOf === undefined)
+                push(`${at}.as_of`, "must be a commit id string");
+            else
+                anchor.as_of = asOf;
+        }
+        if (entry.state !== undefined) {
+            if (isOneOf(ANCHOR_STATES, entry.state)) {
+                anchor.state = entry.state;
+            }
+            else {
+                push(`${at}.state`, `"${String(entry.state)}" is not an anchor state: allowed values are ${list(ANCHOR_STATES)}`);
+            }
+        }
+        anchors.push(anchor);
+    });
+    return anchors;
+}
+/** The frontmatter key each verify method requires its detail under. */
+const VERIFY_DETAIL_KEYS = {
+    check: "check",
+    ask: "ask",
+    "review-by": "review_by",
+};
+function readVerify(value, push) {
+    if (!isPlainMap(value)) {
+        push("why.verify", "must be a map with a method (DESIGN.md §5)");
+        return undefined;
+    }
+    const method = value.method;
+    if (!isOneOf(VERIFY_METHODS, method)) {
+        push("why.verify.method", `"${String(method)}" is not a verify method: allowed values are ${list(VERIFY_METHODS)}`);
+        return undefined;
+    }
+    const spec = { method };
+    const detailKey = VERIFY_DETAIL_KEYS[spec.method];
+    const detail = asStringy(value[detailKey]);
+    if (detail === undefined) {
+        push(`why.verify.${detailKey}`, `method "${spec.method}" requires a "${detailKey}" value`);
+    }
+    else {
+        spec[detailKey] = detail;
+    }
+    return spec;
+}
+function readWhyMeta(frontmatter, path, diagnostics) {
+    const push = (field, message) => diagnostics.push({ path, field, message });
+    const meta = { anchors: [] };
+    const raw = frontmatter.why;
+    if (raw === undefined)
+        return meta;
+    if (!isPlainMap(raw)) {
+        push("why", "must be a map (DESIGN.md §2)");
+        return meta;
+    }
+    for (const key of Object.keys(raw)) {
+        if (!WHY_KEYS.has(key)) {
+            push(`why.${key}`, `unrecognized key: known keys are ${list([...WHY_KEYS])}`);
+        }
+    }
+    if (raw.status !== undefined) {
+        const status = asStringy(raw.status);
+        if (status === undefined) {
+            push("why.status", "must be a string");
+        }
+        else {
+            meta.status = status;
+            const vocab = isOneOf(CONCEPT_TYPES, frontmatter.type) ? STATUS_VOCAB[frontmatter.type] : undefined;
+            if (vocab && !vocab.includes(status)) {
+                push("why.status", `"${status}" is not a ${frontmatter.type} status: allowed values are ${list(vocab)}`);
+            }
+        }
+    }
+    for (const key of ["happened_on", "expired_on"]) {
+        if (raw[key] !== undefined) {
+            const date = asStringy(raw[key]);
+            if (date === undefined)
+                push(`why.${key}`, "must be a date string");
+            else
+                meta[key] = date;
+        }
+    }
+    if (raw.confidence !== undefined) {
+        if (isOneOf(CONFIDENCE_LEVELS, raw.confidence)) {
+            meta.confidence = raw.confidence;
+        }
+        else {
+            push("why.confidence", `"${String(raw.confidence)}" is not a confidence level: allowed values are ${list(CONFIDENCE_LEVELS)}`);
+        }
+    }
+    if (raw.anchors !== undefined)
+        meta.anchors = readAnchors(raw.anchors, push);
+    if (raw.verify !== undefined)
+        meta.verify = readVerify(raw.verify, push);
+    return meta;
+}
+/** Load a `.why/` bundle from disk into the typed view. Never throws on content. */
+export async function loadBundle(root) {
+    const okf = await loadOkfBundle({ id: "why", root });
+    const concepts = new Map();
+    const diagnostics = [];
+    for (const [id, concept] of okf.concepts) {
+        concepts.set(id, {
+            id,
+            path: concept.path,
+            frontmatter: concept.frontmatter,
+            why: readWhyMeta(concept.frontmatter, concept.path, diagnostics),
+            body: concept.body,
+            sections: splitSections(concept.body),
+            links: concept.links.map((link) => ({
+                ...link,
+                section: sectionAt(concept.body, link.targetStart),
+            })),
+        });
+    }
+    return { root: okf.root, concepts, diagnostics, okf };
+}

package/dist/capture.d.ts

@@ -0,0 +1,76 @@
+import { type WhyBundle } from "./bundle.js";
+import { type CommandRunner } from "./evidence.js";
+import { type Finding } from "./lint.js";
+/** A capture step that must stop the command cleanly (exit 1), not crash. */
+export declare class CaptureError extends Error {
+}
+/**
+ * Where drafts live, relative to the bundle root. Must stay a dot-directory:
+ * okf-mcp's bundle walk skips dot-dirs only, and drafts must never serve.
+ */
+export declare const DRAFTS_DIRNAME = ".drafts";
+/** Suffix of the evidence pack written beside each draft. */
+export declare const EVIDENCE_SUFFIX = ".evidence.md";
+/** Above this many hunks a file gets one whole-file anchor, said out loud. */
+export declare const MAX_HUNK_ANCHORS_PER_FILE = 4;
+/** Rationale candidates quoted into the draft; the rest point at the pack. */
+export declare const MAX_RATIONALE_CANDIDATES = 12;
+/**
+ * A discussion paragraph is a rationale candidate when it matches this —
+ * dig's comment-tell vocabulary widened with decision language.
+ */
+export declare const RATIONALE_TELL_RE: RegExp;
+export interface CaptureResult {
+    /** Absolute path of the draft concept file. */
+    draftPath: string;
+    /** Absolute path of the evidence pack written beside it. */
+    evidencePath: string;
+    type: "decision" | "attempt";
+    candidateCount: number;
+    anchorCount: number;
+    /** Degradations and collapses, said out loud (also embedded in the draft). */
+    notes: string[];
+}
+export interface CaptureOptions {
+    /** Injectable so tests answer gh from fixtures and never hit the network. */
+    runner?: CommandRunner;
+}
+interface CapturedAnchor {
+    path: string;
+    lines?: string;
+    as_of: string;
+    state: "live";
+}
+/**
+ * Derive anchor claims from a zero-context (`-U0`) patch: one anchor per
+ * hunk's new-side span, exact to the changed lines. A pure deletion anchors
+ * the single line the cut sits after; a file with no hunks (binary,
+ * rename-only) anchors whole-file; a deleted file anchors nothing; a file
+ * with more than MAX_HUNK_ANCHORS_PER_FILE hunks collapses to one whole-file
+ * anchor with a note — never a silent cap.
+ */
+export declare function anchorsFromPatch(patch: string, asOf: string): {
+    anchors: CapturedAnchor[];
+    files: string[];
+    notes: string[];
+};
+/** Short kebab-case slug from a title; empty when nothing survives. */
+export declare function slugify(text: string): string;
+export declare function capturePr(bundle: WhyBundle, n: number, options?: CaptureOptions): Promise<CaptureResult>;
+export declare function captureCommit(bundle: WhyBundle, ref: string, options?: CaptureOptions): Promise<CaptureResult>;
+export interface PromoteResult {
+    promoted: boolean;
+    /** Bundle-relative target path in the type directory. */
+    path: string;
+    /** Lint findings on the promoted file (errors when refused, else warnings). */
+    findings: Finding[];
+}
+/**
+ * Move one draft into its type directory, gated on lint: the concept is
+ * written through okf-mcp writeConcept (which stamps `timestamp` and
+ * normalizes citations), the reloaded bundle is linted, and any error-severity
+ * finding on the new file rolls the write back and keeps the draft. Findings
+ * elsewhere in the bundle never block a promotion.
+ */
+export declare function promoteDraft(bundle: WhyBundle, ref: string, cwd: string): Promise<PromoteResult>;
+export {};