kessel-sdk 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 136206dbccfc87a36252fa0b635f195d00ebc861f9d26c3a35095403257e971c
-  data.tar.gz: 6e1366c5ed2fc78316fd7804f4ff31ac59819817e919fda84e689c7c8023f980
+  metadata.gz: 6f118f8d4a64bb88e16061100917338de50a57456725240592395e4e9469eb18
+  data.tar.gz: 0cdba6a003c929eb0e111ef832fdc602b13a0dc48dc52ea773522c096408cea8
 SHA512:
-  metadata.gz: 2c015adbcbf6838b582f598b31d7860d31541c4adeb622c60877399b67ae797a516f603185640890f6c711311e0ff9f09ef0968153219b9dddcc070bb75acfeb
-  data.tar.gz: 4967035e1789c864e4197e5e6ffcbf7bfe6e2d47dc24b2c1a4823b83e198171f043f0ceb0f9bee4cbbc5ae5f495882c2654b6d6e08989a4cc15fae5de3513a96
+  metadata.gz: d172c0dc4223a7aca090c58a14ab2c86421383ad1fc0c7931690f576fa1d88130bde656b495455f0fcd91c331d4f2dcb935963a3f9f7a5708640849102d26ddd
+  data.tar.gz: 1112d3a51e7c23f00371d88adf7cc17e8323e20d4d80663272f7a55c87e52c5b50374582c2c203a75d14954773b0ebb982c4df79553a067edcfc737d44721eb9

data/README.md

@@ -58,7 +58,6 @@ lib/
 sig/                         # RBS type signatures for hand-written code
 spec/                        # RSpec test suite
 examples/                    # Working examples with dotenv configuration
