[StorageCache] Add RebalanceJob sub-resource for API version 2026-08-01

[brpanask]

Reviewer Guidance (please read first)

Status: 32/33 required checks green. This PR is ready for ARM review. Three items need a reviewer/maintainer with write access:

1. Approved-LintDiff — Swagger LintDiff is the only red check. The 2 "new" errors are ProvisioningStateMustBeReadOnly false positives from Spectral $ref sibling resolution (OpenAPI 2.0 drops the sibling readOnly: true when inlining the $ref). provisioningState is correctly readOnly: true; the same rule fires on every existing resource (AmlFilesystem, ExpansionJob, ImportJob, Cache, StorageTarget, …) and across other TypeSpec services (apicenter, advisor, standbypool). Only the 2 RebalanceJob entries are classified "new" because the resource path is new. Full before/after breakdown in the comment dated 2026-07-01. Requesting Approved-LintDiff.
2. Remove stale labels BreakingChange-JavaScript-Sdk and BreakingChange-Python-Sdk — left over from an earlier common-types-v6 iteration. The erroneous x-ms-mutability on location was removed and BreakingChange now passes; these labels no longer apply.
3. ARMSignedOff — PR is in WaitForARMFeedback; needs an ARM reviewer sign-off.

PublishToCustomers will be added by us only when we're ready to release to customers (per the Next-Steps-to-Merge bot comment).

---

API Info

Service: StorageCache (Microsoft.StorageCache)
API Version: 2026-08-01
Type: Stable

Changes

Adds the RebalanceJob sub-resource to AMLFS and new expansion-triggered rebalance fields. New API version building on 2026-01-01.

New Resource: RebalanceJob

• GET, PATCH, DELETE, LIST operations for /amlFilesystems/{name}/rebalanceJobs/{jobName}
• States: InProgress, Cancelling, Canceled, Completed, Failed, Deleting, RollingBack

New Fields

• runRebalanceJob opt-in property on the expansion (when set, the expansion creates a RebalanceJob after completing); rebalanceJobName read-only back-reference
• Status fields: balancePercent, filesMigrated, dirsMigrated, bytesMoved, throughputMbps, filesMovedPerSecond, totalErrors, totalSkipped, estimatedRemainingSeconds, statusCode, statusMessage, startTimeUTC, completionTimeUTC

SDK Compatibility

• back-compatible.tsp: clientName/clientLocation decorators for RebalanceJobs
• flattenProperty for RebalanceJob.properties, RebalanceJobProperties.status, RebalanceJobUpdate.properties

Design Notes

RebalanceJob has no PUT/create operation (intentional)

A RebalanceJob is created as a side-effect of an ExpansionJob (when the rebalance opt-in on the expansion is set), not by a customer-initiated PUT. It therefore exposes GET, LIST, PATCH, and DELETE only:

• PATCH is used to request cancellation of an active job via adminStatus (Active -> Cancel).
• DELETE schedules the job for cleanup (cancelling an active job first).
• Customer-initiated create (PUT) is intentionally deferred to a later API version; in this release rebalance jobs originate only from expansion.

provisioningState (read-only) is present because the resource supports asynchronous PATCH/DELETE per RPC-Async-V1-02. This is a read-and-manage resource rather than a create-via-PUT resource, so the absence of a PUT is by design, not an asymmetric-CRUD omission.

RebalanceJob is a ProxyResource (no tags/location)

RebalanceJob is modeled as a ProxyResource (proxy in the ARM manifest), so it has no tags/location envelope.

Checklist

• TypeSpec compiles
• OAV validate-spec passes
• OAV validate-example passes
• Prettier passes
• SpellCheck passes
• BreakingChange passes
• Examples provided for all operations
• SDK compatibility decorators added

Breaking Changes

None - all additive.

[github-actions]

Next Steps to Merge

Next steps that must be taken to merge this PR:

• ❌ This PR targets either the main branch of the public specs repo or the RPSaaSMaster branch of the private specs repo. These branches are not intended for iterative development. Therefore, you must acknowledge you understand that after this PR is merged, the APIs are considered shipped to Azure customers. Any further attempts at in-place modifications to the APIs will be subject to Azure's versioning and breaking change policies. Additionally, for control plane APIs, you must acknowledge that you are following all the best practices documented by ARM at aka.ms/armapibestpractices. If you do intend to release the APIs to your customers by merging this PR, add the PublishToCustomers label to your PR in acknowledgement of the above. Otherwise, retarget this PR onto a feature branch, i.e. with prefix release- (see aka.ms/azsdk/api-versions#release--branches).
• ❌ This PR is in purview of the ARM review (label: ARMReview). This PR must get ARMSignedOff label from an ARM reviewer.
  This PR has ARMChangesRequested label. Please address or respond to feedback from the ARM API reviewer.
  When you are ready to continue the ARM API review, please remove the ARMChangesRequested label.
  Automation should then add WaitForARMFeedback label.
  ❗If you don't have permissions to remove the label, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories.
  For details of the ARM review, see aka.ms/azsdk/pr-arm-review
  
