Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

feat: define annotation namespaces and gateway-enforced ownership

Abierto
  • ¿Algo no está bien?
#4,333 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
grpc, rust
Área
backend-api-design, security

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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:

Lenguaje dominante
Rust
Estrellas
15.4k
Forks
1.7k
Merge medio
2 d 3 h
PR fusionados (30 d)
374

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de NVIDIA/OpenShell

Todos los issues de NVIDIA/OpenShell

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.