CEXT-6527: add upgrade type surface and optional leaf-step upgrade capability

[iivvaannxx]

Description

Adds the upgrade orchestration type surface and folds an optional upgrade capability onto leaf steps:

• Step-capability types in management/common/workflow/upgrade.ts (UpgradeCapability, UpgradeDomainPlan, UpgradeOperation, UpgradePlanningInput/UpgradePlanningResult, UpgradeExecutionContext/UpgradeExecutionResult, CleanupResource, CleanupIdentityOf, UpgradeIssue).
• Orchestration models in management/upgrade/ (UpgradePlan, StoredUpgradeAttempt, StateSnapshot, UpgradeOrchestrationState, SuccessfulUpgradeResult, UpgradeRequestContext).
• LeafStep gains optional planUpgrade/upgrade handlers, authored via the single defineLeafStep helper (no separate step type).
• Placeholder (TODO) adoption in the webhooks subscriptionsStep, specialized to the webhook domain types.
• Extracts a shared LifecycleRequestContext (in common/schema.ts) reused by the installation action and UpgradeRequestContext.

Reuses installation's engine 1:1 — UpgradeIssue mirrors ValidationIssue for the planning channel, and a failed attempt's failure reuses WorkflowError. There is no upgrade runtime yet; these are coordination contracts for parallel workstreams.

Related Issue

CEXT-6527

Motivation and Context

Multiple workstreams (domain handlers, the orchestrator, the management UI) need to build against the upgrade lifecycle in parallel. This delivers the type surface plus a first placeholder domain adoption so they can start against a stable, reviewed contract.

Notes for reviewers:

• The planUpgrade result shape (UpgradePlanningResult) is reconstructed from the HLD and should be confirmed with the orchestrator workstream.
• The planUpgrade/upgrade pairing is a documented convention (both are optional on LeafStep), not type-enforced.

How Has This Been Tested?

• pnpm --filter @adobe/aio-commerce-lib-app typecheck — clean.
• pnpm --filter @adobe/aio-commerce-lib-app test — all pass, including expectTypeOf coordination-contract tests for the upgrade generics.
• pnpm --filter @adobe/aio-commerce-lib-app build — emits .d.ts for the new public exports.
• pnpm --filter @adobe/aio-commerce-lib-app lint / lint:openapi — clean.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have read the DEVELOPMENT document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7160797

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@adobe/aio-commerce-lib-app	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[obarcelonap]

LGTM but I added many comments on try to do not prefix much with upgrade since at the end at some point we may want to use this interfaces for installation too

[iivvaannxx]

@obarcelonap You're right, forgot that we intended to reuse the machinery for installation and uninstallation. I generalized things, please see commit dfa0ed25 (and resolve your comments as you see fit).