-docs/                        # Domain-specific guidelines (see Documentation below)
 ```
 
 Files under `lib/kessel/inventory/v*/`, `lib/google/`, and `lib/buf/` are **generated** by `buf generate` and must never be hand-edited. They are automatically regenerated every 6 hours via CI.
@@ -355,16 +354,11 @@ ruby check.rb
 
 ## Documentation
 
-Detailed domain-specific guidelines are maintained in the `docs/` directory:
+For AI-assisted development context, see [AGENTS.md](AGENTS.md). Directory-local `GUIDELINES.md` files provide detailed conventions for specific areas of the codebase:
 
-- **[API Contracts](docs/api-contracts-guidelines.md)** -- Protobuf code generation, module/namespace mapping, ClientBuilder API, request/response patterns, and RBS type signatures
-- **[Integration](docs/integration-guidelines.md)** -- gRPC client construction, authentication flows, RBAC helpers, streaming/pagination, and environment configuration
-- **[Security](docs/security-guidelines.md)** -- Token caching thread safety, gRPC channel security, credential validation, and secrets management
-- **[Performance](docs/performance-guidelines.md)** -- Token caching, gRPC client reuse, bulk vs. individual operations, consistency controls, and streaming pagination
-- **[Error Handling](docs/error-handling-guidelines.md)** -- Custom exception hierarchy, error wrapping conventions, and gRPC error passthrough policy
-- **[Testing](docs/testing-guidelines.md)** -- RSpec configuration, mocking conventions, coverage setup, and CI expectations
-
-For AI-assisted development context, see [AGENTS.md](AGENTS.md).
+- **[lib/kessel/inventory/GUIDELINES.md](lib/kessel/inventory/GUIDELINES.md)** -- Inventory module: ClientBuilder, service wiring, V1beta2 API patterns, auth integration
+- **[lib/kessel/rbac/GUIDELINES.md](lib/kessel/rbac/GUIDELINES.md)** -- RBAC V2 module conventions
+- **[examples/GUIDELINES.md](examples/GUIDELINES.md)** -- Example script conventions
 
 ## Release Instructions
 
@@ -496,7 +490,7 @@ rake release
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-Please review the [domain-specific guidelines](docs/) before contributing. All specs must pass on Ruby 3.3 and 3.4. Fix RuboCop violations before merging, and update RBS type signatures in `sig/kessel/` when modifying hand-written code.
+Please review [AGENTS.md](AGENTS.md) and the directory-local `GUIDELINES.md` files before contributing. All specs must pass on Ruby 3.3 and 3.4. Fix RuboCop violations before merging, and update RBS type signatures in `sig/kessel/` when modifying hand-written code.
 
 ## License
 

data/lib/google/rpc/status_pb.rb

@@ -7,7 +7,7 @@ require 'google/protobuf'
 require 'google/protobuf/any_pb'
 
 
-descriptor_data = "\n\x17google/rpc/status.proto\x12\ngoogle.rpc\x1a\x19google/protobuf/any.proto\"f\n\x06Status\x12\x12\n\x04\x63ode\x18\x01 \x01(\x05R\x04\x63ode\x12\x18\n\x07message\x18\x02 \x01(\tR\x07message\x12.\n\x07\x64\x65tails\x18\x03 \x03(\x0b\x32\x14.google.protobuf.AnyR\x07\x64\x65tailsBa\n\x0e\x63om.google.rpcB\x0bStatusProtoP\x01Z7google.golang.org/genproto/googleapis/rpc/status;status\xf8\x01\x01\xa2\x02\x03RPCb\x06proto3"
+descriptor_data = "\n\x17google/rpc/status.proto\x12\ngoogle.rpc\x1a\x19google/protobuf/any.proto\"f\n\x06Status\x12\x12\n\x04\x63ode\x18\x01 \x01(\x05R\x04\x63ode\x12\x18\n\x07message\x18\x02 \x01(\tR\x07message\x12.\n\x07\x64\x65tails\x18\x03 \x03(\x0b\x32\x14.google.protobuf.AnyR\x07\x64\x65tailsB^\n\x0e\x63om.google.rpcB\x0bStatusProtoP\x01Z7google.golang.org/genproto/googleapis/rpc/status;status\xa2\x02\x03RPCb\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/kessel/inventory/GUIDELINES.md

@@ -0,0 +1,161 @@
+# Inventory Module Guidelines
+
+This directory contains the Kessel Inventory client module -- the `ClientBuilder` fluent API, version-specific service wiring, and generated protobuf/gRPC stubs. The `ClientBuilder` base class is defined in `../inventory.rb` (the `Kessel::Inventory` module), and each version file in this directory creates service-specific builders from it.
+
+For repo-wide conventions (testing framework, RBS signatures, file headers, error patterns), see AGENTS.md at the repository root.
+
+## File Organization
+
+### Hand-written files (editable)
+
+- `../inventory.rb` -- `Kessel::Inventory` module with `client_builder_for_stub` factory and `ClientBuilder` base class
+- `v1.rb` -- Service wiring for `KesselInventoryHealthService::ClientBuilder` (health checks)
+- `v1beta1.rb` -- Service wiring for V1beta1 typed resource/relationship services (deprecated)
+- `v1beta2.rb` -- Service wiring for `KesselInventoryService::ClientBuilder` (current API)
+
+### Generated files (never edit)
+
+Everything under `v1/`, `v1beta1/`, and `v1beta2/` subdirectories (`*_pb.rb`, `*_services_pb.rb`) is generated by `buf generate` and overwritten automatically every 6 hours via CI. Changes to these files must go upstream in the `.proto` definitions at `buf.build/project-kessel/inventory-api`.
+
+## ClientBuilder Pattern
+
+### Factory Function
+
+`client_builder_for_stub(stub_class)` dynamically creates a new `Class` inheriting from `ClientBuilder` with `@stub_class` set. Each service module creates its builder as a constant:
+
+```ruby
+ClientBuilder = ::Kessel::Inventory.client_builder_for_stub(Stub)
+```
+
+Do not call `client_builder_for_stub` repeatedly at runtime -- the result is cached as a constant.
+
+### Fluent API
+
+`ClientBuilder` uses method chaining -- all authentication methods return `self`:
+
+```ruby
+# Insecure (local dev only)
+client = KesselInventoryService::ClientBuilder.new(target).insecure.build
+
+# OAuth2 authenticated
+client = KesselInventoryService::ClientBuilder.new(target)
+           .oauth2_client_authenticated(oauth2_client_credentials: creds)
+           .build
+
+# Custom credentials
+client = KesselInventoryService::ClientBuilder.new(target)
+           .authenticated(call_credentials: call_creds, channel_credentials: chan_creds)
+           .build
+```
+
+### Credential Defaults and Validation
+
+- When no channel credentials are set, `build` defaults to `GRPC::Core::ChannelCredentials.new` (TLS). This secure-by-default behavior must be preserved.
+- `insecure` sets a sentinel (`:this_channel_is_insecure`) that prevents composing with call credentials.
+- `validate_credentials` runs immediately on each auth method call, not deferred to `build`. This ensures invalid configurations fail at configuration time. Do not move validation to `build`.
+- `build` calls `credentials.compose(@call_credentials)` when both channel and call credentials are present.
+
+### Build Output
+
+`build` returns a single gRPC stub instance (not a tuple). The underlying gRPC channel manages its own HTTP/2 connection pool. Build once at application startup and reuse -- do not create a new stub per request.
+
+## Service Wiring Pattern
+
+Every gRPC service module must follow this exact pattern:
+
+```ruby
+# frozen_string_literal: true
+
+require 'kessel/inventory'
+require 'kessel/inventory/v1betaN/some_service_services_pb'
+
+include Kessel::Inventory
+
+module Kessel
+  module Inventory
+    module V1betaN
+      module KesselSomeService
+        ClientBuilder = ::Kessel::Inventory.client_builder_for_stub(Stub)
+      end
+    end
+  end
+end
+```
+
+The `include Kessel::Inventory` at the top level is required for `client_builder_for_stub` to resolve. The `Stub` constant comes from the generated `*_services_pb.rb` file.
+
+When adding a new service, also add the `ClientBuilder` constant declaration in `sig/kessel/inventory.rbs`.
+
+## Version Conventions
+
+| Directory | Status | Service |
+|---|---|---|
+| `v1/` | Active | `KesselInventoryHealthService` (health checks only) |
+| `v1beta2/` | Active (current) | `KesselInventoryService` (unified inventory API) |
+| `v1beta1/` | Deprecated | Typed K8s resources/relationships. Do not extend. |
+
+All new features target `v1beta2`. The unified `KesselInventoryService` uses `ReportResource`/`DeleteResource` instead of resource-specific services.
+
+Protobuf package `kessel.inventory.v1beta2` maps to Ruby module `Kessel::Inventory::V1beta2` -- note lowercase `beta` (not `V1Beta2`). This follows the protobuf-to-Ruby naming convention from `buf generate`.
+
+## V1beta2 API Patterns
+
+### Check Operations
+
+Check operations use a triplet: `object` (ResourceReference), `relation` (string), `subject` (SubjectReference). Use `Check` for read-path authorization and `CheckForUpdate` for strongly consistent pre-mutation checks.
+
+`CheckSelf` omits the subject (inferred from auth context).
+
+### Bulk Operations
+
+`CheckBulk` and `CheckForUpdateBulk` accept 1--1000 items per RPC. Responses use a `pairs` field where each pair contains either `item` (success) or `error` (`Google::Rpc::Status`). Always check per-item errors -- the RPC can succeed while individual items fail.
+
+### Resource Reporting
+
+`ReportResourceRequest` requires `type`, `reporter_type`, `reporter_instance_id`, `representations`, and `write_visibility`. Convert Ruby hashes to protobuf `Struct` via `Google::Protobuf::Struct.decode_json(hash.to_json)`.
+
+### Consistency Controls
+
+The `Consistency` message supports `minimize_latency` (default, may be stale), `at_least_as_fresh` (token from prior write), and `at_least_as_acknowledged` (waits for all acknowledged writes). `WriteVisibility` on report requests defaults to `WRITE_VISIBILITY_UNSPECIFIED` -- set `IMMEDIATE` only when the caller will immediately `Check` the newly reported resource.
+
+### Streaming RPCs
+
+`StreamedListObjects` and `StreamedListSubjects` use server-side streaming with `RequestPagination` (limit + continuation_token). Iterate with `.each` for constant memory.
+
+### Allowed Enum
+
+V1beta2 uses a shared top-level `Allowed` enum (`ALLOWED_TRUE`, `ALLOWED_FALSE`). V1beta1 uses per-response nested enums (`CheckResponse::Allowed`).
+
+### HTTP API Routes
+
+- V1: `/api/kessel/v1/{method}`
+- V1beta1: `/api/inventory/v1beta1/{domain}/{method}`
+- V1beta2: `/api/kessel/v1beta2/{method}`
+- RBAC V2 REST: `/api/rbac/v2/workspaces/`
+
+## Authentication Integration
+
+Authentication feeds into the `ClientBuilder` through two paths:
+
+- **gRPC path**: `Kessel::GRPC#oauth2_call_credentials(auth)` wraps an `OAuth2ClientCredentials` instance as `GRPC::Core::CallCredentials`. The proc is invoked on every RPC call, hitting the token cache fast path when the token is valid. Do not add blocking operations inside this proc.
+- **HTTP path**: `Kessel::Auth#oauth2_auth_request(oauth)` returns an `OAuth2AuthRequest` implementing the `AuthRequest` interface. The `configure_request(request)` method sets the `authorization` header on `Net::HTTPRequest` objects.
+
+The `AuthRequest` module defines an interface contract -- any class including it must implement `configure_request` or callers get `NotImplementedError`. New auth mechanisms must implement this interface and have matching RBS signatures in `sig/kessel/auth.rbs`.
+
+### Token Caching
+
+`OAuth2ClientCredentials` uses double-checked locking with a `@generation` counter to coalesce concurrent refresh requests into a single SSO call. Cached tokens are frozen with `.freeze` for concurrent read safety. Use `force_refresh: true` only after receiving an explicit 401/UNAUTHENTICATED error, never preemptively.
+
+## Console Helper
+
+`lib/kessel/console.rb` provides `principal_from_rh_identity` and `principal_from_rh_identity_header` for converting Red Hat identity headers into `SubjectReference` objects. It depends on `Kessel::RBAC::V2` factory helpers (specifically `principal_subject`).
+
+The `IDENTITY_TYPE_FIELDS` constant maps identity types to their JSON field names (`'User' => 'user'`, `'ServiceAccount' => 'service_account'`). When adding a new identity type, add it to this hash.
+
+## Adding a New Service Version
+
+1. Run `buf generate` to produce stubs in `lib/kessel/inventory/<version>/`.
+2. Create `lib/kessel/inventory/<version>.rb` following the service wiring pattern above.
+3. Add the `ClientBuilder` constant declaration to `sig/kessel/inventory.rbs`.
+4. Add a corresponding example in `examples/`.
+5. Run `bundle exec rspec` and `steep check`.

data/lib/kessel/inventory/v1beta2/acquire_lock_request_pb.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/acquire_lock_request.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+
+
+descriptor_data = "\n3kessel/inventory/v1beta2/acquire_lock_request.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\"6\n\x12\x41\x63quireLockRequest\x12 \n\x07lock_id\x18\x01 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\x06lockIdBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      AcquireLockRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.AcquireLockRequest").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/acquire_lock_response_pb.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/acquire_lock_response.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n4kessel/inventory/v1beta2/acquire_lock_response.proto\x12\x18kessel.inventory.v1beta2\"4\n\x13\x41\x63quireLockResponse\x12\x1d\n\nlock_token\x18\x01 \x01(\tR\tlockTokenBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      AcquireLockResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.AcquireLockResponse").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/create_tuples_request_pb.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/create_tuples_request.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/relationship_pb'
+require 'kessel/inventory/v1beta2/relation_fencing_check_pb'
+
+
+descriptor_data = "\n4kessel/inventory/v1beta2/create_tuples_request.proto\x12\x18kessel.inventory.v1beta2\x1a+kessel/inventory/v1beta2/relationship.proto\x1a\x35kessel/inventory/v1beta2/relation_fencing_check.proto\"\xd9\x01\n\x13\x43reateTuplesRequest\x12\x16\n\x06upsert\x18\x01 \x01(\x08R\x06upsert\x12>\n\x06tuples\x18\x02 \x03(\x0b\x32&.kessel.inventory.v1beta2.RelationshipR\x06tuples\x12X\n\rfencing_check\x18\x03 \x01(\x0b\x32..kessel.inventory.v1beta2.RelationFencingCheckH\x00R\x0c\x66\x65ncingCheck\x88\x01\x01\x42\x10\n\x0e_fencing_checkBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      CreateTuplesRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.CreateTuplesRequest").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/create_tuples_response_pb.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/create_tuples_response.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/consistency_token_pb'
+
+
+descriptor_data = "\n5kessel/inventory/v1beta2/create_tuples_response.proto\x12\x18kessel.inventory.v1beta2\x1a\x30kessel/inventory/v1beta2/consistency_token.proto\"o\n\x14\x43reateTuplesResponse\x12W\n\x11\x63onsistency_token\x18\x01 \x01(\x0b\x32*.kessel.inventory.v1beta2.ConsistencyTokenR\x10\x63onsistencyTokenBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      CreateTuplesResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.CreateTuplesResponse").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/delete_tuples_request_pb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/delete_tuples_request.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+require 'kessel/inventory/v1beta2/relation_tuple_filter_pb'
+require 'kessel/inventory/v1beta2/relation_fencing_check_pb'
+
+
+descriptor_data = "\n4kessel/inventory/v1beta2/delete_tuples_request.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\x1a\x34kessel/inventory/v1beta2/relation_tuple_filter.proto\x1a\x35kessel/inventory/v1beta2/relation_fencing_check.proto\"\xd0\x01\n\x13\x44\x65leteTuplesRequest\x12M\n\x06\x66ilter\x18\x01 \x01(\x0b\x32-.kessel.inventory.v1beta2.RelationTupleFilterB\x06\xbaH\x03\xc8\x01\x01R\x06\x66ilter\x12X\n\rfencing_check\x18\x02 \x01(\x0b\x32..kessel.inventory.v1beta2.RelationFencingCheckH\x00R\x0c\x66\x65ncingCheck\x88\x01\x01\x42\x10\n\x0e_fencing_checkBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      DeleteTuplesRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.DeleteTuplesRequest").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/delete_tuples_response_pb.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/delete_tuples_response.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/consistency_token_pb'
+
+
+descriptor_data = "\n5kessel/inventory/v1beta2/delete_tuples_response.proto\x12\x18kessel.inventory.v1beta2\x1a\x30kessel/inventory/v1beta2/consistency_token.proto\"o\n\x14\x44\x65leteTuplesResponse\x12W\n\x11\x63onsistency_token\x18\x01 \x01(\x0b\x32*.kessel.inventory.v1beta2.ConsistencyTokenR\x10\x63onsistencyTokenBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      DeleteTuplesResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.DeleteTuplesResponse").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/read_tuples_request_pb.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/read_tuples_request.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+require 'kessel/inventory/v1beta2/relation_tuple_filter_pb'
+require 'kessel/inventory/v1beta2/request_pagination_pb'
+require 'kessel/inventory/v1beta2/consistency_pb'
+
+
+descriptor_data = "\n2kessel/inventory/v1beta2/read_tuples_request.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\x1a\x34kessel/inventory/v1beta2/relation_tuple_filter.proto\x1a\x31kessel/inventory/v1beta2/request_pagination.proto\x1a*kessel/inventory/v1beta2/consistency.proto\"\xa1\x02\n\x11ReadTuplesRequest\x12M\n\x06\x66ilter\x18\x01 \x01(\x0b\x32-.kessel.inventory.v1beta2.RelationTupleFilterB\x06\xbaH\x03\xc8\x01\x01R\x06\x66ilter\x12P\n\npagination\x18\x02 \x01(\x0b\x32+.kessel.inventory.v1beta2.RequestPaginationH\x00R\npagination\x88\x01\x01\x12L\n\x0b\x63onsistency\x18\x03 \x01(\x0b\x32%.kessel.inventory.v1beta2.ConsistencyH\x01R\x0b\x63onsistency\x88\x01\x01\x42\r\n\x0b_paginationB\x0e\n\x0c_consistencyBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      ReadTuplesRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.ReadTuplesRequest").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/read_tuples_response_pb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/read_tuples_response.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/relationship_pb'
+require 'kessel/inventory/v1beta2/response_pagination_pb'
+require 'kessel/inventory/v1beta2/consistency_token_pb'
+
+
+descriptor_data = "\n3kessel/inventory/v1beta2/read_tuples_response.proto\x12\x18kessel.inventory.v1beta2\x1a+kessel/inventory/v1beta2/relationship.proto\x1a\x32kessel/inventory/v1beta2/response_pagination.proto\x1a\x30kessel/inventory/v1beta2/consistency_token.proto\"\xf9\x01\n\x12ReadTuplesResponse\x12<\n\x05tuple\x18\x01 \x01(\x0b\x32&.kessel.inventory.v1beta2.RelationshipR\x05tuple\x12L\n\npagination\x18\x02 \x01(\x0b\x32,.kessel.inventory.v1beta2.ResponsePaginationR\npagination\x12W\n\x11\x63onsistency_token\x18\x03 \x01(\x0b\x32*.kessel.inventory.v1beta2.ConsistencyTokenR\x10\x63onsistencyTokenBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      ReadTuplesResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.ReadTuplesResponse").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/relation_fencing_check_pb.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/relation_fencing_check.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+
+
+descriptor_data = "\n5kessel/inventory/v1beta2/relation_fencing_check.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\"`\n\x14RelationFencingCheck\x12 \n\x07lock_id\x18\x01 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\x06lockId\x12&\n\nlock_token\x18\x02 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\tlockTokenBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      RelationFencingCheck = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.RelationFencingCheck").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/relation_object_reference_pb.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/relation_object_reference.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+require 'kessel/inventory/v1beta2/relation_object_type_pb'
+
+
+descriptor_data = "\n8kessel/inventory/v1beta2/relation_object_reference.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\x1a\x33kessel/inventory/v1beta2/relation_object_type.proto\"|\n\x17RelationObjectReference\x12H\n\x04type\x18\x01 \x01(\x0b\x32,.kessel.inventory.v1beta2.RelationObjectTypeB\x06\xbaH\x03\xc8\x01\x01R\x04type\x12\x17\n\x02id\x18\x02 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\x02idBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      RelationObjectReference = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.RelationObjectReference").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/relation_object_type_pb.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/relation_object_type.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+
+
+descriptor_data = "\n3kessel/inventory/v1beta2/relation_object_type.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\"X\n\x12RelationObjectType\x12%\n\tnamespace\x18\x01 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\tnamespace\x12\x1b\n\x04name\x18\x02 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\x04nameBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      RelationObjectType = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.RelationObjectType").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/relation_subject_filter_pb.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/relation_subject_filter.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n6kessel/inventory/v1beta2/relation_subject_filter.proto\x12\x18kessel.inventory.v1beta2\"\xf9\x01\n\x15RelationSubjectFilter\x12\x30\n\x11subject_namespace\x18\x01 \x01(\tH\x00R\x10subjectNamespace\x88\x01\x01\x12&\n\x0csubject_type\x18\x02 \x01(\tH\x01R\x0bsubjectType\x88\x01\x01\x12\"\n\nsubject_id\x18\x03 \x01(\tH\x02R\tsubjectId\x88\x01\x01\x12\x1f\n\x08relation\x18\x04 \x01(\tH\x03R\x08relation\x88\x01\x01\x42\x14\n\x12_subject_namespaceB\x0f\n\r_subject_typeB\r\n\x0b_subject_idB\x0b\n\t_relationBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      RelationSubjectFilter = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.RelationSubjectFilter").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/relation_subject_reference_pb.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/relation_subject_reference.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+require 'kessel/inventory/v1beta2/relation_object_reference_pb'
+
+
+descriptor_data = "\n9kessel/inventory/v1beta2/relation_subject_reference.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\x1a\x38kessel/inventory/v1beta2/relation_object_reference.proto\"\x9d\x01\n\x18RelationSubjectReference\x12\x1f\n\x08relation\x18\x01 \x01(\tH\x00R\x08relation\x88\x01\x01\x12S\n\x07subject\x18\x02 \x01(\x0b\x32\x31.kessel.inventory.v1beta2.RelationObjectReferenceB\x06\xbaH\x03\xc8\x01\x01R\x07subjectB\x0b\n\t_relationBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      RelationSubjectReference = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.RelationSubjectReference").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/relation_tuple_filter_pb.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/relation_tuple_filter.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/relation_subject_filter_pb'
+
+
+descriptor_data = "\n4kessel/inventory/v1beta2/relation_tuple_filter.proto\x12\x18kessel.inventory.v1beta2\x1a\x36kessel/inventory/v1beta2/relation_subject_filter.proto\"\xf0\x02\n\x13RelationTupleFilter\x12\x32\n\x12resource_namespace\x18\x01 \x01(\tH\x00R\x11resourceNamespace\x88\x01\x01\x12(\n\rresource_type\x18\x02 \x01(\tH\x01R\x0cresourceType\x88\x01\x01\x12$\n\x0bresource_id\x18\x03 \x01(\tH\x02R\nresourceId\x88\x01\x01\x12\x1f\n\x08relation\x18\x04 \x01(\tH\x03R\x08relation\x88\x01\x01\x12[\n\x0esubject_filter\x18\x05 \x01(\x0b\x32/.kessel.inventory.v1beta2.RelationSubjectFilterH\x04R\rsubjectFilter\x88\x01\x01\x42\x15\n\x13_resource_namespaceB\x10\n\x0e_resource_typeB\x0e\n\x0c_resource_idB\x0b\n\t_relationB\x11\n\x0f_subject_filterBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      RelationTupleFilter = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.RelationTupleFilter").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/relationship_pb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/relationship.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+require 'kessel/inventory/v1beta2/relation_object_reference_pb'
+require 'kessel/inventory/v1beta2/relation_subject_reference_pb'
+
+
+descriptor_data = "\n+kessel/inventory/v1beta2/relationship.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\x1a\x38kessel/inventory/v1beta2/relation_object_reference.proto\x1a\x39kessel/inventory/v1beta2/relation_subject_reference.proto\"\xe0\x01\n\x0cRelationship\x12U\n\x08resource\x18\x01 \x01(\x0b\x32\x31.kessel.inventory.v1beta2.RelationObjectReferenceB\x06\xbaH\x03\xc8\x01\x01R\x08resource\x12#\n\x08relation\x18\x02 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\x08relation\x12T\n\x07subject\x18\x03 \x01(\x0b\x32\x32.kessel.inventory.v1beta2.RelationSubjectReferenceB\x06\xbaH\x03\xc8\x01\x01R\x07subjectBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      Relationship = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.Relationship").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/tuple_service_pb.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/tuple_service.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/create_tuples_request_pb'
+require 'kessel/inventory/v1beta2/create_tuples_response_pb'
+require 'kessel/inventory/v1beta2/read_tuples_request_pb'
+require 'kessel/inventory/v1beta2/read_tuples_response_pb'
+require 'kessel/inventory/v1beta2/delete_tuples_request_pb'
+require 'kessel/inventory/v1beta2/delete_tuples_response_pb'
+require 'kessel/inventory/v1beta2/acquire_lock_request_pb'
+require 'kessel/inventory/v1beta2/acquire_lock_response_pb'
+
+
+descriptor_data = "\n,kessel/inventory/v1beta2/tuple_service.proto\x12\x18kessel.inventory.v1beta2\x1a\x34kessel/inventory/v1beta2/create_tuples_request.proto\x1a\x35kessel/inventory/v1beta2/create_tuples_response.proto\x1a\x32kessel/inventory/v1beta2/read_tuples_request.proto\x1a\x33kessel/inventory/v1beta2/read_tuples_response.proto\x1a\x34kessel/inventory/v1beta2/delete_tuples_request.proto\x1a\x35kessel/inventory/v1beta2/delete_tuples_response.proto\x1a\x33kessel/inventory/v1beta2/acquire_lock_request.proto\x1a\x34kessel/inventory/v1beta2/acquire_lock_response.proto2\xdd\x03\n\x12KesselTupleService\x12r\n\x0c\x43reateTuples\x12-.kessel.inventory.v1beta2.CreateTuplesRequest\x1a..kessel.inventory.v1beta2.CreateTuplesResponse\"\x03\x88\x02\x01\x12r\n\x0c\x44\x65leteTuples\x12-.kessel.inventory.v1beta2.DeleteTuplesRequest\x1a..kessel.inventory.v1beta2.DeleteTuplesResponse\"\x03\x88\x02\x01\x12n\n\nReadTuples\x12+.kessel.inventory.v1beta2.ReadTuplesRequest\x1a,.kessel.inventory.v1beta2.ReadTuplesResponse\"\x03\x88\x02\x01\x30\x01\x12o\n\x0b\x41\x63quireLock\x12,.kessel.inventory.v1beta2.AcquireLockRequest\x1a-.kessel.inventory.v1beta2.AcquireLockResponse\"\x03\x88\x02\x01\x42r\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/tuple_service_services_pb.rb

