Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

feat: define annotation namespaces and gateway-enforced ownership

オープン
  • 何か問題がありますか？
#4,333 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
grpc, rust
領域
backend-api-design, security

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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:

主要言語
Rust
スター
15.4k
フォーク
1.7k
平均マージ
1日 21時間
マージ済み PR（30日）
358

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

NVIDIA/OpenShell のほかの issue

NVIDIA/OpenShell の issue をすべて見る

似ている issue

Rust の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。