• ❌ The required check named Swagger LintDiff has failed. Refer to the check in the PR's 'Checks' tab for details on how to fix it and consult the aka.ms/ci-fix guide

Comment generated by summarize-checks workflow run.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.StorageCache-StorageCache
TypeSpec	Microsoft.StorageCache
JavaScript	@azure/arm-storagecache
Python	azure-mgmt-storagecache
C#	Azure.ResourceManager.StorageCache
Go	sdk/resourcemanager/storagecache/armstoragecache
Java	com.azure.resourcemanager:azure-resourcemanager-storagecache

---

Comment generated by After APIView workflow run.

[brpanask]

LintDiff Failures - All Inherited, Not From RebalanceJob

The Swagger LintDiff check shows ~1000 violations, but none are from the new RebalanceJob resource. All violations are pre-existing patterns from existing resources (AmlFilesystem, ImportJob, ExportJob, Cache, StorageTarget, etc.) that appear as "new" because the \stable/2026-08-01/openapi.json\ file is entirely new to this repo.

Violation breakdown (all from existing resources):

• DescriptionMustNotBeNodeName (318) — Existing enum values with matching descriptions (e.g., \"Active": "Active")
• LatestVersionOfCommonTypesMustBeUsed (409) — Using common-types v3 (upgrading to v6 causes cascading breaking changes on the existing 2026-01-01 API version)
• ProvisioningStateMustBeReadOnly (56) — Existing provisioning state patterns
• PostResponseCodes / LroErrorContent / PatchBodyParametersSchema — Existing operation patterns from ARM conversion
• EnumInsteadOfBoolean (25) — Existing boolean properties that cannot be converted without breaking changes

What this PR actually adds:

• New \RebalanceJob\ ProxyResource with GET, PATCH, DELETE, LIST operations
• New \Rebalance\ property on \AmlFilesystemExpansion\
• Proper descriptions, x-ms-identifiers, and x-ms-mutability annotations

Request:

Requesting \Approved-LintDiff\ label since all violations are inherited from the existing TypeSpec conversion (same patterns exist in \stable/2026-01-01/openapi.json\ on main).

Stale labels:

The \BreakingChange-JavaScript-Sdk\ and \BreakingChange-Python-Sdk\ labels are stale (from a previous iteration that used common-types v6). Breaking change checks now pass — please remove these labels.

[brpanask]

LintDiff "New Violations" — False Positive from $ref Sibling Resolution

The 2 remaining "new" ProvisioningStateMustBeReadOnly errors (lines 2443, 2509 in stable/2026-08-01/openapi.json) are false positives caused by a known Spectral resolution behavior.

Root Cause

Our provisioningState property IS correctly marked readOnly: true:

"provisioningState": {
  "$ref": "#/definitions/RebalanceJobPropertiesProvisioningState",
  "description": "ARM provisioning state...",
  "readOnly": true
}

The lint rule ProvisioningStateMustBeReadOnly runs with resolved: true in Spectral. Per OpenAPI 2.0 spec, sibling properties alongside $ref are invalid and get dropped during resolution. So when Spectral inlines the $ref, it loses the sibling readOnly: true — causing the false positive.

This fires on ALL resources in our spec

The same violation fires on every resource (AmlFilesystem, ExpansionJob, ImportJob, AutoExportJob, AutoImportJob, Cache, StorageTarget) — 29 violations total in 2026-08-01. The lint-diff tool classifies them as "existing" because those paths also exist in 2026-01-01. Only the 2 RebalanceJob violations are "new" because it's a brand new resource path.

This is the standard TypeSpec pattern

All TypeSpec-generated ARM resources use $ref + readOnly: true for provisioningState (verified in apicenter, advisor, standbypool). This is how the @visibility(Lifecycle.Read) decorator generates swagger output.

Request

Requesting Approved-LintDiff label — the 2 "new" violations are false positives from the same pattern used by all existing resources in this spec and across other TypeSpec services.

[psah434]

if the lintdiff checks are failing for existing operations/RT's then they must have been failing for previous versions. Can you provide the pr and the exception that would have been provided before?