@@ -0,0 +1,44 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# Source: kessel/inventory/v1beta2/tuple_service.proto for package 'kessel.inventory.v1beta2'
+
+require 'grpc'
+require 'kessel/inventory/v1beta2/tuple_service_pb'
+
+module Kessel
+  module Inventory
+    module V1beta2
+      module KesselTupleService
+        # DEPRECATED: KesselTupleService provides legacy tuple-layer operations.
+        # This service exists only for RBAC backward compatibility and will be removed.
+        # All endpoints are marked deprecated. Do not add new consumers.
+        # Use KesselInventoryService's ReportResource for new integrations.
+        class Service
+
+          include ::GRPC::GenericService
+
+          self.marshal_class_method = :encode
+          self.unmarshal_class_method = :decode
+          self.service_name = 'kessel.inventory.v1beta2.KesselTupleService'
+
+          # DEPRECATED: CreateTuples creates relationship tuples.
+          # This endpoint exists only for RBAC backward compatibility.
+          # Use ReportResource instead for new code.
+          rpc :CreateTuples, ::Kessel::Inventory::V1beta2::CreateTuplesRequest, ::Kessel::Inventory::V1beta2::CreateTuplesResponse
+          # DEPRECATED: DeleteTuples deletes relationship tuples.
+          # This endpoint exists only for RBAC backward compatibility.
+          # Use DeleteResource instead for new code.
+          rpc :DeleteTuples, ::Kessel::Inventory::V1beta2::DeleteTuplesRequest, ::Kessel::Inventory::V1beta2::DeleteTuplesResponse
+          # DEPRECATED: ReadTuples reads relationship tuples.
+          # This endpoint exists only for RBAC backward compatibility.
+          # Use StreamedListObjects/StreamedListSubjects instead for new code.
+          rpc :ReadTuples, ::Kessel::Inventory::V1beta2::ReadTuplesRequest, stream(::Kessel::Inventory::V1beta2::ReadTuplesResponse)
+          # DEPRECATED: AcquireLock acquires a distributed lock.
+          # This endpoint exists only for RBAC backward compatibility.
+          rpc :AcquireLock, ::Kessel::Inventory::V1beta2::AcquireLockRequest, ::Kessel::Inventory::V1beta2::AcquireLockResponse
+        end
+
+        Stub = Service.rpc_stub_class
+      end
+    end
+  end
+end

