feat: implement statefulset primitive

[sourcehawk]

Implements the statefulset Kubernetes resource primitive following the pattern established by the existing ConfigMap and Deployment primitives.

Summary

• Adds statefulset primitive package under pkg/primitives/statefulset/
• Implements required lifecycle interfaces
• Includes editors, mutator, flavors, and builder
• Updates shared documentation (docs/primitives.md) to list the new primitive

Checklist

• Compiles cleanly
• Tests pass
• Follows naming conventions in CONTEXT.md
• Shared file modifications are limited to documentation updates

[Copilot]

Pull request overview

Adds a new statefulset workload primitive to the operator-component-framework, matching the existing primitive patterns (builder/resource, mutation planning, flavors, and lifecycle handlers), plus accompanying editor support, docs, and an end-to-end example.

Changes:

• Introduces pkg/primitives/statefulset/ with builder/resource, mutator, handlers, and flavors (plus tests).
• Adds StatefulSetSpecEditor under pkg/mutation/editors/ (plus tests) to support typed spec mutations.
• Adds documentation and a runnable example demonstrating the new primitive.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pkg/primitives/statefulset/resource.go	Implements the StatefulSet resource wrapper and default field applicator behavior.
pkg/primitives/statefulset/mutator.go	Adds the statefulset mutator with feature-bounded planning and apply ordering (incl. VCT ops).
pkg/primitives/statefulset/handlers.go	Provides default converge/grace/suspend handlers for StatefulSets.
pkg/primitives/statefulset/flavors.go	Adds field-application flavors for preserving labels/annotations (object + pod template).
pkg/primitives/statefulset/builder.go	Provides fluent builder API wiring defaults, mutations, flavors, and handlers.
pkg/primitives/statefulset/mutator_test.go	Tests mutator semantics (ordering, snapshots, presence ops, convenience helpers).
pkg/primitives/statefulset/handlers_test.go	Tests default handler behavior for converge/grace/suspension.
pkg/primitives/statefulset/flavors_test.go	Tests flavor ordering and preservation semantics.
pkg/primitives/statefulset/builder_test.go	Tests builder validation and option wiring.
pkg/mutation/editors/statefulsetspec.go	Introduces a typed editor for appsv1.StatefulSetSpec.
pkg/mutation/editors/statefulsetspec_test.go	Verifies StatefulSetSpecEditor setters and Raw() behavior.
examples/statefulset-primitive/main.go	Runnable example using a fake client to reconcile across spec changes and suspension.
examples/statefulset-primitive/resources/statefulset.go	Builds a StatefulSet resource with mutations, flavors, custom handlers, and data extraction.
examples/statefulset-primitive/features/mutations.go	Example feature mutations demonstrating container edits/presence and metadata edits.
examples/statefulset-primitive/features/flavors.go	Example custom flavors and custom converge/grace/suspend behaviors.
examples/statefulset-primitive/app/owner.go	Re-exports shared example CRD types for the example package.
examples/statefulset-primitive/app/controller.go	Example controller wiring the component framework to the statefulset primitive.
examples/statefulset-primitive/README.md	Documentation on running and understanding the example.
docs/primitives/statefulset.md	User-facing docs for the new statefulset primitive API and behavior.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

[sourcehawk]

Claude Review Cycle 1 Complete

Addressed:

• Fixed duplicated word in Mutate comment: "custom customFieldApplicator" → "custom field applicator" (resource.go:71)
• Fixed incorrect status name in ConvergingStatus comment: "Ready" → "Healthy" to match concepts.AliveConvergingStatusHealthy (resource.go:89)

Intentionally ignored:
None

<!-- claude-review-cycle -->

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

[sourcehawk]

Claude Review Cycle 1 Complete

Addressed:

• mutator.go:452 — VolumeClaimTemplate ops now guarded by ResourceVersion == "" check so they are skipped on existing StatefulSets (immutable after creation). Added test covering the update scenario.

Intentionally ignored:
None

