feat: compile ladybug CGO with Zig, not gcc (#24)

API image is Go-only (compose target api). Python rebuild is profile
index. bin/cgo/zig pins Zig 0.14.1, liblbug, and tokenizers.

bin/brain/get.go

@@ -8,6 +8,7 @@
 //	./bin/brain/get.go <id> --json
 //
 // Needs CGO + libladybug. Python bin/kb/get is the CI fallback (no cgo).
+// CGO compiler is Zig (`eval "$(bin/cgo/zig env)"`), not gcc.
 // NOTE: never run `gofmt -w` on this file — it breaks the shebang.
 package main
 

bin/brain/search.go

@@ -7,7 +7,7 @@
 //	./bin/brain/search.go serve [port]
 //	./bin/brain/search.go --list-model
 //
-// Needs CGO + libladybug (CGO_CFLAGS/CGO_LDFLAGS). Prefer the wrapper
+// Needs CGO + libladybug via Zig (`eval "$(bin/cgo/zig env)"`), not gcc.
 // bin/kb/search which sets those and builds a binary for the embed daemon.
 // NOTE: never run `gofmt -w` on this file — it breaks the shebang.
 package main

bin/cgo/zc++

@@ -0,0 +1,23 @@
+#!/bin/sh
+# bin/cgo/zc++ — CGO CXX. Zig, not g++.
+set -eu
+ROOT="$(CDPATH= cd -- "$(dirname "$0")/../.." && pwd)"
+case "$(uname -m)" in
+  x86_64|amd64) TARGET=x86_64-linux-gnu ;;
+  aarch64|arm64) TARGET=aarch64-linux-gnu ;;
+  *)
+    echo "zc++: unsupported arch $(uname -m)" >&2
+    exit 2
+    ;;
+esac
+if [ -n "${ZIG:-}" ] && [ -x "$ZIG" ]; then
+  :
+elif [ -x "$ROOT/var/zig/zig" ]; then
+  ZIG="$ROOT/var/zig/zig"
+elif command -v zig >/dev/null 2>&1; then
+  ZIG="$(command -v zig)"
+else
+  echo "zc++: zig missing; run bin/cgo/zig first" >&2
+  exit 127
+fi
+exec "$ZIG" c++ -target "$TARGET" "$@"

bin/cgo/zcc

@@ -0,0 +1,24 @@
+#!/bin/sh
+# bin/cgo/zcc — CGO CC. Zig, not gcc.
+# Go invokes CC with many args; a wrapper avoids spaces in $CC.
+set -eu
+ROOT="$(CDPATH= cd -- "$(dirname "$0")/../.." && pwd)"
+case "$(uname -m)" in
+  x86_64|amd64) TARGET=x86_64-linux-gnu ;;
+  aarch64|arm64) TARGET=aarch64-linux-gnu ;;
+  *)
+    echo "zcc: unsupported arch $(uname -m)" >&2
+    exit 2
+    ;;
+esac
+if [ -n "${ZIG:-}" ] && [ -x "$ZIG" ]; then
+  :
+elif [ -x "$ROOT/var/zig/zig" ]; then
+  ZIG="$ROOT/var/zig/zig"
+elif command -v zig >/dev/null 2>&1; then
+  ZIG="$(command -v zig)"
+else
+  echo "zcc: zig missing; run bin/cgo/zig first" >&2
+  exit 127
+fi
+exec "$ZIG" cc -target "$TARGET" "$@"

bin/cgo/zig

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# bin/cgo/zig — CGO toolchain: zig cc (not gcc) + pinned liblbug + libtokenizers.
+#
+#   eval "$(bin/cgo/zig env)"     # export CC/CXX/CGO_*
+#   bin/cgo/zig go build ...      # ensure, then exec with env
+#   bin/cgo/zig ./bin/brain/search.go "query"
+#
+# Pins live in this file. Downloads land in var/ (gitignored).
+set -euo pipefail
+
+ROOT="$(CDPATH= cd -- "$(dirname "$0")/../.." && pwd)"
+ZIG_VERSION=0.14.1
+LBUG_VERSION=0.19.1
+TOKENIZERS_VERSION=1.27.0
+
+arch="$(uname -m)"
+case "$arch" in
+  x86_64|amd64)
+    ZIG_ARCH=x86_64
+    LBUG_ARCH=x86_64
+    TOK_ARCH=x86_64
+    ZIG_SHA=24aeeec8af16c381934a6cd7d95c807a8cb2cf7df9fa40d359aa884195c4716c
+    LBUG_SHA=ed263ae913f68cb0ddba0b98548b58edaac49929766d03bdaaa83be46c68847d
+    TOK_SHA=72556cdca798dd4ea7cdaba308e5f0d68a8cb93b67c96edf485b7a0edd7b07f4
+    ;;
+  aarch64|arm64)
+    ZIG_ARCH=aarch64
+    LBUG_ARCH=aarch64
+    TOK_ARCH=aarch64
+    ZIG_SHA=f7a654acc967864f7a050ddacfaa778c7504a0eca8d2b678839c21eea47c992b
+    LBUG_SHA=b07df2cd533c3976a2a3025866d6420a5f35514d0a822ecc4b2902d55b4725b7
+    TOK_SHA=e96545ad05930c26f51f63d932ee6d3bbd32bbed149e102c5290d587a2293067
+    ;;
+  *)
+    echo "bin/cgo/zig: unsupported arch $arch" >&2
+    exit 2
+    ;;
+esac
+
+CACHE="$ROOT/var/cache"
+LIB="$ROOT/lib-ladybug"
+ZIG_DIR="$ROOT/var/zig-dist"
+ZIG_BIN="$ROOT/var/zig/zig"
+
+sha256of() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    shasum -a 256 "$1" | awk '{print $1}'
+  fi
+}
+
+fetch() {
+  local url="$1" dest="$2" expect="$3"
+  if [ -f "$dest" ] && [ "$(sha256of "$dest")" = "$expect" ]; then
+    return 0
+  fi
+  mkdir -p "$(dirname "$dest")"
+  echo "fetch $url" >&2
+  curl -fsSL "$url" -o "$dest"
+  local got
+  got="$(sha256of "$dest")"
+  if [ "$got" != "$expect" ]; then
+    echo "checksum mismatch $dest: got $got want $expect" >&2
+    rm -f "$dest"
+    exit 1
+  fi
+}
+
+ensure_zig() {
+  if [ -n "${ZIG:-}" ] && [ -x "$ZIG" ]; then
+    return 0
+  fi
+  if [ -x "$ZIG_BIN" ]; then
+    export ZIG="$ZIG_BIN"
+    return 0
+  fi
+  if command -v zig >/dev/null 2>&1; then
+    export ZIG
+    ZIG="$(command -v zig)"
+    return 0
+  fi
+  local tar="$CACHE/zig-${ZIG_ARCH}-linux-${ZIG_VERSION}.tar.xz"
+  fetch "https://ziglang.org/download/${ZIG_VERSION}/zig-${ZIG_ARCH}-linux-${ZIG_VERSION}.tar.xz" \
+    "$tar" "$ZIG_SHA"
+  mkdir -p "$CACHE"
+  rm -rf "$ZIG_DIR"
+  tar -xJf "$tar" -C "$CACHE"
+  mv "$CACHE/zig-${ZIG_ARCH}-linux-${ZIG_VERSION}" "$ZIG_DIR"
+  mkdir -p "$ROOT/var/zig"
+  ln -sfn "$ZIG_DIR/zig" "$ZIG_BIN"
+  export ZIG="$ZIG_BIN"
+}
+
+ensure_libs() {
+  mkdir -p "$LIB"
+  if [ ! -f "$LIB/liblbug.so" ]; then
+    local tar="$CACHE/liblbug-linux-${LBUG_ARCH}.tar.gz"
+    fetch "https://github.com/LadybugDB/ladybug/releases/download/v${LBUG_VERSION}/liblbug-linux-${LBUG_ARCH}.tar.gz" \
+      "$tar" "$LBUG_SHA"
+    tar -xzf "$tar" -C "$LIB"
+  fi
+  if [ ! -f "$LIB/libtokenizers.a" ]; then
+    local tar="$CACHE/libtokenizers.linux-${TOK_ARCH}.tar.gz"
+    fetch "https://github.com/daulet/tokenizers/releases/download/v${TOKENIZERS_VERSION}/libtokenizers.linux-${TOK_ARCH}.tar.gz" \
+      "$tar" "$TOK_SHA"
+    tar -xzf "$tar" -C "$LIB"
+  fi
+}
+
+print_env() {
+  printf 'export ZIG=%q\n' "$ZIG"
+  printf 'export CC=%q\n' "$ROOT/bin/cgo/zcc"
+  printf 'export CXX=%q\n' "$ROOT/bin/cgo/zc++"
+  printf 'export CGO_ENABLED=1\n'
+  printf 'export CGO_CFLAGS=%q\n' "-I$LIB"
+  printf 'export CGO_LDFLAGS=%q\n' "-L$LIB -Wl,-rpath,${CGO_RPATH:-$LIB}"
+}
+
+ensure_zig
+ensure_libs
+
+cmd="${1:-env}"
+if [ "$cmd" = "env" ]; then
+  print_env
+  exit 0
+fi
+
+eval "$(print_env)"
+exec "$@"

