Design document for kube-xset enhancements:
- Generic SubResourceAdapter interface for multiple subresource types
- Name truncation with hash suffix for Kubernetes limits
- Label value handling with automatic truncation
- Backward compatibility with existing SubResourcePvcAdapter

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add a generic SubResourceAdapter interface and utilities for managing
subresources (PVCs, Services, etc.) in XSet controllers:

- SubResourceAdapter interface for generic subresource management
- NameTruncator for DNS-compliant name truncation with hash suffix
- LabelManager for label value handling with original value tracking
- TemplateHash utility using FNV-32a for consistent hashing
- SubResourceAdapterGetter interface for XSetController
- Documentation and implementation plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Implement SubResourceAdapter for PVC and Service resources:

- PvcSubResourceAdapter: manages PVC lifecycle with XSet
- ServiceSubResourceAdapter: example adapter for Service resources
- Both adapters support RecreateWhenXSetUpdated for recreation on updates

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add SubResourceControl to manage subresource lifecycle during XSet updates:

- RecreateWhenXSetUpdated: recreate subresources when XSet is updated
- SyncTargets: sync subresources with targets
- CleanupOnDelete: cleanup subresources when XSet is deleted
- Unit tests for SubResourceControl

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Integrate SubResourceControl into the XSet reconcile loop:

- Add SubResourceControl to SyncControl interface
- Wire subresource lifecycle into SyncTargets, Update, and Delete flows
- Add SyncContext fields for subresource management
- Update XSetController to initialize SubResourceControl

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Design for adding optional GetTargetPrefix and GetSubResourcePrefix
methods to allow controllers and adapters to customize naming prefixes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Plan for implementing optional GetTargetPrefix and GetSubResourcePrefix
methods with tests using aether leaderset controller.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add optional method for customizing target name prefixes.
Controllers can implement this to override the default naming pattern.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add optional method for customizing subresource name prefixes.
Adapters can implement this to override the default naming pattern.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Simplify GetTargetsPrefix to accept an optional override parameter.
Truncation logic moved to controller implementation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Check for optional TargetPrefixGetter implementation and use custom prefix
if provided. Falls back to default naming if not implemented.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add helper function for subresource prefix generation with override support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Check for optional SubResourcePrefixGetter implementation and use custom prefix
if provided. Falls back to default naming if not implemented.

Also update PVC and Service adapters to stop setting Name directly, since
GenerateName is now set by SubResourceControl.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…rceAdapter

Remove GetAttachedResourceNames method from the SubResourceAdapter interface
and refactor all usages to use label-based filtering instead.

The method was fundamentally flawed - it returned ALL subresources attached
to a target, not just those managed by xset. This could lead to incorrect
behavior when a target has external subresources.

Changes:
- Remove GetAttachedResourceNames from SubResourceAdapter interface
- Remove implementation from PvcSubResourceAdapter
- Delete unused ServiceSubResourceAdapter
- Refactor deleteUnusedResourcesForAdapter: remove "is still attached" check
  (K8s finalizers already prevent deletion of in-use PVCs)
- Refactor CheckAllowIncludeExclude: use GetFilteredResources + filterByTarget
- Refactor OrphanTargetResources: use GetFilteredResources + filterByTarget
- Refactor AdoptTargetResources: find orphaned resources by selector + orphaned
  label, then check if mounted to target using SubResourcePvcAdapter.GetXSpecVolumes
- Update all mock implementations in tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…esource

- Remove BuildResource method from SubResourceAdapter interface
- Remove SubResourcePrefixGetter optional interface
- Add SubResourceDecorator optional interface with DecorateResource method
- Move resource creation logic from adapters to control code
- Control code now sets: namespace, owner reference, labels (controlled-by, instance-id, template name/hash)
- Decorators can optionally customize resources (set Name, add custom labels)
- Add comment that Hash in SubResourceTemplate is computed by controller
- Add documentation about fields decorators MUST NOT modify

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Keep docs/superpowers/ as local files only.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add SubResourceTemplateLabelKey and SubResourceTemplateHashLabelKey
- Keep SubResourcePvcTemplateLabelKey as deprecated aliases
- Both map to same string values for backward compatibility

Replace PVC-specific label constants with generic ones

…_adapter

…_control

Allows adapters to register custom types with the scheme

Replace hardcoded switch statement with generic reflection-based extraction

- Replace hardcoded switch statements in newListForGVK/newObjectForGVK
- Use meta.EachListItem for extractListItems
- Update NewRealSubResourceControl to register types via SubResourceSchemeAdapter
- Update all callers to handle error returns

…erface

Required for PvcControl wrapper delegation

…ceControl

- Rewrite pvc_control.go as pvcControlWrapper that delegates to SubResourceControl
- Remove duplicate TemplateHash implementation (use utils.go version)
- Convert between []*corev1.PersistentVolumeClaim and []SubResourceState
- Update tests to use new SubResourceState with GVK field
- Add AdoptSingleResource to SubResourceControl interface for wrapper

This completes the consolidation of PVC-specific logic into the generic
SubResourceControl framework. PvcControl now provides backward compatibility
by wrapping the generic implementation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…to single class

Merge pvc_adapter.go into pvc_control.go and simplify to a single
PvcSubResourceAdapter class that implements SubResourceAdapter.
Remove the unused PvcControl interface and RealPvcControl wrapper
that were not being used anywhere in the codebase.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

PvcSubResourceAdapter is only used internally by BuildAdapters() for
auto-bridging legacy SubResourcePvcAdapter. Move it into getter.go
to keep related code together and simplify the package structure.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

types.go contained NameTruncator and LabelManager utility types.
Merge into utils.go to consolidate all utility code in one file.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

- Use HaveLen instead of len() == in test assertions
- Use indexing instead of range value copy for large structs
- Combine consecutive append calls
- Add nolint comment for unavoidable rangeValCopy when building slice from map

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

1. synccontrols/x_utils.go: Restore DNS validation in GetTargetsPrefix
   - Re-add validation for controllerName prefix to ensure valid DNS subdomain

2. synccontrols/sync_control.go: Fix unused subresource deletion
   - Only delete unused subresources when target is being deleted or replaced
   - Active targets may still reference subresources no longer in spec
   - Update BatchDeleteTargetsByLabel doc comment to reflect current cleanup flow

3. subresource_control.go: Multiple safety improvements
   - setUpCacheForAdapters: Return explicit error when GVK not in scheme
   - deleteResource: Add TODO comment about finalizer removal trade-offs
   - DeleteTargetUnusedResources: Add IMPORTANT doc comment about when to call

4. subresource_control_test.go: Remove empty placeholder tests
   - Remove table-driven tests with no assertions

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Removing all finalizers bypasses safety mechanisms like
kubernetes.io/pvc-protection which prevents PVC deletion while mounted.

Changes:
- deleteResource: Issue normal delete, let Kubernetes handle finalizers
- CreateTargetResources: Wait for dying resources naturally instead of
  forcefully removing their finalizers

Resources with finalizers will get a deletion timestamp and be deleted
when their finalizers are cleared by their respective controllers.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

- Remove unused 'target' parameter from deleteUnusedResourcesForAdapter
- Remove unused 'target' parameter from isAdapterTemplateChanged
- Fix appendAssign warning in sync_control.go

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Keep the updated doc comment that references SubResourceControl
instead of the old ensureReclaimPvcs reference.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>