[psah434]

also if there are violations this is a good opportunity to fix them.

[brpanask]

Thanks @psah434. Before the specifics, some context: StorageCache was migrated to TypeSpec by the ARM TypeSpec conversion team — that team authored the 2026-01-01 base content (#38978, by @Aman-Jain-14), and this same review group (yourself included) was involved in reviewing and approving it. This PR simply adds a new RebalanceJob sub-resource on top of that generated foundation, so the patterns in question aren't new to StorageCache.

On your two points:

Prior PR + exception: This is the same pattern approved in #38978 ("StorageCache base commit for API version 2026-01-01"), which received Approved-LintDiff on 2025-12-10. That PR introduced the provisioningState $ref + readOnly: true shape for every StorageCache resource; the identical shape is in shipped stable/2026-01-01/openapi.json today. The only "new" ProvisioningStateMustBeReadOnly hits on this PR (2) are on the new RebalanceJob resource, using that exact same generated shape.

On fixing: provisioningState is marked readOnly: true. The rule fires because it runs resolved and OpenAPI 2.0 drops properties that sit as siblings of a $ref, so the readOnly is lost during resolution. The shape is emitted by @azure-tools/typespec-azure-resource-manager (@visibility(Lifecycle.Read)); changing it for RebalanceJob alone would make it inconsistent with every other resource in this spec and with the shipped GA version. We'd therefore request the same Approved-LintDiff exception granted on #38978 rather than hand-editing generated output. Happy to add a suppression to suppressions.yaml instead if you prefer that mechanism.

Separately, could the stale BreakingChange-JavaScript-Sdk / BreakingChange-Python-Sdk labels be removed? Those were from an earlier iteration; the BreakingChange checks now pass.

[brpanask]

Context on the outstanding LintDiff findings

These LintDiff results are inherited from the ARM/TypeSpec team's own brownfield conversion of StorageCache, not introduced by this feature change.

TypeSpec conversion PR: #42197 — "[TSP Migration] storagcache TypeSpec migrated from swagger" (conversion wave typespec-conversion-w6), authored by the ARM/TypeSpec migration team and merged 2026-04-10. On that PR the Swagger LintDiff – Analyze Code job also failed, and it was cleared via the Approved-LintDiff label + ARMSignedOff rather than by modifying the emitted spec. The LintDiff run on this PR is here: https://github.com/Azure/azure-rest-api-specs/actions/runs/28615303410

On LatestVersionOfCommonTypesMustBeUsed (common-types v6): This spec declares @armCommonTypesVersion(v3) once at the project level in main.tsp, so it applies to every API version the TypeSpec emits — including the already-shipped stable/2026-01-01 GA version, not just the new 2026-08-01. When we bumped v3→v6 to clear this warning, the emitter regenerated the common-type $refs (ErrorResponse/ErrorDetail, systemData, Operation/OperationListResult, the resource envelope) across the whole spec, which changed the shape of the shipped 2026-01-01 swagger. That tripped the cross-version breaking-change checks and caused the BreakingChange-JavaScript-Sdk / BreakingChange-Python-Sdk labels to be applied — i.e., "fixing" one advisory warning on the new version manufactured breaking changes on a GA API. We reverted to v3 to avoid breaking the shipped contract; the SDK breaking-change labels currently on this PR are stale leftovers from that iteration and can be removed. Upgrading common-types is a spec-wide migration that should be done as its own change (regenerating and re-approving all versions together), not as a side effect of this feature PR.

On ProvisioningStateMustBeReadOnly (2 "new" hits on RebalanceJob): These are false positives from Spectral's $ref-sibling resolution. provisioningState is emitted with readOnly: true, but because it's a named-union type, typespec-autorest emits a bare $ref with sibling readOnly/description; under OpenAPI 2.0 resolution Spectral drops the $ref siblings and loses the readOnly. This is the exact shape the conversion (#42197) produced for all StorageCache resources and that shipped in 2026-01-01; the only "new" hits are on the new RebalanceJob resource using that identical generated shape. We'd request the same Approved-LintDiff exception granted on the conversion rather than hand-editing generated output (happy to add a suppressions.yaml entry instead if you prefer that mechanism).

[psah434]

ARM API Review

Posting findings from the ARM API Reviewer agent (critic-verified, 2 iterations, converged) against commit bb6da1a. See inline comments for findings 1-7. No blocking issues were found; the change is additive and non-breaking against 2026-01-01.

[psah434]

[NEW] 🟠 Warning [TSP @added misalignment] / uniform-versioning — un-gated models.tsp edits regenerate the already-released stable/2026-01-01 spec.

Classification reasoning: Introduced in this PR. This @identifiers(#["name"]) addition and the doc-comment additions (replacing removed documentation-required FIXME suppressions) are not gated by @added(Versions.v2026_08_01), so they flow into the previously-released 2026-01-01 generated spec — adding descriptions to 5 definitions (AutoExportJobUpdateProperties, AutoImportJobUpdateProperties, ImportJobUpdateProperties, MetricAggregationType, userAssignedIdentitiesValue) and x-ms-identifiers: ["name"] to ResourceSkusResult.value (stable/2026-01-01/openapi.json line 7982).

Issue: Descriptions are non-breaking, but modifying a GA version's contract should be intentional, and the x-ms-identifiers addition changes SDK array handling for that GA version.

Suggested fix: Confirm the 2026-01-01 changes are intended. If not, gate these additions to 2026-08-01; otherwise accept them as documented non-breaking improvements. Ensure the oad breaking-change CI passes on the modified 2026-01-01 spec.

[psah434]

[NEW] 🔵 Suggestion [TSP-NUMERIC-TYPE / units clarity] — throughputMbps?: float64.

Classification reasoning: New property added in this PR.

Issue: The name throughputMbps conventionally implies megabits per second, but the doc comment says mebibytes per second (1024×1024 bytes/sec). This is ambiguous for SDK consumers.

Suggested fix: Consider throughputMiBps (or a clearer name). It is a new read-only property, so renaming now is cheap. Low severity since the units are documented.

[psah434]

[NEW] 🔵 Suggestion [Suppression justification §4.1] — casing-style suppressions on startTimeUTC / completionTimeUTC (this line and line 2578).

Classification reasoning: New suppressions added in this PR.

Issue: The reason "Non-standard casing matches existing convention in this project" is a consistency-based justification, which Section 4.1 discourages. The casing itself is defensible given the established project-wide *TimeUTC convention.

Suggested fix: Reword the reason to state the concrete technical rationale (SDK property-name consistency with the sibling *TimeUTC properties across the StorageCache job-resource family).

[psah434]

[NEW] 🔵 Suggestion [@flattenProperty on new APIs §5] — @@Legacy.flattenProperty(RebalanceJob.properties) with a no-legacy-usage suppression.

Classification reasoning: New resource (RebalanceJob) added in this PR; this legacy flatten + suppression are new.

Issue: New resource types should avoid legacy property flattening (SDK-breaking risk). The suppression reason ("Required for ProvisioningStateMustBeReadOnly lint rule to traverse properties") is technically questionable — flattening is not generally required for that rule.

Suggested fix: Verify whether flattening is truly required. If kept for consistency with the sibling job resources, document that concrete rationale in the suppression reason. Low severity given family consistency.

[psah434]

[NEW] 🔵 Suggestion [ARM job-cancellation pattern] — RebalanceJobs exposes GET/LIST/PATCH/DELETE, no PUT; cancellation is via PATCH adminStatus: Cancel.

Classification reasoning: New resource interface added in this PR.

Issue: A dedicated POST cancel action is the more idiomatic ARM pattern for cancelling a job, versus overloading PATCH with an adminStatus field.

Suggested fix: Optional / design observation only — PATCH-adminStatus matches this project's existing job-resource family (ImportJob, AutoExportJob, etc.), so keeping it for consistency is reasonable. No PUT is correct here since RebalanceJob is system-created via the expansion runRebalanceJob flag.

[psah434]

[NEW] 🔵 Suggestion [Consistent error responses §2.7] — mixed error models within the same interface.

Classification reasoning: New resource interface added in this PR.

Issue: get (this line) and listByAmlFilesystem (line 74) use Error = CloudError, while update (line 51) and delete (line 64) use Error = ErrorResponse. Mixed error models across operations of the same resource produce inconsistent error schemas in the generated spec and SDKs.

Suggested fix: Use a single consistent error model across all operations of the RebalanceJobs interface.

[psah434]

[NEW] 🔵 Suggestion [Visibility / mutability §2.3] — adminStatus?: RebalanceJobAdminStatus = RebalanceJobAdminStatus.Active with @visibility(Lifecycle.Read, Lifecycle.Create).

Classification reasoning: New property added in this PR.

Issue: RebalanceJob has no PUT/create operation, so the Lifecycle.Create visibility and the default value are unused in request contexts — the only writable path is PATCH via RebalanceJobUpdateProperties.adminStatus.

Suggested fix: Consider dropping the Lifecycle.Create visibility and the default for clarity. Low severity.