bin/docker-entrypoint

@@ -1,13 +1,10 @@
 #!/usr/bin/env bash
 # bin/docker-entrypoint - run 2dph tools inside the container.
 #
-#   brain                 shell (default)
-#   brain search <q>      bin/brain/search.go
-#   brain index           bin/kb/index --with-mail
-#   brain watch <dir>     compiled /app/bin/watch (bin/brain/watch.go)
-#   brain serve           compiled /app/bin/serve (bin/brain/serve.go)
-#   brain extract         bin/facts/extract (docker×compose pairing)
-#   brain audit           bin/facts/audit
+# API image (Zig CGO binaries):
+#   serve | search | watch
+# Index image (Python write path, compose profile `index`):
+#   index | extract | audit | search (deprecated python wrapper)
 #
 # Usage comment starts at line 2 (self-describing convention).
 set -euo pipefail
@@ -15,13 +12,27 @@ set -euo pipefail
 CMD="${1:-shell}"
 shift || true
 
+if [ -x /usr/local/bin/brain-serve ]; then
+	case "$CMD" in
+		shell) exec bash ;;
+		serve) exec /usr/local/bin/brain-serve "$@" ;;
+		search) exec /usr/local/bin/brain-search "$@" ;;
+		watch) exec /usr/local/bin/brain-watch "$@" ;;
+		index)
+			echo "index is the Python sidecar: docker compose --profile index run --rm index" >&2
+			exit 2
+			;;
+		*) echo "unknown command: $CMD (api: serve|search|watch)" >&2; exit 2 ;;
+	esac
+fi
+
 case "$CMD" in
-  shell) exec bash ;;
-  search) exec "$KB_PY" /app/bin/kb/search "$@" ;;
-  index) exec "$KB_PY" /app/bin/kb/index --with-mail "$@" ;;
-  watch) exec /app/bin/watch "$@" ;;
-  serve) exec /app/bin/serve "$@" ;;
-  extract) exec "$KB_PY" /app/bin/facts/extract "$@" ;;
-  audit) exec "$KB_PY" /app/bin/facts/audit "$@" ;;
-  *) echo "unknown command: $CMD" >&2; exit 2 ;;
+	shell) exec bash ;;
+	search) exec "$KB_PY" /app/bin/kb/search "$@" ;;
+	index) exec "$KB_PY" /app/bin/kb/index --with-mail "$@" ;;
+	watch) exec /app/bin/watch "$@" ;;
+	serve) exec /app/bin/serve "$@" ;;
+	extract) exec "$KB_PY" /app/bin/facts/extract "$@" ;;
+	audit) exec "$KB_PY" /app/bin/facts/audit "$@" ;;
+	*) echo "unknown command: $CMD" >&2; exit 2 ;;
 esac

