You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Issue #2565 — API Surface Inventory: Summary of Findings
Companion to api-surface-inventory-2565.md. Read this first; the inventory is the reference.
Scope: first deliverable of NVIDIA/OpenShell#2565 — "A reviewed inventory of every public API, SDK, configuration, and extension contract, with owners and stability classifications."
Built by reading the tree at branch docs/multi-gateway-oidc-isolation (base 596d729e). All counts are mechanical (grep / descriptor parse), and the commands are listed in §12 of the inventory so the numbers can be regenerated rather than trusted.
What the inventory covers
21 distinct contract surfaces, each with a proposed classification (public/stable, public/experimental, internal) and an unfilled Owner column for maintainers.
3 SDKs (Rust, Python, TypeScript), the CLI, 4 configuration formats, the OCSF event stream, HTTP probe/metrics endpoints, and the identity vocabulary
3 wire-level extension protocols (compute driver, gateway interceptor, supervisor middleware), plus 4 in-process Rust trait extension points that the issue's "credential drivers / other extension points" bullet implies
The centerpiece is a machine-extracted 64-row RPC → auth_mode / scope / workspace_role / global_role matrix for openshell.v1.OpenShell, parsed from the proto annotations themselves so it regenerates instead of rotting.
One genuine strength worth preserving as a documented guarantee: crates/openshell-server/src/auth/descriptor_authz.rsfails gateway startup when a method is missing its (openshell.options.v1.authorization) annotation or uses an unknown auth_mode. Authorization coverage is structurally enforced, not conventionally hoped for.
Findings that change sequencing
Sixteen gaps are recorded in §10 of the inventory, each mapped to a #2565 deliverable. These six matter for ordering the work:
No protobuf breaking-change detector. There is no buf.yaml / buf.work.yaml anywhere in the tree and no CI job that diffs descriptors; protoc 29.6 is pinned in mise.toml for codegen only. Nothing prevents a field-number reuse or a wire-incompatible edit from merging today. Every later stabilization decision needs this mechanism to already exist — land it first.
Pagination is truncation-blind.ListSandboxes, ListProviders, ListWorkspaces, and ListServices accept limit/offset, but no response carries a total, a next-offset, or a truncation flag — a client cannot distinguish a full page from a truncated one. Four further List RPCs (ListSandboxProviders, ListProviderProfiles, ListSandboxPolicies, ListWorkspaceMembers) have no paging at all. Offset paging is also unstable under concurrent mutation.
Workspace defaulting is a proto3 trap. Many requests document workspace as "empty defaults to default". Proto3 cannot distinguish unset from empty, so this is unfixable after the beta boundary without introducing a wrapper type. Decide before, not after.
GetGatewayConfig carries no role requirement — bearer + config:read and nothing else — while the adjacent GetGatewayInfo requires platform_admin and UpdateConfig requires workspace admin. Raised as an authorization-consistency item for owner review. I did not audit the response message field-by-field, so whether this is a vulnerability or merely an inconsistency depends on what the response actually contains.
The Rust SDK's raw module is the only path to most of the API. Inference, providers, policy, logs, settings, SSH, and forwarding are reachable only through the module the crate docs label an "escape hatch". Either promote those domains into the curated surface before beta or state plainly that raw is de-facto stable. Leaving it labelled provisional while it is the sole path to half the API is the least honest option.
The workspace version is 0.0.0. Root Cargo.toml says version = "0.0.0"; the Python package uses dynamic = ["version"]. A beta boundary cannot mean anything until there is a version scheme for the gateway, the CLI, each SDK, the supervisor image, and each extension protocol.
Two structural observations that shape the breaking-change batch:
Capability negotiation is done three different ways across the three extension protocols — a free-form driver_version string (compute driver), service_version plus declarative bindings (supervisor middleware), no version field at all (gateway interceptor) — and not at all in the core API. GetGatewayInfo is platform_admin-only, so ordinary clients cannot probe for features.
Interceptors reference gateway RPCs by name string.InterceptorEvaluation.service / .method carry public service and method names, so renaming any public RPC breaks interceptors even when the wire format is unchanged. The compatibility policy has to state that public method names are part of the contract.
Also outstanding: exactly one deprecated field in the tree, SandboxPolicy.harness (proto/sandbox.proto:292) — the beta boundary is the moment to remove it.
Three blocking questions for maintainers
@openshell/sdk is not in this repository.AGENTS.md and the Rust SDK crate docs both describe a napi-rs wrapper shipping under that name, but there is no napi crate, package.json, or TypeScript source in the tree. Where does it live, who owns it, and is it inside the beta boundary? It cannot be inventoried or classified until located.
The sandbox metadata server (openshell-sandbox::metadata_server, exposed via the MetadataHandler trait) serves HTTP inside the sandbox and is reachable by any process there, including agent code. Supported in-sandbox API, or internal? Silence defaults it to accidentally public.
The Rust and Python SDKs cover different subsets of the gateway API, not nested ones — Python has inference route CRUD that Rust's curated surface lacks; neither covers providers, policy, or settings. Which shape is the reference for the "align equivalent concepts across SDKs" work?
Suggested order of work
Maintainers fill the Owner column and confirm the classifications; resolve the three blocking questions and the two design cutoffs that cannot be deferred (pagination shape, workspace defaulting).
Land protobuf CI gates.
Add a machine-readable stability annotation so the classification table becomes enforceable and can generate the docs deliverable.
Generate the gRPC reference from descriptors, with a CI drift check.
Write the compatibility policy, using the field-reservation practice already in compute_driver.proto and the manifest versioning in supervisor_middleware.proto as in-repo precedent.
Public Contract Inventory — Issue #2565 (Pre-Beta API Stabilization)
Working inventory for the first deliverable of #2565:
"A reviewed inventory of every public API, SDK, configuration, and extension contract, with owners and stability classifications."
Status: draft inventory. Classifications below are proposals — they need owner sign-off before they become the beta contract. Owner column is intentionally unfilled; maintainers assign.
Facts in this document were read from the tree at docs/multi-gateway-oidc-isolation (base 596d729e). Counts are mechanical (grep/descriptor parse), not hand-tallied.
Every RPC carries a mandatory (openshell.options.v1.authorization) annotation. crates/openshell-server/src/auth/descriptor_authz.rsfails startup if a method lacks the option or uses an unknown auth_mode — this is a real strength and should be documented as a guarantee, not left as an implementation detail.
Scope vocabulary to freeze at beta: sandbox:read/write, provider:read/write, config:read/write, workspace:read/write, inference:read/write (S2). Role vocabulary: workspace user/admin, global platform_admin.
9 fields across the tree carry (openshell.options.v1.secret) = true. This is the redaction boundary for interceptors (S8) — the annotation's meaning is itself a public contract for extension authors.
3. S2–S5 — Adjacent Proto Packages
S2 openshell.inference.v1.Inference — 4 RPCs, 12 messages. GetInferenceBundle is sandbox-auth; the three route CRUD RPCs are bearer with inference:{read,write} (write requires workspace admin). Served on the same multiplexed listener as S1.
S3 openshell.datamodel.v1 — ObjectMeta, Workspace, WorkspaceStatus, WorkspacePhase, Provider. Shared identity/metadata shape across S1 and S2; the ObjectMeta field set (name, labels, resource version, workspace) is the closest thing OpenShell has to a resource convention and should be documented as such.
S4 openshell.sandbox.v1 — 22 messages, 2 enums. Carries SandboxPolicy, FilesystemPolicy, LandlockPolicy, ProcessPolicy, NetworkPolicyRule, the whole L7 rule tree (L7Rule, L7Allow, L7DenyRule, L7QueryMatcher, McpOptions, GraphqlOperation), NetworkMiddlewareConfig, and the settings model (SettingScope, SettingValue, EffectiveSetting, PolicySource). This is dual-surface: it is both a gRPC contract and the structural source of truth behind S15's YAML.
S5 openshell.options.v1 — 1 message + 2 extensions on field numbers 50000/50001. Extension numbers are themselves a compatibility commitment.
4. S6 — Supervisor↔Gateway Channel
The 8 sandbox-auth RPCs in §2.1 plus openshell.sandbox.v1.GetSandboxConfigRequest/Response form the gateway↔supervisor contract. Recommend classifying internal but noting the operational constraint: the supervisor image version is coupled to the gateway version, so the compatibility matrix (S-deliverable) must state the supported gateway↔supervisor version skew. gateway.toml already lets operators pin supervisor_image independently of the gateway version, which makes skew a reachable state, not a theoretical one.
7 RPCs: GetCapabilities, ValidateSandboxCreate, CreateSandbox, GetSandbox, ListSandboxes, StopSandbox, DeleteSandbox, WatchSandboxes (stream). 28 messages. Deliberately isolated from S1's public resource model — DriverSandbox/DriverSandboxSpec/DriverSandboxStatus are driver-owned, and the gateway translates. Already practises field reservation (reserved 4, 5; reserved "supports_gpu", "gpu_count" in GetCapabilitiesResponse; reserved 10 / "gpu_device" in DriverSandboxSpec) — good precedent to codify in the policy.
Consumed in-process by openshell-driver-{docker,podman,kubernetes} and over a socket by openshell-driver-vm. GetCapabilitiesResponse.driver_version is the only capability-negotiation handle today and it is a free-form string.
In-tree Rust-side surface: crates/openshell-core re-exports; drivers are separate crates, so the Rust trait boundary is also a de-facto extension API for anyone vendoring a driver.
3 RPCs: Describe → InterceptorManifest, SnapshotProviderProfiles, Evaluate. Phases: MODIFY_OPERATION, VALIDATE, POST_COMMIT (note 1 is skipped — enum already has a hole). InterceptorEvaluation identifies the target by public service/method strings, which pins S1's service and method names into the extension contract — renaming an S1 RPC is a breaking change for interceptors even if the wire format is compatible. Worth calling out explicitly in the policy.
Operator-facing config: [[openshell.gateway.interceptors]] + [[...bindings]] in gateway.toml, with GatewayInterceptorBindingPolicy, GatewayInterceptorFailurePolicy, GatewayInterceptorPhaseConfig enums (openshell-core::config). Docs: docs/extensibility/gateway-interceptors.mdx.
3 RPCs: Describe, ValidateConfig, EvaluateHttpRequest. MiddlewareManifest/MiddlewareBinding already self-describe version and limits (service_version, max_body_bytes, timeout with a documented 10ms–30s range and "may shorten but not extend the operator timeout" rule). The manifest comments say "V1 supports HTTP_REQUEST" / "V1 supports PRE_CREDENTIALS" — the enums are pre-shaped for growth, which is the right posture.
Operator-facing config: [[openshell.supervisor.middleware]] in gateway.toml, plus SupervisorMiddlewareService in proto/sandbox.proto and NetworkMiddlewareConfig/MiddlewareEndpointSelector in policy. Docs: docs/extensibility/supervisor-middleware.mdx. Rust: openshell-supervisor-middleware (registry + remote transport), openshell-supervisor-middleware-builtins.
Other extension points named in the issue
Credential providers — openshell-providers::ProviderPlugin trait plus DiscoveryContext. In-process trait only; no wire protocol. Either declare it internal or give it a protocol before calling it an extension point.
Provider profile sources — openshell-server::ProviderProfileSource trait; composed via GatewayProviderProfileSourceConfig (builtin, user, interceptor-supplied). The interceptor-backed variant makes this partly external via S8.
Escape hatch (propose public/experimental):raw — re-exports openshell_core::proto wholesale plus AuthedGrpcClient/AuthedInferenceClient tonic aliases. Everything not covered by the curated layer (inference, providers, policy, logs, settings, SSH, forwarding) is only reachable here, which means most real users touch raw. Decision needed: either promote the missing domains into the curated surface before beta, or accept that raw is de-facto stable and say so. Leaving it labelled "escape hatch" while it is the only path to half the API is the least honest option.
Also public: auth, config, edge_tunnel, error, oidc, refresh, transport, types modules. edge_tunnel (Cloudflare Access proxy) and transport leak deployment specifics into the SDK surface — candidates for #[doc(hidden)] or internal reclassification.
S11 Python (python/openshell)
Hand-written wrapper over generated stubs. Public classes: SandboxClient, SandboxSession, Sandbox, SandboxRef, SandboxStatusRef, ExecChunk, ExecResult, SandboxError, TlsConfig, InferenceRouteClient, InferenceRouteConfig, WorkspaceClient, WorkspaceRef. __all__ in __init__.py is the declared surface — verify it matches the intended set before beta.
Notes for review: SandboxClient.from_active_cluster() reads XDG_CONFIG_HOME gateway state and OIDC token bundles from disk, coupling the SDK to CLI on-disk layout — that layout becomes a contract by implication. Generated _proto/*_pb2.py stubs are checked in for 5 of 9 protos (datamodel, inference, openshell, options, sandbox); e2e regenerates them in CI, so there are two sources of truth.
Feature parity gap vs. S10: Python has inference route CRUD, Rust does not (curated). Rust has wait_* helpers and Python has them too, but Rust lacks provider/policy/settings coverage that Python also lacks. Neither covers the full S1 surface; the two cover different subsets. Aligning these is squarely in scope for the "align equivalent concepts across SDKs" bullet.
S12 TypeScript (@openshell/sdk)
Referenced by AGENTS.md and the S10 crate docs as "the napi-rs wrapper that ships as @openshell/sdk", but there is no napi crate, package.json, or TS source in this repository (only scripts/lint-mermaid/ node_modules). It lives elsewhere or has not landed. Blocking question for the inventory: where does it live, who owns it, and is it in scope for the beta boundary? If yes, it needs its own parity review against S10/S11.
Machine-readable output is a contract: OutputFormat and PolicyGetOutput enums gate JSON/YAML emission consumed by scripts and agents. Propose: JSON output shapes are public/stable; human-readable text is explicitly not a contract; rule and doctor are internal (already hidden); ssh-proxy token mode is internal (sandbox connect implementation detail) while name mode is public (documented for ~/.ssh/config).
Also part of the CLI contract by implication: exit codes, XDG_CONFIG_HOME gateway directory layout, and shell-completion behaviour.
Tables: [openshell], [openshell.gateway]{.tls,.oidc,.auth,.mtls_auth,.gateway_jwt,.otlp}, [[openshell.gateway.interceptors]]{.bindings}, [[openshell.supervisor.middleware]], [openshell.drivers.<name>]. Documented source precedence and package-managed locations are part of the contract.
PolicyViolation and L7ConfigStanza are user-visible. SandboxPolicy.harness is the tree's only[deprecated = true] field — needs a removal decision at the beta boundary.
Provider profile YAML
providers/*.yaml (13 profiles)
providers docs
Schema: id, display_name, description, category, credentials[]{name, description, env_vars, required, refresh{strategy, refresh_before_seconds, max_lifetime_seconds, additional_outputs[], material[]{name, description, required, secret}}}. Refresh strategy values (e.g. aws_sts_assume_role) are an enum-by-convention with no schema enforcement. Shipped profiles are data and the schema's only specification.
Helm values
deploy/helm/openshell/values.yaml (414 lines)
chart README
Top-level keys: replicaCount, workload, image, supervisor, imagePullSecrets, nameOverride, fullnameOverride, serviceAccount, sandboxServiceAccount, podAnnotations, podLabels, podSecurityContext, securityContext, service, podLifecycle, probes, resources, nodeSelector, tolerations, affinity, server, networkPolicy, pkiInitJob, certManager, grpcRoute. server (150 lines) renders gateway.toml, so S14 and S17 must move together.
S18 OCSF — openshell-ocsf, OCSF_VERSION = "1.7.0", 8 event classes: Network Activity, HTTP Activity, SSH Activity, Process Activity, Detection Finding, Application Lifecycle, Device Config State Change, Base Event. JSONL output is shipped to external systems, so field names, the shorthand format, and severity mapping are all consumer-visible. Upstream OCSF version bumps are a compatibility event for downstream parsers and need a stated policy.
S19 HTTP — /healthz, /readyz (openshell-server/src/http.rs), /metrics (Prometheus text). /health also routed in multiplex.rs. Response bodies and status-code semantics are probe contracts; metric names and labels are dashboard/alert contracts and are currently undocumented.
S20 Identity — scope and role vocabulary from §2.1, [openshell.gateway.oidc] claim mapping, the gateway-minted sandbox JWT (DriverSandboxSpec.sandbox_token, K8s projected-SA-token variant), and mTLS auth. IdP-side configuration expectations are documented in docs/reference/gateway-auth.mdx.
S21 Sandbox metadata server — openshell-sandbox::metadata_server exposes an HTTP surface inside the sandbox via the MetadataHandler trait (method + path + raw body, with a timeout). Reachable by any process in the sandbox, i.e. by agent code. Needs an explicit classification — it is either a supported in-sandbox API or it must be documented as internal.
10. Gaps Found While Inventorying
These are findings, not scope creep — each maps to a #2565 deliverable.
Tooling and gates (deliverable: "automated compatibility checks and release gates")
No protobuf linter or breaking-change detector. There is no buf.yaml/buf.work.yaml anywhere in the tree and no CI job that diffs descriptors. protoc 29.6 is pinned in mise.toml for codegen only. Nothing prevents a field-number reuse or a wire-incompatible edit from merging today. This is the single highest-leverage gap.
Two sources of truth for Python stubs.python/openshell/_proto/*_pb2.py are committed for 5 protos while e2e-test.yml regenerates stubs in CI. Drift is silent.
No generated gRPC reference.docs/reference/ has six pages, none of them a proto reference. Confirms that deliverable is greenfield.
Versioning (deliverable: "versioning strategy")
4. Workspace version is 0.0.0. Root Cargo.toml carries version = "0.0.0" and the Python package uses dynamic = ["version"]. Before a beta boundary can mean anything, the version scheme for the gateway, CLI, each SDK, the supervisor image, and each extension protocol has to be decided — and #2565 asks for exactly that.
5. No stability annotations in proto. Classification lives nowhere machine-readable. Consider a (openshell.options.v1.stability) method/message option so the classification in §1 is enforceable and renderable into docs.
6. Capability negotiation is ad hoc. S7 has driver_version (free string), S9 has service_version + declarative bindings, S8 has a manifest with no version field, and S1/S2 have no capability-discovery RPC at all (GetGatewayInfo is platform_admin-only, so ordinary clients cannot probe features). The issue calls for version/capability negotiation; today three extension protocols do it three different ways and the core API does not do it.
API design consistency (deliverable: "align equivalent concepts")
7. Pagination is truncation-blind.ListSandboxes, ListProviders, ListWorkspaces, ListServices take limit/offset, but no response carries a total, a next-offset, or a truncation flag — a client cannot tell a full page from a truncated one. ListSandboxProviders, ListProviderProfiles, ListSandboxPolicies, ListWorkspaceMembers have no paging at all. Offset paging is also unstable under concurrent mutation.
8. GetGatewayConfig has no role requirement — bearer + config:read and nothing else, while the neighbouring GetGatewayInfo requires platform_admin and UpdateConfig requires workspace admin. Any authenticated caller holding config:read can read gateway config. Flagging as an authorization-consistency item for owner review; whether it is a vulnerability depends on what the response actually contains, which I did not audit field-by-field.
9. Workspace defaulting is implicit. Many requests document workspace as "empty defaults to default", with all_workspaces as a mutually-exclusive bool. Proto3 cannot distinguish unset from empty, so "unset means default workspace" is unfixable later without a wrapper type — decide now.
10. GatewayInterceptorPhase skips value 1 and MODIFY_OPERATION is 2. Harmless but worth a reserved 1 for clarity.
11. S8 pins S1 method names.InterceptorEvaluation.service/method are strings naming public RPCs, so any S1 rename breaks interceptors. The policy must say that public gRPC method names are part of the contract, not just their wire encoding.
12. One deprecated field outstanding — SandboxPolicy.harness (proto/sandbox.proto:292). The beta boundary is the moment to remove it.
13. Field reservation practice is uneven. 6 tag reservations tree-wide (compute_driver.proto ×2, openshell.proto ×4 with matching name reservations, sandbox.proto ×2 without name reservations). No enum has ever reserved a value. Needs a rule, not a habit. See the proto audit (§4 F8) for detail.
Ownership and scope
14. S12 (@openshell/sdk) is referenced but absent from the repo. Cannot be inventoried or classified until located. Blocking question for maintainers.
15. S21 (sandbox metadata server) is unclassified. In-sandbox agent code can reach it; silence defaults it to "accidentally public".
16. Rust SDK raw is the only path to most of S1. See §6. Requires a decision, not just a label.
11. Suggested Next Steps
Maintainers fill the Owner column in §1 and confirm/adjust the proposed classifications. Resolve the three blocking questions (gaps 14, 15, 16) and the two design cutoffs that cannot be deferred (gaps 7, 9).
Land protobuf CI gates first (gap 1) — every later breaking-change decision needs a mechanism to enforce it.
Add a machine-readable stability annotation (gap 5) so §1 becomes enforceable and can generate the docs deliverable.
Generate the gRPC reference from descriptors with a CI drift check.
Write the compatibility policy, using the reservation and manifest-versioning practices already in compute_driver.proto and supervisor_middleware.proto as the in-repo precedent.
12. How This Was Built
Reproducible commands, so the inventory can be regenerated rather than trusted:
Verdicts are static-analysis based. Rules about historical mutations (tag reuse, type changes,
repeated→scalar, default changes) cannot be verified from one tree state; they are marked
unverifiable with a note on what the current state implies.
1. Rule-by-rule scorecard
#
Rule
Verdict
Evidence
1
Don't re-use a tag number
Unverifiable / at risk
6 reservations exist, so deletions have occurred. No CI gate detects reuse (§4 F1). Risk is amplified by F1: serialized protos live in the DB, not just logs.
2
Do reserve tag numbers for deleted fields
Partial
6 number reservations across 3 files. sandbox.proto:243 and :274 reserve numbers but not names.
3
Do reserve numbers for deleted enum values
N/A
No enum values deleted; no enum carries reserved. No practice established.
4
Do put new enum aliases last
N/A
No allow_alias anywhere.
5
Don't change the type of a field
Unverifiable
—
6
Don't add a required field
Pass
All files proto3; no required keyword. No misuse of a // required comment convention either (the 7 "required" hits are prose or bool required profile fields).
7
Don't make a message with lots of fields
Pass
Largest is NetworkEndpoint at 23 fields. Only 5 messages exceed tag 15.
8
Do include an unspecified value in an enum
Pass — full compliance
All 14 enums declare *_UNSPECIFIED = 0 as the first value. Best-in-class result.
9
Don't use C/C++ macro constants for enum values
Pass
No NULL/NAN/DOMAIN/ERROR/MAX/MIN value names.
10
Do prefer extensions over Any
Pass
Zero google.protobuf.Any. Two custom extensions on MethodOptions/FieldOptions (authorization, secret) — the recommended pattern. But see F7: 11 google.protobuf.Struct fields are a related schemaless escape.
11
Do use well-known types and common types
Fail
Zero uses of Timestamp or Duration. 37 hand-rolled int64 *_ms timestamps; 4 different duration encodings. → F3
12
Do define message types in separate files
Deviation
openshell.proto is 2,600 lines / 180 messages / 64 RPCs / 6 enums in one file. → F10
13
Don't change the default value of a field
Unverifiable
Aggravated by the "empty workspace means default" convention (inventory gap 9).
14
Don't go from repeated to scalar
Unverifiable
—
15
Do follow the style guide for generated code
Partial
No file-level options set at all (no go_package, java_package, java_outer_classname). Acceptable today — only Rust (prost/tonic) and Python (grpcio-tools) are generated, neither of which needs them. Becomes a gap the moment a Go or Java client is wanted.
16
Don't use text format messages for interchange
Pass
No text_format / .textpb usage in crates/, python/, or e2e/.
17
Never rely on serialization stability across builds
At risk
F1: proto payloads are the DB storage format. Not a cache-key misuse, but the same fragility class — worth an explicit check that no code hashes or compares serialized bytes.
18
Don't generate Java protos in the same package as other code
N/A
No Java generation.
19
Do derive Java package from the .proto package
N/A
No Java generation.
20
Avoid using language keywords for field names
Fail
bool global (×3) is a hard Python keyword — attribute access is a SyntaxError. string type (×6) is a Rust keyword → r#type. string from (×1). → F2
21
Do use different messages for RPC APIs and storage
Fail — most severe
7 public RPC messages are persisted verbatim as the DB payload. → F1
22
Don't use booleans for something with two states now that might have more later
Fail
verify/no_verify bool pair encodes tri-state; 20+ single-bool ack responses; bool global duplicates an existing enum. → F4, F5, F6
Worth stating plainly, because these are the parts the beta policy should lock in rather than change:
Enum hygiene is complete. 14/14 enums have *_UNSPECIFIED = 0 first, with consistent
SCREAMING_SNAKE prefixed value names. Nothing to fix.
No Any. The two custom option extensions (authorization, secret) are exactly the
pattern protobuf.dev recommends over Any, and authorization is enforced at startup.
Field reservation is already practised in compute_driver.proto (supports_gpu, gpu_count,
gpu_device) and openshell.proto (phase, current_policy_version, gpu_device,
proposal_approval_mode, volume_claim_templates). The habit exists; it needs to become a rule.
Driver/public model separation is deliberate and documented.compute_driver.proto explicitly
refuses to import the public Sandbox/SandboxPhase, and the header comment in openshell.proto
states the translation invariant. This is the right instinct — F1 is what happens where that
instinct was not applied.
Message sizes are healthy. No 100-field monsters, minimal 2-byte-tag territory.
supervisor_middleware.proto self-describes versions and limits (service_version,
max_body_bytes, bounded timeout) and pre-shapes its enums for growth.
3. Correction to the inventory
api-surface-inventory-2565.md §10 gap 13 says openshell.proto has "9 reserved statements".
That count came from grep -c reserved, which matched the SPDX header line
("All rights reserved") and prose comments. The real figure is 4 tag reservations + 4 name
reservations in openshell.proto, and 6 tag reservations total across the tree. The gap's
conclusion is unchanged and slightly strengthened: reservation practice is uneven and needs a rule.
4. Findings, ranked
F1 — Public RPC messages are the database storage format (rule 21)
crates/openshell-server/src/persistence/mod.rs decodes DB rows straight into public protos:
fn decode_record<T:Message + Default + SetResourceVersion>(record:ObjectRecord)
-> PersistenceResult<T>{letmut message = T::decode(record.payload.as_slice())?;// payload IS the proto
impl ObjectType for … confirms which types are persisted this way:
Consequence for #2565: every pre-beta breaking change to these messages is simultaneously a data
migration. The two concerns the rule exists to separate are fused. The codebase has already been
bitten — decode_record's own comment records it:
"This is a breaking upgrade — pre-workspace records will carry an empty workspace until they are re-created."
This also escalates rule 1 from "a stale copy might exist in a log" to "stale copies are the
production dataset," and makes rule 17 (serialization stability) load-bearing.
Additionally, 4 pure-storage messages — StoredProviderCredentialRefreshState,
StoredProviderProfile, StoredPolicyRevision, StoredDraftChunk — are declared inside the
public openshell.v1 package despite appearing in no RPC signature. They ship in every generated
client, are visible in the descriptor pool, and would fall under any "no breaking changes to
openshell.v1" promise.
Options, cheapest first:
Move the 4 Stored* messages to an internal package (openshell.internal.storage.v1) in their
own file. Non-breaking on the wire; excludes them from the beta promise immediately.
For the 7 dual-purpose types, introduce storage twins and translate at the persistence boundary —
the same pattern compute_driver.proto already uses for DriverSandbox. Costly but it is the
rule's actual remedy, and pre-beta is the only cheap moment.
Minimum if (2) is deferred: document explicitly that these messages carry a storage contract,
forbid tag reuse in them permanently, and add a migration checklist to the compatibility policy.
F2 — bool global is a Python keyword; attribute access is a syntax error (rule 20)
Every Python SDK consumer touching global-scoped policy or settings must use getattr/setattr.
This is precisely the "protobuf may rename such fields and provide non-standard access patterns"
outcome the rule warns about. Renaming is breaking, so it has to happen before the beta boundary.
string type (×6: compute_driver.proto:187,205; datamodel.proto:76; openshell.proto:860,891;
supervisor_middleware.proto:164) is a Rust keyword; prost emits pub r#type: String — verified in
target/debug/build/openshell-core-*/out/openshell.v1.rs:189. Lower severity (codegen handles it)
but non-idiomatic in the SDK's own language. string from (gateway_interceptor.proto:138) is a
Python keyword in the same class.
Fix: rename global → scope (see F5, which wants an enum there anyway), type → a
domain-specific name (endpoint_type, event_type, condition_type), from → from_header or
source. Reserve the vacated tags and names.
F3 — No well-known types for time; four duration encodings (rule 11)
Zero google.protobuf.Timestamp / Duration in the tree. Instead:
The string form is the most interesting: supervisor_middleware.proto needed sub-second precision
and reached for a hand-parsed string with a documented 10ms–30s range, which is exactly the problem
Duration solves. Millisecond timestamps also mean sub-millisecond precision is unreachable, and
optional int64 expires_at_ms (openshell.proto:1569) is doing by hand what Timestamp's message
presence gives for free.
Fix: migrate to Timestamp/Duration at new tag numbers, reserve the old ones. Breaking, so
pre-beta. If the team consciously prefers scalar epoch-millis for JSON ergonomics or Rust
convenience, that is a defensible call — but it should be a written, uniform decision that at
minimum collapses four duration encodings into one, not the current accident.
F4 — verify / no_verify: two booleans for one tri-state (rule 22)
inference.proto:85-87 in SetInferenceRouteRequest:
bool verify = 4; // Verify the resolved upstream endpoint synchronously before persistence.
bool no_verify = 5; // Skip synchronous endpoint validation before persistence.
Four wire states encode three intents, one of which (verify=true, no_verify=true) is
contradictory and has no defined resolution in the proto. {false,false} presumably means
"server default" — undocumented. Should be one enum:
VERIFICATION_UNSPECIFIED / VERIFICATION_REQUIRED / VERIFICATION_SKIPPED, which also leaves room
for VERIFICATION_ASYNC later.
F5 — The SANDBOX/GLOBAL axis is encoded three different ways (rules 20, 22)
The same two-valued concept appears as:
openshell.sandbox.v1.SettingScope — UNSPECIFIED / SANDBOX / GLOBAL (enum, correct)
openshell.sandbox.v1.PolicySource — UNSPECIFIED / SANDBOX / GLOBAL (a second identical enum)
bool global in three request messages (F2's keyword problem)
So the codebase already agreed this should be an enum — twice — and then used a bool in the requests
anyway. Consolidating on SettingScope fixes F5 and F2 together and makes room for a future
workspace-level scope, which the workspace model makes plausible.
F6 — Single-bool ack responses cannot be extended (rule 22)
~20 responses whose entire payload is one boolean: bool deleted (×8 across sandbox, service,
provider, provider-profile, provider-refresh, workspace, inference-route), plus revoked,
attached, detached, imported, updated, removed, success, valid.
These cannot express states that delete/attach operations routinely need: already absent,
accepted but asynchronous, partially applied, succeeded with warnings. DeleteSandbox in
particular is asynchronous — the sandbox enters SANDBOX_PHASE_DELETING — so bool deleted is
already an imprecise answer to what happened.
Fix: for mutations with genuinely one outcome, prefer an empty response and let gRPC status
codes carry the result (NOT_FOUND for absent). For the rest, an outcome enum. Note that removing
a field from a response is breaking for clients that read it, so this is pre-beta work.
F7 — google.protobuf.Struct as a typed-payload substitute (adjacent to rule 10)
11 Struct fields. Two distinct uses, with different risk:
Legitimate — driver/middleware pass-through config (platform_config, driver_config,
config ×3, resources). The gateway genuinely does not know these schemas. This is the correct
use, though resources and driver_config in the publicSandboxSpec
(openshell.proto:821,834) mean public API fields have no schema, no validation, and no
compatibility story.
Concerning — gateway_interceptor.protoproposed_operation (×2), current_state,
committed_response. The whole gateway operation is handed to interceptors as untyped JSON. The
extension author gets no generated types, and the (secret) field annotation cannot be applied
by the protobuf runtime — redaction has to be reimplemented by hand over JSON, which is what
crates/openshell-gateway-interceptors/src/proto_json.rs does. A hand-rolled redaction path over
a schemaless payload guarding fields marked secret is worth a focused security review
independent of #2565.
F8 — Incomplete and missing reservations (rules 2, 3)
sandbox.proto:243 and :274 reserve tag 8 but not the field name. The rule asks for both.
GatewayInterceptorPhase skips value 1 (MODIFY_OPERATION = 2) with no reserved 1;. Harmless
today, confusing to an extension author reading the enum.
No enum has ever reserved a value. Fine now; the policy should state the practice before it's needed.
F9 — Enum and field semantics worth tightening
SandboxPhase has bothSANDBOX_PHASE_UNSPECIFIED = 0 and SANDBOX_PHASE_UNKNOWN = 5 — two
"don't know" states with no documented distinction. Clients must handle both; nobody will.
bool domain (openshell.proto:1062, :1125) — a boolean named for a noun, apparently meaning
"this endpoint is a DNS name rather than an IP". Should be an address-type enum (rule 22).
bool all_workspaces alongside string workspace, documented as mutually exclusive, in 4
requests. oneof expresses this in the type system instead of in prose. Ties to inventory gap 9 —
and a oneof would also fix the proto3 unset-vs-empty ambiguity for workspace.
bool delete_setting = 5 in UpdateConfigRequest is an action flag inside an update message,
with the constraint "sandbox-scoped deletes are rejected" enforced only in prose.
F10 — openshell.proto is a 2,600-line monolith (rule 12)
180 messages, 64 RPCs, 6 enums, one file. The rule's rationale is refactoring cost, and F1 is a
concrete instance: the storage types are hard to extract precisely because everything lives together.
Lowest-priority finding on its own, but splitting by domain (sandbox / provider / policy+draft /
workspace / service / storage) before the beta boundary would let those domains carry independent
stability designations — which is what §1 of the inventory is trying to express and currently cannot.
5. What this changes for the #2565 plan
The audit reorders the breaking-change batch in inventory §11:
F1 tier-1 (move Stored* out of openshell.v1) is non-breaking on the wire and shrinks the
public surface before it is frozen. Do it first, independent of everything else.
Field renames (F2) and time types (F3) are mechanical, wide, and breaking. They belong in the
same coordinated batch as the pagination and workspace-defaulting changes, not in a later pass.
F4/F5/F6 (bool→enum) change response shapes, so they must land before the boundary or never.
F1 tier-2 (storage twins) is the largest item and the one most likely to be deferred. If it
is deferred, that decision needs to be explicit in the compatibility policy, because it converts
every future proto change to those 7 types into a migration.
The protobuf CI gate (inventory gap 1) should encode the rules this audit found already
violated — keyword field names, missing name-reservations, bare bool in new response messages —
not just wire-breakage detection. buf lint covers several of these out of the box; the
storage/RPC split and the keyword policy need custom rules or review checklist items.
Section 1b — Deep Review: Is the Proto Using the Right Data Model?
Companion to api-surface-inventory-2565.md and -proto-audit.md. The audit asked "does this
follow protobuf's rules?"; this asks the harder question: "is this the right model of the domain?"
Tree: branch docs/multi-gateway-oidc-isolation, base 596d729e.
Evaluated on seven axes: identity and addressing, tenancy, type discipline,
single source of truth, spec/status separation, normalization, and extensibility.
Verdict
The model has a sound skeleton and inconsistent execution. The Kubernetes-inspired core —
ObjectMeta + spec + status, phase enums, label selectors, optimistic concurrency — is the right
choice for a control plane managing long-lived reconciled resources, and where it is applied it is
applied well. compute_driver.proto's deliberate refusal to share the public Sandbox type is
genuinely good design.
The problems are not skeleton problems. They are that the skeleton stops halfway:
Eight resources use ObjectMeta; the policy, draft, and settings subsystems invented three
parallel identity and versioning schemes instead.
The security-critical policy types are stringly-typed and fail open, and in one case the
proto's documented values no longer match the implementation at all (D2 — the most
consequential finding in this review).
"Which sandbox?" is expressed five different ways across 64 RPCs, with two incompatible
identifier kinds (D1).
Policy exists in four concurrent representations, one of which is a magic key inside the
settings map (D3).
None of this is fatal, and most of it is the ordinary residue of a system that grew feature-first.
But nearly every item is breaking to fix, which is exactly why #2565 exists. My overall read: the
model is roughly 70% of the way to coherent, the remaining 30% is concentrated in policy/settings and
addressing, and the beta boundary is the last cheap moment to close it.
D1 — "Which sandbox?" is asked five different ways
The single most visible coherence defect. Across the RPCs that operate on a sandbox:
Three spellings for the same name concept, two for the same id concept, and no way to tell which
an RPC wants except by reading the proto. A client that lists sandboxes and then wants to exec into
one cannot reuse the identifier it already has without knowing that ListSandboxes returns both and
ExecSandbox needs specifically the id.
There is a latent rule that almost holds — id is globally unique, so id-addressed RPCs need no
workspace; name is workspace-scoped, so name-addressed RPCs carry workspace. It is coherent, and
it is broken in one place: GetSandboxLogsRequest carries bothsandbox_id = 1 and
workspace = 6. Either the id is not globally unique (in which case ExecSandbox and WatchSandbox
are under-specified and cross-workspace-ambiguous) or the workspace field there is dead weight. Both
readings are a bug; they differ only in which RPCs are wrong.
Compounding it, GetProviderRequest addresses by name while GetProviderProfileRequest,
DeleteProviderProfileRequest, and UpdateProviderProfilesRequest address by id. So even within
the provider subsystem the addressing kind flips between the two adjacent resource types.
Recommendation. Pick one. The lowest-churn option that also fixes the tenancy problem (D5) is a
single SandboxRef message — { oneof { string name; string id; } string workspace; } — used by
every sandbox-scoped request. Failing that, at minimum: one field name per identifier kind, and a
documented rule for which RPCs accept which. This must be settled before the identifiers are frozen;
it is a rename across ~30 messages.
D2 — Security-critical policy fields are stringly-typed and fail open
NetworkEndpoint (sandbox.proto:97, 23 fields — the largest message in the tree) is the type
operators hand-write and the type that defines the sandbox network security boundary. Four of its
fields are free-form strings enumerating a closed value set:
Field
Documented values
Should be
protocol
"rest", "websocket", "graphql", "sql", ""
enum
tls
"terminate", "passthrough"
enum
enforcement
"enforce", "audit"
enum
access
"read-only", "read-write", "full"
enum
D2a — enforcement fails open on any unrecognized value
let enforcement = matchget_object_str(val,"enforcement").as_deref(){Some("enforce") => EnforcementMode::Enforce,
_ => EnforcementMode::Audit,};
EnforcementMode::Audit is #[default] and documented as "Log violations but allow traffic
through." So any value that is not byte-exactly "enforce" silently degrades to allow-and-log:
"Enforce", "ENFORCE", "enfroce", " enforce", or any value a future version adds. I found no
gateway-side validation rejecting unknown enforcement values on write — nothing in
openshell-policy matches on these strings outside of test fixtures.
The failure is silent, fails open, and lands on the security boundary. A proto3 enum would not fix
authorization by itself, but it moves the typo from "silently permissive at request time" to
"rejected at policy-set time," which is the entire point.
D2b — The proto's documented tls values no longer match the implementation
The implementation (l7/mod.rs:29-37, 140-170) has:
TlsMode::{ Auto, Skip } — only two real modes, Auto is #[default]
"skip" → Skip — the only value that changes behavior, and it is not documented in the proto
"terminate" → Auto
"passthrough" → Auto, plus a runtime OCSF warning: "'tls: passthrough' is deprecated; TLS
termination is now automatic. Use 'tls: skip' to explicitly disable. This field will be removed in
a future version."
So the proto comment is not merely stale, it is inverted on a security property: it names
passthrough as the default, implying traffic is not terminated unless asked. The real default is
Auto, which does terminate TLS and inject credentials. An operator reasoning from the proto would
reach the opposite conclusion about whether their traffic is being intercepted.
This is the concrete cost of stringly-typed fields plus no generated reference: the contract and the
code drifted on a security-visible default and nothing caught it. It is also direct evidence for the
inventory's deliverable "documentation generated from or validated against the protobuf definitions."
Recommendation. Convert all four to enums with *_UNSPECIFIED = 0, define whether unspecified
means "secure default" or "reject", and reject unknown values at write time. Fix the tls
documentation immediately regardless of whether the enum migration lands — that part is a
non-breaking comment change and should not wait for the beta batch.
D3 — Policy exists in four concurrent representations
The same SandboxPolicy payload is modeled four ways at once:
Embedded in spec — SandboxSpec.policy (field 7), set at create time.
A versioned revision series — SandboxPolicyRevision { version, policy_hash, status, load_error, created_at_ms, loaded_at_ms, policy, provenance }, with its own PolicyStatus
lifecycle (PENDING/LOADED/FAILED/SUPERSEDED).
A magic key inside the settings map. Both GetGatewayConfigResponse.settings and
GetSandboxConfigResponse.settings are documented as "excluding the reserved policy key" — so
policy is stored as a value in the generic settings map and then explicitly excluded at the API
boundary.
Merge operations — PolicyMergeOperation with 6 oneof variants, applied via UpdateConfig.
Plus a fifth parallel model for proposals: draft chunks (PolicyChunk, StoredDraftChunk,
DraftChunkPayload) with their own draft_version counters.
Representation 3 is the clear defect. A generic key-value settings map holding a large structured
policy under a reserved key means two different concepts share one storage mechanism, and every API
that reads settings must remember to un-merge them. The phrase "excluding the reserved policy key"
appearing in two response messages is the model telling on itself.
Recommendation. Policy is a first-class versioned resource; settings are key-value. Separate the
storage. SandboxPolicyRevision (representation 2) is the right primary model — it has versions,
hashes, load status, and provenance. Give it ObjectMeta (it currently has none) and make
representations 1 and 4 explicit writes against it rather than alternative homes for the data.
D4 — UpdateConfig is a god-RPC
UpdateConfigRequest (10 fields) performs at least five distinct operations selected by field
presence and a boolean:
Intent
Selector
Replace sandbox policy
policy + global=false
Replace global policy
policy + global=true
Upsert a setting
setting_key + setting_value
Delete a setting
setting_key + delete_setting=true (global only)
Apply incremental merges
merge_operations (sandbox only)
Every constraint lives in prose: "Sandbox-scoped deletes are rejected", "only network_policies and
inference fields may differ from create-time policy", "Ignored for global-scoped updates" (twice),
"Sandbox-scoped only". Nothing in the type system prevents sending policy + merge_operations +
delete_setting together, and the proto does not say what happens if you do.
The name compounds it: UpdateConfig names neither the resource nor the operation, yet it is the
single most privileged mutation path in the API (dual auth, config:write, workspace admin).
Recommendation. Split into UpdateSandboxPolicy, UpdateGlobalPolicy, MergeSandboxPolicy,
SetSetting, DeleteSetting. Failing that, a oneof mutation makes the five modes mutually
exclusive in the type system. This is the highest-value split in the API: it is the most privileged
RPC and currently the least type-constrained.
D5 — Workspace tenancy is a sibling field, not a parent
workspace appears as a plain string on ~40 request messages, paired in four of them with
bool all_workspaces documented as mutually exclusive. ObjectMeta.workspace carries it on
resources. This is the recognizable shape of tenancy added after the fact — and it produces three
distinct problems:
Unset vs. empty is unresolvable. Documented everywhere as "Empty defaults to default".
Proto3 cannot distinguish an unset string from "", so "no workspace specified" and "the empty
workspace" are the same wire state forever. Once frozen, adding a distinction requires a new field.
The mutual exclusion is prose-only.{workspace: "foo", all_workspaces: true} is
representable and undefined. A oneof scope { string workspace; bool all_workspaces; } would
express it in the type system and solve (1), since oneof gives presence.
Three unrelated things are called "scope".SettingScope (sandbox/global),
ProviderProfile.scope ("platform"/"workspace"/"", a string), and the workspace dimension
itself. A reader cannot tell which axis "scope" refers to without context.
Recommendation. Adopt oneof for the workspace/all-workspaces pair now — it fixes the presence
problem and the exclusivity problem in one breaking change that must happen pre-beta. Whether to go
further to hierarchical resource names (workspaces/foo/sandboxes/bar) is a bigger call; flat fields
plus a oneof is a defensible end state and far cheaper.
D6 — Six concurrent version counters with no unified concurrency story
Seven, counting global_policy_version. Three different widths for conceptually identical counters,
and draft_version is uint64 in PolicyChunk/SubmitPolicyAnalysisRequest but int64 in
StoredDraftChunk and DraftChunkPayload — a signedness mismatch between the RPC and storage views
of the same value, which is only possible because storage and RPC types were allowed to drift (see
audit F1).
Meanwhile expected_resource_version (optimistic concurrency) appears on only 4 requests, and
UpdateConfigRequest documents "If 0, the server uses the current version (backward
compatibility)" — i.e. the safe path is opt-in and the default is last-write-wins.
Recommendation. Document each counter's scope and monotonicity guarantee in one place; unify
widths on uint64; fix the draft_version signedness split. Decide whether
expected_resource_version becomes mandatory for mutations — a compare-and-swap that defaults to
"don't check" will produce lost updates under concurrent agents, which is the product's core use case.
D7 — Parallel maps instead of composed values
Provider (datamodel.proto:72) carries two maps that must be kept in sync by convention:
map<string, string> credentials = 3 [(secret) = true];
map<string, int64> credential_expires_at_ms = 5; // keyed by credential/env var name
Nothing structurally ties a credential to its expiry; a caller can set one without the other, and
the key space is documented ambiguously as "credential/env var name" — two different naming
domains. The composed form (map<string, CredentialValue> where CredentialValue holds value plus
expiry) makes the invariant unbreakable and would also let the (secret) annotation sit on the value
field rather than the whole map.
The same by-name cross-referencing recurs in the provider profile model:
ProviderProfileCredential.env_vars (repeated string), and
ProviderCredentialRefreshOutput.credential pointing at a sibling credential by name, with the
relationship enforced only in prose. providers/aws-s3.yaml shows this in practice — one
assume_role call minting three credentials via additional_outputs, wired by string name.
D8 — Spec/status separation leaks implementation into the public status
Sandbox gets the shape right (metadata/spec/status) and SandboxSpec is clean. SandboxStatus
is not:
string sandbox_name = 1; // "Compute-platform sandbox object name"
string agent_pod = 2; // "Name of the agent pod or equivalent runtime instance"
string agent_fd = 3; // "File descriptor or endpoint for reaching the agent service"
string sandbox_fd = 4; // "File descriptor or endpoint for reaching the sandbox service"
agent_pod is Kubernetes vocabulary in a driver-agnostic public type. agent_fd/sandbox_fd are
described as "File descriptor or endpoint" — a field that is either of two unrelated things, typed
as a string, with no discriminator. And sandbox_name duplicates metadata.name under a different
meaning (compute-platform name vs. OpenShell name), which is a trap.
openshell.proto's own header comment says the gateway "translates internal compute-driver
observations into these public resource messages" — these four fields are where that translation
didn't happen.
SandboxCondition is the other weak spot, and it imports Kubernetes' weakest idea verbatim:
string type = 1; // stringly-typed (also a Rust keyword — see audit F2)
string status = 2; // "True", "False", or "Unknown" — a tri-state as a string
string last_transition_time = 5; // a timestamp as a string
status should be a three-valued enum. last_transition_time as a string is a fifth time
encoding in a tree that already has four (audit F3) and the only one that is not numeric.
D9 — SandboxSpec and SandboxTemplate overlap on three axes
Concept
In SandboxSpec
In SandboxTemplate
environment
environment = 5
environment = 6
labels/annotations
via ObjectMeta
labels = 4, annotations = 5
resources
resource_requirements = 9 (typed)
resources = 7 (Struct)
Two environment maps with no documented precedence — a caller setting FOO in both has no defined
winner. Two label sets that do have distinct meanings (OpenShell object labels used for selectors
vs. compute-platform labels stamped on the pod) but names that don't say so. Two resource models
side by side, one portable and typed, one platform-specific and schemaless, with the boundary between
them undocumented.
Recommendation. Document precedence and rename for intent (platform_labels,
platform_resources) at minimum. Merging the environment maps is the cleaner fix and is breaking.
D10 — ProviderProfile mixes enum discipline with structured strings
Strings that are enums — source ("builtin"/"user"/"interceptor/{name}"),
scope ("platform"/"workspace"/""), ProviderProfileCredential.auth_style.
source is worse than stringly-typed: "interceptor/{name}" embeds structured data in a string,
so consumers must string-split to recover the interceptor name. That wants
oneof source { Builtin; User; string interceptor_name; } or an enum plus a separate name field.
Identity divergence — bare string id = 1 instead of ObjectMeta, while every neighbouring
resource uses ObjectMeta. Requests address profiles by id and providers by name (see D1).
Two resource versions — ProviderProfile.resource_version = 10andStoredProviderProfile.metadata.resource_version. Documented as "Built-in profiles and new
profile files use 0", so which one is authoritative depends on provenance. This is audit F1's
storage/RPC fusion producing a concrete ambiguity.
D11 — Scalar/repeated duplicates and prose-only mutual exclusion
NetworkEndpoint again:
uint32 port = 2; // "Single port (backwards compat). Use `ports` for multiple ports.// Mutually exclusive with `ports` — if both are set, `ports` takes precedence."
repeated uint32 ports = 9;
string access = 6; // "Mutually exclusive with rules."
repeated L7Rule rules = 7;
The port/ports pair is the protobuf.dev "repeated vs scalar" hazard handled the only safe way
(keep both, document precedence) — correct given the constraint, but it leaves two fields meaning one
thing permanently, on the security-critical type. access/rules is a genuine oneof expressed in
prose. Both are pre-beta cleanup candidates: reserve port, keep ports; make access/rules a
oneof.
Also here: host + allowed_ips have conditional semantics — "If host is empty, any domain is
allowed as long as it resolves to an IP in this list." Behavior branching on the emptiness of one
field to reinterpret another is exactly what oneof exists to prevent, and on a security field the
stakes are the same as D2.
10 RPCs deviate from <Rpc>Request/<Rpc>Response. Two are legitimately event streams
(ExecSandboxEvent, SandboxStreamEvent). The rest share a response type across operations:
Sharing means these operations can never diverge. A create-only field (an initial credential, a
one-time token, a warning about defaults applied) cannot be added without it appearing — and
requiring definition — on the read path too. The cost is small today and unbounded later, and the
fix (distinct response messages wrapping the same resource) is a pure addition if done before the
responses are frozen.
What is genuinely right, and should be locked in
Stated explicitly so the stabilization pass doesn't churn it:
ObjectMeta is the correct shape and its field set (id, name, labels, annotations,
created_at, resource_version, workspace, deletion_timestamp) covers what a control plane needs.
The deletion_timestamp_ms immutability rule and label conventions are documented well.
spec/status separation on Sandbox is right, and SandboxSpec is a clean desired-state
message. D8 is about status only.
Driver/public model isolation — DriverSandbox deliberately omits public lifecycle fields and
the gateway translates. This is the pattern the rest of the model should copy (and the pattern
audit F1 shows was not applied to persistence).
Phase enums with normalized semantics.SandboxPhase's doc comment explicitly tells clients to
use the phase rather than interpret raw conditions — correct guidance. (Its UNSPECIFIED vs
UNKNOWN duplication is a small wart; see audit F9.)
PolicyStatus is a well-designed lifecycle enum.PENDING/LOADED/FAILED/SUPERSEDED with
documented meanings, including the last-known-good behavior on FAILED. This is the quality bar
the rest of the policy model should meet.
SettingValue as a typed oneof rather than a stringly-typed value map.
PolicyMergeOperation as a oneof of 6 typed operations — the right way to model incremental
edits; it just needs to not share an RPC with four other intents (D4).
(secret) field annotation as a first-class model concept for a redaction boundary.
Priority for the #2565 breaking-change batch
Ordered by (consequence × cost-of-deferral):
Finding
Breaking?
Why this rank
1
D2b — fix tls documentation
No
Security-visible doc inversion. Ship immediately, independent of everything.
2
D2a — enums for enforcement/protocol/tls/access + write-time rejection
Yes
Fails open on the security boundary today.
3
D1 — one addressing scheme (SandboxRef)
Yes
Touches ~30 messages; only gets more expensive. Resolve the GetSandboxLogs id+workspace contradiction as part of it.
D6's draft_version signedness and D10's dual resource_version should ride with audit F1.
Cross-references: audit F1 (storage/RPC fusion) underlies D6 and D10; F2 (keyword field
names) overlaps D1's rename work and SandboxCondition.type; F3 (time types) overlaps D8's
last_transition_time; F5 (SANDBOX/GLOBAL encoded three ways) is the same defect as D3 and D5
seen from the enum side. Sequencing them together avoids touching the same messages twice.
Section 1c — Deep Review: The gRPC Service Protocol
Companion to api-surface-inventory-2565.md, -proto-audit.md, and -data-model-review.md.
The inventory enumerated the gRPC surface. The proto audit checked message/field hygiene. The data
model review examined resource shape. This review examines the API as a service protocol — error
model, idempotency, streaming lifecycle, async completion, service decomposition, standard-protocol
conformance, and transport metadata. These are the dimensions #2565 lists under gRPC documentation and
that none of the prior three documents addressed.
Tree: branch docs/multi-gateway-oidc-isolation, base 596d729e.
Verdict
The protocol layer is weaker than the type layer, and it contains the first outright bugs found in
this whole review. The type-level work (audit, data model) surfaced design debt — things that are
awkward but behave as documented. This layer surfaced three places where the implementation does
not do what the proto says it does:
G1 — WatchSandbox's stop_on_terminal never stops on ERROR, despite the proto documenting
"(READY or ERROR)". A client watching a failing sandbox hangs until its own deadline.
G2 — SandboxStreamWarning is dead surface: the proto defines it, the CLI handles it, the
server never emits it. On lag the server kills the stream with RESOURCE_EXHAUSTED instead.
G3 — The standard gRPC health and reflection services are allowlisted as unauthenticated and
asserted in a test, but neither is registered. Dead auth surface, and generic gRPC tooling and
Kubernetes gRPC probes cannot talk to the gateway.
Beyond the bugs, the two structural gaps are no idempotency mechanism on any mutation (G4) and
no async-completion model for operations that are asynchronous by design (G5). Both are
additive to fix, which makes them unusually cheap for a pre-beta batch — and both get much more
expensive to add once clients depend on current retry behavior.
One notable corroboration: both first-party SDKs poll instead of using WatchSandbox. The Rust
wait_ready polls get_sandbox; the Python one calls get() in a time.sleep(1) loop. When the
people who wrote the streaming RPC don't use it for its canonical use case, that is the strongest
available signal that G1/G2 make it untrustworthy in practice.
G1 — stop_on_terminal does not stop on ERROR(implementation contradicts proto)
The contract (openshell.proto:1283):
// Stop streaming once the sandbox reaches a terminal phase (READY or ERROR).
bool stop_on_terminal = 7;
The implementation checks Ready only — in both places it is evaluated,
crates/openshell-server/src/grpc/sandbox.rs:831 (initial snapshot) and :906 (live loop):
if stop_on_terminal {let phase = SandboxPhase::try_from(sandbox.phase()).unwrap_or(SandboxPhase::Unknown);if phase == SandboxPhase::Ready{return;}}
SandboxPhase::Error is never tested. A client that sets stop_on_terminal and waits for a sandbox
that fails provisioning receives the ERROR snapshot and then the stream stays open indefinitely,
until the client's own deadline or timeout fires. The failure mode is a hang on the unhappy path,
which is the path where a fast, clear signal matters most.
(For the record, sandbox.phase() is a hand-written accessor in
openshell-core/src/metadata.rs:88 reading status.phase — it correctly handles the reserved
top-level phase field. That part is fine; only the Error omission is the bug.)
Fix: add || phase == SandboxPhase::Error at both sites. Non-breaking, and it makes the proto's
existing documentation true. Should ship independently of the beta batch.
G2 — SandboxStreamWarning is dead API surface; lag terminates the stream
The proto defines a graceful-degradation channel (openshell.proto:1304):
oneof payload {
...
// Warning from the server (e.g. missed messages due to lag).
SandboxStreamWarning warning = 4;
}
The CLI implements the consumer side (openshell-cli/src/run.rs:797 matches on
Payload::Warning(w)). But no code anywhere constructs a SandboxStreamWarning — the only
reference in the tree is that CLI match arm.
What actually happens on lag: the watch handler subscribes to broadcast::channel(1024) buses
(tracing_bus.rs:60, :424; sandbox_watch.rs:35 uses 128), and every receive error routes through
sandbox_watch.rs:61-69:
All three call sites (grpc/sandbox.rs:923, :949, :967) send that Err and then return —
terminating the stream. So a consumer that falls 1024 events behind on a chatty sandbox loses its
watch entirely rather than receiving the warning the protocol was designed to deliver.
Compounding it, there is no resumption mechanism.WatchSandboxRequest has no
start_resource_version, resume token, or cursor. It offers log_tail_lines and event_tail
("best-effort" replay counts) and log_since_ms — all logs/events only, nothing for status
snapshots. So after a lag kill or any disconnect, the client reconnects, gets a fresh snapshot, and
cannot determine which status transitions it missed. A sandbox that went PROVISIONING → ERROR → (recreated) READY is indistinguishable from one that went straight to READY.
This is the mechanism behind the SDK polling observation. Polling GetSandbox is strictly more
reliable than this watch contract today, so that is what both SDKs do.
Fix, in order: (1) emit the warning and continue on Lagged rather than terminating — the
proto already has the message, this is implementing declared behavior; (2) add a resume cursor keyed
on ObjectMeta.resource_version so reconnects are gap-free; (3) put the dropped-message count in a
typed field on the warning rather than a prose string.
G3 — Standard health and reflection are allowlisted but not served
crates/openshell-server/src/auth/oidc.rs:30-33:
/// These are structural bypasses for gRPC infrastructure that doesn't map to a/// single RPC method. Per-method bypasses (e.g. `Health`) are declared at the/// handler with `auth_mode: "unauthenticated"` in the proto annotation.constUNAUTHENTICATED_PREFIXES:&[&str] = &["/grpc.reflection.","/grpc.health."];
And a test asserts is_unauthenticated_method("/grpc.health.v1.Health/Check") (oidc.rs:416).
But grpc.health.v1 and grpc.reflection are not served: no tonic-health or
tonic-reflection dependency in openshell-server/Cargo.toml, and the only grpc.health.v1 mention
in the entire crate tree is that test assertion. The gateway serves a custom
openshell.v1.OpenShell/Health instead.
Consequences:
Two unauthenticated path prefixes are permanently open to methods that don't exist. Not exploitable
on its own — an unimplemented method returns UNIMPLEMENTED — but it is auth surface with no
corresponding service, and a future dependency that registers reflection would become
unauthenticated by default, silently exposing the full schema.
Kubernetes grpc probes, grpcurl, grpc_health_probe, and service meshes cannot health-check the
gateway through the standard mechanism. The Helm chart's probes must use the HTTP /healthz
endpoint instead (which exists — see inventory S19 — so this is a conformance gap, not an outage).
Without reflection, grpcurl-style exploration requires the client to already have descriptors —
which interacts with the inventory's "publish generated gRPC reference" deliverable.
Decide: either register the standard services (and keep the allowlist) or drop the allowlist
prefixes (and document that OpenShell deliberately does not implement them). The current state — an
allowlist for absent services — is the one option that has costs and no benefits.
G4 — No idempotency mechanism on any mutation
I found no idempotency key, client token, or request-dedup field on any request message in the
tree. (supervisor_middleware.proto's request_id is per-HTTP-request correlation for middleware
evaluation, unrelated; the two dedup mentions in openshell.proto are draft-chunk comments.)
The concrete hazard is CreateSandbox, whose name field is optional:
// Optional user-supplied sandbox name. When empty the server generates one.
string name = 2;
Client behavior
Retry after a timeout or transport error
Explicit name
Second attempt returns ALREADY_EXISTS (compute/mod.rs:728, :770) — recoverable, but the client cannot distinguish "my first attempt succeeded" from "someone else took the name"
Empty name
Server generates a fresh 6-character name (persistence/mod.rs::generate_name) — the retry creates a second sandbox, leaking compute
Since a sandbox is a billable, resource-consuming object and CreateSandbox is the API's primary
mutation, silent duplicate creation on retry is the highest-consequence protocol gap here. It is also
the reason a client library cannot safely implement automatic retries — which means every SDK either
doesn't retry creates (unreliable) or risks duplicates (wasteful).
Fix: add an optional client_token / idempotency_key to CreateSandbox and the other
non-idempotent mutations, with a documented dedup window; return the original result on replay.
Purely additive — a new optional field — so this can land without breaking anyone.
G5 — Asynchronous operations have no completion model
Several operations are asynchronous by design but return synchronous scalars:
Revision persisted PENDING; sandbox loads it later
policy revision
CreateSandbox and UpdateConfig handle this acceptably — they return a resource whose status
communicates that work is outstanding, and PolicyStatus (PENDING/LOADED/FAILED/SUPERSEDED)
is a genuinely well-modeled async lifecycle. DeleteSandbox returning bool deleted is the outlier:
the boolean cannot express "accepted, teardown in progress", which is the normal case.
There is no operation resource, no long-running-operation pattern, and no way to await completion
except polling GetSandbox for NOT_FOUND — which is exactly what both SDKs' wait_deleted does
(openshell-sdk/src/client.rs:240, Python sandbox.py:549). That works, but it makes every client
reimplement the same polling loop, and it cannot distinguish "deletion finished" from "deletion
failed and the record was garbage-collected."
This overlaps data-model finding D-F6 (single-bool ack responses) but is a distinct concern: D-F6 is
about typing, G5 is about the missing completion protocol. Fixing the type without adding a way
to await completion leaves the gap.
G6 — Error model: consistent codes, no structured details
Positive first: code selection across 727 Status:: sites is more disciplined than expected, and
the mapping is centralized where it matters. persistence_error_to_status (grpc/mod.rs:86)
documents its policy explicitly — CAS conflicts → ABORTED to signal retry-with-fresh-data, other
persistence errors → INTERNAL. Code distribution:
Code
Sites
Code
Sites
INVALID_ARGUMENT
242
UNAVAILABLE
18
INTERNAL
224
ABORTED
11
FAILED_PRECONDITION
65
RESOURCE_EXHAUSTED
9
NOT_FOUND
57
ALREADY_EXISTS
6
PERMISSION_DENIED
41
DEADLINE_EXCEEDED
2
UNAUTHENTICATED
31
CANCELLED / UNKNOWN / UNIMPLEMENTED
1 each
Two concerns:
INTERNAL at 224 sites (31%) is high.INTERNAL is non-retryable and carries no client
guidance. Some of these are genuinely internal, but a third of all error paths returning "something
broke, good luck" suggests error classification stopped at the first plausible code. Worth a pass
to reclassify the ones that are actually UNAVAILABLE (retryable), FAILED_PRECONDITION
(state-dependent), or RESOURCE_EXHAUSTED.
No structured error details anywhere. No google.rpc.Status, ErrorInfo, BadRequest, or
RetryInfo — every error is a bare tonic::Status with a human-readable string. Clients cannot
programmatically distinguish why an INVALID_ARGUMENT failed (which field?), cannot get a
machine-readable reason code, and cannot be told a retry delay. With 242 INVALID_ARGUMENT sites,
a BadRequest detail naming the offending field would be a large usability win for agent clients
that must self-correct.
Neither the codes nor the retryability contract is documented anywhere — #2565 asks for exactly that,
and the discipline already in the code makes documenting it cheap.
G7 — Streaming lifecycle: no half-close, undefined cross-stream ordering
Seven streaming RPCs. The tunnel ones carry raw bytes and have the thinnest contracts:
No close or half-close frame. Neither envelope can express "I'm done sending, keep receiving."
For ForwardTcp (one TCP connection per gRPC stream) the only close signal is stream termination,
so TCP half-close cannot be forwarded. Protocols that rely on it — some HTTP/1 patterns, nc -q,
certain database clients — will behave differently through the tunnel than direct.
No flow control or sequence numbers at the application layer. HTTP/2 flow control provides
backpressure, so this is defensible, but it should be a documented decision rather than an omission.
RelayStream's control plane lives on a different stream.RelayOpen/RelayClose/
RelayOpenResult are variants of SupervisorMessage/GatewayMessage on ConnectSupervisor, while
data flows on RelayStream, correlated by channel_id. This is a reasonable mux design (SSH-like),
but the proto defines no ordering guarantee between a RelayClose on one stream and in-flight
data on the other, and no behavior for "control stream dies while data streams are open."
Credit where due: ConnectSupervisor has an explicit liveness contract — bidirectional
heartbeats (SupervisorHeartbeat, GatewayHeartbeat) with a server-recommended
heartbeat_interval_secs in SessionAccepted, plus SessionAccepted/SessionRejected handshake
results and instance_id for epoch detection. That is the best-specified stream in the API and the
model the others should follow.
G8 — Pagination: server-side clamping is sound, responses are truncation-blind
This refines inventory gap 7, which was written before I had read the handlers. The server side is
better than the inventory implied:
clamp_limit(raw, default, max) = if raw == 0 { default } else { raw.min(max) }, with
MAX_PAGE_SIZE = 1000 and a default of 100 (50 for policy revisions), applied consistently at 7 real
call sites across sandboxes, providers, provider profiles, services, workspaces, workspace members,
and policies. So there is a documented-in-code default and a hard cap; unbounded reads are not
possible.
The gap that remains is entirely on the response side: no ListXResponse carries a total count, a
next offset, or a truncation flag. A client asking for 1000 and receiving 1000 cannot tell whether
that is the complete set or the cap. Combined with offset paging (unstable under concurrent
mutation — an insert during iteration shifts the window and can skip or duplicate records), a client
walking a large workspace has no way to know it got a consistent or complete view.
Still true from the inventory: ListSandboxProviders, ListProviderProfiles, and
ListWorkspaceMembers have no paging fields at all (workspace members are bounded instead by
MAX_WORKSPACE_MEMBERS = 1000 server-side).
Fix: add total_size and/or next_page_token to list responses (additive). Migrating from
offset to keyset/token paging is the more correct fix and is breaking, so it belongs in the pre-beta
batch if it happens at all.
G9 — One 64-RPC service mixes three trust tiers
openshell.v1.OpenShell carries all of:
Traffic class
RPCs
Callers
End-user / agent control plane
~45
CLI, TUI, SDKs
Sandbox supervisor callbacks
8 (auth_mode: "sandbox")
supervisors only
Platform administration
4 (platform_admin)
operators
The authorization annotations enforce the boundary correctly at runtime — that part works. The
problem is that a single service definition cannot carry differentiated stability guarantees. The
inventory's §1 wants to classify the supervisor channel (S6) as internal, version-locked and the
user surface (S1) as public/stable, and there is no way to express that while both live in one
service: any client generated from the descriptor gets stubs for all 64, and the supervisor RPCs
appear in the public SDKs' raw surface.
Splitting into openshell.v1.OpenShell (public), openshell.internal.v1.SupervisorControl, and
openshell.admin.v1.PlatformAdmin would let each version independently, shrink the public surface, and
make the trust tiers legible from the schema rather than only from annotations. It is a breaking
change to the supervisor and admin paths and additive-only for ordinary clients — a favorable ratio
for a pre-beta batch, and it directly serves the "explicit stability designation per surface"
deliverable.
G10 — Transport metadata and deadlines are undocumented
Metadata contract. The auth token travels in metadata (the SDK's EdgeAuthInterceptor attaches
it), but nothing in proto/ or docs/ specifies the header names, the sandbox-token vs.
bearer-token distinction on the wire, or whether workspace may travel in metadata (it does not — it
is a message field everywhere, per data-model D5). #2565 explicitly asks for "authentication and
transport metadata" documentation; today a non-Rust, non-Python client author would have to read
openshell-sdk/src/auth.rs to discover it.
Deadline propagation. I found no code reading grpc-timeout / request deadlines from client
metadata to bound downstream work. Tonic cancels the handler future when the client disconnects, so
cancellation largely works via Rust drop semantics — but a client's 5-second deadline does not
become a 5-second budget for the compute-driver call underneath it. The gateway's own timeouts are
independent constants. For long operations behind short client deadlines this produces orphaned
work that completes after nobody is listening.
Rate limiting.gateway.toml configures a gRPC rate limit and 9 sites return
RESOURCE_EXHAUSTED, but no RetryInfo detail accompanies it (see G6), so clients cannot learn the
retry delay from the response.
Priority
Split by cost, because this layer has an unusually favorable set of cheap wins:
Ship now — non-breaking, fixes declared-but-wrong behavior:
Finding
Change
1
G1
Add the Error check to stop_on_terminal at both sites. Two lines.
2
G2a
Emit SandboxStreamWarning and continue on Lagged instead of terminating.
3
G3
Register standard health + reflection, or remove the allowlist prefixes.
4
G4
Add optional client_token to CreateSandbox and other non-idempotent mutations.
5
G8a
Add total_size / truncation signal to list responses.
Service split is the only way to give surfaces independent stability designations.
8
G2b
Watch resume cursor — changes request shape; without it the stream is unreliable by design.
9
G5
DeleteSandbox response shape + an await-completion story (pairs with data-model D-F6).
10
G7
Close/half-close frames in TcpForwardFrame / RelayFrame.
11
G8b
Offset → keyset/token paging, if it happens at all.
Documentation deliverables (no code change): G6's status-code and retryability contract, G7's
streaming lifecycle semantics, G10's metadata and deadline contract. All three are #2565 line items
and all three are cheap now that the behavior is characterized above.
Cross-references
G5 ↔ data-model D-F6 (single-bool acks): same messages, different concern. Fix together.
G9 ↔ inventory S1/S6 classification: the split is what makes those designations expressible.
G8 supersedes inventory gap 7 — the server-side clamping detail was missing there.
G3 ↔ inventory gap 3 (no generated gRPC reference): reflection is part of the discoverability story.
G2/G1 explain why both SDKs poll, which is context for the inventory's SDK-parity work.
Reproducing
grep -rhoE "Status::(\w+)" crates/openshell-server/src --include=*.rs | sort | uniq -c | sort -rn
grep -rn "SandboxStreamWarning" crates/ --include=*.rs # only the CLI match arm
grep -n "stop_on_terminal" -A8 crates/openshell-server/src/grpc/sandbox.rs
grep -rn "grpc.health.v1" crates/ --include=*.rs # only a test assertion
grep -rn "tonic_health\|tonic_reflection" crates/ --include=Cargo.toml # absent
grep -nE "idempotenc|client_token" proto/*.proto # absent
grep -rn "clamp_limit" crates/openshell-server/src --include=*.rs
Tree: branch docs/multi-gateway-oidc-isolation, base 596d729e.
Headline: the strategic finding
AIP corroborates almost every finding, but wholesale AIP adoption is the wrong recommendation for
OpenShell — and understanding why sharpens the actual recommendation.
OpenShell's API is built on the Kubernetes idiom: ObjectMeta with name/labels/
annotations/resourceVersion, spec/status separation, phase enums, label selectors. AIP
codifies the Google Cloud idiom: name as a full hierarchical resource path, etag for
concurrency, state (never "status"), google.longrunning.Operations, and the google.api.*
annotation family.
These two conventions are coherent internally and conflict with each other on specifics:
Concern
Kubernetes idiom (what OpenShell chose)
AIP idiom
Identity
metadata.name — a bare name, scoped by namespace
name — a full path, workspaces/w/sandboxes/s
Concurrency
resourceVersion (opaque int)
etag (RFC 7232 string, field 99)
Lifecycle
status.phase
state, with Status explicitly reserved
Async
resource visible with non-ready phase
google.longrunning.Operation
Choosing the Kubernetes idiom is defensible and probably correct for OpenShell: Kubernetes is a
first-class compute driver, the operators deploying it already read K8s objects, and the Helm chart is
a primary distribution path. AIP-122's hierarchical names buy their value mainly from Google's
centralized IAM/logging infrastructure, which OpenShell does not have.
So the recommendation is not "become AIP-compliant." It is: pick one idiom and be internally
consistent, and adopt the AIPs that are idiom-neutral. OpenShell's real defect is not that it chose
Kubernetes over Google — it is that it applied Kubernetes conventions to eight resources and then
invented ad-hoc schemes for policy, drafts, settings, and addressing. Every prior finding is an
instance of that.
This split gives a clean triage, used throughout below:
Idiom-neutral AIPs — good practice regardless of house style. Adopt these. (Errors, idempotency,
pagination signalling, time types, field behavior, enum-vs-bool, delete semantics, compatibility rules.)
Idiom-specific AIPs — presuppose the Google idiom. Note the divergence, do not adopt.
(Resource name paths, etag, LRO service, state renaming.)
1. AIPs that escalate existing findings from "should" to "must"
These change severity or give a precise target shape. This is where AIP adds the most value.
1.1 AIP-193 (Errors) escalates G6 — this is now a hard violation
AIP-193: "All error responses must include an ErrorInfo within details", with a
reason (UPPER_SNAKE_CASE, ≤63 chars) and domain, and contextual values in metadata rather than
interpolated into the message string.
I confirmed zero structured details in the tree (google.rpc / ErrorInfo / field_info: 0
occurrences in proto/). G6 reported this as a usability gap; AIP treats it as mandatory. Given 242
INVALID_ARGUMENT sites and agent clients that must self-correct from errors, ErrorInfo +
BadRequest.field_violations is the single highest-value additive change in the API.
AIP-193 also adds a rule G6 did not cover: messages must remain stable for a given error once
clients may be parsing them — which constrains the reclassification pass G6 recommends.
Credit where due — a check that came out clean. AIP-193 requires PERMISSION_DENIEDbefore
existence checks, so NOT_FOUND never leaks resource existence to unauthorized callers. I verified
handle_get_sandbox (grpc/sandbox.rs) calls authorize_workspace(...)before the store lookup.
OpenShell is conformant here. Worth documenting as an intentional guarantee in the compatibility
policy so a future refactor doesn't invert it.
1.2 AIP-158 (Pagination) escalates G8 and corrects the recommended shape
AIP-158: "Absence of next_page_token is the only way to communicate 'end-of-collection'."
That makes G8's "truncation-blind responses" a hard violation, not a nice-to-have. It also corrects
my recommendation: I proposed adding total_size. AIP says total_size is optional and may be an
estimate; the required element is next_page_token. Standard field names are
page_size/page_token/next_page_token; offset-style paging is permitted but as a field named
skip, not offset.
So OpenShell's limit/offset is non-standard naming and missing the one required signal. Revised
G8 fix: add next_page_token (additive, non-breaking) first; treat the limit→page_size rename and
offset→token migration as pre-beta breaking work.
Unchanged from G8: the server-side clamp_limit behavior (default 100, MAX_PAGE_SIZE = 1000) is
exactly what AIP-158 prescribes — "APIs should set appropriate defaults and coerce oversized requests
down to maximum permitted size." Conformant already.
1.3 AIP-155 (Request identification) corrects G4's field name
AIP-155 specifies the mechanism precisely: an optional string request_id, ≤36 ASCII characters,
UUID4, annotated (google.api.field_info).format = UUID4, with semantics "if a duplicate request is
detected, the server should return the response for the previously successful request."
G4 recommended "client_token / idempotency_key." AIP's name is request_id — adopt that
instead; it is what every AIP-aware client generator and reviewer will expect. The finding itself
(no idempotency anywhere; empty-name CreateSandbox retries create duplicate sandboxes) stands
unchanged and is confirmed as a genuine gap rather than a stylistic quibble.
1.4 AIP-135 (Delete) makes bool deleted explicitly non-conformant
AIP-135: the Delete response must be google.protobuf.Empty, or the resource itself if
soft-deleted. Returning a boolean is not an option. It also introduces allow_missing for idempotent
delete — "if the method call is on a resource that does not exist, the request is a no-op."
This upgrades data-model D-F6 (the ~20 single-bool ack responses, of which bool deleted appears
8×) from "cannot be extended" to "explicitly wrong shape," and adds a mechanism (allow_missing)
that neither D-F6 nor G5 mentioned. allow_missing is additive and directly useful: it makes
DeleteSandbox safely retryable, which partially addresses G4 for the delete path without a full
request_id implementation.
1.5 AIP-142 (Time) escalates F3 and adds a naming rule I missed
AIP-142 requires google.protobuf.Timestamp/Duration, permitting integer forms only "for legacy or
compatibility reasons" with the unit as a suffix. F3 already reported 0 WKT uses and 37 hand-rolled
int64 *_ms fields.
What F3 missed: AIP-142 also mandates naming — timestamps end in _time, and use imperative,
not past tense: create_time, not created_time. So created_at_ms diverges on three axes at once
(type, suffix, tense), and deletion_timestamp_ms on two.
Partial credit: OpenShell's _ms suffix does satisfy AIP-142's fallback requirement to state the
unit, so the existing fields are the "acceptable legacy form" rather than undocumented integers.
1.6 AIP-216 (States) escalates D8 and names the exact anti-pattern
AIP-216 is unusually specific and OpenShell diverges on four points:
AIP-216 rule
OpenShell
Use State; "Status is reserved for HTTP/gRPC statuses"
State enums nested in the resource message, not top-level
all 14 enums are top-level
The second row is the substantive one: audit F9 flagged the UNSPECIFIED/UNKNOWN duplication as a
"small wart." AIP-216 identifies it as precisely the thing not to do — a state enum should have exactly
one unknown-ish value and it should never be emitted. That raises F9's priority slightly.
The State-vs-Status and READY-vs-ACTIVE rows are idiom-specific; the Kubernetes idiom uses
status.phase and Ready deliberately. I would not rename these. But PolicyStatus is worth a second
look because "status" there genuinely collides with gRPC status in reader comprehension.
Conversely, AIP-216 validates one thing D8 did not credit: "state fields should be Output only" —
SandboxStatus is indeed server-derived and not client-writable. Correct by construction.
1.7 AIP-151 (LRO) partially validates G5, partially escalates it
AIP-151's threshold is "a good rule of thumb is 10 seconds" — sandbox provisioning clearly exceeds
that, so CreateSandbox and DeleteSandbox are LRO candidates.
But AIP-151 also says: "When creating or deleting via long-running operations, the resource should be
included in List and Get calls; however, the resource should indicate that it is not usable, generally
with a state enum."That is exactly what OpenShell does with SANDBOX_PHASE_PROVISIONING /
DELETING. So the create path is half-conformant already — it has the observable-state half and lacks
only the Operation handle.
This tempers G5. The missing piece is a completion handle, not the whole async model. Given AIP-151
requires the standard google.longrunning.Operations service as a new dependency and a new service to
implement, and OpenShell already exposes completion via phase + WatchSandbox, I'd rank full LRO
adoption lower than G5 implied — and prioritize the cheap parts instead: fix DeleteSandbox's
response type (AIP-135) and fix WatchSandbox so the observable-state path is actually reliable
(G1/G2). Making the existing mechanism work beats adding a second one.
1.8 AIP-180 (Backwards compatibility) confirms several of my fixes are correctly placed pre-beta
AIP-180's breaking-change list is the content the inventory's compatibility-policy deliverable needs.
Three items validate recommendations I made without justifying them fully:
"Moving fields into or out of oneofs" is breaking. Confirms that D5 (workspace/all_workspaces
→ oneof), D11 (access/rules → oneof), and D4 (UpdateConfig → oneof mutation) must land
pre-beta or never.
"Changing field types, even if wire-compatible" is breaking. Confirms F3's time-type migration
and D6's draft_versionint64/uint64 unification are beta-boundary work.
"Increasing upper length bounds" on string fields is breaking — a subtle rule none of my
reviews had. Relevant because the gateway enforces MAX_MAP_KEY_LEN, MAX_MAP_VALUE_LEN,
MAX_ROUTABLE_NAME_LEN, MAX_PROVIDERS, MAX_WORKSPACE_MEMBERS in code but documents none of them
in the proto. New action: document current limits in the proto before beta, since raising them
later is a breaking change and lowering them certainly is.
1.9 AIP-205 (Beta-blocking changes) gives the inventory a mechanism it lacked
AIP-205's contribution is procedural: known-imperfect surfaces should carry an in-proto comment
referencing aip.dev/beta-blocker stating what change is needed for beta, so the debt is legible in
the schema rather than in a tracking document.
That is directly useful for #2565. Findings we consciously defer (e.g. full LRO, hierarchical names,
storage/RPC split tier 2) should get a comment at the affected field or method rather than living only
in this gist. It converts our review output into something a future reader of the proto discovers
without archaeology.
2. Where AIP adds findings the prior reviews missed
2.1 NEW — No google.api.field_behavior annotations anywhere (AIP-203)
AIP-203: the annotation must be applied to every field in request messages and resource messages,
carrying at least one of REQUIRED / OPTIONAL / OUTPUT_ONLY, plus IMMUTABLE, INPUT_ONLY,
IDENTIFIER, UNORDERED_LIST as applicable.
This is a genuine gap none of the three prior reviews raised, and it is more than stylistic. The
information exists in OpenShell's protos — as prose:
"Required for sandbox-scoped updates. Not required when global=true" → REQUIRED-ish, conditional
"Immutable after creation" (ObjectMeta.workspace) → IMMUTABLE
"Server-set provenance... Ignored on import/update payloads" (ProviderProfile.source, .scope) → OUTPUT_ONLY
"Once set, this field is immutable" (deletion_timestamp_ms) → IMMUTABLE
"only populated when explicitly requested" (SandboxPolicyRevision.policy) → conditional output
So OpenShell has done the analysis and recorded it in comments a machine cannot read. Consequences:
codegen can't mark fields, validation can't be derived, and #2565's documentation deliverable
("required/optional behavior, defaults, validation rules") has to be written by hand and will drift —
exactly the failure mode already demonstrated by the tls field (data-model D2b).
Recommendation. Adopt field_behavior. It is idiom-neutral (nothing about it presupposes
Google-style resource names), purely additive to the wire format, mechanically checkable in CI, and it
converts existing prose into enforceable contract. Of everything in this cross-check, this is the
highest value-per-unit-effort item. Caveat: it requires depending on google/api/field_behavior.proto,
a small well-known dependency.
2.2 NEW — AIP-126 partially defends the stringly-typed fields, with a caveat
This is the one place AIP disagrees with me, and I was wrong to treat all four fields alike.
AIP-126: enums suit value sets that change "no more than once a year"; "for enumerated values where
the set of allowed values changes frequently, APIs should use a string field instead", formatted
kebab-case with documented values.
Re-examining data-model D2 against that:
Field
Values
AIP verdict
enforcement
enforce, audit
Enum. Two values, stable, security-critical. D2 correct.
tls
terminate, passthrough, (skip)
Enum. Small, stable. D2 correct — and the drift in D2b proves the point.
access
read-only, read-write, full
Enum, but note these are already valid kebab-case, so the string form is at least AIP-shaped.
protocol
rest, websocket, graphql, sql, ""
Genuinely arguable. L7 protocol support is the field most likely to grow (gRPC, MCP, Redis, mongo…). AIP would accept a documented string here.
So D2's core claim survives where it matters most — enforcement and tls should be enums, and the
fail-open parse plus the inverted documentation make that urgent. But D2 overreached on protocol:
if L7 protocol support is expected to expand often, a documented kebab-case string is the AIP-preferred
choice, and converting it to an enum would make each new protocol an enum addition with
client-compatibility considerations.
Corrected D2 recommendation: enum enforcement, tls, access; leave protocol as a string but
document the closed set in the proto and reject unknown values at write time. The fail-open
behavior is the actual defect, and it is fixable for strings too — validation at the write boundary is
independent of the type choice.
2.3 NEW — AIP-147 (Sensitive fields): different mechanism, right outcome, structural risk remains
AIP-147 prefers, for data stored-but-never-read: an input-only field with no output counterpart, or
an OUTPUT_ONLY bool <field>_set, or an obfuscated_ prefix.
OpenShell instead returns the field and scrubs it. Provider.credentials (a map<string,string>
marked (secret) = true) is present in ProviderResponse and ListProvidersResponse, and
redact_provider_credentials (grpc/provider.rs:41) overwrites each value with "REDACTED" on the
read path — applied at 6 call sites, with a test asserting "credential values must be redacted in gRPC
responses."
The security property holds today. But the AIP mechanism is structurally safer: if the field
cannot appear in a response message, a new read path cannot forget to redact. OpenShell's approach
requires every current and future read path to remember — and there are already 6 of them plus the
gateway-interceptor JSON path (data-model D-F7) that reimplements redaction over Struct by hand.
Not a bug. A defense-in-depth gap worth logging: one missed call site is a credential disclosure,
and the type system is not helping. Cheapest hardening consistent with the current shape: make the
redaction a constructor-level invariant (a PublicProvider projection type) rather than a function
callers must remember to apply — which is the storage/RPC separation of audit F1 arriving from a
different direction.
2.4 AIP-215 reframes audit F1 — and mostly supports the cheap tier
AIP-215 requires all API-specific protos to live in a versioned package and forbids cross-API proto
sharing, on dependency-management grounds.
F1's core finding (public RPC messages are the DB storage format) is better supported by
protobuf.dev rule 21 than by AIP-215, which is about API-to-API coupling rather than API-to-storage.
But AIP-215's rationale transfers cleanly to F1's cheap tier: the 4 Stored* messages sitting in
openshell.v1 despite appearing in no RPC are precisely the kind of non-API proto that should not
occupy a versioned API package. Moving them out is non-breaking and now has two independent
justifications.
AIP-215 does not independently justify F1's expensive tier (storage twins for the 7 dual-purpose
resources). That remains a protobuf.dev rule-21 argument, and the cost/benefit call is unchanged.
2.5 AIP-159 gives D5 a concrete, better alternative to the boolean
AIP-159: read across collections with a - wildcard on the parent
(workspaces/-/sandboxes), and "the guidance does not recommend boolean flags."
That makes bool all_workspaces (4 requests) directly non-conformant and supplies a mechanism that
solves both D5 problems at once — the prose-only mutual exclusion and the proto3 unset-vs-empty
ambiguity — because a wildcard is a legal value of the field rather than a second field.
However, the wildcard mechanism presupposes AIP-122 hierarchical names (there must be a "parent"
to wildcard). Adopting it without hierarchical names would mean workspace: "-", which is a
sentinel-value-in-a-string — workable and cheap, but a convention OpenShell would be inventing rather
than inheriting.
Two viable paths for D5, both better than the status quo:
Cheap, idiom-consistent:oneof scope { string workspace; bool all_workspaces; } — as D5
originally recommended. Fixes presence and exclusivity. Stays Kubernetes-shaped.
AIP-shaped:workspace: "-" as a documented wildcard. One field, no oneof, but a magic string.
I'd still recommend the oneof. It expresses the constraint in the type system, which the wildcard
does not, and it doesn't require inventing sentinel semantics.
2.6 AIP-154 confirms D6's semantics are right and only the spelling is non-standard
AIP-154: a string etag (RFC 7232, conventionally field 99); mismatch → ABORTED; missing etag
generally permitted unless the service demands strict consistency.
OpenShell uses uint64 resource_version + expected_resource_version, and
persistence_error_to_status maps CAS conflict → ABORTED. The semantics and the error code are
exactly right; only the field name and type diverge, and that divergence is inherited from the
Kubernetes idiom deliberately. No change recommended.
What AIP-154 does sharpen is D6's open question. AIP-154 permits omitting the etag by default but
notes strict-consistency services may reject with INVALID_ARGUMENT. OpenShell's
expected_resource_version = 0 → "use current version (backward compatibility)" is the permissive
option, i.e. last-write-wins by default. For a product whose premise is many concurrent autonomous
agents mutating shared policy, D6's recommendation to consider making it mandatory is strengthened.
3. Net effect on the prior reviews
Prior finding
AIP effect
Action
G6 (no error details)
Escalated to MUST (AIP-193)
Raise priority; adopt ErrorInfo + BadRequest
G8 (truncation-blind lists)
Escalated to MUST (AIP-158)
next_page_token is the required fix, not total_size
G4 (no idempotency)
Confirmed; name corrected (AIP-155)
Use request_id, UUID4, ≤36 chars
D-F6 (bool deleted)
Escalated to explicit non-conformance (AIP-135)
Empty or resource; add allow_missing
F3 (time types)
Confirmed; naming rule added (AIP-142)
Also _time suffix, imperative tense
D8/F9 (UNSPECIFIED+UNKNOWN)
Escalated (AIP-216)
Collapse to one; never emit it
D5 (all_workspaces bool)
Confirmed; alternative offered (AIP-159)
Keep oneof recommendation
D4/D11 (→ oneof)
Confirmed as breaking (AIP-180)
Pre-beta or never
G5 (async completion)
Partially validated, de-prioritized (AIP-151)
Fix WatchSandbox first; full LRO later
F1 (storage/RPC fusion)
Cheap tier gains support (AIP-215)
Unchanged; move Stored* out
D6 (version counters)
Semantics validated (AIP-154)
No rename; strengthen CAS default
D2 (stringly-typed)
Partially contradicted (AIP-126)
protocol may stay a string; enum the rest
—
NEW: no field_behavior (AIP-203)
Adopt — highest value/effort ratio
—
NEW: undocumented length limits (AIP-180)
Document in proto pre-beta
—
NEW: redaction is call-site-dependent (AIP-147)
Harden structurally
—
NEW: beta-blocker comments (AIP-205)
Annotate deferred debt in-proto
G3/G1/G2 (health, watch bugs)
No AIP coverage
Unchanged — still the only outright bugs
Two findings were wrong or overstated and are corrected above: D2's treatment of protocol
(§2.2) and G5's implied priority for full LRO adoption (§1.7). Everything else survives, and eight
findings gain a normative citation that makes them easier to defend in review.
Nothing AIP says contradicts the three bugs (G1 stop_on_terminal, G2 dead
SandboxStreamWarning, G3 phantom health/reflection). Those remain the highest-priority items in the
whole review regardless of house style, because they are implementation-vs-contract mismatches rather
than design choices.
4. Recommended AIP adoption scope
Adopt (idiom-neutral, high value):
AIP
What
Breaking?
203
field_behavior on all request/resource fields
No
193
ErrorInfo + BadRequest + RetryInfo in error details
No
155
request_id on non-idempotent mutations
No
158
next_page_token in list responses
No (rename of limit/offset is)
135
Delete → Empty/resource; allow_missing
Yes
142
Timestamp/Duration + _time naming
Yes
180
Use its breaking-change list as the compatibility policy's spine
N/A
205
In-proto beta-blocker comments for deferred debt
No
126
Enum-vs-string-vs-bool decision rule
Mixed
Note the divergence, do not adopt (idiom-specific):
AIP
Why not
122
Hierarchical resource names — large restructuring; value depends on Google-style IAM/logging OpenShell lacks. D1's SandboxRef achieves the coherence goal far cheaper.
154
etag — OpenShell's resource_version has identical semantics and the correct ABORTED mapping.
216
State naming / ACTIVE — conflicts with the Kubernetes status.phase/Ready idiom deliberately chosen. Do adopt its one-unknown-value rule.
151
Full google.longrunning.Operations — new service + dependency; existing phase + watch covers the need once G1/G2 are fixed.
159
- wildcard — presupposes AIP-122 parents; oneof is better here.
Document the choice. The compatibility policy (#2565 deliverable) should state plainly that
OpenShell follows the Kubernetes resource idiom, list the AIPs adopted and consciously declined with
reasons, and require new APIs to follow the same idiom. Without that statement, the next contributor
reaches for AIP (or for K8s, or for neither) and the inconsistency that produced every finding in these
reviews regenerates.