fix(amd395): align Linux local model engines

[qinyue0508-cmd]

Summary

• unify native import, scan, resolver, and runtime handling for real root/bin/aima-engine + root/{lib,libexec,amdgcn} bundles
• reject imports unless the promoted binary passes --version, is scan-visible, resolver-visible, and version-valid
• persist/display detected_version and version_match; block unknown, mismatch, stale, and missing native binaries from deploy
• make explicit model_path override an opposite-format DB row in both BF16/safetensors and GGUF directions
• accept compatible llama.cpp revisions and use the AMD APU unified-memory pool for deployment admission

Final head and provenance

• PR head: a426526b2fa2f4f0281fa792f066dc7a12fd17f8
• Latest develop ancestor: d4de6c5b8dcf15ebb7ffc24ec5316547d770d79a
• Baiying-tested package: aima-linux-amd64-v0.5-dev-amd-strix-halo-a426526b2fa2
• Baiying-tested package binary SHA256: 9bb23bf7879f4dafc819d5aba5037bcfa93ee3862571763dbd2551eec8fc2ccf
• build-metadata.json.git_commit: a426526b2fa2f4f0281fa792f066dc7a12fd17f8
• Build time: 2026-08-11T03:45:00Z
• Merge state: no conflicts with develop

GitHub Actions artifact (a separate object from the Baiying-tested package binary):

• Name: aima-amd395-linux-a426526b2fa2
• Artifact ID: 9088025507
• AMD395 Linux Build run: 31455880915
• ZIP archive digest: sha256:c4dd5ad96114ce27adc4dc8ebf57604464e84bc3e1983b0005dd6921fbfebdd1
• Archive size: 26420253 bytes
• Head SHA: a426526b2fa2f4f0281fa792f066dc7a12fd17f8

The ZIP archive digest and tested binary SHA256 identify different objects. Build time is embedded, so independently produced exact-head binaries need not be byte-identical.

Automated validation

All passed on a426526b2fa2f4f0281fa792f066dc7a12fd17f8:

go test ./... -count=1
go vet ./...
go test -race ./internal/engine ./internal/knowledge ./internal/hal ./cmd/aima -count=1

CI on the same head:

AMD395 Linux Build  success  run 31455880915
First Run Smoke     success  run 31455883710

Baiying AMD395 final-head validation

Target: baiying-algorithm-public@192.168.120.178

Isolation:

test root:     /tmp/aima-pr106-a426-codex.1KX99H
AIMA_DATA_DIR: /tmp/aima-pr106-a426-codex.1KX99H/data-main
ports:        18190, 18191, 18192, 18193
negative-only ports: 18197, 18198

Artifact verification on the machine:

$ sha256sum aima-linux-amd64-v0.5-dev-amd-strix-halo-a426526b2fa2
9bb23bf7879f4dafc819d5aba5037bcfa93ee3862571763dbd2551eec8fc2ccf

$ aima version
aima v0.5-dev
build:  2026-08-11T03:45:00Z
commit: a426526b2fa2f4f0281fa792f066dc7a12fd17f8

HAL

$ AIMA_DATA_DIR=<isolated> aima hal detect
GPU: AMD Radeon 8060S Graphics
Architecture: RDNA3.5 / gfx1151
VRAM/unified pool: 98304 MiB
unified_memory: true
ROCm: 7.2.3
System RAM: 127940 MiB

Native bundle import, scan, resolver, and runtime

The source is a 371MB production bundle with bin, lib, libexec, and amdgcn.

$ AIMA_DATA_DIR=<isolated> aima engine import <native-1.5.1-bundle-root>
Engine imported from <native-1.5.1-bundle-root>

$ AIMA_DATA_DIR=<isolated> aima engine scan --runtime native
native_matches=1
binary_path=/tmp/aima-pr106-a426-codex.1KX99H/data-main/dist/linux-amd64/aima-engine-native-amd395/1.5.1/bin/aima-engine
catalog_version=1.5.1
detected_version=1.5.1
version_match=exact
available=true

