Scopes

What is a scope?

The scope of a roar workspace — the directory where you ran roar init, containing the .roar/ subdirectory — tells roar register where its records live, and who can read what.

Four flavors:

Scope is per-workspace: it persists under [scope] in .roar/config.toml and applies to every roar register from that workspace until you change it.

What scope actually controls

roar register ships four things to GLaaS as a unit:

• Artifacts — files (or composite artifacts) with content hashes.
• Jobs — recorded executions with command, inputs, outputs, environment, git info.
• Sessions / DAGs — the graph of jobs that built the artifact.
• Labels — any key/value metadata you've attached.

But the four don't share a single visibility setting. The split worth knowing:

• Artifact registration is always globally visible. GLaaS is a global content-addressable registry by design — anyone with a hash can ask "is this registered?" and get a yes/no regardless of who registered it or under which scope. Two organizations can register the same dataset under their respective private scopes; both registrations co-exist; each org sees their own attached metadata and lineage. This is the point.
• Everything attached to the registration is scope-controlled. Artifact metadata beyond the hash (size, paths, attribution), the jobs that produced or consumed the artifact, the DAGs they form, and labels — these obey the scope rule below.

Visibility matrix

⃰ Today, jobs and DAGs registered under anonymous or public scope are conservatively treated as scope-only on the server side. The eventual public surface — possibly with sensitive fields redacted (git remotes, absolute paths, environment variables) — is being designed; we'll update this note when it ships.

The shorthand: a hash is forever and global; what was attached to that hash is read-controlled.

Quick use

roar scope                         # show this repo's scope + what's available
roar scope use <name>              # set the scope for this repo
roar scope list                    # list scopes available with current auth
roar scope clear                   # unset; next register prompts you to pick

You can also override the persistent scope on a single invocation:

roar register @5 --public          # one-off public publish, scope unchanged
roar register @5 --anonymous       # one-off anonymous publish (no account needed)

The four scopes in detail

anonymous

No account, no login. The artifact registration goes to GLaaS without an account attached; anyone with the hash can ask GLaaS whether it's registered (always true once you've registered it) and read the artifact metadata (size, attribution-free) and labels. The job and DAG records are kept scope-only today — see the visibility matrix.

Picked by default by roar init so you can try roar end-to-end before signing up. Every roar register under anonymous prompts for confirmation; bypass with roar register -y (CI / scripted use).

Anonymous is not "hidden." It's unattributed — GLaaS doesn't know who created the record — but the artifact's existence is globally visible by hash. The friction prompt is there because registration is irreversible from roar's side.

private

Logged in; the registration carries your account attribution and the attached records (metadata, jobs, DAGs, labels) are access-controlled to you (plus anyone you explicitly grant access via GLaaS). The closest analogue to a private git repo. This is what an authenticated repo gets by default when no project is bound.

public

Logged in; the registration is published with your identity attached. Visible to anyone, attributed to your GLaaS account. For open-source releases, papers, blog-post lineage — anything where you want both the artifact and the author to be discoverable.

Differs from anonymous in attribution, not in raw visibility: both make the artifact registration globally readable. public additionally signs it with your account; both keep the attached jobs/DAGs scope-only today.

<owner>/<project>

Logged in; the record is stored under a specific GLaaS project. Visibility is governed by that project's membership and settings — typically "members of this org's project can see this." The right choice when you're working inside an org, contributing to a team artifact, or producing TReqs-linked work.

List your available projects with roar scope list; switch with roar scope use treqs/mnist (or whatever the <owner>/<project> identifier is).

Picking a scope

roar init sets the scope to anonymous by default and prints a hint explaining what that means. From there:

• To try roar without signing up. Do nothing — anonymous is the default. Each roar register will prompt to confirm; pass -y once you've understood the tradeoff.
• To work privately on your laptop. roar login (free; one-time). If your workspace's scope is still the init default, login auto-flips it from anonymous to private and tells you how to pick a project instead. From then on every register from this workspace is access-controlled.
• To contribute to a team project. roar scope use <owner>/<project>. List available scopes from your account with roar scope list. Registers from this workspace go to that project's bucket and inherit its membership.
• To publish persistently public, with your account attached. roar scope use public. Open-source releases, papers, blog-post lineage.
• To publish a one-off public artifact without changing the workspace's scope. roar register @5 --public (per-invocation override; scope unchanged).
• For public lineage without your GitHub identity attached. roar register @5 --anonymous. The artifact is registered globally but unattributed; one-off, doesn't change the workspace scope.

The login auto-flip only happens when scope hasn't been explicitly set yet — if you previously picked a project, login leaves it alone.

Avoiding accidents

Three places roar makes scope visible so you don't ship under the wrong one:

• Every roar register under anonymous prompts to confirm before publishing. Not just the first one: it fires every time, because each register is a separately discoverable record and the visibility implication shouldn't fade after the first prompt. -y skips it; set scope to anything else and the prompt disappears.
• Visibility-increasing scope changes (private → anonymous, <owner>/<project> → public) prompt to confirm. Decreasing exposure (the other direction) is always safe and doesn't prompt.
• roar scope as a status command shows the active scope at a glance — like roar status does for sessions. Run it whenever you're not sure.

Configuration

The active scope persists in .roar/config.toml under [treqs]. Don't edit by hand — roar scope use is the supported surface.

Other relevant keys:

FAQ

Can I change the scope of a record after registration? No. Each register is an atomic publish under the active scope; there's no "make this private now" operation. The friction prompts are designed around this.

What happens if two organizations register the same dataset? Both registrations co-exist. GLaaS deduplicates by content hash, so the artifact's existence is one global fact. But the attached records — each org's jobs, their DAGs, their labels — are kept scope-separate. Org A asking "is abc123… registered?" gets a yes; org A asking "what jobs produced it?" gets only their own jobs back. This is the point of being content-addressable: shared datasets, separate provenance trails.

Does scope affect data stored locally? No. Scope is purely about what roar register publishes to GLaaS. Your local .roar/ directory is yours regardless.

Is anonymous really anonymous? GLaaS doesn't store who created the record — no account, no attribution, no email. The artifact's existence is world-readable by hash, the artifact's metadata is publicly readable, and the underlying network connection has whatever metadata your client environment provides (IP address, user agent). It's "no account required" privacy, not "untraceable" privacy.

Can someone search GLaaS for my private artifacts? Only by hash. There's no global listing of "all artifacts under user X" or "everything in project Y" — those are scope-internal. But if someone already knows a hash you registered privately, they can ask GLaaS "is this registered?" and learn yes/no. They can't read the metadata, jobs, DAGs, or labels.

What's the relationship to roar projects?roar projects link / unlink / list is the older command surface for the project-scope flavor. It still works (as a hidden alias) — roar scope is the unified replacement. roar scope use <owner>/<project> does what roar projects link <project_id> did, plus more.

What about --private and --anonymous flags on roar register? Per-invocation overrides. They work alongside roar scope. Use them for one-offs; use roar scope use for "this whole repo is private from now on."

Where to look next

• Quick Start — first-time setup; defaults to anonymous scope.
• roar Guide — full CLI reference, including the auth flow.
• Labels — labels are part of the record that scope governs.
• Troubleshooting — error messages tied to scope (missing binding, login required, etc.).