Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

feat: define annotation namespaces and gateway-enforced ownership

Aberta
  • Algo errado?
#4,333 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
35/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
grpc, rust
Domínio
backend-api-design, security

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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:

Linguagem predominante
Rust
Estrelas
15.4k
Forks
1.7k
Merge médio
2d 6h
PRs com merge (30d)
397

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de NVIDIA/OpenShell

Todas as issues de NVIDIA/OpenShell

Issues semelhantes

Mais issues de Rust

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.