<!-- claude-review-cycle -->

[sourcehawk]

approve

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

[sourcehawk]

Claude Review Cycle 1 Complete

Addressed:

• Fixed range variable pointer bug in mutator_test.go:52 — findEnv now iterates by index (&env[i]) instead of taking the address of the reused range variable (&e)
• Updated capabilities table in docs/primitives/statefulset.md to align with actual implementation: removed claim of Failing status, replaced "Graceful rollouts" with "Rollout health", and clarified that grace handler returns Degraded/Down without grace-period timing logic

Intentionally ignored:
None

<!-- claude-review-cycle -->

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

[sourcehawk]

Claude Review Cycle 1 Complete

Addressed:

• Added comprehensive resource-level tests for the StatefulSet primitive (Identity, Object deep-copy, Mutate, feature ordering, ConvergingStatus, GraceStatus, DeleteOnSuspend, Suspend, SuspensionStatus, ExtractData, CustomFieldApplicator) — aligning test coverage with the Deployment primitive.

Intentionally ignored:

• PreserveStatus comment (resource.go line 28): Already addressed in a prior commit — generic.PreserveStatus(current, original) is already called on line 25, with a dedicated test (TestDefaultFieldApplicator_PreservesStatus) verifying the behavior.
• PR description checklist comment (statefulsetspec.go line 20): This is a documentation/process note about updating the PR description to clarify that pkg/mutation/editors/statefulsetspec.go is a new shared file. Not a code change — left for the PR author to update the description if desired.

<!-- claude-review-cycle -->

[sourcehawk]

Claude Review Cycle 1 - Follow-up Fix

The PreserveStatus fix in resource.go and corresponding docs update were uncommitted local changes that were not included in the previous push. This caused TestDefaultFieldApplicator_PreservesStatus to fail in CI.

Fixed in commit 75657ad — generic.PreserveStatus(current, original) is now properly committed and CI is green.

<!-- claude-review-cycle-followup -->

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

[sourcehawk]

Claude Review Cycle 3 Complete

Addressed:

• Updated PR description checklist to accurately reflect that shared files (docs/primitives.md) are modified, replacing the misleading "Does not modify shared files" item with "Shared file modifications are limited to documentation updates"
• Fixed markdown table column alignment in docs/primitives.md

Intentionally ignored:
None

<!-- claude-review-cycle -->

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

[sourcehawk]

Claude Review Cycle 4 Complete

Addressed:

• Assert Build() errors in resource_test.go: replaced all res, _ := ...Build() with res, err := ...Build() + require.NoError(t, err) so validation failures are not silently swallowed.
• Fixed WithCustomFieldApplicator docstring to accurately describe that DefaultFieldApplicator deep-copies the entire desired object (metadata and spec), then restores server-managed fields, status, and VolumeClaimTemplates from the live object.

Intentionally ignored:
None

<!-- claude-review-cycle -->

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

[sourcehawk]

Claude Review Cycle 5 Complete

Addressed:

• builder_test.go:87 — Replaced nil Mutate function with a no-op func(_ *Mutator) error { return nil } in the WithMutation test so the test data represents a valid mutation.

Intentionally ignored:
None

<!-- claude-review-cycle -->

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

[Copilot]

The EditContainers doc comment mentions selector evaluation against a snapshot, but it omits an important implication: container edits earlier in the same feature/mutation do not affect which selectors match later edits (matching is based on the snapshot, not the live-mutated container). Consider documenting this explicitly (as is done in the deployment mutator) to prevent surprising behavior for API consumers.

Suggested change

	// - Selector matching is evaluated against a snapshot taken after the current feature's container presence operations are applied.
	// - Selector matching is evaluated against a snapshot taken after the current feature's container presence operations are applied.
	// - All container selectors within the same feature are evaluated against this snapshot; they do not see edits made by earlier EditContainers calls.
	// - Earlier container edits can change the contents of selected containers but cannot change which containers are matched by later selectors in the same feature.