@wrenautomation/birdwatch 0.0.0-stage → 0.30.0

package/dist/engine/view.d.ts

@@ -0,0 +1,138 @@
+import { type Brief } from "./agent.js";
+import type { Deps } from "./ports.js";
+import { type RunState } from "./state.js";
+type Who = {
+    from: string;
+    by: string;
+};
+type Answers = Record<string, Record<string, number>>;
+export interface RunQuery extends Who {
+    id: string;
+    round: number;
+    at: string;
+    terms: string;
+    why: string;
+    site?: string;
+    facet?: string;
+    tier?: number;
+    follow?: {
+        url: string;
+        as: string;
+        document?: string;
+    };
+    /** Hits it wrote, then known hits it found again. */
+    hits: string[];
+    again: string[];
+}
+export interface RunHit extends Who {
+    id: string;
+    round: number;
+    url: string;
+    title?: string;
+    channel?: string;
+    snippet?: string;
+    date?: string;
+    length?: number;
+    /** The sources that returned it. */
+    sources: string[];
+    /** Every query that returned it, the first one first. */
+    queries: string[];
+    call?: {
+        verdict: "keep" | "drop";
+        why?: string;
+    } & Who;
+    judge?: Answers;
+    document?: string;
+}
+export interface RunDocument extends Who {
+    id: string;
+    hit: string;
+    url: string;
+    title?: string;
+    channel?: string;
+    media: string;
+    date?: string;
+    length?: number;
+    chars: number;
+    class?: string;
+    judge?: Answers;
+    verdict?: {
+        quality: string;
+        gap?: string;
+    };
+    /** The person record that owns it. */
+    person?: string;
+}
+export interface RunFinding extends Who {
+    id: string;
+    round: number;
+    document: string;
+    text: string;
+    quote?: string;
+    date?: string;
+    kept: boolean;
+    fixes?: string;
+    class?: string;
+    judge?: Answers;
+    checks: ({
+        ok: boolean;
+        why: string;
+        at: string;
+    } & Who)[];
+}
+/** One step of the back and forth: a decision with its why, or a step's end with its note. */
+export interface Moment extends Who {
+    id: string;
+    at: string;
+    round: number;
+    step?: string;
+    type: string;
+    text: string;
+    why?: string;
+    /** The record it is about. */
+    on?: string;
+    ok?: boolean;
+}
+export interface RunView {
+    v: 1;
+    run: string;
+    brief: Brief;
+    queries: RunQuery[];
+    hits: RunHit[];
+    documents: RunDocument[];
+    findings: RunFinding[];
+    timeline: Moment[];
+    /** Spend per source and op. */
+    spend: {
+        source: string;
+        op: string;
+        calls: number;
+        failed: number;
+        usd: number;
+    }[];
+}
+/** One line per run for a list. */
+export interface RunRow {
+    run: string;
+    ask: string;
+    kind: string;
+    parent: string | null;
+    round: number;
+    /** Null once an edge said stop. */
+    next: {
+        round: number;
+        step: string;
+    } | null;
+    note: string | null;
+    started: string;
+    updated: string;
+    hits: number;
+    documents: number;
+    kept: number;
+    usd: number;
+}
+export declare function rowOf(state: RunState): RunRow;
+export declare function viewOf(state: RunState, b: Brief): RunView;
+/** A run's view from its ledger. */
+export declare function runView(deps: Deps, run: string): Promise<RunView>;
+export {};

package/dist/engine/view.js

