Create a research programme with a goal, constraints, and budget.

Constraints are typed fields, not strings (commitment 4). Wires the optimizer role for this programme.

Structured params (constraints, allowed_variables, budget) may be sent as JSON-encoded strings if your client cannot emit objects.

metric_direction: 'minimize' (e.g. perplexity, loss) or 'maximize' (e.g. accuracy). The optimizer uses this to steer search and rank best trials.

candidate_version_id: optional RSI Phase 0 correlation — which registered candidate created this programme. Must exist if given.

investigation_id: optional zetesis correlation — which open investigation declared this programme as its obligation (open_investigation requires_programme → link_programme). Recorded as claimed provenance: episteme has no read path into zetesis, so the id is stored, not verified.

List all active research programmes.

Call this BEFORE create_programme to check whether a programme already covers your goal. If one exists, add a hypothesis to it (formulate_hypothesis) instead of creating a duplicate programme.

List programmes with optional attribution/status filters (read-only).

candidate_version_id filters to programmes created under that candidate (the RSI Phase-0 correlation) — this is how a candidate's descendants are enumerated. Each row includes candidate_version_id. Unlike list_active_programmes this is a paginated general listing across all statuses.

Update the optimization direction for an existing programme.

Use 'minimize' for loss-like metrics (perplexity, error rate) or 'maximize' for quality metrics (accuracy, F1). The optimizer uses this to rank best trials and steer the search.

This is needed for programmes created before the metric_direction parameter was added to create_programme.

Conclude a hypothesis by accepting/rejecting it.

Creates an immutable conclusion (commitment 8: programmes, not runs). When a claims role is wired, also mints a semantic claim with provenance edges — a byproduct, never a gate on the verdict. Enforcement: commitment 8 — rejects duplicate conclusions for the same hypothesis. Enforcement: commitment 10 — rejects if hypothesis not found or not in this programme. Enforcement: commitment 1 — rejects if no completed trials for the hypothesis. Enforcement: commitment 7 — rejects if any completed trial has no observations.

Close a programme by setting its status to completed or abandoned.

For status="completed": rejects if any hypothesis is still under_test — the agent must call conclude_hypothesis first. Auto-marks proposed → abandoned (no effort was expended).

For status="abandoned": auto-marks all unconcluded hypotheses as abandoned (the whole programme is being abandoned).

Enforcement: state machine — rejects if programme is not active. Enforcement: commitment 1 — the loop is the unit (no closing with unconcluded hypotheses when completing).

Register a researcher version with parent lineage (RSI Phase 0).

The thing doing the research becomes a durable object. parent_id links this candidate to its parent — omit for a genesis candidate. Lineage is never "latest wins": every candidate keeps its ancestry.

capability_profile describes the tools/roles available; it may be sent as a JSON-encoded string.

Enforcement: parent_id must name an existing candidate; code/harness digests must resolve to an ingested blob or be 'none' — a hash of nothing is a claim with no referent.

Enumerate the candidate population, newest first (read-only).

The population listing the Loop-1 roster pulls — candidates are the researchers; champion/challenger status is derived from promotion_decisions (see get_incumbent), never stored.

Read one candidate version (read-only).

Derive the incumbent candidate from decisions (read-only).

Champion/challenger is derived from promotion_decisions, never stored: the latest 'promote' not superseded by a 'rollback' for the same candidate is the incumbent. Empty until the first promote — registered-but-undecided candidates are candidates, not the champion.

List a candidate's verdict trail, oldest first (read-only).

Decisions are insert-only — the trail is the record; reversal is a new 'rollback' verdict, never a mutation.

Descendant quality over attributed programmes (read-only).

For each programme created under this candidate (the Phase-0 candidate_version_id correlation), reports trial/observation counts and the best observed value per metric — 'best' read against the programme's metric_direction.

contract_id scopes the report to that contract's declared metrics (primary + secondary); without it all recorded metrics are reported per programme.

Walk a candidate's parent chain to genesis (self first).

Returns {"lineage": [{id, parent_id, model_ref, code_artifact_digest, ...}, ...]} — the full ancestry that any result attributed to this candidate inherits.

Create an evaluation contract for a programme (RSI Phase 0).

Contracts are insert-only and versioned per programme: each new contract for the same programme gets version = max+1 and supersedes the previous. metrics and promotion_policy may be sent as JSON-encoded strings.

The powered-policy gate enforces presence of the design keys (sesoi_d, target_power, min_evidence_rung), not adequacy — target_power: 0.5 pre-registers fine; adequacy surfaces downstream as underpowered / power_acknowledged on the campaign, not as a mint refusal.

Enforcement: programme must exist.

Read one evaluation contract (read-only).

Contracts are insert-only and versioned per programme — the promotion pipeline reads them to learn which metrics a campaign is scored under.

Record an attributed verdict on a candidate (RSI Phase 0).

verdict: promote | reject | hold | rollback. Decisions are insert-only — reversal is a new decision ('rollback'), never a mutation. evidence_refs may be sent as a JSON-encoded string list. decided_by is required: attribution is first-class.

Enforcement: verdict enum, non-empty rationale/decided_by, candidate (and contract, if given) must exist.

Formulate a falsifiable hypothesis (commitment 3).

Rejects a hypothesis with no failure criterion. variables_involved may be sent as a JSON-encoded string list.

Abandon a hypothesis — attributed, rationaled, never erased.

The exit for a hypothesis that can never conclude: falsified premises, superseded questions, trials that can only fail. Abandoning is NOT a verdict — no conclusion is recorded and no claim is minted; the hypothesis simply leaves the loop as 'abandoned', stamped with who decided and why. Trials already recorded stay on the record.

Applies to proposed and under_test hypotheses; terminal states (accepted|rejected|inconclusive|abandoned) refuse. To abandon every hypothesis in a programme at once, use close_programme(status="abandoned").

List all hypotheses in a programme with their status.

Read-only enumeration — the tool-level counterpart of the programme://{id}/hypotheses resource. Use it to recover a hypothesis id (e.g. in a new session) rather than querying the state database directly.

Design an experiment: create a trial (data item) within the programme.

config may be sent as a JSON-encoded string if your client cannot emit objects.

Enforcement: commitment 5 — budget is an epistemic resource (trial count + wall time). Enforcement: commitment 10 — the agent is a scientist (hypothesis must exist).

Seal the auxiliary bundle for a DESIGNED trial (commitment 6).

ORDERING: call AFTER design_experiment and BEFORE run_trial. The seal is pre-registration — the bundle fixes the auxiliary assumptions (code/env/seeds/splits) before any observation, so they cannot be retro-fitted to results. Trials that have left 'designed' are rejected. The post-run counterpart is executed_code.json — what actually ran, captured at finalization from the strace read-trace.

code_ref MUST be a path to a Python file that exposes: def run_training(config: dict) -> dict returning {"metrics": {...}, "variance": {...}}. The config is the same dict passed to design_experiment. Read the executor://contract resource for the full contract.

data_refs is an optional list of DataRef IDs (from prepare_data). When provided, the bundle records structured data provenance. When omitted, splits is used (backward-compatible).

extra_code_refs is an optional list of additional .py file paths that the trial depends on but cannot be discovered by AST import analysis — e.g. scripts invoked via subprocess.run(). These are captured into code_snippets and stored in code_hash_extra_json so the bundle is fully self-contained and rerunnable from archive (commitment 2 + 5 — the bundle must contain ALL code needed to reproduce, not just the executor).

Enforcement: commitment 1 — the loop is the unit (trial must exist). Enforcement: commitment 6 — the bundle must be controlled (code_ref validated). Concurrency: rejects if trial already has a bundle (no double capture).

Structured params (seeds, splits, data_refs, extra_code_refs) may be sent as JSON-encoded strings; seeds also accepts a bare int.

Capture a bundle using a content address (code_hash) instead of a file path.

This is the rerun-from-archive path: the LLM reads an archived programme, gets the code_hash from the bundle, and captures a new bundle for a new trial using the same code content. No filesystem access is required — the code is loaded from code_snippets by hash, materialized as a real file next to the execution wrapper, and imported at run_trial time.

NOTE: code_hash is a "sha256:..." content address returned by a prior capture_bundle — it is NOT a bundle_id. To re-use an existing bundle's code, pass its code_hash field.

The code_hash must already exist in code_snippets (captured by a prior capture_bundle or prepare_data call). If it doesn't, the tool returns an error.

The bundle's code_ref is set to "code://{code_hash}" — a content address, not a file path. This is the carrier/content separation (Rule 5.4) made explicit: the bundle references the ICE directly.

code_hash_extra is an optional list of additional content addresses for locally-imported or subprocess-dispatched modules captured alongside the primary. Each must already exist in code_snippets. At run_trial time, these are materialized as real files under a _deps/ dir on sys.path, reconstructing each file's path suffix — so from src.mod import x resolves through the real import machinery (commitment 2 + 5).

All other parameters are identical to capture_bundle.

Structured params (seeds, splits, data_refs, code_hash_extra) may be sent as JSON-encoded strings; seeds also accepts a bare int.

Returns: {"bundle_id": "bundle-...", "status": "captured", "code_hash": ...}

Run a trial by calling the executor role.

Imports run_training from the bundle's code_ref and calls it with the trial config. The code_ref must be a path to a .py file exposing def run_training(config: dict) -> dict returning {"metrics": {...}, "variance": {...}}. Read the executor://contract resource for the full contract.

