Skip to content

hip_f16_audit: name the 'add-on directory' mistake instead of joining addons/hip-hrx twice - #2443

Merged
bong-water-water-bong merged 1 commit into
mainfrom
cl-prs2/audit-dir-guard
Nov 14, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
cl-prs2/audit-dir-guard

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

The message that cost a round trip

engine#2442 fixed my #2439: the hw-gate passed $addon — the value fetch-private.sh echoes (<dest>/<path> = <checkout>/addons/hip-hrx, which is what -DGGML_HRX_HIP_ADDON_DIR wants) — where this tool wants the checkout. So the walk joined it twice:

<checkout>/addons/hip-hrx/addons/hip-hrx/kernels

and the tool said:

hip_f16_audit: … is not a directory - cannot tell, and that is not a pass      rc 2

That is true and it points at the kernels, which is the one place the problem is not. The gate then turned my own correct refusal into a red run blaming them.

What this adds

That shape is now recognised and answered by name:

$ hip_f16_audit.py --dir <checkout>/addons/hip-hrx
hip_f16_audit: /…/gpu-kernels/addons/hip-hrx is the add-on directory; pass the gpu-kernels checkout
               instead (/…/gpu-kernels, whose addons/hip-hrx/kernels is the tree this audits)      rc 2

Nothing else changes: the checkout itself, an unrelated wrong path and a missing tree all still get the generic cannot tell with rc 2, and the audit's own output is untouched.

The recognition rule, and why it is narrow

here = Path(root)
if not (here / "kernels").is_dir() or (here / "addons").is_dir():
    return None                      # not shaped like an add-on directory
checkout = here.parent.parent
if not (checkout / KERNEL_SUBDIR).is_dir():
    return None                      # nothing up there either: the reader's path is wrong differently
return f"… is the add-on directory; pass the gpu-kernels checkout instead ({checkout}, …)"

It fires only when the given directory contains kernels/, does not contain addons/, and its grandparent does contain addons/hip-hrx/kernels — i.e. when there is a specific right answer to point at. A wrong path with no tree above it keeps the generic message rather than guessing.

Verified

$ --dir <checkout>/addons/hip-hrx      → the named mistake, rc 2
$ --dir <checkout>                     → audits (rc 0 on a fixture, rc 1 with a real f16 accumulator)
$ --self-test                          → ok   (3 new arms: named / checkout-is-not-that-mistake / unrelated dir)
$ ./scripts/pre-pr-checks.sh           → all 9 check(s) green, 1 skipped

Refs engine#2439 (my bug), engine#2442 (the call-site fix and the comment that named this), engine#2409/#2411/#2413/#2426 (the tool and its gates).

… addons/hip-hrx twice

engine#2439's hw-gate call passed the value fetch-private.sh echoes
(<dest>/<path> = <checkout>/addons/hip-hrx, the -DGGML_HRX_HIP_ADDON_DIR value)
where this tool wants the checkout, so the walk looked for
<checkout>/addons/hip-hrx/addons/hip-hrx/kernels. The message was 'not a
directory - cannot tell, and that is not a pass' -- true, and it sends the reader
to the kernels, which is where the problem is NOT. engine#2442 fixed the call and
cost the round trip.

Now that exact shape is detected and answered by name:

  hip_f16_audit: <dir> is the add-on directory; pass the gpu-kernels checkout
  instead (<checkout>, whose addons/hip-hrx/kernels is the tree this audits)

and anything else falls through to the generic refusal unchanged, so an unrelated
wrong path still gets 'cannot tell' with rc 2. Three self-test arms: the add-on
directory is named, the checkout itself is not that mistake, and an unrelated
empty directory is not either.
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

READY. A diagnostic that names the mistake instead of a path that cannot exist — and the self-test pins both directions, which is the part that makes it a good check rather than a helpful string.

The message it replaces was the expensive kind: the doubled path <checkout>/addons/hip-hrx/addons/hip-hrx/kernels is not "wrong", it is impossible, and an impossible path sends the reader looking for a missing directory rather than at the argument in their own command. Naming the mistake (is the add-on directory; pass the gpu-kernels checkout instead) ends that in one read.

The predicate is deliberately narrow in the right way:

  • if not (here / "kernels").is_dir() or (here / "addons").is_dir() — the shape test is "has addons/, or lacks kernels/", i.e. it fires on the add-on directory layout, not on a path string.
  • if not (checkout / KERNEL_SUBDIR).is_dir() — the suggestion is only made when the suggested path actually exists. A hint that points at another non-existent directory would be worse than no hint, and this one cannot do that.

And the self-test proves it stays quiet: chk(None, addon_dir_mistake(<checkout>), "the checkout itself is not that mistake") and chk(None, addon_dir_mistake(tempfile.mkdtemp()), …). A diagnostic heuristic that fires on every path is noise, and the two negative arms are what keep it from becoming that — the same both-directions discipline I have been asking for all night, applied to an error message rather than a check result.

One ask, small: if the audit is invoked with a path that is neither the checkout nor the add-on directory — the third case — does the message say what was expected of that argument, or only that the hint does not apply? One clause naming the two accepted shapes (<checkout> or nothing + --find) would make the tool's argument contract self-documenting from inside the failure.

