Investigations

An investigation is a person's examination of a failure cluster, helped by a model. The improvement component owns the investigation assistant. What the architecture and contracts fix today is how it calls a model, what it may read, how its cost is accounted for, and how its own activity is kept out of the data it investigates.

Status (25 October 2026). The improvement component is an empty shell in the application today (one model, no routes, no pages); requirements EV-041 to EV-044, EV-046 and EV-047 are not started in the requirements ledger. This page describes the contract the component is being built to, and nothing on it is available yet.

Model access

EvalBook holds no provider key and calls no provider. Every model call the assistant makes goes through app/service/ssoAi.js, the only way to call a model in the application, with the purpose investigation. The call names the organization and a stable idempotency_key equal to the logical request id; Bookbag SSO writes the token ledger row, deduplicates the charge by that key, meters the organization and refuses with TOKEN_LIMIT before the provider is called. EvalBook records an AiCall row per attempt (logical request id, attempt number, purpose, model asked, provider and model answered, usage, outcome including outcome_unknown) for cost allocation; it is never an invoice ledger. A network failure after the request was sent is outcome_unknown, and a retry reuses the same key so SSO charges once.

Budgets

Before each call a reservation is taken atomically against a budget, using a declared worst-case estimate, and settled from the usage SSO returns. A run stops at its bound. The cost of investigations appears under usage and cost in the improvement_ai category, labelled "allocated from SSO usage" with its ledger reference.

What the assistant may read

An investigation reads evidence through the interfaces the owning components serve: traces (getTrace, getSpanPayload), evaluations (caseResultsFor, which the contract names for review and improvement drill-down; getReport), datasets and scorers. A span body is read with the investigating person's own trace.read_body under the project's capture policy, and getSpanPayload with purpose judge refuses content the project forbids sending to an external model; the assistant is bound by the same rule. Nothing is copied into the investigation: it holds references and the person's notes.

The assistant reads. It does not change a dataset, a scorer, a suite or a threshold, and it does not activate anything: every one of those is either a curator's candidate decision or a governed action (see release channels). EvalBook never authorizes; where a change needs approval, MadeBook decides for a linked project and a standalone project applies separation of duties. EvalBook never runs customer code outside the separately installed, outbound-only runner, and the assistant is no exception: the API and worker execute no customer code.

Keeping investigations out of production data

Spans EvalBook records about its own work carry a purpose. The traces interface that online scoring reads (listCompletedTraces with purpose application) never returns evaluation or investigation spans, so an investigation's own model calls are never sampled, scored or judged as if they were customer traffic, and never feed an alert. See online scoring and the trace explorer.

Who may do what

investigation.read lets a trace reader see investigations; investigation.write lets an experiment runner open one. Both sit on top of viewer reads, and neither includes the right to write a suite, a dataset or a proposal's dispatch; the project roles are separated duties, not a ladder. See roles and access.

Where an investigation leads

An investigation ends in evidence: which cases, spans or scores show the failure, and what the person concluded. From there a proposal states a hypothesis and the bound within which CodeBook may attempt a fix, or a dataset candidate is proposed through curation so the failure becomes a test. The assistant's own steps, its prompts and its tools are not yet in the contract and are not described here.