Add phase 15 API lifecycle readiness

Author: ammarheidari

README.md

@@ -44,6 +44,7 @@ The first production milestone is M3UA over a transport abstraction. SCCP, TCAP,
 | Operations | Phase 12 foundation-ready: production operations capability catalog, runbook catalog, incident response targets, health check matrix, rollback plan, maintenance policy, support handbook, readiness report, operations CI profile, and status report added; production operations still require commercial readiness |
 | Compliance and audit | Phase 13 foundation-ready: compliance capability catalog, audit event catalog, evidence retention policy, license compliance policy, data handling classification, export-control policy, readiness report, compliance CI profile, commercial compliance gate, and status report added; enterprise compliance claims still require commercial readiness and adopter-specific legal/regulatory review |
 | Performance and capacity | Phase 14 foundation-ready: performance capability catalog, benchmark scenario catalog, capacity profile, throughput targets, latency budgets, load-test plan, resource budget, readiness report, performance CI profile, and status report added; production performance claims still require representative benchmark evidence |
+| API lifecycle | Phase 15 foundation-ready: API surface catalog, stability contracts, version matrix, deprecation policy, migration guide catalog, breaking-change review policy, public API baseline, readiness report, API lifecycle CI profile, and status report added; stable API lifecycle claims still require commercial readiness and validation evidence |
 | Package governance | Phase 7 policy added: current package metadata is tracked; commercial target still requires package signing and SBOM automation |
 | Security governance | Phase 7 security policy added with private disclosure and severity response targets |
 | Compatibility policy | Phase 7 policy added: net10.0 target, SemVer, pre-stable breaking-change allowance, and stable major-version rule |
@@ -150,6 +151,8 @@ if (!M3uaTypedMessageParser.TryParseSignallingCongestion(
 - [Phase 13 Summary](docs/PHASE13_SUMMARY.md)
 - [Phase 14 Performance](docs/PHASE14_PERFORMANCE.md)
 - [Phase 14 Summary](docs/PHASE14_SUMMARY.md)
+- [Phase 15 API Lifecycle](docs/PHASE15_API_LIFECYCLE.md)
+- [Phase 15 Summary](docs/PHASE15_SUMMARY.md)
 - [Continuous Integration](docs/CI.md)
 - [SCTP Transport](docs/SCTP_TRANSPORT.md)
 - [Compatibility policy](docs/COMPATIBILITY.md)
@@ -177,6 +180,7 @@ The roadmap is intentionally conservative:
 12. Complete production operations and support readiness.
 13. Complete compliance and audit readiness foundations.
 14. Complete performance, capacity, and benchmark readiness foundations.
+15. Complete API stability, deprecation, and migration readiness foundations.
 
 ## License
 

docs/CI.md

@@ -55,3 +55,9 @@ The profile reuses build, test, and pack commands and requires compliance readin
 Phase 14 adds `SigtranPerformanceCi.CreateDefault()` as the metadata contract for validating performance readiness.
 
 The profile reuses build, test, and pack commands, requires performance readiness, and keeps long-running benchmarks opt-in.
+
+## API Lifecycle CI
+
+Phase 15 adds `SigtranApiLifecycleCi.CreateDefault()` as the metadata contract for validating API lifecycle readiness.
+
+The profile reuses build, test, and pack commands and requires public API diff review for API-shaping changes.

docs/PHASE15_API_LIFECYCLE.md

@@ -0,0 +1,70 @@
+# Phase 15 API Stability Deprecation And Migration Readiness
+
+Phase 15 adds API lifecycle readiness for SIGTRAN.NET.
+
+This phase makes the public SDK surface easier to consume in large projects by documenting stability levels, version-line behavior, deprecation rules, migration expectations, breaking-change review, and public API baseline governance.
+
+## API Surface Catalog
+
+`SigtranApiSurfaceCatalog.GetSurfaces()` exposes the public API surfaces that adopters should track:
+
+- M3UA
+- SCTP
+- SCCP
+- TCAP
+- MAP
+- CoreUtilities
+
+Each surface includes a category and namespace prefix.
+
+## Stability Contracts
+
+`SigtranApiStability.GetContracts()` assigns a stability level to each public surface.
+
+M3UA and SCTP are currently preview surfaces. SCCP, TCAP, and MAP remain experimental until their external interoperability evidence and profile validation are complete.
+
+## Version Matrix
+
+`SigtranApiVersionMatrix.GetEntries()` defines release-line behavior:
+
+- `0.x` is pre-stable and can accept breaking changes.
+- `1.x` is planned stable and should reject breaking changes unless a major version is used.
+
+## Deprecation Policy
+
+`SigtranDeprecationPolicies.CreateStableDefault()` defines stable API deprecation expectations:
+
+- At least 180 days of notice.
+- `ObsoleteAttribute` on deprecated APIs.
+- Migration guide coverage.
+- Release-note coverage.
+
+## Migration Guides
+
+`SigtranMigrationGuides.GetEntries()` identifies planned migration guides for the move from pre-stable APIs toward 1.0.
+
+Migration guides must include code samples so users can update applications without reverse-engineering API changes.
+
+## Breaking-Change Review
+
+`SigtranBreakingChangeReview.CreateDefault()` requires API baseline diffs, migration guides, maintainer approval, and major-version handling after stable release.
+
+## Public API Baseline
+
+`SigtranPublicApiBaseline.CreateCurrent()` defines the current pre-stable public API baseline manifest.
+
+The baseline covers known public surfaces and requires diff review before API-shaping changes are accepted.
+
+## API Lifecycle Readiness
+
+`SigtranApiLifecycleReadiness.GetReport()` separates API lifecycle foundation readiness from stable API lifecycle claims.
+
+The API lifecycle foundation is ready when surface catalog, stability contracts, version matrix, deprecation policy, migration guide catalog, breaking-change review, and public API baseline are all present. Stable lifecycle claims still require wider commercial readiness.
+
+## API Lifecycle CI
+
+`SigtranApiLifecycleCi.CreateDefault()` reuses the official build, test, and pack commands while requiring API lifecycle readiness and public API diff review.
+
+## Phase Status
+
+`SigtranPhase15Status.Describe()` summarizes the completed Phase 15 units and separates API lifecycle foundation readiness from stable API lifecycle claims.

docs/PHASE15_SUMMARY.md

@@ -0,0 +1,26 @@
+# Phase 15 Summary
+
+Phase 15 adds the API stability, deprecation, and migration-readiness foundation for SIGTRAN.NET.
+
+## Completed Units
+
+1. API surface catalog.
+2. API stability contracts.
+3. API version matrix.
+4. Deprecation policy.
+5. Migration guide catalog.
+6. Breaking-change review policy.
+7. Public API baseline manifest.
+8. API lifecycle readiness report.
+9. API lifecycle CI profile.
+10. Phase status and documentation.
+
+## Current State
+
+The Phase 15 API lifecycle foundation is complete.
+
+`SigtranPhase15Status.FoundationReady` is expected to be true. `StableApiLifecycleReady` remains false until wider commercial readiness is complete.
+
+## Production Claim Boundary
+
+Phase 15 improves public API governance, but it does not make every protocol surface stable. M3UA and SCTP remain preview. SCCP, TCAP, and MAP remain experimental until interoperability and profile validation evidence exists.

docs/SDK_ROADMAP.md

@@ -139,6 +139,14 @@ Status: Phase 13 is foundation-ready for compliance capability catalog, audit ev
 
 Status: Phase 14 is foundation-ready for performance capability catalog, benchmark scenario catalog, capacity profile, throughput targets, latency budgets, load-test plan, resource budget, performance readiness, performance CI profile, and phase documentation. Production performance claims remain blocked until representative native SCTP and external-peer benchmark evidence is captured and retained.
 
+## Phase 15 - API Stability Deprecation And Migration Readiness
+
+- Add public API surface catalog, stability contracts, version-line matrix, deprecation policy, migration guide catalog, breaking-change review, and API baseline foundations.
+- Keep API lifecycle foundation readiness separate from stable API lifecycle claims.
+- Make API-shaping changes visible and reviewable for open-source and commercial adopters.
+
+Status: Phase 15 is foundation-ready for API surface catalog, stability contracts, version matrix, deprecation policy, migration guide catalog, breaking-change review policy, public API baseline, API lifecycle readiness, API lifecycle CI profile, and phase documentation. Stable API lifecycle claims remain blocked until wider commercial readiness is complete and protocol surfaces have the required validation evidence.
+
 ## Recommended First Deliverable
 
 The first useful SDK release should be an alpha package focused on M3UA over a transport abstraction:

src/sigtran.net.Tests/Program.cs

@@ -90,6 +90,16 @@
 Run("SIGTRAN performance readiness separates foundation from benchmark evidence", SigtranPerformanceReadinessSeparatesFoundationFromBenchmarkEvidence);
 Run("SIGTRAN performance CI profile keeps benchmarks opt-in", SigtranPerformanceCiProfileKeepsBenchmarksOptIn);
 Run("SIGTRAN phase 14 status summarizes performance foundation", SigtranPhase14StatusSummarizesPerformanceFoundation);
+Run("SIGTRAN API surface catalog exposes protocol and governance surfaces", SigtranApiSurfaceCatalogExposesProtocolAndGovernanceSurfaces);
+Run("SIGTRAN API stability contracts mark pre-stable surfaces", SigtranApiStabilityContractsMarkPreStableSurfaces);
+Run("SIGTRAN API version matrix separates pre-stable and stable lines", SigtranApiVersionMatrixSeparatesPreStableAndStableLines);
+Run("SIGTRAN deprecation policy requires obsolete migration and release notes", SigtranDeprecationPolicyRequiresObsoleteMigrationAndReleaseNotes);
+Run("SIGTRAN migration guides require code samples", SigtranMigrationGuidesRequireCodeSamples);
+Run("SIGTRAN breaking change review requires baseline migration and approval", SigtranBreakingChangeReviewRequiresBaselineMigrationAndApproval);
+Run("SIGTRAN public API baseline covers known surfaces", SigtranPublicApiBaselineCoversKnownSurfaces);
+Run("SIGTRAN API lifecycle readiness separates foundation from stable claims", SigtranApiLifecycleReadinessSeparatesFoundationFromStableClaims);
+Run("SIGTRAN API lifecycle CI profile requires public API diff review", SigtranApiLifecycleCiProfileRequiresPublicApiDiffReview);
+Run("SIGTRAN phase 15 status summarizes API lifecycle foundation", SigtranPhase15StatusSummarizesApiLifecycleFoundation);
 Run("Native SCTP platform probe reports socket creation capability", NativeSctpPlatformProbeReportsSocketCreationCapability);
 Run("Native SCTP socket factory creates or reports unsupported platform", NativeSctpSocketFactoryCreatesOrReportsUnsupportedPlatform);
 Run("Native SCTP connection planner resolves endpoints", NativeSctpConnectionPlannerResolvesEndpoints);
@@ -1151,6 +1161,104 @@ static void SigtranPhase14StatusSummarizesPerformanceFoundation()
     Assert(!SigtranPhase14Status.ProductionPerformanceReady, SigtranPhase14Status.Describe());
 }
 
+static void SigtranApiSurfaceCatalogExposesProtocolAndGovernanceSurfaces()
+{
+    IReadOnlyList<SigtranApiSurface> surfaces = SigtranApiSurfaceCatalog.GetSurfaces();
+
+    AssertEqual(6, surfaces.Count, "API surface count");
+    Assert(surfaces.Any(surface => surface.Name == "M3UA" && surface.Category == SigtranApiSurfaceCategory.Codec), "M3UA codec surface should be present");
+    Assert(surfaces.Any(surface => surface.Name == "CoreUtilities" && surface.Category == SigtranApiSurfaceCategory.Governance), "governance surface should be present");
+}
+
+static void SigtranApiStabilityContractsMarkPreStableSurfaces()
+{
+    IReadOnlyList<SigtranApiStabilityContract> contracts = SigtranApiStability.GetContracts();
+
+    AssertEqual(6, contracts.Count, "API stability contract count");
+    Assert(contracts.Any(contract => contract.Surface == "M3UA" && contract.Level == SigtranApiStabilityLevel.Preview), "M3UA should be preview");
+    Assert(contracts.Any(contract => contract.Surface == "MAP" && contract.Level == SigtranApiStabilityLevel.Experimental), "MAP should be experimental");
+    Assert(contracts.All(contract => contract.AllowsBreakingChangesBeforeStable), "pre-stable contracts should allow breaking changes");
+}
+
+static void SigtranApiVersionMatrixSeparatesPreStableAndStableLines()
+{
+    IReadOnlyList<SigtranApiVersionMatrixEntry> entries = SigtranApiVersionMatrix.GetEntries();
+
+    AssertEqual(2, entries.Count, "API version matrix count");
+    Assert(entries.Any(entry => entry.ReleaseLine == "0.x" && entry.AcceptsBreakingChanges), "0.x should accept pre-stable breaking changes");
+    Assert(entries.Any(entry => entry.ReleaseLine == "1.x" && !entry.AcceptsBreakingChanges), "1.x should reject breaking changes without major version");
+}
+
+static void SigtranDeprecationPolicyRequiresObsoleteMigrationAndReleaseNotes()
+{
+    SigtranDeprecationPolicy policy = SigtranDeprecationPolicies.CreateStableDefault();
+
+    Assert(policy.MinimumNoticePeriod >= TimeSpan.FromDays(90), "deprecation notice should be at least 90 days");
+    Assert(policy.RequiresObsoleteAttribute, "deprecation should require ObsoleteAttribute");
+    Assert(policy.RequiresMigrationGuide, "deprecation should require migration guide");
+    Assert(policy.RequiresReleaseNotes, "deprecation should require release notes");
+    Assert(policy.IsStableLifecyclePolicy, "deprecation policy should satisfy stable lifecycle requirements");
+}
+
+static void SigtranMigrationGuidesRequireCodeSamples()
+{
+    IReadOnlyList<SigtranMigrationGuideEntry> entries = SigtranMigrationGuides.GetEntries();
+
+    AssertEqual(3, entries.Count, "migration guide count");
+    Assert(entries.All(entry => entry.RequiresCodeSamples), "migration guides should require code samples");
+    Assert(entries.Any(entry => entry.Id == "prestable-to-1.0"), "prestable to 1.0 migration guide should be planned");
+}
+
+static void SigtranBreakingChangeReviewRequiresBaselineMigrationAndApproval()
+{
+    SigtranBreakingChangeReviewPolicy policy = SigtranBreakingChangeReview.CreateDefault();
+
+    Assert(policy.RequiresApiBaselineDiff, "breaking-change review should require API baseline diff");
+    Assert(policy.RequiresMigrationGuide, "breaking-change review should require migration guide");
+    Assert(policy.RequiresMaintainerApproval, "breaking-change review should require maintainer approval");
+    Assert(policy.RequiresMajorVersionAfterStable, "stable breaking changes should require major version");
+    Assert(policy.IsCommercialApiGovernanceReady, "breaking-change review should be commercial governance ready");
+}
+
+static void SigtranPublicApiBaselineCoversKnownSurfaces()
+{
+    SigtranPublicApiBaselineManifest manifest = SigtranPublicApiBaseline.CreateCurrent();
+
+    AssertEqual("prestable-public-api", manifest.Name, "public API baseline name");
+    Assert(manifest.RequiresDiffReview, "public API baseline should require diff review");
+    Assert(manifest.CoversKnownSurfaces, "public API baseline should cover known surfaces");
+}
+
+static void SigtranApiLifecycleReadinessSeparatesFoundationFromStableClaims()
+{
+    SigtranApiLifecycleReadinessReport report = SigtranApiLifecycleReadiness.GetReport();
+
+    Assert(report.FoundationReady, "API lifecycle foundation should be ready");
+    Assert(!report.CommercialReady, "API lifecycle readiness should still depend on commercial gates");
+    Assert(!report.StableApiLifecycleReady, "stable API lifecycle should not be claimed before commercial readiness");
+}
+
+static void SigtranApiLifecycleCiProfileRequiresPublicApiDiffReview()
+{
+    SigtranApiLifecycleCiProfile profile = SigtranApiLifecycleCi.CreateDefault();
+
+    AssertEqual("api-lifecycle", profile.Name, "API lifecycle CI profile name");
+    Assert(profile.Commands.Count >= 3, "API lifecycle CI should reuse official verification commands");
+    Assert(profile.RequiresApiLifecycleReadiness, "API lifecycle CI should require readiness");
+    Assert(profile.RequiresPublicApiDiffReview, "API lifecycle CI should require public API diff review");
+}
+
+static void SigtranPhase15StatusSummarizesApiLifecycleFoundation()
+{
+    IReadOnlyList<string> capabilities = SigtranPhase15Status.GetCompletedCapabilities();
+
+    AssertEqual(10, SigtranPhase15Status.CompletedUnitCount, "Phase 15 completed unit count");
+    AssertEqual(10, capabilities.Count, "Phase 15 capability count");
+    Assert(capabilities.Contains("api-lifecycle-ci-profile"), "Phase 15 should include API lifecycle CI profile");
+    Assert(SigtranPhase15Status.FoundationReady, SigtranPhase15Status.Describe());
+    Assert(!SigtranPhase15Status.StableApiLifecycleReady, SigtranPhase15Status.Describe());
+}
+
 static void NativeSctpPlatformProbeReportsSocketCreationCapability()
 {
     AssertEqual(132, NativeSctpPlatform.IpProtocolSctp, "native SCTP protocol number");

src/sigtran.net/Core/Utilities/SigtranApiLifecycleCi.cs

@@ -0,0 +1,54 @@
+namespace sigtran.net.Core.Utilities;
+
+/// <summary>
+/// Describes the API lifecycle CI profile.
+/// </summary>
+public sealed class SigtranApiLifecycleCiProfile
+{
+    /// <summary>Creates an API lifecycle CI profile.</summary>
+    /// <param name="name">The profile name.</param>
+    /// <param name="commands">The verification commands.</param>
+    /// <param name="requiresApiLifecycleReadiness">Whether API lifecycle readiness is required.</param>
+    /// <param name="requiresPublicApiDiffReview">Whether public API diffs require review.</param>
+    public SigtranApiLifecycleCiProfile(
+        string name,
+        IReadOnlyList<string> commands,
+        bool requiresApiLifecycleReadiness,
+        bool requiresPublicApiDiffReview)
+    {
+        ArgumentNullException.ThrowIfNull(commands);
+        Name = string.IsNullOrWhiteSpace(name) ? throw new ArgumentException("Profile name is required.", nameof(name)) : name;
+        Commands = commands.Count == 0 ? throw new ArgumentException("At least one command is required.", nameof(commands)) : commands.ToArray();
+        RequiresApiLifecycleReadiness = requiresApiLifecycleReadiness;
+        RequiresPublicApiDiffReview = requiresPublicApiDiffReview;
+    }
+
+    /// <summary>The profile name.</summary>
+    public string Name { get; }
+
+    /// <summary>The verification commands.</summary>
+    public IReadOnlyList<string> Commands { get; }
+
+    /// <summary>Whether API lifecycle readiness is required.</summary>
+    public bool RequiresApiLifecycleReadiness { get; }
+
+    /// <summary>Whether public API diffs require review.</summary>
+    public bool RequiresPublicApiDiffReview { get; }
+}
+
+/// <summary>
+/// Provides API lifecycle CI profile helpers.
+/// </summary>
+public static class SigtranApiLifecycleCi
+{
+    /// <summary>Creates the default API lifecycle CI profile.</summary>
+    /// <returns>The default API lifecycle CI profile.</returns>
+    public static SigtranApiLifecycleCiProfile CreateDefault()
+    {
+        return new(
+            "api-lifecycle",
+            SigtranCiVerification.CreateDefaultProfile().GetCommands(),
+            requiresApiLifecycleReadiness: true,
+            requiresPublicApiDiffReview: true);
+    }
+}