engine list persisted the same nested binary, version evidence, lifecycle_status=verified, and verification_status=verified. engine info aima-engine-native-amd395 showed catalog and installed version 1.5.1.

After unset AIMA_ENGINE_DIR, resolver/deploy selected the dist binary:

.../dist/linux-amd64/aima-engine-native-amd395/1.5.1/bin/aima-engine
  serve --model-dir /home/baiying-algorithm-public/models/Qwen3.6-35B-A3B
  --host 127.0.0.1 --port 18190 --cache-capacity 9216 --context-tokens 8192

$ <dist-binary> --version
aima-engine-native 1.5.1-native

health: HTTP 200, model_loaded=true, resident=true
/v1/chat/completions: HTTP 200, content="AIMA-A426-NATIVE-OK"
deploy status: phase=running, ready=true, recovery_state=healthy

Single-file import of source bin/aima-engine discovered and copied its companion bundle. The imported result contained bin/lib/libexec/amdgcn, returned aima-engine-native 1.5.1-native, and scanned exact/available. It did not leave an unusable launcher.

Native version gate

Reviewer commit dc18f05 advanced the final-head catalog requirement from 1.5.0 to 1.5.1 after the earlier validation. Final-head evidence therefore uses 1.5.1 as exact and treats both older installations as unavailable:

1.5.0: catalog=1.5.1 detected=1.5.0 version_match=mismatch available=false
deploy exit 1: requires catalog version 1.5.1; detected 1.5.0 (mismatch)

1.4.1: catalog=1.5.1 detected=1.4.1 version_match=mismatch available=false
deploy exit 1: requires catalog version 1.5.1; detected 1.4.1 (mismatch)

1.5.1: catalog=1.5.1 detected=1.5.1 version_match=exact available=true

llama.cpp ROCm/HIP and UD-Q4 GGUF

Imported bundle: official-b9637

source version: 9637 (aedb2a5e9)
binary_path=/tmp/aima-pr106-a426-codex.1KX99H/data-gguf/dist/linux-amd64/llamacpp-hip-linux/9637/llama-server
detected_version=9637
catalog_version=b9330
version_match=compatible
available=true

With AIMA_ENGINE_DIR unset, deploy selected that dist binary and the UD-Q4 model:

.../llamacpp-hip-linux/9637/llama-server
  --model .../Qwen3.6-35B-A3B-UD-Q4_K_M.gguf
  --port 18191 --cache-ram 0 --ctx-size 8192 --n-gpu-layers 999 --parallel 1

ROCm0: AMD Radeon Graphics (98304 MiB, 124706 MiB free)
health: HTTP 200
/v1/chat/completions: HTTP 200, content="AIMA-A426-GGUF-OK"
system_fingerprint: b9637-aedb2a5e9
deploy status: phase=running, ready=true, recovery_state=healthy

Explicit model_path precedence

Both opposite-DB-format directions were scanned into the DB and actually deployed without forcing --engine:

DB row: GGUF
explicit model_path: BF16/safetensors directory
selected: dist aima-engine-native 1.5.1
result: HTTP health 200

DB row: safetensors/BF16
explicit model_path: UD-Q4 GGUF file
selected: dist llamacpp-hip-linux b9637
result: HTTP health 200

Cleanup

ports 18190/18191/18192/18193/18197/18198: no listeners
processes under /tmp/aima-pr106-a426-codex.1KX99H: none
available RAM after cleanup: 124862 MiB

@rjckkkkk please re-review final head a426526b2fa2f4f0281fa792f066dc7a12fd17f8. This evidence was regenerated after your dc18f05 and a426526 commits, using the same final head for the artifact, automated tests, CI, and Baiying hardware validation.

[rjckkkkk]

我在 Baiying AMD395 Ubuntu 测试机上对当前 head a17a1c3b162c19dd8c69ede1569975775e571edc 做了复验。当前不能批准，下面几项需要修复并在同一个新 head 上重新完成实机验证。

必须修改