bin/kb/search

@@ -1,10 +1,9 @@
 #!/usr/bin/env bash
 # bin/kb/search — deprecated wrapper. Use bin/brain/search.go.
-# Sets CGO for ladybug, builds a binary (embed daemon needs a real executable),
-# then execs it. Prints one deprecation line.
+# CGO via Zig (bin/cgo/zig), not gcc. Builds a binary then execs it.
 set -euo pipefail
 
-ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+ROOT="$(CDPATH= cd -- "$(dirname "$0")/../.." && pwd)"
 BIN="$ROOT/var/bin/brain-search"
 SRC="$ROOT/internal/brain"
 CMD="$ROOT/bin/brain"
@@ -24,11 +23,10 @@ else
 fi
 
 if [ "$need_build" -eq 1 ]; then
-	echo "Building brain/search..." >&2
+	echo "Building brain/search (zig cc)..." >&2
 	(
 		cd "$ROOT" &&
-			CGO_CFLAGS="-I$ROOT/lib-ladybug" \
-			CGO_LDFLAGS="-L$ROOT/lib-ladybug -Wl,-rpath,$ROOT/lib-ladybug" \
+			eval "$("$ROOT/bin/cgo/zig" env)" &&
 			go build -tags system_ladybug -o "$BIN" ./bin/brain
 	) || exit 1
 fi

bin/tools/test_bin_layout.py

@@ -1,6 +1,7 @@
 """D14 layout: bin/{subject}/{method}.go, libs in internal/, one go.mod."""
 from __future__ import annotations
 
+import os
 import unittest
 from pathlib import Path
 
@@ -157,3 +158,21 @@ class BinLayoutTest(unittest.TestCase):
         for line in first.splitlines():
             if "go-git/go-git" in line:
                 self.assertNotIn("indirect", line)
+
+    def test_cgo_uses_zig_not_gcc(self) -> None:
+        for rel in ("bin/cgo/zig", "bin/cgo/zcc", "bin/cgo/zc++"):
+            p = ROOT / rel
+            self.assertTrue(p.is_file(), f"missing {rel}")
+            self.assertTrue(
+                os.access(p, os.X_OK),
+                f"{rel} must be executable",
+            )
+        zig = (ROOT / "bin" / "cgo" / "zig").read_text()
+        self.assertIn("zig cc", zig)
+        self.assertIn("0.14.1", zig)
+        zcc = (ROOT / "bin" / "cgo" / "zcc").read_text()
+        self.assertIn('exec "$ZIG" cc', zcc)
+        self.assertNotIn("command -v gcc", zcc)
+        search = (ROOT / "bin" / "kb" / "search").read_text()
+        self.assertIn("bin/cgo/zig", search)
+        self.assertNotIn("command -v gcc", search)

bin/tools/test_published_docs.py

@@ -89,6 +89,20 @@ class PublishedDocsTest(unittest.TestCase):
         self.assertFalse((ROOT / "skills" / "db-yaml").exists())
         self.assertTrue((ROOT / "skills" / "postgres" / "SKILL.md").is_file())
 
+    def test_cgo_zig_and_index_profile(self) -> None:
+        plan = (ROOT / "PLAN.md").read_text()
+        self.assertIn("D21", plan)
+        self.assertIn("zig cc", plan)
+        dockerfile = (ROOT / "Dockerfile").read_text()
+        self.assertIn("bin/cgo/zcc", dockerfile)
+        self.assertIn("FROM debian:bookworm-slim AS api", dockerfile)
+        self.assertIn("FROM python:3.12-slim AS index", dockerfile)
+        api = dockerfile[dockerfile.index("FROM debian:bookworm-slim AS api") :]
+        self.assertNotIn("pip install", api)
+        compose = (ROOT / "compose.yaml").read_text()
+        self.assertIn('profiles: ["index"]', compose)
+        self.assertIn("target: api", compose)
+
     def test_readme_search_escalates_web(self) -> None:
         text = (ROOT / "README.md").read_text()
         self.assertIn("--no-web", text)