fix read-only resource extractors observing the empty desired base

[sourcehawk]

Summary

• readResource fetched the cluster object into a deep copy that was then discarded; BaseResource.ExtractData re-deep-copied DesiredObject, so extractors on read-only resources only ever saw the inert base used to build the resource. Documented in Read-only resource extractors receive the empty desired-object base, not the fetched cluster object #115.
• Add concepts.ObservationRecorder with RecordObservation(observed client.Object) error, implement it on BaseResource, and invoke it from readResource after Get so the fetched object is visible to subsequent extractors. Resources built from generic.BaseResource pick this up automatically; custom wrappers that want read-only extractor support forward the method to their base.
• Update WithDataExtractor GoDoc, the Phase 4 description in docs/component.md, and the custom-resource guide so the new method shows up in the typical-methods table and example wrapper.

Closes #115.

Test plan

• make all (lint, fmt, full unit suite, example builds) clean.
• New unit test in pkg/generic/resource_static_test.go proves BaseResource.RecordObservation makes the observed object visible to ExtractData, and rejects wrong-type input.
• New integration tests in pkg/component/read_test.go prove readResource invokes RecordObservation with the populated cluster object and that errors from it propagate with resource identity context.
• If desired, manual verification against a real cluster with a read-only Secret + WithDataExtractor capturing secret.DataHash confirms rotation triggers downstream rollouts.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes a framework bug where data extractors on read-only resources observed the empty “desired base” object instead of the object fetched from the cluster (issue #115). The PR introduces an observation-recording hook so the fetched object is recorded back onto the resource before subsequent inspection (notably data extraction) occurs, and updates docs/tests accordingly.

Changes:

• Add concepts.ObservationRecorder and implement RecordObservation(observed client.Object) error on generic.BaseResource.
• Update the read-only fetch path (readResource) to call RecordObservation after client.Get, enabling extractors to observe live cluster state.
• Add unit/integration tests and update documentation/GoDoc to reflect the new behavior and forwarding requirement for custom wrappers.

Reviewed changes

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

Show a summary per file

File	Description
pkg/generic/resource_static_test.go	Adds unit coverage verifying RecordObservation makes observed state visible to ExtractData and rejects wrong types.
pkg/generic/resource_base.go	Implements RecordObservation by storing the observed typed object; clarifies ExtractData semantics for managed vs read-only.
pkg/generic/builder_base.go	Updates WithDataExtractor GoDoc to describe managed vs read-only extractor inputs and idempotency expectations.
pkg/component/zz_mock_resource_test.go	Adds a mock resource type implementing RecordObservation for component tests.
pkg/component/read.go	Calls RecordObservation after fetching a read-only resource from the cluster.
pkg/component/read_test.go	Adds integration tests ensuring readResource records observations and propagates recorder errors with resource identity context.
pkg/component/concepts/observable.go	Introduces the ObservationRecorder interface and its contract.
docs/custom-resource.md	Updates wrapper guidance and “Typical Methods” table to include RecordObservation forwarding for read-only extractor support.
docs/component.md	Updates Phase 4 lifecycle docs to include observation recording before extraction for read-only resources.