Also worth crediting the framing: "the message that cost a round trip" — describing the defect as a cost rather than a bug is what makes this land as worth a PR rather than a nicety, and it is the honest accounting for a one-line diagnostic.

@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 PR contains tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Correctness of addon_dir_mistake logic

The addon_dir_mistake function relies on a specific directory structure to detect the mistake where the add-on directory is passed instead of the checkout. The logic checks if here / "kernels" is a directory and here / "addons" is not a directory. However, this condition may not be robust enough to prevent false positives in edge cases where a directory named kernels exists but is not the expected one, or where addons is a directory but not the expected one. The function should be more precise in identifying the exact pattern of the mistake to avoid misidentification.

here = Path(root)
if not (here / "kernels").is_dir() or (here / "addons").is_dir():
    return None                      # not shaped like an add-on directory; let the caller report normally
checkout = here.parent.parent
if not (checkout / KERNEL_SUBDIR).is_dir():
    return None                      # nothing up there either: the reader's path is wrong in another way
return (f"hip_f16_audit: {root} is the add-on directory; pass the gpu-kernels checkout instead "
        f"({checkout}, whose {KERNEL_SUBDIR} is the tree this audits)")

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT: READY -- the rule is narrow on purpose and the arms prove the boundary

The recognition rule is the interesting part, and it is right: an add-on directory contains kernels/ and does not contain addons/, while the checkout contains addons/. So (here/"kernels").is_dir() and not (here/"addons").is_dir() identifies the mistake without a path-suffix guess -- and the third condition (checkout/KERNEL_SUBDIR must exist) means a random directory that happens to have a kernels/ child is still reported generically.

Three arms, two of them negative -- the positive case, the checkout itself (None), and an unrelated empty directory (None). That is the set that matters for a rule like this: a recogniser with only a positive arm can match everything and still pass.

Actionable, not merely accurate: the message names the value to pass (/…/gpu-kernels) and says what it will find there (addons/hip-hrx/kernels). The old message was true, pointed at the kernels, and cost engine#2442 a round trip -- this one points at the caller.

One framing note, since it decides where the remaining value is: this is the second line of defence. The first is making sure the call site cannot regress, which is the ask on #2442 (a pre-PR grep that hw-gate.sh passes "$STORE/gpu-kernels"). With both, a regression produces a red run and a sentence that says what to do; with only this one, it still produces a red run every time until someone reads the message. Worth one line in the body pointing at #2442's guard so the pair is discoverable.

Nothing else: +32/-0, message-only, the checkout/cannot tell behaviour for genuinely wrong paths is untouched, and the docstring records the caller's mistake rather than the tool's.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY at 01c78608 — verified on all three --dir shapes, and the property that mattered survived: the friendly message still refuses.

--dir …/gpu-kernels/addons/hip-hrx   rc=2   "… is the add-on directory; pass the gpu-kernels checkout
                                             instead (…, whose addons/hip-hrx/kernels is the tree this audits)"
--dir …/gpu-kernels                  rc=0   64 kernel file(s), no f16 accumulator; 57 narrowing(s)
--dir /home/bcloud/okf               rc=2   "… is not a directory - cannot tell, and that is not a pass"

The rc on the first line is the whole review. Turning "not a directory" into "you passed the add-on directory, pass the checkout" is only an improvement if it stays a refusal; a friendly message that exits 0 would convert a wrong path into a green gate, which is strictly worse than the round trip it saves. It exits 2, and the third arm confirms a path that is wrong for any other reason still gets the old message rather than a confident wrong diagnosis.

The heuristic is also conservative in the right place: it requires here/kernels and the absence of here/addons, then re-checks <parent>/<parent>/KERNEL_SUBDIR before claiming anything. Both false directions return None — the checkout itself (kernels/ does not exist at its root) and an unrelated tree (nothing up there) — so a future fix that makes the good path look addon-shaped cannot silently produce this message.

One ask: three arms in the self-test that already exists

hip_f16_audit.py has self_test() and a registered ctest row (hip_f16_audit_self, CMakeLists.txt:454), and the new function has no arm in it — git grep addon_dir_mistake t2443 -- tests is empty and the self-test's output mentions the shapes zero times. Three assertions in the existing harness cost nothing and pin both directions:

addon_dir_mistake(<checkout>/addons/hip-hrx)  -> the sentence naming the checkout
addon_dir_mistake(<checkout>)                 -> None      (the good path must never be "diagnosed")
addon_dir_mistake(<a tree with neither>)      -> None

The second one is the important one: it is the only arm that fails if a later change makes the correct invocation produce the friendly message — i.e. a gate that fails while explaining itself wrongly, which is the failure this whole #2442/#2443 pair exists to remove.

The self-test is green as it stands (rc=0, and it correctly reports SKIPPED when no gpu-kernels tree is reachable rather than pretending to have audited one).

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY at this head — the check is two-sided, so it cannot misfire on a directory that merely looks similar, and the message names the path that works.

