feat: implement pv primitive by sourcehawk · Pull Request #27 · sourcehawk/operator-component-framework

sourcehawk · 2026-03-22T03:11:24Z

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

Summary

Adds pv primitive package under pkg/primitives/pv/
Implements required lifecycle interfaces
Includes editors, mutator, flavors, and builder

Checklist

Compiles cleanly
Tests pass
Follows naming conventions in CONTEXT.md
Does not modify shared files

Copilot

Pull request overview

Adds a new pv primitive to the framework to manage Kubernetes PersistentVolume resources using the existing primitive patterns (builder/resource/mutator/flavors/status handler), plus documentation and an example.

Changes:

Introduces pkg/primitives/pv/ with builder, resource wrapper, mutator, flavors, and operational status handler (+ unit tests).
Adds a shared PVSpecEditor under pkg/mutation/editors/ to support typed PV spec mutations (+ tests).
Adds a runnable examples/pv-primitive/ example and new documentation page docs/primitives/pv.md.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/primitives/pv/resource.go	PV integration resource wrapper + default PV field applicator preserving immutable fields
pkg/primitives/pv/builder.go	Fluent builder for PV resources with mutations, flavors, operational status handler, extractors
pkg/primitives/pv/mutator.go	PV mutator implementing the “plan-and-apply” pattern with metadata/spec edit ordering
pkg/primitives/pv/handlers.go	Default operational status mapping from PV phases to framework operational statuses
pkg/primitives/pv/flavors.go	PV-specific wrappers for common field-application flavors
pkg/primitives/pv/*_test.go	Unit tests for builder, mutator ordering, flavors, and status handler
pkg/mutation/editors/pvspec.go	New shared typed editor for `PersistentVolumeSpec`
pkg/mutation/editors/pvspec_test.go	Unit tests for the new `PVSpecEditor`
examples/pv-primitive/main.go	Demonstration program showing PV mutation behavior and status handler output
examples/pv-primitive/resources/pv.go	Example factory wiring PV builder + example feature mutations + flavors
examples/pv-primitive/features/mutations.go	Example feature-gated PV mutations for the demo
examples/pv-primitive/app/controller.go	Example package-level commentary about PV ownership constraints
examples/pv-primitive/README.md	Example documentation and run instructions
docs/primitives/pv.md	New primitive documentation page describing PV builder/mutation/status/flavors

examples/pv-primitive/main.go

examples/pv-primitive/README.md

pkg/mutation/editors/pvspec.go

examples/pv-primitive/app/controller.go

Copilot

Pull request overview

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

pkg/mutation/editors/pvspec.go

pkg/primitives/pv/resource.go

sourcehawk · 2026-03-22T13:28:11Z

Claude Review Cycle 1 Complete

Addressed:

Added focused unit tests for DefaultFieldApplicator covering create-vs-update behavior, immutable field preservation (PersistentVolumeSource, VolumeMode, ClaimRef), nil immutable field handling, and verifying the desired object is not mutated (pkg/primitives/pv/resource_test.go)

Intentionally ignored:

PR description/checklist accuracy comment (pvspec.go:6): This is about PR description text, not code. The PVSpecEditor in pkg/mutation/editors is a deliberate addition following the same pattern as ObjectMetaEditor. The PR description should be updated by the author to reflect this shared package addition, but no code change is needed.

Copilot

Pull request overview

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

docs/primitives/pv.md

pkg/mutation/editors/pvspec.go

sourcehawk · 2026-03-22T21:42:53Z

Claude Review Cycle 1 Complete

Addressed:

Line 283 (pv.md): Added cluster-scoped owner constraint documentation to the Guidance section, explaining that PVs require a cluster-scoped owner for controller references and listing workarounds for namespace-scoped components.
Line 15 (pv.md) / primitives index: Added the PV primitive to the Built-in Primitives table and PVSpecEditor to the Mutation Editors table in docs/primitives.md, making the PV docs discoverable from the central index.

Intentionally ignored:

pvspec.go (PR description checklist): This is a meta-comment about the PR description text, not a code issue. The PR description can be updated separately by the author.

Copilot

Pull request overview

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

pkg/primitives/pv/builder.go

docs/primitives.md

sourcehawk · 2026-03-23T03:25:51Z

Claude Review Cycle 1 Complete

Addressed:

builder.go:140 — Refactored Builder.Build() to delegate to generic.IntegrationBuilder.Build(). Added MarkClusterScoped() and WithCustomOperationalStatus() calls in NewBuilder(), removed the custom validate() method. This ensures ValidateBase() runs the full shared validation (identity, applicator, mutator-factory checks) and keeps PV consistent with other primitives.
docs/primitives.md:135 (table alignment) — Fixed spacing in the PV row to align with other rows in the built-in primitives table.

Intentionally ignored:

docs/primitives.md:135 (PR description checklist) — This comment asks to update the PR description/checklist to reflect that shared files are modified. This is a PR metadata issue, not a code change. The PR author should update the description accordingly.

Copilot

Pull request overview

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

pkg/primitives/pv/resource_test.go

docs/primitives/pv.md

examples/pv-primitive/app/controller.go

examples/pv-primitive/README.md

sourcehawk · 2026-03-23T16:59:20Z

Claude Review Cycle 1 Complete

Addressed:

Used Quantity.Equal instead of assert.Equal for resource.Quantity comparisons in resource_test.go (line 48 and also line 127 which had the same issue)
Updated docs/primitives/pv.md (line 291) to reflect actual framework behavior: ownerReferences are skipped (not API-rejected) for cluster-scoped resources with namespace-scoped owners
Updated examples/pv-primitive/app/controller.go (line 8) package comment to reflect conditional ownerReference behavior
Changed examples/pv-primitive/README.md (line 9) from "Data Extraction" to "Result Inspection" to match actual example code

Intentionally ignored:
None

Copilot

Pull request overview

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

Introduces a typed editor for corev1.PersistentVolumeSpec with methods for capacity, access modes, reclaim policy, storage class, mount options, volume mode, and node affinity. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Implements the PV primitive as a cluster-scoped Integration resource: - Builder validates Name only (no namespace for cluster-scoped resources) - DefaultFieldApplicator preserves immutable fields on existing PVs (volume source, volume mode, claim ref) - DefaultOperationalStatusHandler reports status based on PV phase - Mutator with plan-and-apply pattern for metadata and spec edits - Flavors for preserving external labels and annotations Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Documents the PV primitive's integration lifecycle, cluster-scoped identity, immutable field preservation, mutation pipeline, editors, flavors, operational status mapping, and usage guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Demonstrates PV builder, mutations, flavors, and operational status: - Cluster-scoped identity (no namespace) - Immutable field preservation on existing PVs - Boolean-gated mutations for reclaim policy and mount options - PreserveCurrentAnnotations flavor for external fields - Operational status mapping from PV phases Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix compile error: use Spec.PersistentVolumeSource.HostPath instead of non-existent Spec.HostPath field, with nil check - Update README to accurately describe what the example does (in-memory mutations, not fake client; operational status, not status conditions) - Fix controller.go comment to remove reference to non-existent SkipOwnerRef option Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Cover create-vs-update behavior, immutable field preservation (PersistentVolumeSource, VolumeMode, ClaimRef), nil immutable field handling, and verify the desired object is not mutated. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Copilot · 2026-03-25T16:12:06Z

pkg/primitives/pv/mutator.go

+func (m *Mutator) EditObjectMetadata(edit func(*editors.ObjectMetaEditor) error) {
+	if edit == nil {
+		return
+	}
+	m.active.metadataEdits = append(m.active.metadataEdits, edit)
+}


EditObjectMetadata / EditPVSpec dereference m.active unconditionally. If a caller forgets to call BeginFeature() first (possible since NewMutator leaves active nil), this will panic at runtime. Consider making the mutator safe-by-default by auto-starting an initial plan (e.g., initialize plans/active in NewMutator, or lazily call BeginFeature() inside these methods when m.active == nil) so misuse can’t crash reconciliation.

Copilot · 2026-03-25T16:12:07Z

pkg/primitives/pv/mutator.go

+func (m *Mutator) EditPVSpec(edit func(*editors.PVSpecEditor) error) {
+	if edit == nil {
+		return
+	}
+	m.active.specEdits = append(m.active.specEdits, edit)
+}


EditObjectMetadata / EditPVSpec dereference m.active unconditionally. If a caller forgets to call BeginFeature() first (possible since NewMutator leaves active nil), this will panic at runtime. Consider making the mutator safe-by-default by auto-starting an initial plan (e.g., initialize plans/active in NewMutator, or lazily call BeginFeature() inside these methods when m.active == nil) so misuse can’t crash reconciliation.

Copilot · 2026-03-25T16:12:07Z

pkg/primitives/pv/handlers.go

+// A PV in the Pending phase is reported as OperationPending. A PV in the
+// Released or Failed phase is reported as OperationFailing.


The comment refers to OperationPending / OperationFailing, but the implementation returns concepts.OperationalStatusPending / concepts.OperationalStatusFailing. Updating the comment to match the actual status names will avoid confusion for readers searching for those identifiers.

Suggested change

// A PV in the Pending phase is reported as OperationPending. A PV in the

// Released or Failed phase is reported as OperationFailing.

// A PV in the Pending phase is reported as concepts.OperationalStatusPending. A PV in the

// Released or Failed phase is reported as concepts.OperationalStatusFailing.

Copilot · 2026-03-25T16:12:07Z

docs/primitives/pv.md

+
+| Capability                | Detail                                                                                             |
+| ------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Integration lifecycle** | Reports `Operational`, `OperationPending`, or `OperationFailing` based on the PV's phase           |


The doc uses OperationPending / OperationFailing, but the code (and tests) use concepts.OperationalStatusPending / concepts.OperationalStatusFailing. Please align the documentation terminology with the actual framework statuses (and keep it consistent with handlers.go and other primitive docs) to prevent users from looking for non-existent status values.

Suggested change

| **Integration lifecycle** | Reports `Operational`, `OperationPending`, or `OperationFailing` based on the PV's phase |

| **Integration lifecycle** | Reports `Operational`, `concepts.OperationalStatusPending`, or `concepts.OperationalStatusFailing` based on the PV's phase |

Update documentation and handler comments to use the actual concepts.OperationalStatusPending / concepts.OperationalStatusFailing / concepts.OperationalStatusOperational identifiers instead of the shorthand OperationPending / OperationFailing / Operational names. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

sourcehawk · 2026-03-25T16:14:48Z

Claude Review Cycle 1 Complete

Addressed:

handlers.go L14-15: Updated comment to use concepts.OperationalStatusPending / concepts.OperationalStatusFailing instead of OperationPending / OperationFailing
docs/primitives/pv.md L11: Updated capabilities table to use full concepts.OperationalStatus* identifiers
docs/primitives/pv.md L197-199: Updated operational status table to use OperationalStatusPending / OperationalStatusFailing / OperationalStatusOperational instead of shorthand names
docs/primitives/pv.md L243: Updated guidance section to use consistent status names

Intentionally ignored:

mutator.go L58/L73 (nil m.active panic): All other primitives (deployment, configmap) follow the same pattern — BeginFeature() is called by the framework mutation pipeline before any edits are registered. Adding nil-safety only to the PV mutator would be inconsistent with the codebase convention. The NewMutator godoc already documents that BeginFeature must be called first.

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Copilot

Pull request overview

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

Copilot · 2026-03-25T19:01:52Z

pkg/primitives/pv/mutator.go

+func (m *Mutator) BeginFeature() {
+	m.plans = append(m.plans, featurePlan{})
+	m.active = &m.plans[len(m.plans)-1]
+}


EditObjectMetadata / EditPVSpec dereference m.active unconditionally. If BeginFeature() hasn’t been called (or if future refactors call these before BeginFeature()), this will panic at runtime. Consider making the mutator resilient by ensuring an active plan exists (e.g., lazily calling BeginFeature() the first time an edit is registered), or by failing fast with a dedicated, clearer panic/message rather than a nil-pointer dereference.

Copilot · 2026-03-25T19:01:53Z

pkg/primitives/pv/mutator.go

+type Mutator struct {
+	pv *corev1.PersistentVolume
+
+	plans  []featurePlan
+	active *featurePlan
+}


Storing active as a pointer to a slice element is fragile because any future append/re-slice patterns on m.plans could invalidate pointers and make bugs hard to debug. A more robust approach is to store an activeIndex int (or *featurePlan allocated independently), and reference m.plans[m.activeIndex] when appending edits.

Copilot · 2026-03-25T19:01:53Z

pkg/primitives/pv/mutator.go

+func (m *Mutator) BeginFeature() {
+	m.plans = append(m.plans, featurePlan{})
+	m.active = &m.plans[len(m.plans)-1]
+}


Storing active as a pointer to a slice element is fragile because any future append/re-slice patterns on m.plans could invalidate pointers and make bugs hard to debug. A more robust approach is to store an activeIndex int (or *featurePlan allocated independently), and reference m.plans[m.activeIndex] when appending edits.

sourcehawk requested a review from Copilot March 22, 2026 03:43

Copilot started reviewing on behalf of sourcehawk March 22, 2026 03:44 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

examples/pv-primitive/main.go Outdated Show resolved Hide resolved

examples/pv-primitive/README.md Outdated Show resolved Hide resolved

pkg/mutation/editors/pvspec.go Show resolved Hide resolved

examples/pv-primitive/app/controller.go Outdated Show resolved Hide resolved

sourcehawk requested a review from Copilot March 22, 2026 13:20

Copilot started reviewing on behalf of sourcehawk March 22, 2026 13:20 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

pkg/mutation/editors/pvspec.go Show resolved Hide resolved

pkg/primitives/pv/resource.go Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 22, 2026 19:55

Copilot started reviewing on behalf of sourcehawk March 22, 2026 19:55 View session

Copilot AI reviewed Mar 22, 2026

View reviewed changes

docs/primitives/pv.md Show resolved Hide resolved

docs/primitives/pv.md Show resolved Hide resolved

pkg/mutation/editors/pvspec.go Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 23, 2026 03:00

Copilot started reviewing on behalf of sourcehawk March 23, 2026 03:03 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

pkg/primitives/pv/builder.go Outdated Show resolved Hide resolved

docs/primitives.md Show resolved Hide resolved

docs/primitives.md Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 23, 2026 16:08

Copilot started reviewing on behalf of sourcehawk March 23, 2026 16:08 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

pkg/primitives/pv/resource_test.go Outdated Show resolved Hide resolved

docs/primitives/pv.md Outdated Show resolved Hide resolved

examples/pv-primitive/app/controller.go Outdated Show resolved Hide resolved

examples/pv-primitive/README.md Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings March 23, 2026 16:59

Copilot started reviewing on behalf of sourcehawk March 23, 2026 16:59 View session

Copilot AI reviewed Mar 23, 2026

View reviewed changes

sourcehawk and others added 8 commits March 23, 2026 20:16

Fix staticcheck lint: remove redundant embedded field selector

8f995fe

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix lint

597e7de

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:11

Copilot AI reviewed Mar 25, 2026

View reviewed changes

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:15

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:15 View session

sourcehawk requested review from Copilot and removed request for Copilot March 25, 2026 16:16

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:22 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:32 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:33 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:36 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:37 View session

Copilot started reviewing on behalf of sourcehawk March 25, 2026 16:38 View session

sourcehawk added 2 commits March 25, 2026 16:47

fix docs

7c6589c

Merge branch 'main' into feature/pv-primitive

e8aa859

Copilot AI review requested due to automatic review settings March 25, 2026 18:58

sourcehawk merged commit e73a8a1 into main Mar 25, 2026
4 checks passed

sourcehawk deleted the feature/pv-primitive branch March 25, 2026 18:58

Copilot started reviewing on behalf of sourcehawk March 25, 2026 18:58 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

		// A PV in the Pending phase is reported as OperationPending. A PV in the
		// Released or Failed phase is reported as OperationFailing.

	\| Integration lifecycle \| Reports `Operational`, `OperationPending`, or `OperationFailing` based on the PV's phase \|
	\| Integration lifecycle \| Reports `Operational`, `concepts.OperationalStatusPending`, or `concepts.OperationalStatusFailing` based on the PV's phase \|

Conversation

sourcehawk commented Mar 22, 2026

Summary

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 22, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sourcehawk commented Mar 23, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

sourcehawk commented Mar 25, 2026

Claude Review Cycle 1 Complete

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview