Skip to main content
Onyx uses additive campaigns, bounded sessions, durable hypotheses, and immutable experiments.

​
Project

A project is an internal Onyx record for a GitHub repository, optionally scoped by projectPath. Onyx creates or reuses it automatically when the first campaign starts from that repository. Onyx stores project metadata for search, permissions, graph rendering, and repository sync, while git remains the source of truth for code.

​
Campaign

A campaign is a research direction. It is a logical Onyx track, not a mutable git history branch. Campaigns track:
  • name and description;
  • metric name;
  • metric unit;
  • direction, either maximize or minimize;
  • optional creation-commit provenance;
  • active and closed hypotheses;
  • bounded sessions with immutable settlement cutoffs;
  • the evaluation revision used by the newest session.
Campaign status is active or archived. The metric contract is immutable; changing metric name, unit, or direction requires another campaign. Archiving is reversible and makes the campaign read-only. It is rejected while active or stale sessions remain.

​
Hypothesis

A hypothesis is a conceptual research option with active or closed state. It does not own a git base. Closing it immediately cancels its assignments and workers in every open session; reopening only makes it eligible for future sessions.

​
Session and Assignment

Every onyx research run creates a new bounded session. Sessions are never resumed. A session records its repository/setup snapshot, evaluation revision, experiment/deadline bounds, mutable worker target, and an immutable endedAt cutoff when it ends. Open-session liveness is derived as starting, active, stale, or abandoned. Each selected hypothesis gets one immutable session assignment with its own starting commit. Adding a hypothesis during a run does not change that session; it becomes available to the next one.

​
Evaluation Revision

An evaluation revision is a comparison cohort identified by a deterministic fingerprint of the metric contract, required metric step, normalized metric tool, and its committed declared inputs. Metrics, charts, and hypothesis best projections are scoped to a revision. Onyx does not combine incomparable revisions into one leaderboard.

​
Experiment

An experiment is one recorded run with an immutable result commit. Experiments track:
  • base commit SHA;
  • result commit SHA;
  • result ref, usually refs/onyx/experiments/<campaignId>/<runRef>;
  • status;
  • primary metric value;
  • secondary metrics;
  • agent notes;
  • output summary;
  • optional checks result;
  • optional setup, hypothesis, worker, and provenance links.
  • required session, assignment, and evaluation-revision links.
The server owns revision-scoped best projections, worker visibility, hypothesis state, knowledge, provenance, worker leases, and accepted experiment order within each session. Reports arriving after a session or assignment cutoff remain as discarded diagnostics. Explicit reconcile closes abandoned sessions and repairs stale projections without hidden GET-side writes.