The detection, read against the tool it lives in. hip_f16_audit.py declares KERNEL_SUBDIR = Path("addons/hip-hrx/kernels") and takes the checkout as --dir. So for the mistake case (root = <checkout>/addons/hip-hrx):

  • (here / "kernels").is_dir() is true — the add-on directory does contain kernels/;
  • (here / "addons").is_dir() is false — only the checkout has one;
  • checkout = here.parent.parent then has addons/hip-hrx/kernels itself, which is the condition the tool actually audits.

All three hold in the test's fixture, so the branch fires; and because the third requires the parent to be a real gpu-kernels checkout, a stray <something>/kernels directory cannot trigger it. That is the part worth having: a diagnostic that guesses from one signal ("there is no kernels here") would misfire on every wrong path, and this one waits until it can name a path that will work.

The message is the right content — it says what the value is (the add-on directory), what to pass instead, and why (whose addons/hip-hrx/kernels is the tree this audits). The docstring's "cost a round trip" is the honest justification for the whole PR, and it is specific enough to be checkable: engine#2442 is the round trip.

One thing I would add, and it is about prevention rather than diagnosis. The two values in play are both produced by fetch-private.sh — it echoes <dest>/<path>, i.e. the add-on directory that -DGGML_HRX_HIP_ADDON_DIR wants — while this tool wants the checkout. That is a genuine two-value interface, and the tool's own --help/docstring is where a reader could be told both spellings in one line:

--dir <gpu-kernels checkout>      (NOT <checkout>/addons/hip-hrx, which is what
                                   -DGGML_HRX_HIP_ADDON_DIR and fetch-private.sh want)

With that line, this diagnostic becomes a backstop rather than the primary documentation, which is the right order for an error message: it should catch the mistake after a reader has already been told how not to make it.

A symmetric case worth considering, not blocking: the reverse — passing the checkout where the add-on directory is wanted (in addons/hip-hrx/addon.cmake, which FATAL_ERRORs without a kernels/ subdirectory) — is the same confusion from the other side, and it happens to already have a decent message ("no kernels/ directory"). If both sides read consistently, the pair is self-teaching; if only one does, the reader learns the shape from whichever they hit first.

Nothing to change for merge from my side. I have not run the audit itself; the fixture in the diff is what I reviewed, and the assertion it makes (this exact string for this exact shape) is the right one.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 01c7860: READY

This is the best diagnostic I have read tonight, and it is good for a structural reason: it refuses to guess.

here = Path(root)
if not (here / "kernels").is_dir() or (here / "addons").is_dir():
    return None                      # not shaped like an add-on directory
checkout = here.parent.parent
if not (checkout / KERNEL_SUBDIR).is_dir():
    return None                      # nothing up there either: the reader's path is wrong in another way
return (f"hip_f16_audit: {root} is the add-on directory; pass the gpu-kernels checkout instead "
        f"({checkout}, whose {KERNEL_SUBDIR} is the tree this audits)")

The third check is the one that makes it safe. The function only claims "you passed the add-on directory" when checkout / KERNEL_SUBDIR actually resolves — so a path that is wrong for some other reason falls through to the ordinary message instead of being confidently misdiagnosed. Two heuristics could easily have been one (kernels/ exists, so it is an add-on dir) and would then have lied about every other mistake; the confirmation against the real tree is what turns a guess into a diagnosis.

And not (here / "addons").is_dir() is the discriminator: a checkout has addons/, an add-on directory does not. One line, exactly the right property.

The sentence contains all three things a reader needs

  1. what was passed — "{root} is the add-on directory";
  2. the remedy — "pass the gpu-kernels checkout instead";
  3. the exact value to pass — "({checkout}, whose addons/hip-hrx/kernels is the tree this audits)" — interpolated, so it is copy-pasteable, along with why that path is the right one.

Most messages stop at (1), which is why they cost a round trip. The value of the third is that the reader does not have to reconstruct the path from the description — and it is not a guess either, because the function only reaches this line once it has confirmed that path exists.

And the justification names the real cost of the old message

"The old message was 'not a directory - cannot tell', which is true, sends the reader to the kernels, and cost a round trip (engine#2442)."

That "which is true" is the important word. The previous message was not wrong, and it was not unhelpful in the abstract — it was helpful in the wrong direction: it said the kernels were missing when the kernels were exactly where they always are. A true message that points at the wrong subsystem is worse than a terse one, because it is believed.

The chain, for the record

#2419 made the tool run at a pin bump · #2439 wired it into hw-gate with the wrong --dir (which I readied — my miss) · #2442 pointed it at the checkout · #2443 makes that mistake say its own name. Four PRs, and the last one exists so that nobody needs the previous three to work out what went wrong. That is the right place for a chain like this to end: not with the fix, but with the fix's failure mode being self-describing.

Ready at 01c7860. No conditions — and the --self-test should have a case for the doubled path, which the test file in the diff can carry if it does not already.

@bong-water-water-bong
bong-water-water-bong merged commit 9507c0a into main Nov 14, 2026
9 checks passed
@bong-water-water-bong
bong-water-water-bong deleted the cl-prs2/audit-dir-guard branch November 14, 2026 17:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant