fix(build): close real local-build gaps found in a hands-on build/run audit #154

2026-08-15T22:55:00Z

will.anderson commented

2026-08-15 22:55:00 +00:00

Summary

Hands-on local-build/run audit, done in an isolated worktree
(.worktrees/build-audit, off origin/main). Every claim below is backed by
a real command + real output; full evidence trail is in Neuron memory
(tags neuron-technologies/neuron,build-audit).

1. dist/soul.c was stale — 11 commits / 459 lines behind chat.el,
missing PR #122 (OpenAI tools + agentic loop, incl. two "silently break
chat" fixes). tools/soulc-stamp.sh --check confirmed it;
tools/build-soul-from-dist.sh correctly refused to build (exit 9).
Regenerated + re-stamped. No runnable regen script existed anywhere
upstream (AGENTS.md only said "elb/elc compile the sources," vaguely, and
wasn't even committed — see below). Added tools/regenerate-soul-amalgam.sh,
verified to reproduce the real amalgam's exact symbol set (byte-identical
content, modulo the 5 genuinely new PR #122 functions). Root-caused and
documented (in AGENTS.md) three real elc/elb toolchain gotchas hit
along the way — stale .elh caches silently truncating the build to as
little as 251 of 2541 real functions with exit code 0; elb cannot produce
this repo's single-TU amalgam at all; elc silently drops the first 1-2
top-level functions after any comment block when compiling a flat
concatenated file.

2. The build script didn't actually build on macOS —
tools/build-soul-from-dist.sh was missing -lssl -lcrypto entirely
(drifted from CI's own recipe) and failed to link
(ld: library 'ssl' not found, Homebrew's openssl@3 is keg-only). Fixed
to match CI's link line and auto-detect the Homebrew lib path on Darwin.
Verified: dist/neuron now builds clean and boots on a throwaway port with
a scratch HOME, answers /health — never touched live :7770/:8742.

3. Committed .elh compiler-header caches were actively harmful —
elc/elb prefer a stale cached header over recompiling its source,
silently, with no error. This is what caused the under-resolved amalgam
above, more than once, before the cause was isolated. Removed from git,
gitignored going forward.

4. AGENTS.md/README.md existed only on disk, never committed — and
documented the pre-collapse ~90-tool MCP surface as current. Committed
corrected versions: live 9-op surface (read/write/relate/supersede/ think/attend/assert/ground/learn, merged in #153), the audit-verified
build recipe, and confirmed port topology.

5. Port :7771 is a live three-way collision — axon (unbuilt Rust,
already known/out of scope), neuron-connectd (the MCP-connector sidecar
routes.el/chat.el call right now on every boot/agentic turn, per a real
detailed spec that was never implemented), and council (the anti-
confabulation service actually bound to :7771 in prod, which live-answers
both other things' requests with unrelated 404s — worse than a clean
connection-refused). Added connectd/ — a minimal local-dev stub
implementing just the documented contract as "zero connectors configured,"
for local correctness only. Does not attempt OAuth/a real MCP client —
that's a real, separate product decision. See connectd/README.md.

Test plan

tools/soulc-stamp.sh --check passes against the regenerated amalgam
bash tools/build-soul-from-dist.sh dist/neuron succeeds clean on macOS
Regenerated binary boots on throwaway port + scratch HOME, answers /health
connectd/connectd_service.py tested standalone on a throwaway port against the documented /mcp/tools, /mcp/servers, /mcp/call, /healthz contract
No live :7770/:8742 process touched at any point
Reviewer: confirm the :7771 collision resolution (moving council, or repointing connectd) before wiring the stub into any LaunchAgent — not done here, flagged as a decision for Will

Not done here (out of scope / needs a decision)

axon (Rust) itself — unbuilt, independently known, no source to build against
The real neuron-connectd sidecar (OAuth + MCP SDK client) — the stub only covers local-build/run correctness
Resolving the live :7771 port collision (touches a running production LaunchAgent)
dist/ still has ~13 untracked backup binaries (neuron.bak-*, neuron.pre-*, ~38MB) in the original checkout — noted, not touched (low priority, pre-existing clutter)

## Summary Hands-on local-build/run audit, done in an isolated worktree (`.worktrees/build-audit`, off `origin/main`). Every claim below is backed by a real command + real output; full evidence trail is in Neuron memory (tags `neuron-technologies/neuron,build-audit`). **1. `dist/soul.c` was stale** — 11 commits / 459 lines behind `chat.el`, missing PR #122 (OpenAI tools + agentic loop, incl. two "silently break chat" fixes). `tools/soulc-stamp.sh --check` confirmed it; `tools/build-soul-from-dist.sh` correctly refused to build (exit 9). Regenerated + re-stamped. No runnable regen script existed anywhere upstream (AGENTS.md only said "elb/elc compile the sources," vaguely, and wasn't even committed — see below). Added `tools/regenerate-soul-amalgam.sh`, verified to reproduce the real amalgam's exact symbol set (byte-identical content, modulo the 5 genuinely new PR #122 functions). Root-caused and documented (in `AGENTS.md`) three real `elc`/`elb` toolchain gotchas hit along the way — stale `.elh` caches silently truncating the build to as little as 251 of 2541 real functions with exit code 0; `elb` cannot produce this repo's single-TU amalgam at all; `elc` silently drops the first 1-2 top-level functions after any comment block when compiling a flat concatenated file. **2. The build script didn't actually build on macOS** — `tools/build-soul-from-dist.sh` was missing `-lssl -lcrypto` entirely (drifted from CI's own recipe) and failed to link (`ld: library 'ssl' not found`, Homebrew's `openssl@3` is keg-only). Fixed to match CI's link line and auto-detect the Homebrew lib path on Darwin. Verified: `dist/neuron` now builds clean and boots on a throwaway port with a scratch `HOME`, answers `/health` — never touched live `:7770`/`:8742`. **3. Committed `.elh` compiler-header caches were actively harmful** — `elc`/`elb` prefer a stale cached header over recompiling its source, *silently*, with no error. This is what caused the under-resolved amalgam above, more than once, before the cause was isolated. Removed from git, gitignored going forward. **4. `AGENTS.md`/`README.md` existed only on disk, never committed** — and documented the pre-collapse ~90-tool MCP surface as current. Committed corrected versions: live 9-op surface (`read/write/relate/supersede/ think/attend/assert/ground/learn`, merged in #153), the audit-verified build recipe, and confirmed port topology. **5. Port `:7771` is a live three-way collision** — `axon` (unbuilt Rust, already known/out of scope), `neuron-connectd` (the MCP-connector sidecar `routes.el`/`chat.el` call right now on every boot/agentic turn, per a real detailed spec that was never implemented), and `council` (the anti- confabulation service actually bound to `:7771` in prod, which live-answers both other things' requests with unrelated 404s — worse than a clean connection-refused). Added `connectd/` — a minimal local-dev stub implementing just the documented contract as "zero connectors configured," for local correctness only. Does not attempt OAuth/a real MCP client — that's a real, separate product decision. See `connectd/README.md`. ## Test plan - [x] `tools/soulc-stamp.sh --check` passes against the regenerated amalgam - [x] `bash tools/build-soul-from-dist.sh dist/neuron` succeeds clean on macOS - [x] Regenerated binary boots on throwaway port + scratch `HOME`, answers `/health` - [x] `connectd/connectd_service.py` tested standalone on a throwaway port against the documented `/mcp/tools`, `/mcp/servers`, `/mcp/call`, `/healthz` contract - [x] No live `:7770`/`:8742` process touched at any point - [ ] Reviewer: confirm the `:7771` collision resolution (moving council, or repointing connectd) before wiring the stub into any LaunchAgent — not done here, flagged as a decision for Will ## Not done here (out of scope / needs a decision) - `axon` (Rust) itself — unbuilt, independently known, no source to build against - The real `neuron-connectd` sidecar (OAuth + MCP SDK client) — the stub only covers local-build/run correctness - Resolving the live `:7771` port collision (touches a running production LaunchAgent) - `dist/` still has ~13 untracked backup binaries (`neuron.bak-*`, `neuron.pre-*`, ~38MB) in the original checkout — noted, not touched (low priority, pre-existing clutter)

will.anderson added 1 commit 2026-08-15 22:55:01 +00:00

fix(build): close real local-build gaps found in a hands-on build/run audit

Neuron Soul CI / build (pull_request) Successful in 3m42s

Details

Neuron Soul CI / deploy (pull_request) Has been skipped

Details

5bd9fbe9cd

Three verified, currently-live problems, each closed with real evidence
(full trace kept in Neuron memory, tags neuron-technologies/neuron,build-audit):

1. dist/soul.c was stale relative to main's own chat.el (11 commits / 459
   lines behind, missing PR #122's OpenAI-tools + agentic-loop work and its
   two "silently break chat" fixes). tools/soulc-stamp.sh --check confirmed
   it; tools/build-soul-from-dist.sh correctly refused to build (exit 9).
   Regenerated and re-stamped. No runnable regen script existed anywhere
   upstream — added tools/regenerate-soul-amalgam.sh, which reproduces the
   committed amalgam's exact symbol set (byte-for-byte content match, modulo
   the genuinely new PR #122 functions) and is documented end-to-end in
   AGENTS.md, including three real elc/elb toolchain gotchas found and
   root-caused along the way (stale .elh caches silently truncating builds;
   elb cannot produce this repo's single-TU amalgam; elc silently drops the
   first function(s) after a comment block in a flat-concatenated compile).

2. tools/build-soul-from-dist.sh failed to link on macOS (`ld: library 'ssl'
   not found` — Homebrew's openssl@3 is keg-only) and was missing -lssl
   -lcrypto entirely, drifted from CI's own working recipe. Fixed: adds
   -L$(brew --prefix openssl@3)/lib on Darwin, matches CI's link line.
   Verified: dist/neuron now builds and boots clean on a throwaway
   port/HOME (never touched the live :7770/:8742).

3. Untracked committed *.elh compiler-header caches (elc/elb prefer a stale
   cached header over recompiling its source, silently, with no error —
   this is what caused an under-resolved 251-2541-function amalgam multiple
   times during this audit before the cause was found). Removed from git,
   gitignored going forward.

Also: AGENTS.md and README.md existed on disk but were never committed
(git log on both returned nothing) and documented the pre-collapse ~90-tool
MCP surface as current. Committed corrected versions reflecting the live
9-op surface (read/write/relate/supersede/think/attend/assert/ground/learn,
merged in #153) and the audit-verified build recipe/port topology.

Added connectd/ — a minimal local-dev stub for the neuron-connectd MCP
sidecar. routes.el/chat.el call 127.0.0.1:7771 for it right now on every
soul boot and agentic turn per a real, detailed 2026-06-13 spec
(mcp-connectors-adoption-spec.md); the sidecar itself was never built.
Meanwhile :7771 is a live three-way collision (axon's unbuilt-Rust default,
this connectd contract, and council — the anti-confabulation service
actually running there in prod, which live-answers both other things'
requests with unrelated 404s instead of a clean bridge-down signal). This
stub only implements the documented contract as "zero connectors
configured" for local-dev correctness; it does not attempt OAuth or a real
MCP client — that is a real, separate product decision. See
connectd/README.md for the full trace and the open question left for Will.

will.anderson referenced this pull request

2026-08-15 23:40:47 +00:00

Self-load fix: relevance-ranked graph projection + architecture docs (clean re-merge) #155

will.anderson referenced this pull request

2026-08-15 23:46:11 +00:00

routes: @route dispatch conversion + latent Bool/String crash fixes (clean re-merge) #157

will.anderson referenced this pull request

2026-08-15 23:51:16 +00:00

fix(build): close real local-build gaps from the hands-on build/run audit (clean re-merge) #158

will.anderson closed this pull request

2026-08-15 23:51:46 +00:00