Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

feat: define annotation namespaces and gateway-enforced ownership

Aperta
  • Qualcosa non va?
#4,333 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
grpc, rust
Ambito
backend-api-design, security

Direzione di ricerca

Start by inventorying annotation writers and readers at the cited gateway validation and sandbox creation paths, compute and session constants, UpdateConfig contract, and policy tests. Then define the ownership contract and trace every client-facing annotation write path, including retention and provenance compatibility. Done means documented namespaces, consistent gateway enforcement, and tests confirming allowed metadata, rejected writes, and preserved lifecycle and provenance behavior.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

User Story

As an OpenShell client developer or operator, I want a consistent annotation namespace and ownership contract enforced by the gateway, so that CLI, SDK, and direct API clients receive the same behavior and caller metadata remains usable.

Problem Statement

Review of PR #4325 identified that checking reserved annotation keys only in the CLI does not establish a contract across all clients. The review recommendation is to remove the CLI-only reserved-key check and its associated test and documentation claims from that PR, and address namespace consistency and any required reservation separately here.

Existing annotations use both openshell.nvidia.com/ and internal.openshell.ai/. These prefixes do not currently imply the same ownership rules: retention is supplied by the CLI and interpreted by the gateway, internal runtime/session annotations are gateway-managed, and existing policy-update tests accept caller/interceptor-supplied provenance under openshell.nvidia.com/.

Impact / Why This Matters

A CLI-only restriction produces different annotation behavior for otherwise equivalent clients. Blocking an entire prefix without defining its ownership can also reject existing provenance workflows while leaving a different namespace of gateway-managed metadata unrestricted.

Today, client developers must infer ownership from individual writers and readers and implement their own conventions. That workaround cannot guarantee consistency across clients or future annotation write paths.

Proposed Design

Inventory existing annotation keys and classify their intended writers and readers. Define and document consistent prefixes for caller metadata, gateway-managed state, and provenance supplied by integrations. Decide which prefixes or individual keys require reservation, rather than assuming every existing prefixed annotation must become reserved.

Where reservation applies, enforce it at gateway boundaries for every client-facing write path, including sandbox creation and sandbox-scoped configuration/policy updates. Define any supported trusted-integration behavior explicitly. Clients should receive a clear, consistent error when writing metadata they do not own.

Preserve ephemeral sandbox creation and existing supported provenance workflows, or document and test an explicit compatibility transition. Retention currently travels as an annotation from the CLI, so a blanket gateway rejection needs a replacement contract or a deliberate exception.

This is a follow-up to #4325 and #4303; it does not require implementing annotation ownership policy in the creation-time CLI flag change.

Acceptance Criteria

  • Existing annotation keys, prefixes, and intended ownership are inventoried, including retention, internal runtime/session state, and integration provenance.
  • A consistent annotation namespace and ownership contract is documented, identifying which keys/prefixes are reserved, if applicable.
  • Any reserved-key rules are enforced by the gateway on all applicable caller-facing annotation write paths, with the same behavior for CLI, SDK, and direct RPC clients.
  • Tests exercise gateway rejection of disallowed writes and acceptance of supported caller and integration metadata.
  • Ephemeral sandbox lifecycle and supported policy provenance remain functional; any intentional compatibility change has documented migration guidance and tests.
  • Public API documentation, user documentation, and related skills reflect the resulting contract.

Alternatives Considered

  • CLI-only reservation: Gives early feedback but produces inconsistent behavior across clients and misses other write paths.
  • Reserve all of openshell.nvidia.com/ immediately: Conflicts with existing provenance examples and CLI-supplied retention unless compatibility is addressed.
  • Leave all annotation ownership implicit: Avoids compatibility changes but perpetuates inconsistent namespaces and uncertainty about which metadata callers may write.

Agent Investigation

Source references are pinned to PR #4325 head ef959bc0eadca999e4dfae160165532a4dad97d0:

Lingua principale
Rust
Stelle
15.4k
Fork
1.7k
Merge medio
1g 19h
PR unite (30g)
347

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di NVIDIA/OpenShell

Tutte le issue di NVIDIA/OpenShell

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.