1. 修复 native bundle 导入“成功但不可用”

   当前 head 的现场结果：

   • 单文件导入 .../bin/aima-engine 返回成功，扫描也显示 1 个 native engine，但 dist 中只有 706568-byte launcher；执行导入后的 aima-engine --version 退出 127，报 bundled ELF loader is missing。最新的 configured companion 查找仍覆盖不到真实 bundle 的 root/bin/aima-engine + root/{lib,libexec,amdgcn} 布局。
   • 按文档建议导入完整 371MB bundle 目录后，dist/bin/aima-engine --version 可以运行，但 aima engine scan --runtime native 返回 native_matches=0 和 []。扫描器只检查 dist 根目录且不递归，runtime/catalog 又只解析 bare aima-engine。
   • ImportEngine 丢弃导入后的 scan 结果，因此上述两种情况都会静默返回成功。

   请统一 import、scan、runtime 对 bundle root / nested binary 的解析规则。只有当导入后的 binary 可被扫描、可被 resolver 定位，并通过最小 --version smoke 时，import 才能返回成功。新增真实目录拓扑测试：root/bin/aima-engine、root/lib、root/libexec、root/amdgcn，不要只测 binary 与 so 同目录的简化 fixture。

2. 强制校验预装 native engine 必须是 catalog 声明的 1.5.0

   catalog/engines/aima-engine-native-amd395.yaml 声明 version: 1.5.0，但当前 scanner 只要 regex 捕获到任何版本就标记 version_match=exact，没有和 catalog version 比较；unknown/mismatch 仍然 available=true，入库时还丢弃 DetectedVersion/VersionMatch。测试机上同时存在 1.2.0、1.3.0、1.4.0、1.4.1 和 1.5.0，这会让旧版被当成 1.5.0 使用。

   请比较实际版本与 catalog 期望版本；unknown/mismatch 至少必须阻止 deploy，并持久化、展示 detected version 和 match 状态。

3. 显式 model_path 必须优先于扫描 DB 中的 format

   当前 resolveWithFallback 会先无条件应用同名 DB row 的 WithModelFormat。双格式模型中，如果 DB 记录的是 GGUF，而调用方显式传入 BF16/safetensors 路径，native variant 会在检查显式路径前被过滤；反向同理。请以显式路径识别出的格式为准，或在提供 model_path 时不要套用无关 DB row 的格式，并补两个方向的回归测试。

4. 先 rebase 最新 develop 并解决冲突

   PR 当前仍为 CONFLICTING / DIRTY，且包含 159 个文件、96 个 commits；需要在解决冲突后的最终 head 上重新验证，不能复用旧 SHA 的结果。

必须完成的测试机验证

请使用修复后的同一个最终 head SHA 构建 artifact，并把以下命令、关键输出、SHA256 和 build-metadata.json.git_commit 记录到 PR 描述或 evidence 文件：

1. 在 Baiying AMD395 上确认 HAL：Radeon 8060S / gfx1151 / 98304 MiB unified memory。
2. 使用隔离的 AIMA_DATA_DIR 和未占用端口，不影响已有服务。
3. 导入完整 native bundle，随后：
   • engine scan/list/info 能看到导入后的 nested binary；
   • detected version 为 1.5.0、match 为 exact；
   • unset AIMA_ENGINE_DIR 后 resolver/deploy 仍使用 dist 内导入的 binary；
   • --version、health 和一次 /v1/chat/completions 均成功。
4. 单文件导入必须满足二选一：导入后可独立运行，或在导入阶段以明确错误拒绝；不能返回 success 后留下不可运行 launcher。
5. 负向测试：分别扫描 1.4.1 和 1.5.0；1.4.1 必须 mismatch/unavailable 且不能 deploy，1.5.0 必须 exact/available。
6. 双格式验证：
   • safetensors/BF16 解析并实际运行在 aima-engine-native；
   • UD-Q4 GGUF 解析并实际运行在 llama.cpp ROCm/HIP；
   • 显式 model_path 覆盖 DB 中相反格式的两个方向都正确。