@@ -0,0 +1,188 @@
+import { brief } from "./agent.js";
+import { ownersOf } from "./people.js";
+import { fold, kept } from "./state.js";
+const who = (r) => ({ from: r.from, by: r.by });
+const some = (v, k) => (v === undefined ? {} : { [k]: v });
+export function rowOf(state) {
+    const s = state.snapshot;
+    return {
+        run: state.run,
+        ask: s?.ask.text ?? "",
+        kind: s?.ask.kind ?? "",
+        parent: s?.parent?.run ?? null,
+        round: state.round,
+        next: state.next,
+        note: state.note,
+        started: state.records[0]?.at ?? "",
+        updated: state.records.at(-1)?.at ?? "",
+        hits: state.hits.length,
+        documents: state.documents.length,
+        kept: state.findings.filter((f) => kept(state, f)).length,
+        usd: state.spends.reduce((a, x) => a + (x.usd ?? 0), 0),
+    };
+}
+/** The record a moment shows, or null for bulk records (hits, pages, the judge, spends). */
+function momentOf(r) {
+    const base = { id: r.id, at: r.at, round: r.round, ...some(r.step, "step"), ...who(r) };
+    switch (r.type) {
+        case "snapshot":
+            return { ...base, type: r.type, text: `plan: ${r.ask.text}`, why: r.sources.join(", ") };
+        case "query":
+            return {
+                ...base,
+                type: r.type,
+                text: r.follow ? `follow ${r.follow.as} of ${r.follow.url}` : r.terms,
+                why: r.why,
+                ...some(r.facet, "on"),
+            };
+        case "call":
+            return { ...base, type: r.type, text: r.verdict, on: r.on, ...some(r.why, "why") };
+        case "check":
+            return {
+                ...base,
+                type: r.type,
+                text: r.ok ? "backed" : "failed",
+                on: r.on,
+                why: r.why,
+                ok: r.ok,
+            };
+        case "edge":
+            return { ...base, type: r.type, text: r.next, why: r.why };
+        case "done":
+            return { ...base, type: r.type, text: r.step, ok: r.ok, ...some(r.note, "why") };
+        case "gap":
+            return { ...base, type: r.type, text: r.note, ...some(r.on, "on") };
+        case "steer":
+            return { ...base, type: r.type, text: r.text };
+        case "class":
+            return { ...base, type: r.type, text: r.class, on: r.on, why: r.why };
+        case "pattern":
+            return { ...base, type: r.type, text: r.text };
+        case "person":
+            return { ...base, type: r.type, text: r.name, why: r.why };
+        case "dead":
+            return { ...base, type: r.type, text: r.facet, why: r.why };
+        case "draft":
+            return { ...base, type: r.type, text: r.for };
+        // A finding written by hand; the extract's bulk ones show in its step's end.
+        case "finding":
+            return r.step ? null : { ...base, type: r.type, text: r.text, on: r.document };
+        default:
+            return null;
+    }
+}
+export function viewOf(state, b) {
+    const calls = new Map();
+    for (const c of state.calls)
+        calls.set(c.on, c);
+    const docOfHit = new Map(state.documents.map((d) => [d.hit, d.id]));
+    const owners = ownersOf(state);
+    const verdicts = new Map(state.verdicts.map((v) => [v.document, v]));
+    const hitQueries = new Map(state.hits.map((h) => [h.id, [...h.queries]]));
+    const again = new Map();
+    for (const f of state.founds) {
+        hitQueries.get(f.hit)?.push(f.query);
+        again.set(f.query, [...(again.get(f.query) ?? []), f.hit]);
+    }
+    const wrote = new Map();
+    for (const h of state.hits) {
+        const q = h.queries[0];
+        if (q)
+            wrote.set(q, [...(wrote.get(q) ?? []), h.id]);
+    }
+    const checks = new Map();
+    for (const c of state.checks)
+        checks.set(c.on, [...(checks.get(c.on) ?? []), { ok: c.ok, why: c.why, at: c.at, ...who(c) }]);
+    const callOf = (id) => {
+        const c = calls.get(id);
+        return c ? { call: { verdict: c.verdict, ...some(c.why, "why"), ...who(c) } } : {};
+    };
+    const spend = new Map();
+    for (const s of state.spends) {
+        const k = `${s.source}\u0000${s.op}`;
+        const row = spend.get(k) ?? { source: s.source, op: s.op, calls: 0, failed: 0, usd: 0 };
+        row.calls++;
+        if (!s.ok)
+            row.failed++;
+        row.usd += s.usd ?? 0;
+        spend.set(k, row);
+    }
+    return {
+        v: 1,
+        run: state.run,
+        brief: b,
+        queries: state.queries.map((q) => ({
+            id: q.id,
+            round: q.round,
+            at: q.at,
+            terms: q.terms,
+            why: q.why,
+            ...some(q.site, "site"),
+            ...some(q.facet, "facet"),
+            ...some(q.tier, "tier"),
+            ...some(q.follow, "follow"),
+            hits: wrote.get(q.id) ?? [],
+            again: again.get(q.id) ?? [],
+            ...who(q),
+        })),
+        hits: state.hits.map((h) => ({
+            id: h.id,
+            round: h.round,
+            url: h.url,
+            ...some(h.title, "title"),
+            ...some(h.channel, "channel"),
+            ...some(h.snippet, "snippet"),
+            ...some(h.date, "date"),
+            ...some(h.length, "length"),
+            sources: h.sources,
+            queries: hitQueries.get(h.id) ?? h.queries,
+            ...callOf(h.id),
+            ...some(state.judged.get(h.id), "judge"),
+            ...some(docOfHit.get(h.id), "document"),
+            ...who(h),
+        })),
+        documents: state.documents.map((d) => {
+            const v = verdicts.get(d.id);
+            return {
+                id: d.id,
+                hit: d.hit,
+                url: d.url,
+                ...some(d.title, "title"),
+                ...some(d.channel ?? state.hits.find((h) => h.id === d.hit)?.channel, "channel"),
+                media: d.media,
+                ...some(d.date, "date"),
+                ...some(d.length, "length"),
+                chars: d.text.length,
+                ...some(state.classOf.get(d.id), "class"),
+                ...some(state.judged.get(d.id), "judge"),
+                ...(v ? { verdict: { quality: v.quality, ...some(v.gap, "gap") } } : {}),
+                ...some(owners.get(d.id)?.id, "person"),
+                ...who(d),
+            };
+        }),
+        findings: state.findings.map((f) => ({
+            id: f.id,
+            round: f.round,
+            document: f.document,
+            text: f.text,
+            ...some(f.proof.quote ?? undefined, "quote"),
+            ...some(f.date, "date"),
+            kept: kept(state, f),
+            ...some(f.fixes, "fixes"),
+            ...some(state.classOf.get(f.id), "class"),
+            ...some(state.judged.get(f.id), "judge"),
+            checks: checks.get(f.id) ?? [],
+            ...who(f),
+        })),
+        timeline: state.records.flatMap((r) => momentOf(r) ?? []),
+        spend: [...spend.values()].sort((a, b) => b.usd - a.usd || b.calls - a.calls),
+    };
+}
+/** A run's view from its ledger. */
+export async function runView(deps, run) {
+    const records = await deps.ledger.trace(run);
+    if (!records.length)
+        throw new Error(`run ${run}: no records`);
+    return viewOf(fold(run, records), await brief(deps, run));
+}
+//# sourceMappingURL=view.js.map

