Retained tenant inventory reads
Source verification: de7b64acb36b0a2b5f1bfcdc1bc8a4270d248396 (2026-10-21). This is an owner API source contract with component HTTP and Router-frame tests. Deployment and a complete estate census require separate evidence.
Request
An authenticated global administrator may explicitly inspect retained environment and target records for a known registered tenant. Send exactly one mode value:
GET /api/v1/release-orchestrator/environments?lifecycle=all
X-StellaOps-TenantId: <registered-tenant-slug-or-uuid>
X-StellaOps-Retained-Tenant-Read: true
Only these existing GET operations opt in:
| Operation | Existing route policy |
|---|---|
/api/v1/release-orchestrator/environments | EnvironmentEstateRead: orch:read or release:read |
/api/v1/release-orchestrator/environments/{id}/targets | EnvironmentEstateRead: orch:read or release:read |
The owner verifies the canonical validated stellaops:admin=true claim and the actual endpoint authorization policy before binding owner services. Admin roles or raw admin headers do not establish this identity. A global-admin claim does not bypass read scopes or additional endpoint policy metadata. The same checks execute when the Router invokes the mapped request delegate directly.
The header is a request mode, not identity evidence. Its value must be exactly true, including case, with one value. Empty values, false, and repeated or comma-joined values are invalid. Existing authentication and resource-server requirements still apply.
Registration and retained data
The separate registered-tenant reader queries the host’s existing local tenants replica on every retained selection, including UUIDs. It validates a matching registered, non-tombstoned catalog row before returning its UUID. The supported producer statuses are active and suspended; a Console display label such as disabled is not a catalog status accepted by this reader.
Environment and target services then read their own tenant-scoped stores. Their URLs, DTOs, ordering and lifecycle filters are unchanged. Use lifecycle=all when the census needs all environment or target lifecycle states. Existing deployment list/detail reads already use their selected tenant string; they are preserved without a new retained mode.
| Result | Meaning |
|---|---|
400 retained_read_mode_invalid | The supplied mode is empty, unsupported or repeated. |
403 retained_read_not_supported | The mapped environment/target-family endpoint or HTTP method does not opt in. |
403 retained_read_forbidden | The validated global-admin identity or actual route policy is missing. |
400 retained_read_tenant_required | The request has no resolvable selected tenant. |
403 retained_read_tenant_refused | The answered directory has no accepted registered tenant for that selection. |
| Fault response | The directory is unavailable, inconsistent, malformed or timed out; this is not an empty inventory. |
The retained refusal body has a fixed message and does not disclose the selected tenant or private directory exception. Request cancellation remains cancellation. The configured tenant-directory timeout bounds the request’s wait even when a lookup ignores its cancellation token; it does not prove that such a lookup has stopped executing.
Other owner route groups, including deployment reads, retain their existing handling; this mode is not applied globally to every owner endpoint.
Identity boundary
The accepted UUID exists only in a scoped HTTP request item for these two GETs. It does not call BeginOverride or populate the ordinary tenant caches. Explicit execution overrides retain precedence. Agent and background delegates retain ordinary execution identity. The mode cannot grant a mutation scope or opt a mutation/operational endpoint into retained reads.
With the header absent, ordinary resolution remains unchanged, including its existing canonical-UUID shortcut and active-slug cache behavior. This feature does not impose a new universal inactive-UUID write prohibition or invalidate previously memoized ordinary identities.
Dated live evidence
RRO-1 (2026-10-21) adopts the reviewed source in the shared owner image built from clean 9a135ccc084f7c0e40671e270b309b8d70a1a2c4. The same issued administrator session observes 403 without the mode, 200 with exact true, and 400 for false and comma-joined true,true on a known inactive catalog tenant. Its complete seven-tenant census uses the mode only on the two opt-ins; deployments retain ordinary reads. These four live controls do not replace the source tests for other authorization/fault cases. See the rollout/census receipt.
Verification and operation limits
Re-verify the owner contract with:
pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Integration.Tests/StellaOps.ReleaseOrchestrator.Integration.Tests.csproj -Class '*RetainedTenantReadEndpointTests' -BuildProjectReferences
The neutral contract is covered separately by RetainedTenantResolverTests in StellaOps.Auth.ServerIntegration.Tests. These tests use in-memory stores, producer-shaped local-replica outcomes, fixture authentication and the real scope-policy handler. They do not exercise a deployed JWT authority, catalog feed/database, Gateway hop or a complete multi-tenant estate census.
Source completion alone does not update the served owner or alter a frozen operator packet. The separate dated RRO-1 evidence above records actual adoption. The future CA-14 operation still requires a supported complete owner census, fresh resource admission and its exact execution grant. See the operator procedure.