When the bundle carries data_refs, the config handed to run_training is extended with two injected keys: 'data_paths' ({split: resolved read-only path}) and 'data_ref_paths' ({data_ref_id: resolved read-only path}). The stored config_json keeps the designed config verbatim — the injection is runtime-only.

For long-running jobs, this returns quickly with status "running". Use get_trial_status to poll for completion. Note the return is not immediate — there is a consistent ~10 s handshake/settle before status "running" comes back; that settle window is what makes cancel-race behaviour reproducible.

Enforcement: commitment 6 — the bundle must be controlled. Rejects if the bundle is not fully captured. Concurrency: rejects if trial is already running (no double execution).

Check the status of a running or completed trial.

Returns: {"trial_id": ..., "status": "running"|"completed"|"failed", "executor_output": ...} # raw output once finalized

executor_output is persisted on the trial row at finalize time — it survives server restarts (the executor's async cache does not).

artifact_path is a transient staging directory — its contents are captured content-addressed into SQLite at finalize and the files deleted. An empty artifact_path is by design, not lost data: recover contents via get_blob / the code:// resource.

Enforcement: commitment 1 — the loop is the unit (orphan check).

Wait for a trial to reach a terminal state — one call instead of a polling loop.

Polls get_trial_status internally every poll_seconds until the trial is completed/failed/retryable/abandoned or timeout_seconds elapses (server-side cap: 60s). Returns the final status payload plus 'waited_seconds' and 'timed_out'. Caps the get_trial_status amplification loop: a 60s wait replaces ~30 round-trips.

Cancel a running trial, or abandon a designed one.

running → failed: kills the subprocess, marks failed. The record's failed here reflects the cancellation act, not an observed execution failure — cancelled: true in the payload marks the distinction, and an already finished executor reply means the executor completed first. A cancel landing before the task registers tombstones the id so no child can spawn under the terminal row. designed → abandoned: no executor to kill, no evidence lost — the honest terminal for a design that will never run (e.g. a bundle locked to code that no longer exists). The FSM has always permitted designed → abandoned; close_programme uses the same transition for programme-scoped sweeps.

Enforcement: commitment 1 — the loop is the unit (orphan check).

Mark a running trial as retryable (infrastructure failure).

This is for trials that are stuck in 'running' due to infrastructure issues (server restart, executor state lost, timeout) — NOT for scientific failures. A retryable trial is terminal and does not count as evidence.

It does NOT unlock re-capture or re-run: a terminal trial's record is finished. To retry the work, design_experiment a new trial and capture_bundle on it (file-path or code://).

Enforcement: commitment 1 — the loop is the unit (orphan check).

Correct a terminal trial's status — the recorded repair act.

For mislabeled records: e.g. the executor's outer wrapper exited 0 while the recorded output documents a crash ("status": "error" / nonzero inner exit code in the payload). Source must be completed|failed|retryable (all terminal — a retryable source is a correction made in error or evidence re-read after the fact); target must be completed|failed|retryable. reason is mandatory. Correcting TO completed requires the record to evidence a completed run — a cancellation receipt, reaper note, or failure output does not qualify, so that direction is refused unless the executor record documents an actual completion.

The correction is appended to the trial's executor_output_json under 'corrections' — the record shows both what was claimed and what it was corrected to. Never hand-edit the database: a direct sqlite3 UPDATE bypasses this audit trail.

Enforcement: commitment 1 — the loop is the unit (orphan check).

List all trials in a programme with configs and status.

Read-only enumeration — the tool-level counterpart of the programme://{id}/trials resource. Use it to recover a trial id (e.g. in a new session) rather than querying the state database directly.

Record an observation (data item about a quality).

metrics and variance may be sent as JSON-encoded strings.

Only completed trials can be observed — a failed trial produced no measurement; its failure lives in its status, executor_output, and artifacts, not here. All-zero variance is rejected (n identical outcomes are one effective measurement, not reproducibility). If nothing is concludable, close the programme 'abandoned' rather than fabricating variance.

Enforcement: commitment 7 — reproducibility is the price of admission. Rejects a single point estimate with no variance.

Update the belief state for a programme.

Calls the optimizer role's tell, then reads the updated posterior. Enforcement: commitment 2 — memory precedes optimization. Enforcement: commitment 9 — belief is a tracked quantity.

Assess programme health: progressive vs degenerating (commitment 8).

Reads observations from state.db and best_trials from the optimizer.

Get the next experiment configuration from the optimizer role.

Reports remaining budget (commitment 5: budget is an epistemic resource). Enforcement: commitment 5 — rejects when budget is exhausted.

Prepare a dataset and return a DataRef ID.

Two regimes:

• generated: runs the generator (via executor), stores output, computes hash. Requires generator_code_ref, generator_seed. Generator contract: the file must expose generate_data(config, output_path) — config carries 'seed' AND 'generator_seed' (same value — either spelling works) plus generator_params flattened at the top level; a seed/generator_seed key inside generator_params is superseded so the recorded seed always equals the seed delivered. The dataset is written to output_path. A generator may print a single-line {"error": "..."} JSON object to stdout to report a structured failure. The generator runs under the executor's default interpreter ([executor] python) — not a bundle env; only packages installed there are importable.

• captured: registers an external URI, computes hash if accessible. Requires source_uri.

For stream capture (captured + temporal), provide capture_window_start and capture_window_end.

The DataRef is stored in the state DB and the data is stored in data storage (separate from code storage). Access is read-only.

Returns: {"data_ref_id": "data-ref-...", "split": ..., "regime": ...}

generator_params and capture_source_metadata may be sent as JSON-encoded strings.

Verify data provenance by re-computing the hash.

Returns: {"verified": bool, "recorded_hash": ..., "computed_hash": ...}

If verified is false, the data was modified after preparation — a provenance violation that invalidates any trial using this data.

List all archive files (open and sealed).

Returns a list of archives with their IDs, paths, programme counts, and sealed status. Sealed archives are read-only; open archives are still accepting new programmes.

Get details about an archive, including its programmes.

Returns the archive metadata (path, sealed status, hash) and the list of programmes archived in it.

Get an archived programme's details from its archive file.

Returns the programme metadata, hypotheses, trials, beliefs, and conclusions from the archive SQLite file. The programme is read-only — it cannot be modified or restored to the live DB.

Verify an archive's integrity.

For sealed archives: recomputes SHA-256 of the .db file, compares to the recorded hash.

For open archives: verifies structural integrity (DB can be opened, row counts match the registry).

Returns: {verified: bool, recorded_hash, computed_hash (sealed only)}

Archive terminal programmes that are still in the live DB.

This is a migration tool for programmes that were closed (completed or abandoned) before the automatic archiver was implemented. It scans the live DB for terminal programmes not yet archived and archives them.

dry_run=true reports the scan result ({would_archive, would_mark_archived, skipped}) without writing anything.

Under normal operation, this is a no-op — close_programme already archives automatically. This tool only catches programmes that slipped through (e.g. abandoned before Phase 3 was deployed).

Returns: {archived: [...], errors: [...], skipped: int}

Capture artifact files for trials that predate artifact capture.

Scans all trials with an artifact_path but no rows in trial_artifacts. Reads files from disk and stores them in SQLite (gzip-compressed). Files over 50MB are skipped and marked oversized. Files that no longer exist on disk are marked lost.

dry_run=true reports the pending trial ids without reading or storing anything.

cleanup: when True, staging files are deleted after successful capture (the SQLite copy becomes authoritative). Default False keeps the originals — conservative for migration of old trials.

Under normal operation this is a no-op — _finalize_trial already captures artifacts automatically. This tool only catches trials that slipped through (finalized before artifact capture was implemented).

Returns: {captured: [...], oversized: [...], lost: [...], trials_scanned: int, trials_with_existing: int}

Audit the experiment store against the loop's invariants.

Returns {status: ok|violations, checks: [{name, ok, violations, detail}]}. Detection complement to write-time enforcement: orphaned running trials, completed trials lacking observations, unsealed executions, strace divergence, undigested input data, budget overruns, stuck hypotheses, stalled trials. Report-only — nothing is repaired or mutated. The run is logged to /logs/ (retention: [integrity] log_max_files).

Acknowledge an open integrity violation — insert-only.

The check log is append-only; this records the disposition (remediated | accepted-with-reason) against (check_name, object_ref) so the finding stops gating writes and leaves the digest's blockers. The underlying record is never touched — remediation itself is done by the corrective tools first.

Describe a content-addressed blob by digest (read-only).

The resolution check behind digest claims: returns {exists, resolved_in, size_bytes, content_type, captured_at} across the content stores — artifact_files (HTTP ingest), code_snippets, bundles.code_hash. resolved_in names every store holding the hash; a digest may live in more than one. Existence + metadata only — bytes are never returned. This is the read upstream servers use to verify a digest before accepting it on a registration call. For the bytes themselves, get_blob.

Retrieve a content-addressed blob's bytes by digest (read-only).

The read-back half of describe_blob: returns the stored bytes (base64 in content_b64) plus {digest, size_bytes, content_type, captured_at, resolved_in, served_from}. The returned bytes are re-hashed and verified against the requested digest — a blob whose stored bytes don't match its key is refused with the computed digest reported, never served.

Errors: malformed_digest | not_found | no_bytes | digest_mismatch | too_large. Read-only: no state is mutated.

Read one of this server's resources by URI (read-only).

The MCP surface exposes resources only through resources/read — this tool gives tool-only clients the same read surface. Ownership is by construction: a URI outside this server's registered schemes resolves to nothing and errors rather than crossing the loop boundary. Never a write path.