@crewhaus/provability 0.0.0-stage → 0.8.0

package/dist/evidence.d.ts

@@ -0,0 +1,326 @@
+import { CrewhausError } from "@crewhaus/errors";
+import { type PathRoots } from "./origin";
+import type { EvidenceIndex, EvidenceRecord } from "./types";
+export declare class ProvabilityError extends CrewhausError {
+    readonly name = "ProvabilityError";
+}
+/** One tool call, before its origins are read off it. */
+export type ToolCall = {
+    readonly toolUseId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+    /** The result as logged. */
+    readonly content: string;
+    /**
+     * The whole output, when `content` is tool-result-store's preview of it
+     * (`spilledOutput`): what the tool returned, which the evidence is read
+     * from. Absent when the log holds the result whole.
+     */
+    readonly body?: string;
+    readonly isError: boolean;
+    readonly sessionId?: string;
+    readonly turnNumber?: number;
+};
+/**
+ * The input schema a tool declared, by the name the log records it under
+ * (`RegisteredTool.jsonSchema`: for an MCP tool, what its server
+ * advertised), or `undefined` when the caller cannot say. Read for an MCP
+ * tool's origins (`inputOrigins`): only a field the schema declares names
+ * one.
+ */
+export type InputSchemaLookup = (toolName: string) => unknown;
+/** Where path-shaped inputs are measured from (default `process.cwd()`, the
+ *  directory the tools themselves resolve relative paths against). */
+export type EvidenceOptions = Pick<PathRoots, "workspaceRoot"> & {
+    /** Stamped onto records built from messages (they carry no session of their own). */
+    readonly sessionId?: string;
+    /**
+     * The input schema each tool declared (`InputSchemaLookup`) — the gate
+     * passes its catalog's. Default: the schema `defaultCatalog` holds for the
+     * tool, where a compiled harness registers its MCP tools. (0.8.0
+     * additive, convergence pass.)
+     */
+    readonly inputSchemaOf?: InputSchemaLookup;
+    /**
+     * Where the runtime spilled results over its threshold (its
+     * `toolResultRoot`; default `.crewhaus/tool-results` under the workspace
+     * root, tool-result-store's own default). A spilled output is read back
+     * only from under it (`spilledOutput`).
+     */
+    readonly toolResultsRoot?: string;
+};
+/** `sha256:<hex>` of a string's UTF-8 bytes. */
+export declare function sha256Of(text: string): string;
+/**
+ * Is `status` a page's own answer — 2xx? A 404 or a 503 body is the
+ * server's error page, not the page a citation names (design §2's
+ * `grounded` row: the cited source's BODY was fetched): one that prints
+ * the path it was asked for would otherwise ground any claim the model
+ * spelled into that path. A 3xx a fetcher hands back (it follows
+ * redirects) carries no page either.
+ */
+export declare function servesPage(status: number | undefined): boolean;
+/**
+ * The text a record is grounded against: the result — the whole output
+ * where the log holds tool-result-store's preview of it (`body`) — with its
+ * transport header taken off: WebFetch's `URL:`/`Status:` block and the `[user prompt:
+ * …]` line it prepends when the call carried a `prompt` (that is the model's
+ * OWN text: left in, a model could write the claim into `prompt` and find it
+ * "in the source"), and Fetch's status line and response headers. Read only
+ * off the tool that prints each; anything else is the result, verbatim.
+ */
+export declare function groundingBody(record: Pick<EvidenceRecord, "content" | "input" | "toolName" | "body">): string;
+/**
+ * The properties a tool's declared input schema lists at its top level, or
+ * `undefined` when no schema is known. A schema that lists none there (a
+ * `$ref`, an `anyOf`, a bare `{ type: "object" }`) declares no field this
+ * can read an address from: the empty set, so nothing its input carries
+ * names an origin (fail closed).
+ */
+export declare function declaredFields(schema: unknown): ReadonlySet<string> | undefined;
+/**
+ * Every place a call's input points at, whatever its schema declares — a
+ * builtin reader's one field, an MCP tool's URL and path fields and the
+ * entries of its `paths` / `files` lists — for the state-root test
+ * (verify.ts `provenanceOf`): a call whose input names the session log read
+ * it, whichever origin the body was then indexed under
+ * (`read_multiple_files {paths: [".crewhaus/sessions/…"], url}`).
+ */
+export declare function inputPlaces(toolName: string, input: unknown, roots?: PathRoots): string[];
+/** Is `toolName` one of the builtin readers (`WebFetch`, `Fetch`, `Read`: `READERS`)? */
+export declare function isReader(toolName: string): boolean;
+/** One place a call names: where it writes, or (`source`) where it copies, moves or unpacks from. */
+export type WrittenPlace = {
+    readonly place: string;
+    readonly source: boolean;
+};
+/**
+ * The places a call may have WRITTEN, and the ones it copied, moved or
+ * unpacked them from, as its input names them, normalized like a
+ * citation's (verify.ts `provenanceOf` reads them: a source the run wrote
+ * itself and then read back, or a copy of the harness's own state). Any
+ * tool's input, builtin or not: the place it writes by
+ * {@link TARGET_FIELDS}; the place it copies from by {@link SOURCE_FIELDS};
+ * a list ({@link LIST_FIELDS}) as sources beside a target (`ConcatFiles`)
+ * and as written places otherwise; and each file a diff
+ * ({@link PATCH_FIELDS}) names, under the call's `cwd` (`GitApplyPatch`).
+ * None for a call that only reads — a builtin reader (`WebFetch`, `Read`, a
+ * GET or HEAD `Fetch`) and `ProvabilityPreflight`, which writes nowhere.
+ * Whether the tool can write at all (a pure tool cannot) is the caller's
+ * question.
+ */
+export declare function writtenPlaces(toolName: string, input: unknown, roots?: PathRoots): WrittenPlace[];
+/** What a call put where it wrote: the text it added, and the text it replaced. */
+export type WrittenText = {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+};
+/**
+ * The text a call put where it wrote ({@link writtenPlaces}), read off its
+ * input by field (verify.ts `selfWriter`): what a content field
+ * ({@link CONTENT_FIELDS}) carries, at any depth (`MultiEdit`'s `edits`, an
+ * MCP file server's `edits[].newText`), and a diff's `+` lines, as added;
+ * what an edit replaces ({@link OLD_TEXT_FIELDS}) and a diff's `-` lines, as
+ * removed — so an `Edit` of `14` to `30` added `30`, not `14`. A search's
+ * `pattern`, a commit `message`, an address: none of those is text put
+ * anywhere.
+ */
+export declare function writtenText(input: unknown): WrittenText;
+/**
+ * The input strings a call names its origins by, as written: the URL or
+ * path it was pointed at, not text it was handed — a builtin reader's one
+ * declared field, a non-builtin's URL and path fields whose origin the
+ * record carries (what `inputOrigins` read off an MCP tool, and the address
+ * a record built outside the log was fetched under — the research
+ * crawler's carry their own origins). A key the tool does not declare names
+ * no origin (`mcpOrigins`), so its value is text the call was handed like
+ * any other. `grounded`'s echo test (verify.ts `echoCheck`) reads these
+ * apart from the call's other strings, because a URL's slug can spell a
+ * claim the page itself states — a reader returns the page, not its
+ * address — and only a body that PRINTS the address (a 404 page repeating
+ * the path it was asked for, a page headed with its own URL) can be
+ * reflecting it.
+ */
+export declare function originFieldValues(record: Pick<EvidenceRecord, "toolName" | "input" | "origins">, roots?: PathRoots): string[];
+/** Every string a call's input carries, at any depth (the grounded echo test reads them too). */
+export declare function inputStrings(value: unknown, out?: string[], depth?: number): string[];
+/**
+ * The URL a record's body was served from, where the fetcher says so: the
+ * final URL a WebFetch header names on its first line, after any redirect
+ * (design §5.2), normalized. `undefined` for any other record — its body is
+ * what its origins name. A citation of the requested URL grounds in a body
+ * this URL served, so the host checks that hold a redirect hop (`sources.deny`,
+ * the private-address rule) and `grounded.independent` read the body by
+ * this (verify.ts `grounded`).
+ */
+export declare function servedFrom(record: Pick<EvidenceRecord, "toolName" | "content" | "body">): string | undefined;
+/**
+ * One call as an evidence record: its origins read off the input — a
+ * builtin reader's one field (WebFetch's and Fetch's `url`, Read's `path`),
+ * or an MCP tool's `url`, `uri`, `href`, `file_path`, `path`, `file`,
+ * `filePath` as far as its declared schema lets them (`mcpOrigins`), unless
+ * its result is an echo of its input (`inputOrigins`, `echoesInput`) — and
+ * the URL a WebFetch result's header names on its
+ * first line (indexed BESIDE the requested URL, so that once tool-web
+ * prints the final URL there a citation of either grounds — see
+ * `webFetchHeader`), and the hits a multi-source result carries (Retrieve;
+ * JSON results with `url`/`uri`/`href`/`link`/`source` from an MCP tool —
+ * see `resultHits` for which tools). A fetcher's HTTP status is carried
+ * (`status`): a non-2xx body is not the page (`servesPage`). Error results
+ * are recorded too: the verifiers reject them, by reason.
+ *
+ * Everything is read off the whole output (`body`) where the log holds a
+ * spill preview of it; `content` stays what the log holds, which a replay
+ * is compared against.
+ */
+export declare function recordFromCall(call: ToolCall, opts?: EvidenceOptions): EvidenceRecord;
+/**
+ * The whole output of a call whose logged result is tool-result-store's
+ * preview of it, or `undefined` (design §5.2: grounding needs the bodies
+ * the run read). runtime-core logs, and shows the model, only the first 100
+ * lines or 10 KB of a result over the threshold, then the path the whole
+ * was saved at; the claim the model reads further down a long page (the
+ * preview tells it to `Read` the parts) is in that file, not in the log.
+ *
+ * Read back only where it can be nothing but this call's own output:
+ *
+ * - the path is `<toolResultsRoot>/<runId>/<toolUseId>.txt` (or the
+ *   `<toolUseId>.<n>.txt` tool-result-store moves on to when the name is
+ *   taken) — THIS call's id, one run directory down, under the root the
+ *   runtime spills to; a logged result is the tool's output verbatim, so a
+ *   page that ends with a forged tail naming some other file reads nothing;
+ * - the file is a regular file opened inside that root, no link followed
+ *   (`@crewhaus/tool-safety/fs`), at most {@link MAX_SPILL_BYTES};
+ * - it begins with the head the log holds.
+ *
+ * Anything else — a file gone, a tenant root not passed here — leaves the
+ * preview as the record's text: fewer words, a claim further down unmet,
+ * never more than the run read.
+ */
+export declare function spilledOutput(content: string, toolUseId: string, opts?: Pick<EvidenceOptions, "workspaceRoot" | "toolResultsRoot">): string | undefined;
+/**
+ * The structural slice of a transcript message this reads: Anthropic-shaped
+ * `MessageParam`s (assistant `tool_use` blocks `{ id, name, input }`, user
+ * `tool_result` blocks `{ tool_use_id, content, is_error }`). Declared here
+ * so the package imports no model SDK.
+ */
+export type EvidenceMessage = {
+    readonly role: string;
+    readonly content: string | ReadonlyArray<unknown>;
+};
+/**
+ * Records for every completed tool call in a transcript, in call order. A
+ * `tool_use` with no `tool_result` yet is not a record (the call never
+ * finished); a result whose call is not in the transcript is skipped. An id
+ * that appears twice (a provider that reuses ids) pairs its LAST call with
+ * its LAST result, as the log walk does (`evidenceFromSessionLog`). A
+ * result the runtime spilled is read whole (`spilledOutput`).
+ */
+export declare function evidenceFromMessages(messages: ReadonlyArray<EvidenceMessage>, opts?: EvidenceOptions): EvidenceRecord[];
+export type SessionLogEvidenceOptions = {
+    /** The session whose log to read: `sess_<16 hex>`. */
+    readonly sessionId: string;
+    /** Where session `.jsonl` logs live (default `.crewhaus/sessions`). */
+    readonly rootDir?: string;
+    /** Walk sub-agent child sessions (`sub_agent_start` brackets). Default true. */
+    readonly includeChildren?: boolean;
+    /** How deep the child walk descends. Default 8. */
+    readonly maxDepth?: number;
+    /** Workspace root for path-shaped inputs (default `process.cwd()`). */
+    readonly workspaceRoot?: string;
+    /** Where the runtime spilled large results (see `EvidenceOptions.toolResultsRoot`). */
+    readonly toolResultsRoot?: string;
+    /** The input schema each tool declared (see `EvidenceOptions.inputSchemaOf`). */
+    readonly inputSchemaOf?: InputSchemaLookup;
+    /**
+     * Told when a session's log could not be read to its end — a torn last
+     * line from a crash mid-append, a malformed line, a link where the log
+     * should be. The records read before it are kept; the gate logs this.
+     */
+    readonly onUnreadable?: (info: {
+        readonly sessionId: string;
+        readonly message: string;
+    }) => void;
+};
+/**
+ * Records for every completed tool call in a session's event log, child
+ * sessions included, in call order: a child's calls are placed where its
+ * `sub_agent_start` bracket sits in the parent, because that is when they
+ * ran. The child walk follows the brackets `continuity-store`'s
+ * `resolveEvidence` follows — `sub_agent_start` payloads name a
+ * `childSessionId`, a session is read once, the depth is bounded — so a
+ * researcher child's fetches ground the parent's answer. (It is not that
+ * function: this reads every call of the tree once, in call order, where
+ * `resolveEvidence` looks one id up breadth-first.)
+ *
+ * One id logged more than once in a session pairs its LAST `tool_use` with
+ * its LAST `tool_result`, at the position it first appeared — the rule
+ * continuity-store's `scanSession` applies, so `PlanComplete` and the
+ * `checked` rung read one log the same way (design §6.3). An approval
+ * replay logs the `tool_use` twice (the second line records the input that
+ * RAN) and the result once; a provider that reuses ids (an
+ * OpenAI-compatible server's `functions.<name>:<n>`) logs both twice, and
+ * the last call is paired with its own result rather than with the first
+ * call's. A result the runtime spilled is read whole (`spilledOutput`).
+ * `turnNumber` is carried when a payload records one. A missing log
+ * — the session's or a child's — yields no records, never a throw. A log
+ * that cannot be read to its end (`@crewhaus/event-log` throws at a
+ * malformed line — a crash mid-append leaves one — or refuses a link at
+ * the log's name) keeps the records read before that point and reports it
+ * through `onUnreadable`: fewer records fails closed — a claim whose
+ * evidence was lost is unmet — where a throw would fail OPEN, every later
+ * turn of the session served `unverified` because one child's log is torn.
+ * Reading never creates the log directory.
+ */
+export declare function evidenceFromSessionLog(opts: SessionLogEvidenceOptions): Promise<EvidenceRecord[]>;
+export type EvidenceIndexOptions = {
+    /**
+     * The session being graded — the parent, whose sub-agents' logs the walk
+     * reads too (`evidenceFromSessionLog`). A record that names no session
+     * (the in-memory transcript's: `evidenceFromMessages` without
+     * `EvidenceOptions.sessionId`) is one of its calls, and a `tool:<id>` its
+     * calls and a child's share resolves to its own. Default: the session of
+     * the first record that names one — the log walk reads the parent first,
+     * and a parent's call (the `Task` that spawned a child) is logged before
+     * the child's bracket.
+     */
+    readonly sessionId?: string;
+};
+/**
+ * The index over `records`, one record per call: a call is its session and
+ * its `toolUseId` together (design §5.2: the index is keyed per call), so
+ * the log's record and the transcript's of ONE call merge into one, in the
+ * order each call first appears, and two sessions' calls never do. The
+ * log's record wins where the two disagree, except where the log holds
+ * only runtime-core's summary of block content and the transcript holds
+ * the text.
+ *
+ * An id is unique only within a conversation: an OpenAI-compatible server
+ * numbers its calls per conversation (`functions.<name>:<n>`, see
+ * `evidenceFromSessionLog`), and every sub-agent child is a fresh one, so a
+ * parent's first fetch and its child's share an id. Merged by id alone, the
+ * two became one record — one call's body, indexed under both calls' URLs:
+ * a claim the other page contradicts grounded, and the honest one failed.
+ * A record that names no session is the parent's (see
+ * {@link EvidenceIndexOptions.sessionId}); where the parent has no call by
+ * its id, it is the twin of the one call that has its tool and its input,
+ * and otherwise a call of its own.
+ *
+ * `byToolUseId` answers a `tool:<id>` the way continuity-store's
+ * `resolveEvidence` does — the parent's call first, then a child's — and
+ * an id only several children share (and the parent does not) is
+ * ambiguous: `undefined`, with every candidate on `callsById`, so the
+ * gate says so rather than grade one sub-agent's result for another's.
+ *
+ * `bySource` takes a normalized origin; a raw URL is normalized for the
+ * caller. Error records are indexed like any other — the verifiers reject
+ * them by reason, so "fetched, but it failed" reads differently from "never
+ * fetched".
+ */
+export declare function buildEvidenceIndex(records: Iterable<EvidenceRecord>, opts?: EvidenceIndexOptions): EvidenceIndex;
+/**
+ * The index restricted to calls made in `turnNumbers` (`scope: turn`). A
+ * record with no `turnNumber` is dropped: under a turn scope, evidence whose
+ * turn is unknown cannot be shown to be this turn's.
+ */
+export declare function restrictToTurns(index: EvidenceIndex, turnNumbers: ReadonlySet<number>): EvidenceIndex;