feat: define annotation namespaces and gateway-enforced ownership

[elezar]

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:

• PR CLI restriction rejects openshell.nvidia.com/.
• Gateway annotation validation checks syntax and size; sandbox creation copies request annotations into metadata.
• Compute annotation constants and session annotation constants use internal.openshell.ai/.
• UpdateConfig contract describes caller-provided opaque annotations and projection into sandbox metadata; tests supply openshell.nvidia.com/policy-signature and openshell.nvidia.com/policy-provenance.