contracts

Contracts

Versioned values that cross repository boundaries. A contract is a schema plus a provenance rule, never a shared library type.

When two repositories need to exchange a value, they exchange bytes that validate against a schema at a named version. Vendoring a Go struct is a last resort and must be recorded here, because a vendored copy drifts silently.

rho.graph/v1

Status: implemented by rho; produced by rover; no cross-repo consumer wired yet.

The portable execution graph. The vocabulary — nodes, edges, shared state — is defined in rho/internal/contracts/graph/graph.go and vendored from the removed GrayCodeAI/eagle module.

Node types: agent, tool, function, start, end, router, quality, execution, operations, system.

Node kinds classify a node by the ecosystem view it belongs to: system, knowledge, execution, policy, quality, operations.

Provenance. rho/internal/contracts/graph/graph.go carries this header:

Vendored from github.com/GrayCodeAI/eagle/graph at v0.0.0-20260902153929-5877bed17503 (MIT, Copyright (c) 2026 GrayCode AI). The upstream repository no longer exists; this copy is owned by Rho as its contract surface.

The upstream is gone. Until a published contracts module exists, this file is the contract's real location, and any change to it is an ecosystem-wide change.

Known gap. No JSON Schema exists for the wire format. The type exists; the serialized shape is not independently specified. Any second implementation must currently read Go.

graycode-cloud.graph/v1

Status: declared only. No producer, no consumer, no schema.

Reserved for the hosted control plane. It is listed so tooling does not treat its absence as an oversight, and it should not be cited as if it were real.

usage.recorded.v1

Status: partially implemented by flux. Capture works; attribution does not.

flux records provider usage at flux/provider/observability/usage_tracker.go:

type UsageEntry struct {
    Tokens    int
    CostUSD   float64
    Timestamp time.Time
    Provider  string
    Model     string
}

UsageTracker wraps this with daily, hourly, and session limits plus threshold alerts, so a run cannot silently exceed a budget.

What exists: per-session token and dollar capture, with limits and alerts.

What does not: any link from a UsageEntry to the unit of work that caused it. A UsageEntry knows which model was called and what it cost. It does not know which outcome it was spent on, how much of it was rework, or whether the result was accepted.

That gap is why this contract is declared here and not merely implemented. Cost without attribution is a dashboard. Attribution is a ledger.

Naming hazard. flux also defines UsageRecord and UsageTracker in catalog/opencodego/. These are provider-specific catalog types and are not the ecosystem usage event. Do not conflate them.

Adding a contract

1. Write the JSON Schema here first. Not the Go type — the schema.
2. State the producer and every consumer.
3. State what happens when a consumer sees a version it does not understand. The answer must not be "guess."
4. If you vendor a type from a sibling, record the upstream module and version in this directory, as rho.graph/v1 does.