docs(render): carry core#694's invariant beside the characterization test

core#693 is fixed in codefly-dev/core#694 (open, green, cut from v0.7.1 and not
yet released), so the handshake it owes this PR is recorded where whoever pins
the release will need it rather than only in a comment thread.

TestAPartialRootOverrideReplacesAComposedModuleGroupWhole now names core#694 and
states the exact invariant to flip to over its own fixture: CONFIG_DIR keeps the
module's value, CONFIG_MODE's undischarged ${profile} survives and makes Load
FAIL by name, an emptied required key and an undeclared key are refused by name
(ErrEmptyProfileValue / ErrUndeclaredProfileKey), and the group stays composed —
which removes consequence (3), the truncated group widening its delivery to
every service of the composition.

docs/orchestration.md stops presenting the interim operator rule as open-ended.
It applies today, because the CLI pins v0.7.1; once core#694's release is pinned
it NARROWS rather than disappears, because core#694 deliberately leaves a group
inherited from a composed WORKSPACE (the product model) replacing whole — that
precedence has to be decided per key for the product model first. An operator's
--set is unchanged either way.

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

Author: antoinetoussaint-byte

docs/orchestration.md

@@ -394,10 +394,24 @@ and this package then injects the truncated group into **every** service of the
 composition rather than only the ones that declared it. A partial override
 narrows a group's contents and widens its delivery at the same time.
 
-This is filed as [codefly-dev/core#693](https://github.com/codefly-dev/core/issues/693),
-with the reproduction and the per-key semantics it should get. Until it lands,
-declare **every** key of a composed module's group when overriding it, or
-override none of them.
+This is filed as [codefly-dev/core#693](https://github.com/codefly-dev/core/issues/693)
+and **fixed in [core#694](https://github.com/codefly-dev/core/pull/694)**, which
+is open and green but not yet released, so the CLI still pins `v0.7.1` and the
+behaviour above is what a composition meets today.
+
+Until that release is pinned here: declare **every** key of a composed module's
+group when overriding it, or override none of them.
+
+When it is pinned, three of the four statements above stop being true for a
+**module's** group — an override becomes exactly a partial override, an
+undischarged `${profile}` is reported rather than discarded, and the group stays
+composed, so its delivery stays scoped to the services that declared it instead
+of widening to every service of the composition. The interim rule then narrows
+rather than disappearing: core#694 deliberately leaves a group inherited from a
+composed **workspace** (the product model) replacing whole, because the
+precedence there has to be decided per key for the product model first. An
+operator's `--set` is unchanged either way — still attributed to the run, still
+composition-root even on a composed name.
 `TestAPartialRootOverrideReplacesAComposedModuleGroupWhole`
 (`pkg/orchestration`) pins the current behaviour and names the core function, so
 the CLI's expectations move when core's do. The semantics it should get already

pkg/orchestration/composed_group_override_test.go

@@ -63,7 +63,30 @@ func groupKeys(infos []*basev0.ConfigurationInformation, group string) []string
 //     the ones that declared it. A partial override thus narrows the group's
 //     contents and widens its delivery at once.
 //
-// Filed as codefly-dev/core#693, with this reproduction and the three losses.
+// Filed as codefly-dev/core#693, with this reproduction and the three losses,
+// and FIXED in codefly-dev/core#694 (open and green, branch
+// issue-693-fix-configurations-a-workspace-override-of-a-composed, cut from
+// v0.7.1 — so the release carrying it is the next tag after v0.7.1).
+//
+// This test will fail the moment that release is pinned here, which is what it
+// was written to do. The invariant to flip it to, over this same fixture:
+//
+//   - CONFIG_DIR keeps the module's /etc/app — a key the root does not supply
+//     is no longer discarded;
+//   - CONFIG_MODE's undischarged ${profile} survives the override and is
+//     reported in Unsupplied, so Load FAILS naming app-config/CONFIG_MODE where
+//     it returns nil below;
+//   - a root value that empties a ${profile} key is refused by name
+//     (configurations.ErrEmptyProfileValue), and a key the module's group does
+//     not declare is refused by name (configurations.ErrUndeclaredProfileKey);
+//   - the group STAYS composed: ComposedBy keeps the name and it is absent from
+//     CompositionRootWorkspaceConfigurationNames, so consequence (3) below
+//     disappears — a partial override no longer widens the truncated group's
+//     delivery to every service of the composition.
+//
+// core#694 leaves a group inherited from a composed WORKSPACE replacing whole,
+// so the operator rule in docs/orchestration.md narrows to that case rather
+// than going away.
 //
 // What it must become, and where: core should overlay the consuming workspace's
 // values onto the module's group per key, the way `profileOverlay.add` already