data/lib/kessel/rbac/GUIDELINES.md

@@ -0,0 +1,104 @@
+# RBAC V2 Module Guidelines
+
+## Directory Purpose
+
+This directory contains the hand-written RBAC convenience layer (`Kessel::RBAC::V2`) built on top of V1beta2 protobuf types. It provides workspace operations over both HTTP and gRPC, plus factory helpers for constructing protobuf resource/subject references.
+
+## File Organization
+
+The module is split across three files reopening the same `Kessel::RBAC::V2` module:
+
+- `v2.rb` -- Public API: `fetch_default_workspace`, `fetch_root_workspace`, `list_workspaces`, plus private response processing. Defines the `Workspace` struct and constants.
+- `v2_helpers.rb` -- Factory methods for protobuf references: `workspace_type`, `role_type`, `principal_resource`, `role_resource`, `workspace_resource`, `principal_subject`, `subject`.
+- `v2_http.rb` -- Private HTTP helpers: `run_request` (sets headers, calls auth), `check_http_client` (validates host/port match).
+
+All three files must be required together -- `lib/kessel-sdk.rb` handles this. Do not require individual files in isolation.
+
+## Module Design
+
+- `V2` is a Ruby module meant to be `include`d, not instantiated. Tests use `include Kessel::RBAC::V2` directly in the RSpec context.
+- `V2` includes `Kessel::Inventory::V1beta2` to access protobuf types (`SubjectReference`, `ResourceReference`, `RepresentationType`, etc.) without full qualification.
+- The `include V1beta2` appears in both `v2.rb` and `v2_helpers.rb` -- this is intentional for load-order independence.
+
+## Constants and Structs
+
+- `WORKSPACE_ENDPOINT = '/api/rbac/v2/workspaces/'` -- the REST path appended to `rbac_base_endpoint`.
+- `DEFAULT_PAGE_LIMIT = 1000` -- page size for `list_workspaces` auto-pagination.
+- `Workspace = Struct.new(:id, :name, :type, :description)` -- keyword-argument struct returned by HTTP workspace fetches.
+
+## Factory Helper Conventions
+
+All factory methods in `v2_helpers.rb` follow these rules:
+
+- Every RBAC resource uses `reporter_type: 'rbac'` (hardcoded, not configurable).
+- `principal_resource(id, domain)` formats `resource_id` as `"#{domain}/#{id}"` -- the domain comes first.
+- `principal_subject(id, domain)` wraps `principal_resource` in a `SubjectReference`.
+- `subject(resource_ref, relation = nil)` is a generic factory -- pass `nil` for relation to omit it.
+- `workspace_type` and `role_type` return `RepresentationType` structs, not `ResourceReference`.
+- Factory methods return frozen protobuf objects (protobuf default). Do not `.dup` or mutate them.
+
+## HTTP Workspace Operations
+
+### Request Pattern
+
+- `fetch_workspace` (private) strips trailing slashes from `rbac_base_endpoint`, appends `WORKSPACE_ENDPOINT`, sets a `type` query parameter, and issues a `GET` request.
+- The `x-rh-rbac-org-id` header is required on every request -- set from the `org_id` parameter in `run_request`.
+- Authentication is optional: when `auth` is non-nil, `auth.configure_request(request)` is called. The `auth` object must implement the `AuthRequest` interface (i.e., `Kessel::Auth#oauth2_auth_request(oauth)` return value).
+
+### HTTP Client Handling
+
+- When `http_client` is `nil`, a new `Net::HTTP` is created per call (one TCP connection per fetch).
+- When `http_client` is provided, `check_http_client` validates that its `address` and `port` match the endpoint URI. Mismatches raise `RuntimeError`.
+- For multiple workspace fetches, pass a pre-started `Net::HTTP` to avoid repeated TCP handshakes.
+
+### Response Processing
+
+- `process_response` raises `RuntimeError` for non-success HTTP status codes.
+- It expects exactly one workspace in `data[]` -- any other count raises `RuntimeError`.
+- `extract_workspace` maps JSON keys to the `Workspace` struct.
+
+## gRPC Workspace Listing
+
+`list_workspaces(inventory, subject, relation, continuation_token = nil, consistency: nil)` returns a lazy `Enumerator`:
+
+- Internally calls `inventory.streamed_list_objects` with a `StreamedListObjectsRequest`.
+- Auto-paginates: extracts `continuation_token` from each response's `pagination` field.
+- Stops when the server returns no responses or `continuation_token` is nil/falsy.
+- The `consistency` parameter is forwarded to every paginated request -- it is not modified between pages.
+- Consume with `.each` for constant memory, or `.to_a` to materialize all results (use with caution on large datasets).
+
+## Error Handling
+
+- Local validation and HTTP failures use bare `RuntimeError` (via `raise "message"`) -- not custom exception classes. These cover workspace fetch HTTP errors and unexpected response shapes.
+- gRPC errors from `streamed_list_objects` propagate directly as `GRPC::BadStatus` subclasses -- do not wrap them.
+
+## RBS Type Signatures
+
+- Signatures live in `sig/kessel/rbac.rbs`. Update this file when adding or changing public method signatures.
+- The `Workspace` struct, all public methods, and `list_workspaces` return type (`Enumerator`) are declared.
+- Run `steep check` after changes to verify type correctness.
+
+## Testing
+
+- Tests are in `spec/kessel/rbac/v2_spec.rb`.
+- The spec includes `Kessel::RBAC::V2` in the test context and calls module methods directly.
+- HTTP calls are fully mocked -- `Net::HTTP`, `Net::HTTP::Get`, `URI`, and response objects.
+- gRPC streaming is mocked by stubbing `inventory.streamed_list_objects` with arrays or dynamic blocks.
+- Test pagination by returning different continuation tokens across multiple mock invocations.
+- Assert both the exception class and a message regex for error paths.
+
+## RuboCop
+
+This directory is subject to RuboCop rules (unlike generated code). Limits: method length 25, class length 150, cyclomatic complexity 10, line length 120.
+
+## Relationship to Kessel::Console
+
+`lib/kessel/console.rb` depends on `v2_helpers.rb` (via `require_relative 'rbac/v2_helpers'`) and uses `principal_subject` to convert Red Hat identity headers into `SubjectReference` objects. Changes to factory helper signatures affect `Console`.
+
+## Adding New RBAC Operations
+
+1. Determine whether the operation is HTTP-based (REST) or gRPC-based (protobuf service call).
+2. Add public methods to `v2.rb`. Add factory helpers to `v2_helpers.rb`. Add HTTP plumbing to `v2_http.rb`.
+3. Update `sig/kessel/rbac.rbs` with the new method signature.
+4. Add tests in `spec/kessel/rbac/v2_spec.rb` following the existing mock patterns.
+5. Run `bundle exec rspec` and `steep check`.

