@wrenautomation/birdwatch 0.0.0-stage → 0.29.0

package/dist/engine/ports.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The ports the runner is given, as one plain `deps` object. A source is one file that answers
+ * `search` (hits for a query) or `open` (a hit read whole) or both; the registry holds them by
+ * name and the plan's allow-list picks per run. The model is the planner's, the extractor
+ * `./document`'s, the ledger `./ledger`'s. Nothing here reaches the network: the adapters in `src/sources` do.
+ */
+import type { Model } from "@wrenautomation/models";
+import type { Judge } from "@wrenautomation/models/judge";
+import type { Document, Extractor } from "../document/index.js";
+import type { Ids } from "../ledger/ids.js";
+import type { Ledger } from "../ledger/ledger.js";
+import type { CostKind, FollowAs, From, HitRecord, QueryRecord } from "../ledger/records.js";
+import type { Criterion, HitViewIn, PlanFile, Proposal } from "../plan/index.js";
+export interface Source {
+    name: string;
+    kind: "search" | "open" | "both";
+    cost: CostKind;
+    /** Who the records it writes are from. A person pasting URLs is `human`; the default is `tool`. */
+    from?: From;
+    /** Who its records are by: the person behind a paste. The default is the source's name. */
+    by?: string;
+    /**
+     * Whether its search keeps to that site (a query's `site`). A site-scoped query skips a
+     * searcher that would answer from everywhere. Absent: it keeps to any site.
+     */
+    keeps?(site: string): boolean;
+    /** Hits as the source shows them for free. Throw on failure: the runner writes the spend. */
+    search?(query: QueryRecord): Promise<HitViewIn[]>;
+    /** Whether it lists that page's own posts (`posts`) or pages like it (`similar`). */
+    follows?(as: FollowAs, url: string): boolean;
+    /** The follow's hits, newest or closest first, `n` at most. Throw on failure, like search. */
+    follow?(as: FollowAs, url: string, n: number): Promise<HitViewIn[]>;
+    /**
+     * Whether this source opens that URL at all (a YouTube page, an http(s) page). The read step
+     * asks before a call, so a source that was never going to open it writes no spend. Absent: it
+     * opens everything.
+     */
+    opens?(url: string): boolean;
+    /**
+     * Opens only its own site's URLs, better than any general opener (a thread as data, not a
+     * fetched wall): it gets its turn before the rest, whatever the allow-list's order.
+     */
+    first?: true;
+    /**
+     * The hit read whole. Throw with the reason when it was fetched and nothing usable came back
+     * (a 403, a block, no reader for the media): the runner writes the spend `ok: false` with the
+     * reason and the next opener gets its turn.
+     */
+    open?(hit: HitRecord): Promise<Document>;
+}
+export type Sources = Map<string, Source>;
+export declare const registry: (...sources: Source[]) => Sources;
+/** The allow-list's sources, in its order. A name no source answers to fails the run at its start. */
+export declare function pick(sources: Sources, names: readonly string[]): Source[];
+export interface Deps {
+    sources: Sources;
+    ledger: Ledger;
+    /** null: no model. The plan is the proposals given; every hit is read; nothing is extracted. */
+    model: Model | null;
+    /** The steps that decide what comes next (plan, triage, review) take it; absent: `model`. */
+    decider?: Model | null;
+    extractor: Extractor;
+    /** Cheap typed answers on every hit, page and finding: a hint and a router. Absent or null: none. */
+    judge?: Judge | null;
+    clock: () => Date;
+    ids: Ids;
+    /** `by` on the records the runner itself writes. */
+    runner: string;
+    /** The pause between tries of a call that failed with a Transient; `setTimeout` by default. A test passes a stub. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface RunOptions {
+    /** Absent on a resume: the first snapshot has it. */
+    ask?: {
+        text: string;
+        kind: PlanFile["kind"];
+        known?: string[];
+        /** What the ask takes as given; a known line with no source joins them. */
+        premises?: string[];
+        /** The person's tests of a good source: the judge asks each on every hit and page. */
+        criteria?: Criterion[];
+        /** What the person says at the start; `steer` records add to it between rounds. */
+        steer?: string[];
+        site?: string;
+    };
+    /** The ledger's tuned plan file for the ask's kind; the stock one when absent. */
+    planFile?: PlanFile;
+    /** Queries from people or other models, merged with the model's in round 1. */
+    proposals?: readonly Proposal[];
+    /** Narrows the plan file's sources for this run. */
+    sources?: readonly string[];
+    /** Openers let in only to open and follow, never to search. Absent: the last snapshot's. */
+    opens?: readonly string[];
+    /** A new run's parent, and why this child: `--parent`. */
+    parent?: {
+        run: string;
+        why: string;
+    };
+    /** An earlier run to continue. */
+    resume?: string;
+    /** A run id for a new run; `deps.ids()` when absent. */
+    run?: string;
+    /** Called after each step, for a progress line. */
+    onStep?: (event: StepEvent) => void;
+    /** Steps to run before returning, whatever the pointer says: 64 by default. A loop that advances a run a little per pass passes a few. */
+    steps?: number;
+    /** Stop after each round's review when it says `again`: the person steers, then resumes. */
+    pause?: boolean;
+}
+export interface StepEvent {
+    run: string;
+    round: number;
+    step: string;
+    ok: boolean;
+    note?: string;
+    ms: number;
+}
+/**
+ * The searchers a query goes to: all of them, or for a site-scoped query those that keep to it.
+ * A follow goes to the sources that follow its URL that way.
+ */
+export declare const searchersFor: (sources: readonly Source[], q: Pick<QueryRecord, "site" | "follow">) => Source[];
+/** How many hits a follow lists. */
+export declare const FOLLOW_N = 30;

