Skip to content

RFC 0001 — Resource model

Status: accepted (scaffold) Date: 2026-07-24 Implemented in: apps/api/internal/core

Problem

O4VE addresses many kinds of thing — agents, tools, experiments, datasets, metrics, environments, runs, plus the org structure they live in. If every kind gets its own identifier scheme, its own URL shape, and its own CRUD handlers, the surface grows linearly with the catalog and the console has to learn each one.

Decision

Every addressable thing is a resource: one shared envelope, one hierarchy, one URL grammar, one storage contract.

Hierarchy

tenant
└── workspace
    └── project
        ├── agents
        ├── tools
        ├── experiments
        ├── datasets
        ├── metrics        (includes judges: a judge is a metric of type "judge")
        ├── environments
        └── runs

Teams and members are tenant-scoped, because access control is granted across workspaces.

Each kind declares the level it is unique within:

Level Meaning Kinds
root no parent tenant
tenant unique within a tenant workspace, team, member
workspace unique within a workspace project
project unique within a project agent, tool, experiment, dataset, metric, environment, run

The level is not decoration. It decides three things mechanically: which ancestors a create call must supply, which columns a lookup filters on, and which URL a client builds. Scope.Narrow(level) is the single function that enforces it, so a workspace lookup never accidentally filters on the project the request path happened to carry.

Surfaces

Kinds also declare a surface, which is what the console sidebar groups by:

Surface Kinds, in order
Build agents, tools, experiments, datasets, metrics & judges, environments
Execute runs
Govern teams, projects, workspaces, members, tenants

The API publishes this as a manifest at GET /v1/nav. The console renders whatever the manifest declares, so adding a kind to the backend adds a working page to the frontend with no frontend change.

Identity

Three ways to name the same thing, each for a different consumer:

Form Example For
ID agt_9f1c0b4a7d2e4f0a8b6c5d3e2f1a0b9c machines; stable across renames
Slug sdr-baseline humans; unique within scope, [a-z0-9-]{1,64}
URN urn:o4ve:acme/production/gtm-agents/agent/sdr-baseline logs, certificates, cross-system references

IDs carry a kind prefix so they are self-describing in a log line or a support ticket, and so a malformed reference fails at parse time rather than as a confusing not-found. Path segments accept either an ID or a slug: /v1/.../agents/sdr-baseline and /v1/.../agents/agt_9f1c... both resolve.

Envelope

Every resource carries the same Meta — id, kind, slug, display name, description, scope, labels, revision, timestamps, archive marker — and adds a kind-specific Spec. Runs additionally carry a mutable Status, because they are the only kind whose outcome changes after creation.

Revision is an optimistic-concurrency token. An update supplying a stale revision is rejected with 409, which is what stops a console tab left open for an hour from silently clobbering someone else's edit.

Deletion is archival. Nothing that a run's evidence points at may vanish, or the attribution certificates stop being verifiable.

URL grammar

/v1/tenants/{tenant}
/v1/tenants/{tenant}/workspaces/{workspace}
/v1/tenants/{tenant}/workspaces/{workspace}/projects/{project}
/v1/tenants/{tenant}/workspaces/{workspace}/projects/{project}/{plural}
/v1/tenants/{tenant}/workspaces/{workspace}/projects/{project}/{plural}/{name}

Collections take GET and POST; items take GET, PATCH, and DELETE. Runs add two verbs that are state transitions rather than CRUD: POST .../runs/{name}/cancel and GET .../runs/{name}/events (Server-Sent Events).

Errors are RFC 9457 problem documents with a stable type slug, so clients write one error path.

Consequences

Good. One generic handler pair serves every kind. Registering a resource is one line in registry() plus a struct. The console needs no per-kind code to list or inspect. Scope isolation is enforced in one place (requestScope), which is a small enough surface to audit.

Cost. A shared envelope means kinds that want a genuinely different lifecycle have to either fit the envelope or opt out, as runs already do for creation. Expect a second opt-out when environments grow immutable published versions.

Deferred. Immutable versioning is declared in KindInfo.Versionc but not implemented; today a resource has a revision, not a published version history. Experiments that must be reproducible a year later need the version, so this is the next thing to build. Cross-project references (an agent in project A using a dataset in project B) are deliberately not supported yet.