data/lib/kessel/rbac/v2.rb

@@ -14,12 +14,14 @@ module Kessel
       DEFAULT_PAGE_LIMIT = 1000
       Workspace = Struct.new(:id, :name, :type, :description)
 
-      def fetch_default_workspace(rbac_base_endpoint, org_id, auth: nil, http_client: nil)
-        fetch_workspace(rbac_base_endpoint, org_id, 'default', auth: auth, http_client: http_client)
+      def fetch_default_workspace(rbac_base_endpoint, org_id, auth: nil, http_client: nil, with_ancestry: true)
+        fetch_workspace(rbac_base_endpoint, org_id, 'default', auth: auth, http_client: http_client,
+                                                               with_ancestry: with_ancestry)
       end
 
-      def fetch_root_workspace(rbac_base_endpoint, org_id, auth: nil, http_client: nil)
-        fetch_workspace(rbac_base_endpoint, org_id, 'root', auth: auth, http_client: http_client)
+      def fetch_root_workspace(rbac_base_endpoint, org_id, auth: nil, http_client: nil, with_ancestry: true)
+        fetch_workspace(rbac_base_endpoint, org_id, 'root', auth: auth, http_client: http_client,
+                                                            with_ancestry: with_ancestry)
       end
 
       # Lists all workspaces that a subject has a specific relation to.