package/dist/engine/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/engine/view.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * birdwatch: research from the open web, driven by an agent one step per command, every record
+ * in a ledger. Five doors: `./engine` (the ask and plan files, the source port, registry, run
+ * state, the steps and the agent commands), `./sources` (SearXNG, Exa, Google, arXiv, yt-dlp, the
+ * site readers, the fetcher, the ladder, a paste, the ledger), `./ledger` (the records, a folder of
+ * JSON lines per run per writer, yield rows), `./document` (`Document`, `Finding`, `Proof`, readers
+ * by media, the claim extractor) and this root (the engine's CLI commands, `addEngineCommands`,
+ * for a host that mounts them on its own program). Reading the web and files is
+ * `@wrenautomation/read`'s; every model call goes through `@wrenautomation/models`. Design: wren's
+ * `designs/2026-10-26-research-engine.md`.
+ */
+export * from "./app/index.js";
+export * from "./engine/index.js";
+export * from "./ledger/index.js";
+export * from "./sources/index.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * birdwatch: research from the open web, driven by an agent one step per command, every record
+ * in a ledger. Five doors: `./engine` (the ask and plan files, the source port, registry, run
+ * state, the steps and the agent commands), `./sources` (SearXNG, Exa, Google, arXiv, yt-dlp, the
+ * site readers, the fetcher, the ladder, a paste, the ledger), `./ledger` (the records, a folder of
+ * JSON lines per run per writer, yield rows), `./document` (`Document`, `Finding`, `Proof`, readers
+ * by media, the claim extractor) and this root (the engine's CLI commands, `addEngineCommands`,
+ * for a host that mounts them on its own program). Reading the web and files is
+ * `@wrenautomation/read`'s; every model call goes through `@wrenautomation/models`. Design: wren's
+ * `designs/2026-10-26-research-engine.md`.
+ */
+export * from "./app/index.js";
+export * from "./engine/index.js";
+export * from "./ledger/index.js";
+export * from "./sources/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/ledger/files.d.ts

