chore(audit): sweep alias/exception tables for rot - entries that mask defects instead of recording divergence #303

New issue

Closed

opened 2026-07-20 15:57:15 +00:00 by hexajon · 1 comment

hexajon commented

2026-07-20 15:57:15 +00:00

(Migrated from codeberg.org)

Follow-up to #291, generalizing its root pattern. Deferred by owner direction (2026-07-20): file now, sweep in a later pass.

The pattern

#291's collision was invisible partly because a parity alias was papering over it: cliCanonicalAliases mapped actions/artifacts -> actions/run-artifacts, so the parity suite saw a satisfied mapping while the actual CLI carried two colliding artifacts commands and the per-run one was unreachable. The alias recorded what the surface was SUPPOSED to look like, and its existence silenced the very check that should have caught the drift. When PR #302 fixed the collision, the alias was already dead weight.

That is a class, not an instance: any alias table, exception list, or divergence-recording map can rot from "documenting a legitimate divergence" into "masking a defect" - and these tables are precisely the places drift guards are told not to look.

The sweep

Audit every such table for entries that are dead (target or source no longer exists), self-satisfied (the divergence they record has since been fixed, so the entry now maps a live name onto a live name and could hide a future collision), or masking (the entry exists because a defect was papered over rather than fixed). Known tables to start from - the sweep should enumerate exhaustively rather than trust this list:

cliCanonicalAliases and any sibling maps in internal/parity/
exclusion/allowlist sets inside the parity and drift guards themselves (layering, duplication, getconfigfordir, diag drift)
endpointSuggestions in internal/service/api/suggestions.go (suggestions pointing at renamed/removed commands)
hook-script pattern lists in hooks/ that name specific commands or paths
any "known divergence" or "skip" lists in tests

Acceptance

Every entry in every enumerated table is classified: live-and-legitimate (keep, with the divergence it records still true), dead (remove), or masking (remove AND fix or file the underlying defect)
Where mechanically checkable, a guard pins the class: e.g. an alias's source key must not itself resolve to a live surface (a live source means the alias is hiding a #291-style collision), and every alias target must exist - so future rot fails a test instead of sitting silent
The sweep's findings are recorded on this issue (table, entry, classification, action) so the audit is repeatable

Follow-up to #291, generalizing its root pattern. Deferred by owner direction (2026-07-20): file now, sweep in a later pass. ## The pattern #291's collision was invisible partly because a parity alias was papering over it: `cliCanonicalAliases` mapped `actions/artifacts -> actions/run-artifacts`, so the parity suite saw a satisfied mapping while the actual CLI carried two colliding `artifacts` commands and the per-run one was unreachable. The alias recorded what the surface was SUPPOSED to look like, and its existence silenced the very check that should have caught the drift. When PR #302 fixed the collision, the alias was already dead weight. That is a class, not an instance: any alias table, exception list, or divergence-recording map can rot from "documenting a legitimate divergence" into "masking a defect" - and these tables are precisely the places drift guards are told not to look. ## The sweep Audit every such table for entries that are dead (target or source no longer exists), self-satisfied (the divergence they record has since been fixed, so the entry now maps a live name onto a live name and could hide a future collision), or masking (the entry exists because a defect was papered over rather than fixed). Known tables to start from - the sweep should enumerate exhaustively rather than trust this list: - `cliCanonicalAliases` and any sibling maps in `internal/parity/` - exclusion/allowlist sets inside the parity and drift guards themselves (layering, duplication, getconfigfordir, diag drift) - `endpointSuggestions` in `internal/service/api/suggestions.go` (suggestions pointing at renamed/removed commands) - hook-script pattern lists in `hooks/` that name specific commands or paths - any "known divergence" or "skip" lists in tests ## Acceptance - [ ] Every entry in every enumerated table is classified: live-and-legitimate (keep, with the divergence it records still true), dead (remove), or masking (remove AND fix or file the underlying defect) - [ ] Where mechanically checkable, a guard pins the class: e.g. an alias's source key must not itself resolve to a live surface (a live source means the alias is hiding a #291-style collision), and every alias target must exist - so future rot fails a test instead of sitting silent - [ ] The sweep's findings are recorded on this issue (table, entry, classification, action) so the audit is repeatable

hexajon commented

2026-07-21 13:52:06 +00:00

(Migrated from codeberg.org)

Sweep record, so the audit is repeatable.

Method: read every table, crawled the full CLI command tree (516 leaves), mechanically checked every alias/override source and target against it; parity suite green throughout.

Classification - the four canonicalization maps in internal/parity/parity.go (the unguarded corner):

Table	Entries	Verdict
cliCanonicalAliases	47	all LIVE (every source resolves to a real command's pre-alias key; targets are legit CLI/MCP divergences)
cliDomainAliases	11	10 LIVE; `package -> packages` DEAD (no `package` command exists - the noun is already plural; remap unreachable, removed)
cliPathOverrides	5	all LIVE
mcpCanonicalAliases	0	empty since ADR 0029; comment current

The actions/artifacts -> actions/run-artifacts alias that motivated this issue was already removed by hand in the collision-guard commit - which is exactly the problem: nothing FORCED that removal.

Every guarded allowlist is healthy: IntentionalCLIOnly/MCPOnly, gated domains, KnownGaps, safetyWithheldKeys, routing/diag/cli-after-cd/mutation/side-effect allowlists, ownerRepoNoOpSites, getConfigForDirSites - all bidirectionally machine-locked already (the ...AreUsed / ...PinnedSites pattern). endpointSuggestions is machine-validated by suggestion_drift.go - the model the alias maps needed. Hook scripts' tool references: all name live tools (no reverse existence-guard exists; noted below). MASKING entries found: zero.

Fix landed: alias_staleness_test.go adds the missing guards - source-liveness (would have forced the artifacts removal), target-resolution, domain-head liveness, override-prefix liveness, and the MCP-side mirror - each with a planted-violation subtest so a refactor cannot neuter it. One subtlety: liveness walks the cobra tree INCLUDING hidden commands (madtea api is hidden by design and its alias is live).

Flagged, not decided here: (1) packages being plural while its command siblings are singular is a naming question, separate from the dead-alias removal; (2) madt_* names written inside hooks/*.sh have no existence guard (routing drift reads them as a corpus only) - same rot class one layer out, all currently live, low priority.

Sweep record, so the audit is repeatable. **Method:** read every table, crawled the full CLI command tree (516 leaves), mechanically checked every alias/override source and target against it; parity suite green throughout. **Classification - the four canonicalization maps in internal/parity/parity.go (the unguarded corner):** | Table | Entries | Verdict | |---|---|---| | cliCanonicalAliases | 47 | all LIVE (every source resolves to a real command's pre-alias key; targets are legit CLI/MCP divergences) | | cliDomainAliases | 11 | 10 LIVE; `package -> packages` DEAD (no `package` command exists - the noun is already plural; remap unreachable, removed) | | cliPathOverrides | 5 | all LIVE | | mcpCanonicalAliases | 0 | empty since ADR 0029; comment current | The `actions/artifacts -> actions/run-artifacts` alias that motivated this issue was already removed by hand in the collision-guard commit - which is exactly the problem: nothing FORCED that removal. **Every guarded allowlist is healthy:** IntentionalCLIOnly/MCPOnly, gated domains, KnownGaps, safetyWithheldKeys, routing/diag/cli-after-cd/mutation/side-effect allowlists, ownerRepoNoOpSites, getConfigForDirSites - all bidirectionally machine-locked already (the ...AreUsed / ...PinnedSites pattern). endpointSuggestions is machine-validated by suggestion_drift.go - the model the alias maps needed. Hook scripts' tool references: all name live tools (no reverse existence-guard exists; noted below). MASKING entries found: zero. **Fix landed:** alias_staleness_test.go adds the missing guards - source-liveness (would have forced the artifacts removal), target-resolution, domain-head liveness, override-prefix liveness, and the MCP-side mirror - each with a planted-violation subtest so a refactor cannot neuter it. One subtlety: liveness walks the cobra tree INCLUDING hidden commands (`madtea api` is hidden by design and its alias is live). **Flagged, not decided here:** (1) `packages` being plural while its command siblings are singular is a naming question, separate from the dead-alias removal; (2) madt_* names written inside hooks/*.sh have no existence guard (routing drift reads them as a corpus only) - same rot class one layer out, all currently live, low priority.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#303

No description provided.

Rows
Columns