@@ -100,12 +102,12 @@ module Kessel
         )
       end
 
-      def fetch_workspace(rbac_base_endpoint, org_id, workspace_type, auth: nil, http_client: nil)
+      def fetch_workspace(rbac_base_endpoint, org_id, workspace_type, auth: nil, http_client: nil,
+                          with_ancestry: true)
         rbac_base_endpoint = rbac_base_endpoint.delete_suffix('/')
         uri = URI(rbac_base_endpoint + WORKSPACE_ENDPOINT)
-        query = {
-          type: workspace_type
-        }
+        query = { type: workspace_type }
+        query[:with_ancestry] = 'true' if with_ancestry
         uri.query = URI.encode_www_form(query)
         if http_client.nil?
           http_client = Net::HTTP.new(uri.host, uri.port)

data/lib/kessel/version.rb

@@ -2,6 +2,6 @@
 
 module Kessel
   module Inventory
-    VERSION = '1.10.0'
+    VERSION = '1.11.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kessel-sdk
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Project Kessel
@@ -210,6 +210,7 @@ files:
 - lib/kessel/console.rb
 - lib/kessel/grpc.rb
 - lib/kessel/inventory.rb
+- lib/kessel/inventory/GUIDELINES.md
 - lib/kessel/inventory/v1.rb
 - lib/kessel/inventory/v1/health_pb.rb
 - lib/kessel/inventory/v1/health_services_pb.rb
