Multi-Tenant Same-Key Rollout and Compatibility Policy

Date: 2026-02-22 Source sprint: SPRINT_20260222_053_DOCS_multi_tenant_same_api_key_contract_baseline.md Related ADR: ADR-002 — Multi-tenant same-API-key selection

Purpose

This document is the phased deployment plan and compatibility policy for moving Stella Ops to the one-selected-tenant-per-token model defined in ADR-002. It coordinates the rollout across Authority, Router/Gateway, Platform, Scanner, Graph, and Web, and defines the bounded backward-compatibility window for legacy tenant headers.

Audience: release managers and module owners coordinating the multi-tenant cutover, plus operators who need to understand the legacy-header compatibility window and the strict-mode timeline.

Rollout Goals

• Deploy one-selected-tenant-per-token behavior with no cross-tenant leakage.
• Preserve bounded backward compatibility for legacy tenant headers during migration.
• Enforce strict mode only after module-level validation is complete.

Phase Plan

Phase 0 - Contract and Feature Flags (2026-02-22 to 2026-02-28)

• Deploy order:
  • Publish ADR + service impact ledger + flow sequences + acceptance matrix.
  • Introduce feature flags required for bounded compatibility paths.
• Exit criteria:
  • Contract docs accepted by Authority, Router, Platform, Scanner, Graph, and Web owners.
  • Sprint trackers for 053-060 are ready with test evidence plans.
• Rollback criteria:
  • Contract ambiguity or unresolved cross-module naming conflicts.

Phase 1 - Authority + Router/Gateway Compatibility Mode (2026-03-01 to 2026-03-07)

• Deploy order:
  • Authority (20260222.054) before Router/Gateway (20260222.055).
  • Enable compatibility aliases while keeping canonical header/claim behavior authoritative.
• Exit criteria:
  • Token issuance resolves selected tenant deterministically.
  • Router strips spoofed inbound headers and rewrites canonical tenant headers.
  • Targeted Authority/Router tests pass in CI.
• Rollback criteria:
  • Token issuance regression or tenant mismatch false positives on production traffic.

Phase 2 - Service Migration: Platform, Scanner, Graph (2026-03-08 to 2026-03-17)

• Deploy order:
  • Platform (20260222.056)
  • Scanner (20260222.057)
  • Graph (20260222.058)
• Exit criteria:
  • Tenant resolver paths and endpoint policies are consistent.
  • Cross-tenant access attempts are rejected deterministically.
  • Module integration tests for tenant isolation pass.
• Rollback criteria:
  • Data partition mismatch, endpoint policy regression, or unresolved tenant conflict errors.

Phase 3 - Web Global Selector + Client Unification (2026-03-18 to 2026-03-24)

• Deploy order:
  • Web selector and runtime state unification (20260222.059).
  • Playwright tenant matrix and QA evidence (20260222.060).
• Exit criteria:
  • Global tenant selector switches tenant context across primary pages.
  • Canonical tenant injection path is active with legacy usage telemetry.
  • Tier 2c UI evidence is complete.
• Rollback criteria:
  • Tenant switch causes stale data bleed, broken navigation, or unrecoverable error states.

Phase 4 - Strict Mode + Legacy Removal (earliest start 2026-04-01)

• Deploy order:
  • Disable legacy tenant header acceptance for new clients first.
  • Remove compatibility aliases from runtime clients and gateway compatibility branches.
• Exit criteria:
  • Legacy header usage telemetry remains at zero for 14 consecutive days.
  • No dependency remains on scalar-only or header-only tenant override paths.
• Rollback criteria:
  • Any tenant selection outage or blocked tenant-scoped production path.

Compatibility Window

• Legacy header aliases (X-StellaOps-Tenant, X-Stella-Tenant, X-Tenant-Id) are supported in compatibility mode through 2026-03-31.
• Starting 2026-04-01, strict mode can be enabled once zero legacy usage is confirmed for 14 days.
• Canonical header is X-StellaOps-TenantId during and after migration.

Observability Checkpoints

• Gateway telemetry for stripped/spoofed tenant headers.
• Legacy header usage counters from Web tenant interceptor telemetry.
• Authority token issuance/validation audit events for tenant mismatch/ambiguity.
• Platform/Scanner/Graph tenant conflict and forbidden response rates.

Rollback Playbook

• If regressions appear:
  • Re-enable compatibility feature flags.
  • Freeze strict-mode rollout.
  • Revert last deployment batch for the affected module only.
  • Re-run tenant isolation acceptance matrix against last-known-good build.
• Rollback does not change ADR model (one selected tenant per token); it only restores bounded compatibility behavior.

Production Readiness Checklist

• [ ] Authority token issuance + validation tests green with selected tenant model.
• [ ] Router/Gateway spoof/mismatch protections verified in staging.
• [ ] Platform, Scanner, Graph tenant isolation tests green.
• [ ] Web selector tests and Playwright tenant matrix green (desktop + mobile).
• [ ] Legacy header telemetry reviewed with dated cutoff evidence.
• [ ] Go/no-go decision documented by QA and Project Manager.