[wasabii]

What this changes

Gets Weft ready for its first release to external users.

README for external readers. The README is rewritten for people meeting Weft for the first time. It now covers what Weft is, a runnable quick start, features, install and image verification, and an index of the docs. The detail the old README carried is moved, not dropped: docs/operating.md covers status conditions, pruning, teardown, flags, metrics and uninstalling; docs/design.md covers the comparison with other tools, why Starlark, and non-goals. Install instructions no longer assume prerelease-only (--devel).

New API group, weft.alethic.solutions/v1, served alongside weft.run/v1alpha1. Weft is already deployed internally under weft.run, so the old group keeps working unchanged:

• Two CRDs, one schema. Kubernetes can't convert between groups, so each group has its own CRD. Canonical types live in api/v1; api/v1alpha1 embeds v1's spec and status, and a test checks the generated schemas match. The weaves.weft.run CRD changes only in two description lines.
• Each Weave writes its own group's keys (internal/naming): finalizers, provenance label and annotation, the owned and adopt annotations, and the field manager. A test pins the weft.run keys so they can't change by accident. The leader election lease keeps its old name, so a rolling upgrade's old and new pods share one lease.
• One reconciler per group, both working on the v1 type internally (internal/controller/served.go). The watch registry, metrics and kube client know which group a Weave belongs to, so same-named Weaves in the two groups never interfere.
• Moving a Weave between groups keeps its objects in place. A v1 Weave takes over what its same-named weft.run predecessor made, without recreating anything. It moves field ownership from the old field manager to its own, so its first apply removes the old provenance. This happens in two ways:
  • Manually: delete the old Weave with kubectl delete … --cascade=orphan, then apply the v1 one.
  • Through Helm or Flux: swap the apiVersion in one release. Helm, Flux's helm-controller and kustomize-controller all create new objects before pruning removed ones (checked in their source). A weft.run Weave deleted while a live v1 successor exists strips its own owner references and lets go, instead of tearing down. That existence check bypasses the cache, because a stale answer would mean a teardown.
• Guards against mistakes:
  • A v1 Weave refuses objects a still-live predecessor manages, with the exact command to finish the move.
  • It waits while the predecessor is being deleted.
  • A v1 program that still uses weft.run/owned is refused, rather than owning (and later deleting) what it meant to keep.
• Both groups are always served. The chart always installs both CRDs and grants access to both, and the controller always reconciles both. There's deliberately no switch to turn weft.run off, because turning it off while weft.run Weaves remain would strand them. It goes away when a future release removes it. reap covers both groups. docs/migrating.md is the guide for internal teams.

Upgrade fix found by a real Helm upgrade test:

• A stored image digest kept the old binary. The publish job wrote the image digest into values.yaml, so --reuse-values kept the previous release's image under the new chart. The upgrade then reports success, but the old controller keeps running and serves no v1. (On kind, with an intermediate version of this branch, the old binary crash-looped on a since-removed flag.) The digest now ships in charts/weft/files/image-digest. Order of precedence: image.digest, then image.tag, then the published digest, then appVersion. The docs recommend --reset-then-reuse-values for the first upgrade from a prerelease.

Behaviour changes worth noting:

• Per-Weave metrics gain a group label.
• The weft.run controller is now named weave-weft-run in controller-runtime's own metrics; weave now means v1.
• While both CRDs are installed, plain kubectl get weave is ambiguous between the two groups. I expect it resolves to v1, but haven't checked that on a cluster.
• A user-set image.tag now takes effect on a published chart instead of being silently overridden by the pinned digest.

Checks

• make generate produces no diff. Run as the equivalent controller-gen steps; make isn't available on the Windows machine this was written on.
• make test passes, and the controller and chart suites actually ran rather than skipping. The full suite ran with -race in a golang:1.27.1 container against envtest 1.37.0; the controller suite has 54 tests, 8 of them new for the two groups and handover. The chart suite ran locally with Helm 4.3.
• make lint is clean (golangci-lint v2.13.2 in a container).

End-to-end on kind (Kubernetes 1.37, Helm 4.3):

1. Installed the published 0.1.0-pre.37 chart.
2. Deployed two weft.run Weaves (ConfigMaps, a Secret, an unowned ConfigMap, a Deployment) from an app Helm chart.
3. Upgraded Weft to this branch with --reuse-values (with an earlier revision that still had a toggle, since removed). Both groups were served, the old Weaves stayed Ready, and they were actively reconciled (an input edit propagated within about a second).
4. Switched the app chart's apiVersion in one helm upgrade. With a real garbage collector running, every object kept its UID, ownership moved to the v1 Weaves, no weft.run labels, annotations or field managers were left, and the Deployment's pod never restarted.
5. A first attempt at step 4 failed partway, on a Helm server-side-apply conflict I had caused. Helm had created the v1 Weaves and deleted nothing. The v1 Weaves refused the still-owned objects, and nothing was torn down.

Nothing here needs a +semver bump; the next version is still the first 0.1.0.

Does this touch the impersonation boundary?

Yes: internal/kube and the controller's RBAC.

• RBAC: the controller gains the same three rules on weaves in weft.alethic.solutions that it already held in weft.run. It gains no access to anything a composition might generate.
• Factory.For now takes the Weave's group. It only selects the field manager; the impersonated identity is still built solely from the Weave's own namespace and ServiceAccount.
• New Client.TransferFieldOwnership. It runs on the impersonated client, so it needs patch on the object as that ServiceAccount, the same verb server-side apply already needs. It only rewrites metadata.managedFields entries for apply operations.
• The handover's removal of owner references goes through the existing impersonated RemoveOwnerReference.
• The only unimpersonated reads added check whether a Weave of the same name exists in the other group: a metadata-only get on weaves, which the controller already reads with its own identity. No composition data is read without impersonation.

So a Weave still cannot do more than its ServiceAccount can. The handover takes over only objects whose provenance names the same Weave, and anyone able to forge that provenance could already grant consent with the adopt annotation.