@@ -236,6 +237,8 @@ files:
 - lib/kessel/inventory/v1beta1/resources/reporter_data_pb.rb
 - lib/kessel/inventory/v1beta1/resources/resource_label_pb.rb
 - lib/kessel/inventory/v1beta2.rb
+- lib/kessel/inventory/v1beta2/acquire_lock_request_pb.rb
+- lib/kessel/inventory/v1beta2/acquire_lock_response_pb.rb
 - lib/kessel/inventory/v1beta2/allowed_pb.rb
 - lib/kessel/inventory/v1beta2/check_bulk_request_pb.rb
 - lib/kessel/inventory/v1beta2/check_bulk_response_pb.rb
@@ -251,10 +254,23 @@ files:
 - lib/kessel/inventory/v1beta2/check_self_response_pb.rb
 - lib/kessel/inventory/v1beta2/consistency_pb.rb
 - lib/kessel/inventory/v1beta2/consistency_token_pb.rb
+- lib/kessel/inventory/v1beta2/create_tuples_request_pb.rb
+- lib/kessel/inventory/v1beta2/create_tuples_response_pb.rb
 - lib/kessel/inventory/v1beta2/delete_resource_request_pb.rb
 - lib/kessel/inventory/v1beta2/delete_resource_response_pb.rb
+- lib/kessel/inventory/v1beta2/delete_tuples_request_pb.rb
+- lib/kessel/inventory/v1beta2/delete_tuples_response_pb.rb
 - lib/kessel/inventory/v1beta2/inventory_service_pb.rb
 - lib/kessel/inventory/v1beta2/inventory_service_services_pb.rb
+- lib/kessel/inventory/v1beta2/read_tuples_request_pb.rb
+- lib/kessel/inventory/v1beta2/read_tuples_response_pb.rb
+- lib/kessel/inventory/v1beta2/relation_fencing_check_pb.rb
+- lib/kessel/inventory/v1beta2/relation_object_reference_pb.rb
+- lib/kessel/inventory/v1beta2/relation_object_type_pb.rb
+- lib/kessel/inventory/v1beta2/relation_subject_filter_pb.rb
+- lib/kessel/inventory/v1beta2/relation_subject_reference_pb.rb
+- lib/kessel/inventory/v1beta2/relation_tuple_filter_pb.rb
+- lib/kessel/inventory/v1beta2/relationship_pb.rb
 - lib/kessel/inventory/v1beta2/report_resource_request_pb.rb
 - lib/kessel/inventory/v1beta2/report_resource_response_pb.rb
 - lib/kessel/inventory/v1beta2/reporter_reference_pb.rb
@@ -269,7 +285,10 @@ files:
 - lib/kessel/inventory/v1beta2/streamed_list_subjects_request_pb.rb
 - lib/kessel/inventory/v1beta2/streamed_list_subjects_response_pb.rb
 - lib/kessel/inventory/v1beta2/subject_reference_pb.rb
+- lib/kessel/inventory/v1beta2/tuple_service_pb.rb
+- lib/kessel/inventory/v1beta2/tuple_service_services_pb.rb
 - lib/kessel/inventory/v1beta2/write_visibility_pb.rb
+- lib/kessel/rbac/GUIDELINES.md
 - lib/kessel/rbac/v2.rb
 - lib/kessel/rbac/v2_helpers.rb
 - lib/kessel/rbac/v2_http.rb