A hook step must be cheap when there is nothing to do, and one was not

§9.1 said a hook is where a board-setup step belongs and never said what such a step
costs. It runs on every board on every update, so "already done" is the normal case and
the price is paid on every future release rather than once — and the hook phase gains a
step per feature while the budget does not move. The budgets, now written down: 600s for
pre-install, which is `UPDATE_MAX_SILENCE_SECONDS` and therefore a contract with every
client rather than a private figure, and 120s for post-install, shared with the units, the
accounts and the restart.

Three of the four scripts already obeyed this and said so one comment at a time.
`setup-npu.sh` stamps the runtime version and compares it; `setup-gstreamer.sh` compares a
stamp and two `dpkg -s`; `setup-npu.sh` also skips the whole overlay path when a driver is
already bound, so a re-run does not touch /boot at all. The corollary states the shape
those three arrived at independently.

`setup-rkaiq.sh` did not: it ran `gcc -shared -fPIC -O2` on every update, on every board,
for ever. It now keeps the built source at /usr/local/lib/rkaiq-modinfo-shim.c the way
`setup-npu.sh` keeps its `.dts`, and rebuilds when that copy no longer matches — so a
release that changes the C file still gets a new shim, and one that does not pays a `cmp`.

**Keyed on the source and not on the kernel, which the shim's own header argued against.**
It said the object is built on the board because "the struct size it probes for is a
property of the running kernel, so a binary built anywhere else would be guessing". The
size is a property of the running kernel, but `probe_kernel_req` brute-forces it at
*runtime* on the first intercepted ioctl and caches it in a static; the includes are
libc's. The object is aarch64 and nothing more. Corrected there, because that sentence is
exactly what stops the next person adding this gate.

The python pass over the IQ file stays unconditional. It is one interpreter start against
a file that is already correct, it prints which of the two cases it found, and gating it
would cost more in machinery than it saves.

Assisted-by: Claude:claude-opus-5

docs/design/updater-design.md

@@ -928,6 +928,17 @@ are not a precedent; they are three instances.
   a fresh install does. It is a forcing function rather than a proof — the escape hatch is a line
   in a table — but all four instances would have had to argue for that line, and none of them
   could have.
+- **A hook step must be idempotent, and it must be cheap when there is nothing to do.** The
+  first because it runs on every board on every update rather than once, so "already done" is the
+  normal case and not the exception. The second because the cost is paid on every update for
+  ever: a step that takes ten seconds on a board that already has everything is ten seconds added
+  to every future release, and the hook phase grows by one step per feature while the budget does
+  not move. The budgets are 600s for pre-install (`UPDATE_MAX_SILENCE_SECONDS`, a contract with
+  every client — it is the longest an apply may go silent) and 120s for post-install, shared with
+  the units, the accounts and the restart. The shape that works is a stamp: `setup-npu.sh` writes
+  the runtime version to `/usr/lib/librknnrt.version` and compares it, `setup-gstreamer.sh`
+  compares a stamp and two `dpkg -s` calls, and both do nothing measurable on a board that is
+  already set up.
 - **A script the hook runs must be packaged.** `every_script_the_hooks_run_is_packaged`
   reads `script=scripts/…` assignments out of both hooks and fails the build if any
   packaging site omits one.

scripts/rkaiq-modinfo-shim.c

@@ -16,9 +16,12 @@
  * reads for IQ file selection.
  *
  * Build:   gcc -shared -fPIC -O2 -o rkaiq_modinfo_shim.so rkaiq-modinfo-shim.c -ldl
- * Install: see scripts/setup-rkaiq.sh, which builds it on the board — the
- *          struct size it probes for is a property of the running kernel, so a
- *          binary built anywhere else would be guessing. The systemd drop-in
+ * Install: see scripts/setup-rkaiq.sh, which builds it on the board because it
+ *          must be aarch64 — and for no other reason. The struct size is a
+ *          property of the running kernel, but this probes for it at *runtime*
+ *          on the first intercepted ioctl, so the object does not depend on the
+ *          kernel it was compiled against and setup-rkaiq.sh only rebuilds it
+ *          when the source changes. The systemd drop-in
  *          sets LD_PRELOAD for the rkaiq_3A service alone; nothing else on the
  *          board has this ioctl intercepted.
  *

scripts/setup-rkaiq.sh

@@ -201,9 +201,25 @@ if ! command -v gcc >/dev/null 2>&1; then
         || die "could not install gcc, so the shim cannot be built"
 fi
 
-say "building the ioctl shim"
-gcc -shared -fPIC -O2 -o "$SHIM_SO" "$SHIM_SRC" -ldl \
-    || die "could not build ${SHIM_SRC}"
+# Only when there is something to build. `hooks/preinstall` runs this script on every update, so
+# an unconditional `gcc` is a compile on every release for ever on a board that already has the
+# shim — the cost updater-design.md §9.1 says a hook step may not have. The built source is kept
+# beside the object, the way `setup-npu.sh` keeps its `.dts`, and a release that changes the C
+# file rebuilds because the copy no longer matches.
+#
+# Keyed on the source alone, and not on `uname -r`, because the shim does not depend on the
+# kernel it was built against: it brute-forces the kernel's struct size at *runtime*, once, on
+# the first intercepted ioctl. It is built on the board because it must be aarch64, which is the
+# only reason.
+SHIM_BUILT_SRC=/usr/local/lib/rkaiq-modinfo-shim.c
+if [ -f "$SHIM_SO" ] && cmp -s "$SHIM_SRC" "$SHIM_BUILT_SRC"; then
+    say "the ioctl shim is current"
+else
+    say "building the ioctl shim"
+    gcc -shared -fPIC -O2 -o "$SHIM_SO" "$SHIM_SRC" -ldl \
+        || die "could not build ${SHIM_SRC}"
+    install -m 644 "$SHIM_SRC" "$SHIM_BUILT_SRC"
+fi
 
 # ── the sensor-mode pin ───────────────────────────────────────────────────────
 #