RFC 011: ARD-backed catalog discovery for portable environments

[thegovind]

Summary

The overall goal is to let a user search by task for a portable OpenEnv RL environment across any Hub that publishes ARD entries or is covered by an ARD adapter.

The two-PR strategy separates OpenEnv's domain contract from generic ARD conformance diagnostics:

• This OpenEnv draft owns the domain contract: the Environment Card, the logical environment/artifact/provider projection split, identity, trust, evidence, and the read-only discovery boundary.
• The companion generic ARD conformance draft stops the conformance CLI from treating valid extension application/* media types as warnings. It does not add an OpenEnv type to ARD core.

The PRs are coordinated but independent. ARD already permits the extension type, and RFC 011 does not depend on the diagnostic change. Together they make the extension path understandable and reviewable.

flowchart LR
  subgraph Contracts["Coordinated, independent drafts"]
    O["OpenEnv RFC 011<br/>domain contract"]
    A["ARD PR 85<br/>extension diagnostics"]
  end
  subgraph Later["Later product work, not shipped here"]
    B["Offline benchmark"] --> H["Hugging Face provider adapter"] --> P["Public ARD entries"] --> S["Second-provider portability spike"] --> C["openenv discover"]
  end
  O --> B
  A -. "cleaner conformance output,<br/>not a prerequisite" .-> P

Loading

Why this matters

OpenEnv can resolve known environments, but it cannot search by task for one the user does not know. ARD supplies generic discovery and federation, OpenEnv supplies environment semantics, and adapters map native inventory and provider facts.

On 2026-08-26, a one-day probe enumerated 14 public first-party openenv/* Spaces; 13 met eligibility. Hub semantic retrieval surfaced 2/13 with running-only defaults and 7/13 when non-running candidates were included. These snapshot observations are feasibility evidence, not a benchmark. Search cannot define inventory; an independently audited provider snapshot must define ground truth before ranking.

Proposed decisions

• Carry the experimental Environment Card through ARD's open media-type envelope.
• For resolvable environments, separate logical identity, one card per immutable revision, revision-bound provider-native source identity, and dynamic provider projections. One source record may yield multiple environment cards.
• Keep ARD publisher, OpenEnv owner, provider source, and optional canonical identity as distinct claims; never infer licenses or trust.
• Represent resolvable, external, and unknown artifacts, and distinguish declared MCP from validation evidence bound to the same artifact revision.
• Keep orchestration separate from agent tools. openenv discover is metadata-only: no install, import, image pull, wake, reset, step, default endpoint probe, or MCP call.
• Allow a user-directed assistant to query metadata while keeping catalog access and simulation control away from the agent being trained.
• Keep execution-provider offers, Train or evaluation jobs, runs, rollouts, and traces outside the Environment Card.
• Reuse RFC 008 reports rather than defining another validation format.

Scope

This PR changes only:

• rfcs/011-ard-catalog-discovery.md
• rfcs/README.md

It does not add a CLI command, registry, adapter, crawler, ranking service, runtime endpoint, or dependency. Diagrammed product stages are later work.

What we need from reviewers

The RFC has 15 open questions. Four are acceptance-blocking: where the card schema lives, how generation and metadata precedence work, which second provider and source profile prove portability, and whether the benchmark stop rule is acceptable.

Also review the v0.1 portability gate: resolvable cards describe one immutable revision; provider-native source identity supports multiple environments in one source record; a user-directed assistant may perform metadata-only discovery without exposing it to the agent being trained; and a public second-provider spike must return complete cards before CLI work. Lifecycle, private credentials, and dereference remain explicit open questions.

The adapter experiment stops if it cannot enumerate every independently eligible record. CLI work stops unless a frozen, independently labeled inventory shows the candidate ranker improving held-out nDCG@5 by at least 0.10 over the lexical baseline without reducing recall@5. The paired bootstrap 95% confidence interval's lower bound must remain above zero. The report is published even if the proposal fails.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run /pre-submit-pr or the applicable repository checks and addressed all issues

RFC Status

• Not required
• RFC exists: this PR adds draft RFC 011
• RFC needed before merge

Test Plan

Docs-only change:

• python3 scripts/sync_env_docs.py --check
• git diff --check
• Parsed all 3 JSON examples.
• Rendered all 5 Mermaid diagrams.
• Checked all local Markdown links.

Claude Code Review

Alignment review covered .claude/docs/PRINCIPLES.md, .claude/docs/INVARIANTS.md, and active RFCs. It corrected the static/dynamic provider split, ARD publisher trust, RFC 008 evidence reuse, the semantic orchestration boundary, and the independently labeled benchmark. No invariant violation remains.

Related work:

• RFC 008 (RFC: 008 Environment auto validation #778; document merged in RFC 008: Environment auto-validation #1041, status In Review)
• ards-project/ard-spec#44
• ards-project/ard-spec#66