7. 运行并记录：
   • go test ./... -count=1
   • go vet ./...
   • go test -race ./internal/engine ./internal/knowledge ./internal/hal ./cmd/aima -count=1
8. 测试结束后清理临时进程和监听端口。

PR 描述目前仍写 Latest focused commit: 5011c98，原有 BF16/GGUF 实机结果不覆盖后续的 9319afa 和当前 a17a1c3 bundle/runtime 修改，请在最终 head 上重新给出完整证据。

[rjckkkkk]

我复查了当前最终 head ce93341979491eec481054f7cad6ea4599a2a648。代码层面的三组修复和新增回归覆盖方向正确，本地在该 SHA 上重新运行以下命令均通过：

• go test ./... -count=1
• go vet ./...
• go test -race ./internal/engine ./internal/knowledge ./internal/hal ./cmd/aima -count=1

当前仍不能批准或合并，原因如下。

1. 最终 head 尚未完成要求的 Baiying AMD395 实机验证

PR 描述明确写明 ce933419… 的硬件验证为 BLOCKED，且此前 review 中要求的 HAL、隔离数据目录与端口、完整 native bundle import/scan/list/info、unset AIMA_ENGINE_DIR 后 resolver/deploy、--version/health/chat、1.4.1 与 1.5.0 负正向、BF16 native、UD-Q4 llama.cpp ROCm/HIP、双向显式 model_path 覆盖，以及进程/端口清理均未在这个最终 SHA 上给出证据。旧 SHA 的结果不能替代最终 head。

我在 2026-08-11 UTC 重试 192.168.120.178:22 时，SSH banner 和密钥交换已经恢复，服务端允许 publickey/password；但当前评审环境中已有密钥未获授权，因此仍无法代为完成实机复测。请在同一个最终 head 上补齐此前列出的完整测试机证据后重新请求 review。

2. artifact SHA 证据不一致

PR 描述写的 Artifact SHA256 是 43d1504980b6bcfda7460c19530d47a99232089bbccad2df62d88776990d7586，但当前 GitHub Actions artifact aima-amd395-linux-ce9334197949 的 API digest 是 sha256:f9b8b4844712c7c9fbf52ce9b09ea1ea72f4bea043f7f40add17d9b5f8c57da5；下载后包内二进制及 checksums.txt 记录的 SHA256 是 de91e23fc5f2739de671dbc6637f69227bfac3069320f3ee6c916ceca1dc5406。build-metadata.json.git_commit 确实是 ce93341979491eec481054f7cad6ea4599a2a648。请明确每个 SHA 对应的对象并修正 PR 描述，确保测试机使用的正是可追溯到该 head 的这份 artifact。

两项 Actions 检查目前均通过，分支也与 develop 无冲突；但 CI 不能替代上述 AMD395 实机门槛。

[qinyue0508-cmd]

@rjckkkkk 已按上一轮 review 要求完成修复，并在同一个最终 head bb710b199b48557cb5f7db5c17f91d7095d83382 上重新完成 Baiying AMD395 实机验证。

PR 描述已更新完整证据：HAL、隔离 AIMA_DATA_DIR/端口、native 完整 bundle 与单文件导入、1.4.1 mismatch / 1.5.0 exact、unset AIMA_ENGINE_DIR 后 dist resolver/deploy、BF16 native 与 UD-Q4 llama.cpp ROCm/HIP、显式 model_path 双向覆盖、health/chat、artifact SHA 对象区分及清理结果。三个本地测试命令和 2/2 CI 也均通过。请基于当前最终 head 重新 review。

[rjckkkkk]

我重新 review 了当前 head a426526b2fa2f4f0281fa792f066dc7a12fd17f8。该 SHA 上两项 Actions 检查通过，本地重新运行以下命令也全部通过：

• go test ./... -count=1
• go vet ./...
• go test -race ./internal/engine ./internal/knowledge ./internal/hal ./cmd/aima -count=1

当前仍不能批准或合并，有两个阻塞项。

1. Baiying 实机证据不是当前最终 head