package/dist/engine/ports.js

@@ -0,0 +1,28 @@
+/**
+ * The ports the runner is given, as one plain `deps` object. A source is one file that answers
+ * `search` (hits for a query) or `open` (a hit read whole) or both; the registry holds them by
+ * name and the plan's allow-list picks per run. The model is the planner's, the extractor
+ * `./document`'s, the ledger `./ledger`'s. Nothing here reaches the network: the adapters in `src/sources` do.
+ */
+export const registry = (...sources) => new Map(sources.map((s) => [s.name, s]));
+/** The allow-list's sources, in its order. A name no source answers to fails the run at its start. */
+export function pick(sources, names) {
+    const missing = names.filter((n) => !sources.has(n));
+    if (missing.length)
+        throw new Error(`no source named ${missing.join(", ")}`);
+    return names.map((n) => sources.get(n));
+}
+/**
+ * The searchers a query goes to: all of them, or for a site-scoped query those that keep to it.
+ * A follow goes to the sources that follow its URL that way.
+ */
+export const searchersFor = (sources, q) => {
+    const f = q.follow;
+    if (f)
+        return sources.filter((s) => s.follow && s.follows?.(f.as, f.url));
+    const searchers = sources.filter((s) => s.search);
+    return q.site ? searchers.filter((s) => s.keeps?.(q.site) ?? true) : searchers;
+};
+/** How many hits a follow lists. */
+export const FOLLOW_N = 30;
+//# sourceMappingURL=ports.js.map

package/dist/engine/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/engine/ports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkDH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAG,OAAiB,EAAW,EAAE,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpG,sGAAsG;AACtG,MAAM,UAAU,IAAI,CAAC,OAAgB,EAAE,KAAwB;IAC7D,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7E,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAW,CAAC,CAAC;AACpD,CAAC;AAiED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,OAA0B,EAC1B,CAAuC,EAC7B,EAAE;IACZ,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACnB,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAc,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3F,CAAC,CAAC;AAEF,oCAAoC;AACpC,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC"}

package/dist/engine/recall.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What earlier runs proved, found again: the findings of every run in the ledger, ranked by
+ * MiniSearch (BM25 over the finding's text and quote, prefix and a little fuzz). Each carries its
+ * quote, its source's date and its run, so a later run sees how old a fact is and where it came
+ * from. A finding a call or a failed check dropped is left out. Read only: the agent decides what
+ * still holds, puts it in `known` or reads the source again (WA-934, option A).
+ */
+import { type Ledger } from "../ledger/ledger.js";
+import type { AskKind } from "../plan/index.js";
+export interface Recalled {
+    finding: string;
+    run: string;
+    /** The ask of the run that found it. */
+    ask: string;
+    text: string;
+    quote: string;
+    url: string;
+    /** The source's own date, when its document had one. */
+    date: string | null;
+    /** When the run found it. */
+    found: string;
+    /** Who wrote it: the agent's id for a finding it read and added, a model's id for `extract`. */
+    by: string;
+    /** `kept`: a call kept it; `open`: no call on it yet. Ranking ignores it. */
+    state: "kept" | "open";
+    /** Other runs that found the same quote on the same page, newest first. */
+    alsoIn: string[];
+    score: number;
+}
+export interface RecallOptions {
+    /** At most this many; 20 by default. */
+    n?: number;
+    /** Leave this run out: the one asking. */
+    not?: string;
+    /** Only runs of this ask kind. */
+    kind?: AskKind;
+    /** Only these runs: a child's siblings and parent. */
+    runs?: readonly string[];
+}
+/** Several ledgers read as one (a folder per day): their records merged in time order. */
+export declare const joined: (ledgers: readonly Pick<Ledger, "scan">[]) => Pick<Ledger, "scan">;
+export declare function recall(ledger: Pick<Ledger, "scan">, terms: string, o?: RecallOptions): Promise<Recalled[]>;

package/dist/engine/recall.js

@@ -0,0 +1,71 @@
+/**
+ * What earlier runs proved, found again: the findings of every run in the ledger, ranked by
+ * MiniSearch (BM25 over the finding's text and quote, prefix and a little fuzz). Each carries its
+ * quote, its source's date and its run, so a later run sees how old a fact is and where it came
+ * from. A finding a call or a failed check dropped is left out. Read only: the agent decides what
+ * still holds, puts it in `known` or reads the source again (WA-934, option A).
+ */
+import MiniSearch from "minisearch";
+import { latestCalls, ofType } from "../ledger/ledger.js";
+import { byTime } from "../ledger/records.js";
+/** Several ledgers read as one (a folder per day): their records merged in time order. */
+export const joined = (ledgers) => ({
+    scan: async (f) => (await Promise.all(ledgers.map((l) => l.scan(f)))).flat().sort(byTime),
+});
+const fold = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+export async function recall(ledger, terms, o = {}) {
+    if (!terms.trim())
+        throw new Error("recall needs terms");
+    const records = await ledger.scan({ type: ["snapshot", "finding", "call"] });
+    const asks = new Map();
+    for (const s of ofType(records, "snapshot"))
+        if (!asks.has(s.run))
+            asks.set(s.run, { text: s.ask.text, kind: s.ask.kind });
+    const calls = latestCalls(records);
+    // Newest first, so the first of a quote seen twice is the latest proof of it.
+    const findings = ofType(records, "finding")
+        .filter((f) => f.run !== o.not && calls.get(f.id) !== "drop")
+        .filter((f) => !o.kind || asks.get(f.run)?.kind === o.kind)
+        .filter((f) => !o.runs || o.runs.includes(f.run))
+        .reverse();
+    const byKey = new Map();
+    for (const f of findings) {
+        const quote = f.proof.quote ?? "";
+        const key = `${f.proof.url}\u0000${fold(quote)}`;
+        const seen = byKey.get(key);
+        if (seen) {
+            if (f.run !== seen.run && !seen.alsoIn.includes(f.run))
+                seen.alsoIn.push(f.run);
+            continue;
+        }
+        byKey.set(key, {
+            finding: f.id,
+            run: f.run,
+            ask: asks.get(f.run)?.text ?? "",
+            text: f.text,
+            quote,
+            url: f.proof.url,
+            date: f.date ?? null,
+            found: f.at,
+            by: f.by,
+            state: calls.get(f.id) === "keep" ? "kept" : "open",
+            alsoIn: [],
+            score: 0,
+        });
+    }
+    const index = new MiniSearch({
+        idField: "finding",
+        fields: ["text", "quote"],
+        searchOptions: { boost: { text: 2 }, prefix: true, fuzzy: 0.2 },
+    });
+    index.addAll([...byKey.values()]);
+    const of = new Map([...byKey.values()].map((r) => [r.finding, r]));
+    return index
+        .search(terms)
+        .slice(0, o.n ?? 20)
+        .flatMap((hit) => {
+        const r = of.get(hit.id);
+        return r ? [{ ...r, score: Math.round(hit.score * 100) / 100 }] : [];
+    });
+}
+//# sourceMappingURL=recall.js.map

package/dist/engine/recall.js.map

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

package/dist/engine/runner.d.ts

@@ -0,0 +1,30 @@
+import { type Envelope, type From, type Step } from "../ledger/records.js";
+import type { Deps, RunOptions } from "./ports.js";
+import { type RunState } from "./state.js";
+import { type StepContext } from "./steps.js";
+export interface RunResult {
+    run: string;
+    rounds: number;
+    /** Why the run stopped: the last edge's why, or the step that gave up. */
+    note: string | null;
+    /** The run stopped on an edge, not on a step that gave up. */
+    finished: boolean;
+    /** The run stopped after a review that said `again`, on `pause`: `resume` goes on. */
+    paused: boolean;
+    /**
+     * The review said `again` into a round past the budget: the runner parked, and this says so.
+     * The budget is a guard rail: `resume` goes one more round; the agent's `plan --run` opens it.
+     */
+    parked: string | null;
+    state: RunState;
+}
+/** Tries per call over a Transient. */
+export declare const TRIES = 3;
+/** The default step bound: three full rounds and some backs. */
+export declare const DEFAULT_STEPS = 64;
+/** The pause before the next try: to `retryAfter` (a minute at most), else a second per try so far. */
+export declare function waitMs(attempt: number, retryAfter: string | undefined, now: () => Date): number;
+export declare function run(deps: Deps, options?: RunOptions): Promise<RunResult>;
+/** The step context: `write` fills the envelope, `invoke` and `modelOn` write every spend. The agent commands build one per call. */
+export declare function context(deps: Deps, options: RunOptions, run: string, round: number, step: Step): StepContext;
+export type { Envelope, From };

package/dist/engine/runner.js

@@ -0,0 +1,209 @@
+/**
+ * The interpreter: fold the trace, take the pointer's step from the table, write `done`, fold
+ * again. `--resume` is the same loop on an old run: the fold says where it stopped. Every model
+ * ask and source call writes a `spend` with what it cost and whether it worked. A call that
+ * fails with a `Transient` is tried again with a pause, three tries in all, every attempt on
+ * record; a step that still cannot go on throws it past the runner with no `done`, so a resume
+ * runs the step again once the cause has passed. A model answer the output cap cut (models'
+ * `Cut`) is a spend that worked, with its tokens: the extractor goes on from it. `pause` stops
+ * the loop after a review that says `again`, so the person can steer before the next round.
+ */
+import { isCut, isTransient, modelOf, promptText, } from "@wrenautomation/models";
+import { judgeFailure } from "@wrenautomation/models/judge";
+import { LedgerRecord } from "../ledger/records.js";
+import { fold } from "./state.js";
+import { STEP_TABLE } from "./steps.js";
+/** Tries per call over a Transient. */
+export const TRIES = 3;
+/** The longest pause before another try, whatever `retry-after` said. */
+const MAX_WAIT_MS = 60_000;
+/** The default step bound: three full rounds and some backs. */
+export const DEFAULT_STEPS = 64;
+/** The pause before the next try: to `retryAfter` (a minute at most), else a second per try so far. */
+export function waitMs(attempt, retryAfter, now) {
+    if (retryAfter) {
+        const until = Date.parse(retryAfter) - now().getTime();
+        if (!Number.isNaN(until))
+            return Math.max(0, Math.min(until, MAX_WAIT_MS));
+    }
+    return 1000 * attempt;
+}
+const message = (err) => (err instanceof Error ? err.message : String(err));
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function run(deps, options = {}) {
+    const id = options.resume ?? options.run ?? deps.ids();
+    if (!options.resume && !options.ask)
+        throw new Error("a new run needs an ask");
+    const steps = options.steps ?? DEFAULT_STEPS;
+    let state = fold(id, await deps.ledger.trace(id));
+    if (options.resume && !state.records.length)
+        throw new Error(`run ${id}: no records`);
+    let paused = false;
+    let parked = null;
+    for (let n = 0; n < steps && state.next; n++) {
+        const { round, step } = state.next;
+        const ctx = context(deps, options, id, round, step);
+        const t0 = performance.now();
+        let result;
+        try {
+            result = await STEP_TABLE[step](ctx, state);
+        }
+        catch (err) {
+            if (isTransient(err))
+                throw err;
+            result = { ok: false, note: message(err) };
+        }
+        await ctx.write({ type: "done", step, ok: result.ok, ...(result.note ? { note: result.note } : {}) }, { from: "tool", by: deps.runner });
+        const ms = Math.round(performance.now() - t0);
+        options.onStep?.({
+            run: id,
+            round,
+            step,
+            ok: result.ok,
+            ...(result.note ? { note: result.note } : {}),
+            ms,
+        });
+        state = fold(id, await deps.ledger.trace(id));
+        if (!result.ok)
+            break;
+        if (step !== "review" || state.next?.step !== "plan")
+            continue;
+        const budget = state.snapshot?.budget;
+        if (budget && state.next.round > budget.rounds) {
+            parked = `round ${state.next.round} is past the budget of ${budget.rounds}: parked. The edge says: ${state.note}`;
+            break;
+        }
+        if (options.pause) {
+            paused = true;
+            break;
+        }
+    }
+    return {
+        run: id,
+        rounds: state.round,
+        note: state.note,
+        finished: !state.next && state.edges.at(-1)?.next === "stop",
+        paused,
+        parked,
+        state,
+    };
+}
+const tokens = (u) => ({
+    ...(u?.usd !== undefined ? { usd: u.usd } : {}),
+    ...(u && (u.input !== undefined || u.output !== undefined)
+        ? {
+            tokens: {
+                ...(u.input !== undefined ? { input: u.input } : {}),
+                ...(u.output !== undefined ? { output: u.output } : {}),
+            },
+        }
+        : {}),
+});
+/** The steps that decide what comes next: the decider's. The bulk (extract, check) is the model's. */
+const DECIDES = new Set(["plan", "triage", "review"]);
+/** The step context: `write` fills the envelope, `invoke` and `modelOn` write every spend. The agent commands build one per call. */
+export function context(deps, options, run, round, step) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const write = async (record, who) => {
+        const id = deps.ids();
+        const full = LedgerRecord.parse({
+            ...record,
+            id,
+            run,
+            round,
+            step,
+            at: deps.clock().toISOString(),
+            from: who.from,
+            by: who.by,
+        });
+        await deps.ledger.append(full);
+        return id;
+    };
+    const spend = (source, op, about, on, t0, outcome) => write({
+        type: "spend",
+        source: source.name,
+        op,
+        about: about.slice(0, 200),
+        ...(on ? { on } : {}),
+        cost: source.cost,
+        ms: Math.round(performance.now() - t0),
+        ...outcome,
+    }, { from: "tool", by: deps.runner });
+    /** One attempt, its spend written either way. */
+    const once = async (source, op, about, on, call, usageOf) => {
+        const t0 = performance.now();
+        try {
+            const out = await call();
+            await spend(source, op, about, on, t0, { ok: true, ...tokens(usageOf?.(out)) });
+            return out;
+        }
+        catch (err) {
+            if (isCut(err))
+                await spend(source, op, about, on, t0, { ok: true, ...tokens(err.usage) });
+            else
+                await spend(source, op, about, on, t0, {
+                    ok: false,
+                    error: message(err),
+                    ...(isTransient(err) && err.retryAfter ? { retryAfter: err.retryAfter } : {}),
+                });
+            throw err;
+        }
+    };
+    /** The call again after a Transient, with a pause, TRIES in all. */
+    const tried = async (call) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await call();
+            }
+            catch (err) {
+                if (!isTransient(err) || attempt >= TRIES)
+                    throw err;
+                await sleep(waitMs(attempt, err.retryAfter, deps.clock));
+            }
+        }
+    };
+    const invoke = async (source, op, about, on, call) => {
+        try {
+            return await tried(() => once(source, op, about, on, call));
+        }
+        catch (err) {
+            if (isTransient(err))
+                throw err;
+            return null;
+        }
+    };
+    // Every call writes a spend, a repair's too: the wrap is on `complete`, and `ask` is built over it.
+    const modelOn = (on) => {
+        const m = deps.model && ((DECIDES.has(step) && deps.decider) || deps.model);
+        if (!m)
+            return null;
+        return modelOf({
+            id: m.id,
+            provider: m.provider,
+            takes: m.takes,
+            complete: (req) => {
+                const text = promptText(req.prompt) ?? "";
+                const about = text.split("\n").find((l) => l.trim()) ?? "";
+                return tried(() => once({ name: m.id, cost: "metered" }, "ask", about, on, () => m.complete(req), (r) => r.usage));
+            },
+        });
+    };
+    const judge = async (on, about, state, questions) => {
+        const j = deps.judge;
+        if (!j)
+            return { failure: "off" };
+        const t0 = performance.now();
+        const spender = { name: j.id, cost: "metered" };
+        try {
+            const r = await j.judge(state, questions);
+            await spend(spender, "ask", about, on, t0, { ok: true, ...tokens(r.usage) });
+            return r;
+        }
+        catch (err) {
+            await spend(spender, "ask", about, on, t0, { ok: false, error: message(err) });
+            return { failure: judgeFailure(err) };
+        }
+    };
+    return { deps, options, model: modelOn(), modelOn, run, round, step, write, invoke, judge };
+}
+//# sourceMappingURL=runner.js.map

package/dist/engine/runner.js.map

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

package/dist/engine/state.d.ts

@@ -0,0 +1,99 @@
+import { type CallRecord, type CheckRecord, type ClassRecord, type DeadRecord, type DocumentRecord, type DraftRecord, type EdgeRecord, type FindingRecord, type FoundRecord, type GapRecord, type HitRecord, type JudgeRecord, type LedgerRecord, type PatternRecord, type PersonRecord, type QueryRecord, type SnapshotRecord, type SourceClass, type SpendRecord, type SteerRecord, type Step, type VerdictRecord } from "../ledger/records.js";
+import { Plan } from "../plan/index.js";
+export interface Pointer {
+    round: number;
+    step: Step;
+}
+export interface RunState {
+    run: string;
+    records: LedgerRecord[];
+    /** The latest snapshot: the ask and the allow-list. Absent before round 1's plan. */
+    snapshot: SnapshotRecord | null;
+    /** The round the pointer is in. */
+    round: number;
+    /** Where to go next; null when the run stopped. */
+    next: Pointer | null;
+    /** Why the run stopped or the last step gave up. */
+    note: string | null;
+    queries: QueryRecord[];
+    hits: HitRecord[];
+    documents: DocumentRecord[];
+    findings: FindingRecord[];
+    /** The extractor's word on each document it handled. */
+    verdicts: VerdictRecord[];
+    calls: CallRecord[];
+    spends: SpendRecord[];
+    edges: EdgeRecord[];
+    /** What the person said along the way, oldest first. */
+    steers: SteerRecord[];
+    /** What a step or a person said a round lacks. */
+    gaps: GapRecord[];
+    /** The sample check's word on each finding it checked. */
+    checks: CheckRecord[];
+    /** What the agent says several findings say together. */
+    patterns: PatternRecord[];
+    drafts: DraftRecord[];
+    classes: ClassRecord[];
+    /** Facets the agent gave up on, for the rest of the run. */
+    dead: DeadRecord[];
+    /** People the agent named across platforms, in time order. */
+    people: PersonRecord[];
+    /** The latest class on each document and finding. */
+    classOf: Map<string, SourceClass>;
+    /** The judge's latest answers on each hit, document and finding. */
+    judged: Map<string, JudgeRecord["answers"]>;
+    judges: JudgeRecord[];
+    /** A known hit found again by another query. */
+    founds: FoundRecord[];
+    /** The hit record for each canonical URL: a hit seen again, in any round, is a `found`, not a new record. */
+    hitByKey: Map<string, string>;
+    /** The latest call on each hit and finding. */
+    called: Map<string, "keep" | "drop">;
+}
+/** Records must be in time order. */
+export declare function fold(run: string, records: readonly LedgerRecord[]): RunState;
+/** The plan of a round as the planner made it, rebuilt from its snapshot and queries. */
+export declare function planOf(state: RunState, round: number): Plan;
+/** A finding stays kept unless its latest call is a drop. */
+export declare const kept: (state: RunState, f: FindingRecord) => boolean;
+/** What the run has found so far: the kept findings' sentences with their URLs, oldest first. */
+export declare const found: (state: RunState, round?: number) => string[];
+/**
+ * The round a person's gap or back edge is about. Between rounds (a pause, a stop) the pointer
+ * is one ahead of the last review, so it is the round that review closed; mid-round, the current one.
+ */
+export declare const personRound: (state: RunState) => number;
+/** The queries that found a hit: the one that wrote it, then every one it came back for. */
+export declare const queriesOf: (state: RunState) => Map<string, Set<string>>;
+/** The hits of a round, the ones no call has named yet. */
+export declare const uncalledHits: (state: RunState, round: number) => HitRecord[];
+/**
+ * The hits to read: kept by triage in this round, no document yet. A failed open is tried again
+ * on a rerun (`birdwatch back <run> read`).
+ */
+export declare const toRead: (state: RunState, round: number) => HitRecord[];
+/**
+ * The kept findings to check, at most `n`, spread across documents: each document's first
+ * unchecked finding, then each one's second, and so on. A finding with no quote, or one checked
+ * already, is not in it. Findings come in record order, so the sample is the same on a rerun.
+ */
+export declare function spreadSample(state: RunState, n: number, only?: (f: FindingRecord) => boolean): FindingRecord[];
+/** Share of kept findings a check reads at least: the budget's `checks` is the floor under it. */
+export declare const CHECK_SHARE = 0.1;
+/** The sample's size: the budget's `checks`, or a tenth of the kept findings in reach, whichever is more; 0 checks is none. */
+export declare const checkCount: (inReach: number, budget: number) => number;
+/** A round's sample for the check step, less what the round checked already. */
+export declare const toCheck: (state: RunState, round: number, budget: number) => FindingRecord[];
+/** The documents of a round without a verdict: the extract step has not finished them. */
+export declare const toExtract: (state: RunState, round: number) => DocumentRecord[];
+/** A finding's class: its own, else its document's; undefined when neither has one. */
+export declare const classOfFinding: (state: RunState, f: FindingRecord) => SourceClass | undefined;
+/**
+ * Sources per class over findings still kept: distinct sites, but each forum thread (a
+ * document) counts on its own, so 31 threads on one forum are 31 voices, not one site.
+ */
+export declare function classesOf(state: RunState, ids: readonly string[]): Partial<Record<SourceClass | "unclassed", number>>;
+/** The sources a set of findings rests on: the sum over `classesOf`. */
+export declare const sourcesOf: (classes: ReturnType<typeof classesOf>) => number;
+/** Vendor echo: every classed source is a vendor, and vendors cite each other. */
+export declare const echoOf: (classes: ReturnType<typeof classesOf>) => boolean;