@@ -0,0 +1,39 @@
+import { type AskKind, PlanFile } from "../engine/types.js";
+import { type Filter, type Ledger, type YieldFilter } from "./ledger.js";
+import { LedgerRecord } from "./records.js";
+/** A line the backend could not read: a partial last line from a killed writer, or a record it does not know. */
+export interface Problem {
+    file: string;
+    line: number;
+    why: string;
+}
+export declare class FilesLedger implements Ledger {
+    readonly root: string;
+    readonly writer: string;
+    /** Lines skipped on read, since this ledger was made. Report them; never throw on them. */
+    readonly problems: Problem[];
+    /** `writer` names this session's file: a person's name, a session id. `by` on a record stays data. */
+    constructor(root: string, writer: string);
+    runDir(run: string): string;
+    file(run: string): string;
+    append(record: LedgerRecord): Promise<void>;
+    /** The runs on disk, by name. */
+    runs(): Promise<string[]>;
+    private readFile;
+    trace(run: string): Promise<LedgerRecord[]>;
+    scan(filter?: Filter): Promise<LedgerRecord[]>;
+    yield(filter?: YieldFilter): Promise<{
+        hits: number;
+        reads: number;
+        proposed: number;
+        kept: number;
+        by?: string | undefined;
+        source?: string | undefined;
+        channel?: string | undefined;
+        kind?: "video" | "channel" | "web" | "person" | "site" | undefined;
+    }[]>;
+    planPath(kind: AskKind): string;
+    /** The tuned plan file for a kind, or null when the ledger has none (the stock plan file applies). */
+    readPlan(kind: AskKind): Promise<PlanFile | null>;
+    writePlan(planFile: PlanFile): Promise<string>;
+}

package/dist/ledger/files.js