PR 描述和测试机证据锁定的是 bb710b199b48557cb5f7db5c17f91d7095d83382，但当前实际 head 已推进到 a426526b2fa2f4f0281fa792f066dc7a12fd17f8，中间新增：

• dc18f054：Catalog native engine 从 1.5.0 改为 1.5.1，新增 cache_capacity: 9216，关闭 warmup，并改变运行能力声明；
• a426526b：benchmark 的 temperature=0 行为修改。

这不是可由旧实测自动覆盖的无关重建。现有证据明确验证的是 1.5.0 exact/available 和 1.5.0 BF16 health/chat；在当前 Catalog 下，1.5.0 应变为 mismatch/unavailable，而且 1.5.1 的新启动参数与关闭 warmup 也尚未在硬件上验证。

当前 Actions artifact 是 aima-amd395-linux-a426526b2fa2，artifact API digest 为 sha256:c4dd5ad96114ce27adc4dc8ebf57604464e84bc3e1983b0005dd6921fbfebdd1，下载后二进制 SHA256 为 ebb1d454c7f1854f0aa741231fd8f95b0b38b7e25ff477544525d8394b60db5a，且 build-metadata.json.git_commit 为当前 head。PR 中记录的 Baiying-tested package 仍是 bb710b1 的不同二进制。

请在不再推进的最终 head 上，用对应 artifact 重新完成至少 1.5.1 import/scan/version gate、BF16 resolver/deploy、health/chat、新 cache_capacity 参数、GGUF 路径与清理验证，并更新所有 SHA 证据。

2. compatible llama.cpp import 无法完成文档声明的 ensure/deploy 生命周期

ImportNative 对 b9637 持久化的是：

• Version = 9637
• DetectedVersion = 9637
• CatalogVersion = b9330
• VersionMatch = compatible

但 internal/engine/lifecycle.go 的 installedVersionMatches 仍只做原始字符串精确比较。默认 engine.ensure llamacpp-hip-linux --apply 请求 Catalog 版本 b9330，因此不会复用并激活刚导入的 9637。

即使显式使用 --version 9637 激活，local overlay 会把 asset 版本改为 9637，而 validatedPreinstalledNativeBinary 仍要求 VersionMatch == exact；库存记录保持 compatible，部署会被拒绝。当前实测之所以能启动，是未激活的 dist binary 被 runtime 直接找到，绕过了文档要求的生命周期路径。

请统一 compatible 版本在 import、ensure、overlay 和 deploy gate 中的判定，并新增端到端回归：导入 b9637 → 默认或明确的 ensure apply → 激活该库存项 → deploy 必须选中同一 binary 并成功；不应依赖未激活 dist binary 的隐式发现。

[rjckkkkk]

Approved final head a426526. Both CI checks pass. The exact Actions artifact was verified and retested on Baiying AMD395 with isolated data/ports: native 1.5.1 directory and single-file import, 1.5.0 mismatch/deploy rejection, unset-AIMA_ENGINE_DIR dist deployment, BF16 and GGUF explicit-path precedence, llama.cpp HIP, AIMA proxy routing, deterministic benchmark temperature 0 (3/3 success), and complete process/port cleanup.

[qinyue0508-cmd]

更正上一条说明：在该说明发布后，@rjckkkkk 又提交了 dc18f05（native catalog 1.5.1）和 a426526，因此我没有复用 bb710b1 的硬件结果，而是基于最终合并 head a426526b2fa2f4f0281fa792f066dc7a12fd17f8 重新构建并完整跑了一遍 Baiying AMD395 验证。

PR 描述现已替换为 a426526 的最终证据：测试包 SHA256 9bb23bf7879f4dafc819d5aba5037bcfa93ee3862571763dbd2551eec8fc2ccf，metadata commit 与 head 一致；native 1.5.1 exact、1.5.0/1.4.1 mismatch 且禁止 deploy；native BF16、llama.cpp UD-Q4、双向显式 model_path、health/chat 均通过；三个本地命令及 2/2 CI 通过；隔离进程和端口已清理。PR 已由 reviewer 合并。