252 lines
15 KiB
Markdown
252 lines
15 KiB
Markdown
---
|
|
status: draft
|
|
system: executors
|
|
requirements:
|
|
- REQ-EXECUTORS-EXECUTOR-PROFILE-ENV-PRECEDENCE-001
|
|
created: 2026-08-17
|
|
owners:
|
|
- tbd
|
|
---
|
|
# Executor-Profile Environment Precedence System Design Part 2
|
|
|
|
## Purpose and boundaries
|
|
|
|
This design preserves the technical source detail for `REQ-EXECUTORS-EXECUTOR-PROFILE-ENV-PRECEDENCE-001` during migration.
|
|
|
|
## Requirement mapping
|
|
|
|
| Requirement | Design section |
|
|
| --- | --- |
|
|
| `REQ-EXECUTORS-EXECUTOR-PROFILE-ENV-PRECEDENCE-001` | [Migrated source detail](#migrated-source-detail) |
|
|
|
|
## Migrated source detail
|
|
|
|
## Resolution procedure
|
|
|
|
The order of these steps is part of the contract. A different order produces different answers for
|
|
mixed secret and multi-origin cases.
|
|
|
|
For each environment key, in a deterministic TOTAL sort order over named columns.
|
|
|
|
The sort that exists today at `environment.go:97` compares `Key`, then `Origin`, then `SecretID`.
|
|
That is not a total order, and the gap is load-bearing rather than theoretical: two definitions
|
|
agreeing on all three but differing in `WorkspaceID` share one `definitionIdentity` (identity is
|
|
`"secret:" + SecretID` for a secret), so they MERGE, and which one survives is decided by input
|
|
order — while `WorkspaceID` is exactly what `resolveEnvironmentDefinition` branches on to choose
|
|
between a global reveal and `RevealForWorkspace`. Input order could therefore change the revealed
|
|
value, which AC-30 forbids.
|
|
|
|
The sort therefore gains two further NAMED columns and becomes, all ascending:
|
|
|
|
Key, then Origin, then SecretID, then WorkspaceID, then Literal
|
|
|
|
Adding columns can only break ties that were previously left to input order, so no definition set
|
|
whose outcome is already deterministic changes (AC-16, AC-29a).
|
|
|
|
For each key, in that order:
|
|
|
|
1. **Skip blanks.** Discard any definition whose `Key` is empty or whitespace-only.
|
|
2. **Group** the remaining definitions by `Key`.
|
|
3. **Merge identical identities.** Definitions sharing one `definitionIdentity` collapse to a
|
|
single surviving definition, recording every contributing origin, exactly as today. Merging
|
|
happens **before** any tier or secret evaluation. The merged group RETAINS THE FULL SET of
|
|
contributing origins; step 6 classifies the group by that set, not by the single surviving
|
|
`Definition.Origin` field.
|
|
4. **If one identity survives**, that is the value. No conflict, no override record.
|
|
5. **If more than one identity survives, apply the secret veto first.** If any surviving
|
|
definition for that key has a non-empty `SecretID`, return `*ConflictError` whose `Origins`
|
|
holds **every CONTRIBUTING origin of every surviving identity** (per "The secret veto"),
|
|
de-duplicated and sorted ascending. Tier rank is not consulted.
|
|
6. **Otherwise compare tiers.** Classify each surviving IDENTITY — not each surviving
|
|
`Definition` — into a tier by `TierForOrigin`. **An identity's tier is the STRONGEST
|
|
(numerically smallest) tier among ALL of its contributing origins.**
|
|
- If the highest occupied tier holds more than one surviving identity, return
|
|
`*ConflictError` whose `Origins` holds every CONTRIBUTING origin of every surviving identity,
|
|
including origins from lower tiers, de-duplicated and sorted ascending.
|
|
- Otherwise the single identity in the highest occupied tier wins, every identity in a lower
|
|
tier is discarded, and one override record is emitted. Both origin lists in that record are
|
|
DE-DUPLICATED SETS (see "The override record"): `WinningOrigins` holds each distinct
|
|
contributing origin of the winning identity once, and `LosingOrigins` holds each distinct
|
|
origin appearing anywhere among the discarded identities once — one entry per ORIGIN, never
|
|
one per discarded identity.
|
|
7. **Reveal** secrets only for surviving winners, after the whole key set is conflict-free,
|
|
preserving today's ordering in `Resolve`.
|
|
|
|
Step 5 preceding step 6 is deliberate: a secret and a literal that disagree must block even when
|
|
they sit in different tiers.
|
|
|
|
Steps 5 and 6 use ONE enumeration rule between them — every contributing origin of every surviving
|
|
identity, de-duplicated and sorted. Stating it once per step rather than only on the precedence
|
|
path is deliberate: merging happens at step 3, before either, so BOTH paths can face a surviving
|
|
identity whose single `Definition.Origin` field under-reports the origins that produced it.
|
|
|
|
Step 6's "including origins from lower tiers" is deliberate: when the top tier is itself
|
|
ambiguous, the error should name every origin the user has to look at, matching today's behaviour
|
|
of reporting the complete participating set.
|
|
|
|
**Step 6 classifies the IDENTITY by its strongest contributing origin, and that word "strongest"
|
|
is load-bearing.** Classifying by the surviving `Definition.Origin` instead would silently
|
|
discard a Tier 1 value in the most common real configuration this feature exists to serve.
|
|
Worked case: key `AGENT_MODEL` carries `executor profile` literal X, `agent profile` literal X
|
|
(the SAME literal — precisely the duplicate-the-value workaround the Why section says users
|
|
employ today), and `managed runtime` literal Y from `profileInfo.Model`
|
|
(`environment_resolution.go:65`). Step 3 merges the X pair into one identity. Under the
|
|
five-column sort the surviving `Definition` is the `agent profile` one, because
|
|
`"agent profile" < "executor profile"` — so classifying by that single field would put identity X
|
|
in Tier 2, leave Y as the sole Tier 1 identity, and hand the key to Y while silently dropping an
|
|
`executor profile` literal that disagrees with it. AC-5 requires that pair to conflict. Under the
|
|
strongest-contributing-origin rule, identity X is Tier 1 (via `executor profile`), the top tier
|
|
holds two identities, and the key conflicts — which is what AC-5 says and what AC-5a pins.
|
|
|
|
## The override record
|
|
|
|
The record is a declared Go type, not a shape left to the builder. It lives in the `environment`
|
|
package beside the tier table, and it carries identity and rank only — never a value.
|
|
|
|
```go
|
|
// Tier ranks an origin. LOWER IS STRONGER: Tier 1 beats Tier 2 beats Tier 3.
|
|
type Tier int
|
|
|
|
const (
|
|
TierAuthoritative Tier = 1
|
|
TierProfileDefault Tier = 2
|
|
TierAgentRuntimeDefault Tier = 3
|
|
)
|
|
|
|
// OriginTier pairs an origin string with the tier it classified into.
|
|
type OriginTier struct {
|
|
Origin string
|
|
Tier Tier
|
|
}
|
|
|
|
// OverrideRecord describes one environment key whose value was chosen by tier
|
|
// precedence instead of blocking the launch. It contains no literal value, no
|
|
// SecretID, and no decrypted secret.
|
|
type OverrideRecord struct {
|
|
Key string // the environment key that was overridden
|
|
WinningOrigins []string // SET: >= 1 entry, each distinct origin ONCE,
|
|
// sorted ascending; MAY span tiers
|
|
WinningTier Tier // the STRONGEST tier among WinningOrigins — the tier the
|
|
// winning identity was classified into by procedure step 6
|
|
LosingOrigins []OriginTier // SET: >= 1 entry, each distinct origin ONCE,
|
|
// sorted by Origin ascending
|
|
}
|
|
```
|
|
|
|
`WinningOrigins` is a SLICE, not a string. A merged winner can legitimately have more than one
|
|
contributing origin — that is exactly the case AC-8a describes, where two Tier 1 definitions share
|
|
one `definitionIdentity`, merge, and then beat a Tier 2 literal.
|
|
|
|
### BOTH ORIGIN LISTS ARE SETS, NOT BAGS
|
|
|
|
This is a contract, not an implementation detail, because it decides observable test assertions
|
|
and observable counter values:
|
|
|
|
> **Every origin string appears AT MOST ONCE in `WinningOrigins`, and at most once across all of
|
|
> `LosingOrigins`.** Both lists are de-duplicated by origin string, then sorted. Neither list ever
|
|
> contains two entries carrying the same `Origin`.
|
|
|
|
Concretely, per list:
|
|
|
|
- **`WinningOrigins`** holds each DISTINCT origin that contributed to the winning identity. Two
|
|
definitions that share both an origin and a `definitionIdentity` contribute ONE entry, not two.
|
|
- **`LosingOrigins`** holds each DISTINCT origin appearing anywhere among the discarded
|
|
identities, paired with that origin's own tier. One entry per ORIGIN — **never one per discarded
|
|
identity.** So when a single losing origin contributes SEVERAL differing identities, which is
|
|
exactly what AC-6's stronger-tier carve-out produces, that origin still yields ONE
|
|
`LosingOrigins` entry and therefore ONE counter increment (AC-8d).
|
|
|
|
Because `Tier` is functionally determined by `Origin` through `TierForOrigin`, de-duplicating by
|
|
origin can never discard distinct tier information: two entries sharing an `Origin` are always
|
|
identical `OriginTier` values.
|
|
|
|
**The two lists are de-duplicated INDEPENDENTLY, and one origin MAY appear in both.** The rule
|
|
above bounds each list on its own; it does not make them disjoint, and THE SYSTEM SHALL NOT
|
|
subtract `WinningOrigins` from `LosingOrigins`. Worked case: `executor profile` = X,
|
|
`agent profile` = X, `agent profile` = Y. Identity X is contributed by both origins and classifies
|
|
Tier 1; identity Y is contributed by `agent profile` alone and classifies Tier 2; X wins. Then
|
|
`WinningOrigins` is `[agent profile, executor profile]` and `LosingOrigins` is
|
|
`[{agent profile, TierProfileDefault}]` — the same origin on both sides, because it genuinely both
|
|
contributed to the winner and had a distinct value discarded. The metric label pair is
|
|
`winning_origin=agent profile+executor profile;losing_origin=agent profile`, which is correct
|
|
rather than a defect to normalise away.
|
|
This is resolver-level only, for the same reason AC-6's ambiguous case is: reaching it needs one
|
|
origin contributing two differing identities, and the only origin that can do that is
|
|
`executor profile` (AC-6a), which is Tier 1 and therefore never a loser. It is pinned because the
|
|
rule is otherwise silent on the interaction and a builder could reasonably "clean up" the
|
|
duplicate, changing an observable counter value with no AC to catch it.
|
|
|
|
Three reasons this is the SET reading and not the bag reading, in order of weight:
|
|
|
|
1. **It preserves today's behaviour.** `selectDefinitions` already accumulates contributing
|
|
origins in a `map[string]struct{}` (`origins[key][origin] = struct{}{}`) and already emits
|
|
`ConflictError.Origins` de-duplicated and sorted. The bag reading would be a silent behaviour
|
|
CHANGE to merge-origin reporting on a path this feature was not asked to touch.
|
|
2. **It is what the counter means.** AC-24 counts "per-ORIGIN, not per input definition". Under the
|
|
bag reading, one key overriding one origin could increment the same
|
|
`winning_origin=…;losing_origin=…` label pair twice, which makes the metric a count of internal
|
|
identity groupings rather than of overrides.
|
|
3. **It makes AC-28's ordering total.** With origins unique, `Origin` alone totally orders
|
|
`LosingOrigins`; under the bag reading it does not, and AC-27's deep-equality requirement would
|
|
rest on an undefined order between indistinguishable entries.
|
|
|
|
**The winning origins may span tiers, and `WinningTier` is the strongest of them.** A merge groups
|
|
definitions by `definitionIdentity`, which is the hash of the literal (or the secret ID) and says
|
|
nothing about origin, so one identity can be contributed by an `executor profile` (Tier 1) and an
|
|
`agent profile` (Tier 2) that happen to carry the same value. `WinningTier` therefore records the
|
|
tier the identity was CLASSIFIED into by procedure step 6 — the numerically smallest tier among
|
|
`WinningOrigins` — not a property shared by every member. Consumers that need the per-origin
|
|
detail read `WinningOrigins`; `WinningTier` answers only "which tier won this key".
|
|
|
|
Note the remaining asymmetry with `LosingOrigins`, which pairs each origin with its OWN tier via
|
|
`OriginTier`. That is deliberate and is not affected by the set rule above: losers are enumerated
|
|
per origin because AC-24 fans the counter out per losing origin, whereas the winner is a single
|
|
classified identity with a single rank.
|
|
|
|
### Signatures
|
|
|
|
```go
|
|
// CHANGED: gains a third return value.
|
|
func Resolve(ctx context.Context, definitions []Definition, reveal RevealFunc) (map[string]string, []OverrideRecord, error)
|
|
|
|
// UNCHANGED.
|
|
func Validate(definitions []Definition) error
|
|
```
|
|
|
|
`Resolve` gains a return value. That is a deliberate, named change to the function signature; the
|
|
exported FIELDS of `Definition`, `ConflictError` and `SecretError` are untouched. There are only
|
|
two call sites to update: `Manager.resolveStrictEnvironment`
|
|
(`environment_resolution.go:51`, the sole production resolve site) and `resolveEnvironmentSources`
|
|
(`task_environment.go:40`, which today is reached only from tests).
|
|
|
|
**What each call site does with the new value.** `Manager.resolveStrictEnvironment` consumes the
|
|
records: it emits the AC-23 log and the AC-24 counter increments. `resolveEnvironmentSources`
|
|
DISCARDS them (`resolved, _, err := ...`) and SHALL NOT log or count. That is not laziness about a
|
|
test helper — it is AC-46's rule applied consistently: emission is tied to an actual launch
|
|
resolution, and this function is reached from no production path (5 test callers, 0 production).
|
|
A test helper that incremented the shared expvar map would make the counter a count of test runs.
|
|
If a future change gives it a production caller, that caller must take over the emission and this
|
|
clause must be revisited.
|
|
|
|
**On any error, `Resolve` returns NO override records.** When the third return value is non-nil the
|
|
second SHALL be `nil` and the first SHALL be `nil`, matching today's `return nil, err` on every
|
|
failure path. This is all-or-nothing, not partial (AC-20a).
|
|
|
|
The case is reachable and is not hypothetical. Records are computed for every key before any
|
|
secret is revealed, because step 7 reveals only after the whole key set is conflict-free. So a set
|
|
where key `A` is resolved by tier precedence while key `B` conflicts, or where `A` overrides and
|
|
any secret then fails to reveal, has already produced a record for `A` at the moment the error is
|
|
returned. Handing those records back would let `Manager.resolveStrictEnvironment` log
|
|
`environment override applied` and increment `environment_override_applied_total` for a launch
|
|
that failed and applied nothing — corrupting the counter AC-24 defines and contradicting AC-46's
|
|
"tied to an actual resolution". A launch that does not start has not overridden anything.
|
|
|
|
`Validate` keeps its `error`-only signature and emits no records, no log, and no counter
|
|
increment. This is safe rather than merely convenient: the preflight set is assembled by
|
|
`Executor.taskEnvironmentSources` from `managed runtime`, `executor profile` and
|
|
`repository <name>` definitions only — every one of them Tier 1 — because agent-profile
|
|
definitions are not appended until `resolveStrictEnvironment` runs at the lifecycle site. A
|
|
Tier-1-only set can never occupy two tiers, so it can never produce an override, so there is
|
|
nothing for `Validate` to return. If a future change adds a Tier 2 or Tier 3 definition to the
|
|
preflight set, this AC must be revisited (AC-19b).
|