@@ -0,0 +1,113 @@
+/**
+ * The files backend: a folder in any repo. `runs/<run>/<writer>.jsonl`, one file per run per
+ * writer, so two sessions on one run never touch the same file and git merges clean. A trace is
+ * the union of a run's files in time order. Plan files sit beside the runs,
+ * `plans/<kind>.json`. DuckDB reads the JSONL as it is.
+ */
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { PlanFile } from "../engine/types.js";
+import { matches, yieldRows } from "./ledger.js";
+import { byTime, LedgerRecord } from "./records.js";
+const safe = (name) => name.replace(/[^A-Za-z0-9._-]+/g, "-");
+const exists = async (dir) => {
+    try {
+        return await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+};
+export class FilesLedger {
+    root;
+    writer;
+    /** Lines skipped on read, since this ledger was made. Report them; never throw on them. */
+    problems = [];
+    /** `writer` names this session's file: a person's name, a session id. `by` on a record stays data. */
+    constructor(root, writer) {
+        this.root = root;
+        this.writer = writer;
+    }
+    runDir(run) {
+        return join(this.root, "runs", safe(run));
+    }
+    file(run) {
+        return join(this.runDir(run), `${safe(this.writer)}.jsonl`);
+    }
+    async append(record) {
+        await mkdir(this.runDir(record.run), { recursive: true });
+        await appendFile(this.file(record.run), `${JSON.stringify(record)}\n`, "utf8");
+    }
+    /** The runs on disk, by name. */
+    async runs() {
+        return (await exists(join(this.root, "runs"))).sort();
+    }
+    async readFile(path) {
+        const out = [];
+        const text = await readFile(path, "utf8");
+        const lines = text.split("\n");
+        const complete = text.endsWith("\n") ? lines.length - 1 : lines.length - 1;
+        lines.forEach((line, i) => {
+            if (!line.trim())
+                return;
+            if (i >= complete) {
+                this.problems.push({ file: path, line: i + 1, why: "partial last line" });
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                this.problems.push({ file: path, line: i + 1, why: "not JSON" });
+                return;
+            }
+            const r = LedgerRecord.safeParse(parsed);
+            if (r.success)
+                out.push(r.data);
+            else
+                this.problems.push({ file: path, line: i + 1, why: r.error.issues[0]?.message ?? "bad" });
+        });
+        return out;
+    }
+    async trace(run) {
+        const dir = this.runDir(run);
+        const files = (await exists(dir)).filter((f) => f.endsWith(".jsonl")).sort();
+        const parts = await Promise.all(files.map((f) => this.readFile(join(dir, f))));
+        return parts.flat().sort(byTime);
+    }
+    async scan(filter = {}) {
+        const runs = filter.run !== undefined ? [filter.run] : await this.runs();
+        const parts = await Promise.all(runs.map((r) => this.trace(r)));
+        return parts
+            .flat()
+            .filter((r) => matches(r, filter))
+            .sort(byTime);
+    }
+    async yield(filter = {}) {
+        return yieldRows(await this.scan(), filter);
+    }
+    planPath(kind) {
+        return join(this.root, "plans", `${kind}.json`);
+    }
+    /** The tuned plan file for a kind, or null when the ledger has none (the stock plan file applies). */
+    async readPlan(kind) {
+        try {
+            return PlanFile.parse(JSON.parse(await readFile(this.planPath(kind), "utf8")));
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    async writePlan(planFile) {
+        const path = this.planPath(planFile.kind);
+        await mkdir(join(this.root, "plans"), { recursive: true });
+        await writeFile(path, `${JSON.stringify(planFile, null, 2)}\n`, "utf8");
+        return path;
+    }
+}
+//# sourceMappingURL=files.js.map

package/dist/ledger/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/ledger/files.ts"],"names":[],"mappings":"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"}

package/dist/ledger/ids.d.ts

@@ -0,0 +1,4 @@
+export type Ids = () => string;
+export declare const ulids: () => Ids;
+/** `a-000001`, `a-000002`, ...: readable ids for tests. */
+export declare const countingIds: (prefix?: string) => Ids;

package/dist/ledger/ids.js

@@ -0,0 +1,9 @@
+/** Record ids: ULIDs, time-ordered and unique per writer. A test passes a counter instead. */
+import { monotonicFactory } from "ulid";
+export const ulids = () => monotonicFactory();
+/** `a-000001`, `a-000002`, ...: readable ids for tests. */
+export const countingIds = (prefix = "r") => {
+    let n = 0;
+    return () => `${prefix}-${String(++n).padStart(6, "0")}`;
+};
+//# sourceMappingURL=ids.js.map

package/dist/ledger/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/ledger/ids.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAIxC,MAAM,CAAC,MAAM,KAAK,GAAG,GAAQ,EAAE,CAAC,gBAAgB,EAAE,CAAC;AAEnD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,GAAG,GAAG,EAAO,EAAE;IAC/C,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,GAAG,EAAE,CAAC,GAAG,MAAM,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AAC3D,CAAC,CAAC"}

package/dist/ledger/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The ledger: the research engine's append-only store. The contract (`Ledger`: append, trace,
+ * scan, yield), the record shapes (one envelope, then the plan's and the document's fields), the files
+ * backend (JSONL per run per writer, plan files beside it) and a memory backend for tests.
+ * wren's Postgres answers the same four calls.
+ */
+export * from "./files.js";
+export * from "./ids.js";
+export * from "./ledger.js";
+export * from "./memory.js";
+export * from "./records.js";

package/dist/ledger/index.js

@@ -0,0 +1,12 @@
+/**
+ * The ledger: the research engine's append-only store. The contract (`Ledger`: append, trace,
+ * scan, yield), the record shapes (one envelope, then the plan's and the document's fields), the files
+ * backend (JSONL per run per writer, plan files beside it) and a memory backend for tests.
+ * wren's Postgres answers the same four calls.
+ */
+export * from "./files.js";
+export * from "./ids.js";
+export * from "./ledger.js";
+export * from "./memory.js";
+export * from "./records.js";
+//# sourceMappingURL=index.js.map

package/dist/ledger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ledger/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/ledger/ledger.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The ledger contract: four calls every backend answers. `append` one record; `trace` one run's
+ * records in time order; `scan` records across runs by a filter; `yield` what sources, proposers,
+ * channels and ask kinds yielded, as the yield rows. The yield is a fold over records, shared here
+ * so the files backend and a database compute the same rows (a database may do it in SQL).
+ */
+import type { AskKind, PlanFile, YieldRow } from "../engine/types.js";
+import { type From, type LedgerRecord, type RecordOf, type RecordType, type Step } from "./records.js";
+export interface Filter {
+    run?: string;
+    type?: RecordType | readonly RecordType[];
+    from?: From;
+    by?: string;
+    step?: Step;
+    round?: number;
+    /** ISO time: records at or after it. */
+    since?: string;
+}
+export interface YieldFilter {
+    source?: string;
+    by?: string;
+    channel?: string;
+    kind?: YieldRow["kind"];
+}
+export interface Ledger {
+    append(record: LedgerRecord): Promise<void>;
+    /** One run's records, by time then id. */
+    trace(run: string): Promise<LedgerRecord[]>;
+    /** Records across runs, by time then id. */
+    scan(filter?: Filter): Promise<LedgerRecord[]>;
+    yield(filter?: YieldFilter): Promise<YieldRow[]>;
+    /** The tuned plan file of a kind, when the ledger keeps plan files (the files backend does). */
+    readPlan?(kind: AskKind): Promise<PlanFile | null>;
+    writePlan?(planFile: PlanFile): Promise<string>;
+}
+export declare function matches(r: LedgerRecord, f: Filter): boolean;
+export declare const ofType: <T extends RecordType>(records: readonly LedgerRecord[], type: T) => RecordOf<T>[];
+/** The latest call on each record: keep or drop. Records must be in time order. */
+export declare function latestCalls(records: readonly LedgerRecord[]): Map<string, "keep" | "drop">;
+/**
+ * Rows per source, per proposer (`by` of the queries), per channel and per ask kind: hits seen,
+ * documents read, findings proposed, findings kept by the latest call. The chain is
+ * query → hit → document → finding, so a finding counts for every source that returned its hit.
+ * A finding is kept unless its latest call is a drop: the gate kept it; a review or a person drops.
+ */
+export declare function yieldRows(records: readonly LedgerRecord[], filter?: YieldFilter): YieldRow[];