will.anderson
e610a412b9
dist/soul.c: regenerated amalgamation (1.15MB) from the reconciled sources via the hide-.elh + elc --target=c recipe, so the shipped translation unit CI compiles now actually carries every landed fix — genesis-boot SIGSEGV (#150), safety-contact 988 truncation (#96), url-decode multi-word search, honest receipts (#100/#101), immutability arc (#83), and the bounded payloads (#103). verify-soul-contract.sh, two non-weakening fixes (both false-NEGATIVE bugs that spuriously failed a CORRECT soul; neither relaxes what fails a defective one): 1. #199 by-id gate: verify tombstone/KEPT via /api/neuron/graph?id=<id>&depth=1 (a compact neighborhood) instead of grepping engram_scan_nodes_json(9999,0) — a multi-MB, salience-ordered, 9999-capped whole-graph dump in which the salience-0.01 tombstone marker sorts past the cap and vanished. 2. Isolation: pin SOUL_ISE_URL to the dead axon port. Unsetting ENGRAM_URL was not enough — the periodic engram sync defaults its source to the LIVE engram (http://localhost:8742), so the 'isolated' gate pulled the operator's real brain (56 -> 12k nodes in seconds), which both broke Section B determinism and read live state. Now the soul stays on its own store. Verified GREEN on a throwaway port/HOME (live :7770/:8742/~/.neuron untouched): gate PASS x3 (presence 27/27, immutability all 5 KEPT); safety-contact POST 218B / GET 208B full untruncated; multi-word search (%20 and +) returns ranked hits with an all-gibberish control at 0; bounded session/begin 1370B; honest ok:false on a missing-id delete; genesis (ntn-genesis) boots clean through mem_save with no SIGSEGV.
262 lines
13 KiB
Bash
Executable File
262 lines
13 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# verify-soul-contract.sh — the soul contract gate.
|
|
#
|
|
# TERMINOLOGY (canonical): the ENGRAM is the brain — the memory/knowledge-graph
|
|
# substrate. The binary this gate exercises is the SOUL — the runtime/reasoning
|
|
# engine compiled from dist/soul.c that serves the /api/ surface. The app
|
|
# (neuron-ui) bundles the soul binary at resources/<platform>/neuron.
|
|
#
|
|
# WHY THIS EXISTS
|
|
# For a while the soul binary was hand-dropped, and a stale one shipped: it
|
|
# 404'd several capability routes the app calls (knowledge-graph node
|
|
# update/delete, live-run narration, safety-contact, ...). This gate makes
|
|
# shipping a stale soul IMPOSSIBLE. It has two enforced sections:
|
|
# A. PRESENCE — every route the app calls must be ANSWERED (not 404, not
|
|
# the el-runtime "no handler"). This is the packaging gate:
|
|
# if it fails, do not package.
|
|
# B. IMMUTABILITY — engram nodes/memories are immutable by design. To
|
|
# "update" is to create a NEW node + a supersede EDGE back to
|
|
# the original; the original is KEPT. To "delete" is to
|
|
# supersede/tombstone, never hard-remove. A soul that
|
|
# hard-deletes an engram node is DEFECTIVE and fails the gate.
|
|
#
|
|
# SAFETY
|
|
# Never touches the live soul (:7770), live engram (:8742), or ~/.neuron.
|
|
# Boots on a throwaway port (default 7799) with HOME=$(mktemp -d), a throwaway
|
|
# engram snapshot, a non-genesis cgi id, no ENGRAM_URL (so it uses its own
|
|
# in-process store, never the live server), NEURON_API_URL pointed at a dead
|
|
# port, and no ANTHROPIC_API_KEY (so no probe triggers a real LLM call).
|
|
# Connectors proxy to a HARDCODED 127.0.0.1:7771 (no env override): those
|
|
# sub-routes are probed with GET, which the soul maps to a read-only
|
|
# connectd_get, so this gate never writes to a running connectd bridge.
|
|
#
|
|
# USAGE
|
|
# scripts/verify-soul-contract.sh <path-to-soul-binary> [port]
|
|
# exit 0 = all required routes answered AND no destructive engram mutation;
|
|
# non-zero = a route is missing (presence) or a mutation route hard-deletes.
|
|
set -uo pipefail
|
|
|
|
SOUL="${1:?usage: verify-soul-contract.sh <soul-binary> [port]}"
|
|
PORT="${2:-7799}"
|
|
|
|
if [ "$PORT" = "7770" ] || [ "$PORT" = "8742" ] || [ "$PORT" = "7771" ]; then
|
|
echo "REFUSING: port $PORT is a live service port. Use a throwaway port." >&2
|
|
exit 2
|
|
fi
|
|
if [ ! -x "$SOUL" ]; then echo "not executable: $SOUL" >&2; exit 2; fi
|
|
|
|
BASE="http://127.0.0.1:$PORT"
|
|
THROW_HOME="$(mktemp -d "${TMPDIR:-/tmp}/soul-contract-home.XXXXXX")"
|
|
SOUL_LOG="$(mktemp "${TMPDIR:-/tmp}/soul-contract-log.XXXXXX")"
|
|
SOUL_PID=""
|
|
cleanup() {
|
|
[ -n "$SOUL_PID" ] && kill "$SOUL_PID" 2>/dev/null
|
|
[ -n "$SOUL_PID" ] && { sleep 0.3; kill -9 "$SOUL_PID" 2>/dev/null; }
|
|
rm -rf "$THROW_HOME" "$SOUL_LOG"
|
|
}
|
|
trap cleanup EXIT INT TERM
|
|
|
|
# =============================================================================
|
|
# THE CONTRACT — routes the app (neuron-ui/src/main/kotlin/ai/neuron/ui/*.kt)
|
|
# calls against the soul ($SOUL). Format: "METHOD PATH".
|
|
#
|
|
# EXCLUDED and why:
|
|
# /api/auth, /api/auth/status, /api/dispatch, /api/tasks
|
|
# -> served by the APP's own DispatchServer.kt (localhost:8080), not the
|
|
# soul. Not soul routes.
|
|
# /api/tags
|
|
# -> not handled by any soul .el (app-side/other). Pre-verified excluded.
|
|
# /api/neuron/, /api/neuron/node/, /api/connectors/ (bare prefixes)
|
|
# -> base-path string constants used to build the concrete routes below.
|
|
#
|
|
# KNOWN-PENDING (probed + reported, NON-blocking):
|
|
# POST /api/engram/import -> the app's "Restore memory" path. No soul handler
|
|
# yet, and the app hides Restore from shipped builds (B3, "lands in an
|
|
# update"). Reported so we see it; does not block packaging.
|
|
#
|
|
# Connectors sub-routes are listed as GET (see SAFETY note): handle_connectors is
|
|
# monolithic, so a GET reaching it proves the whole connectors surface without
|
|
# writing to the live bridge. Binary-strings cross-check confirms each POST
|
|
# sub-path literal is compiled in.
|
|
# =============================================================================
|
|
REQUIRED=(
|
|
"GET /api/graph/nodes"
|
|
"GET /api/graph/edges"
|
|
"POST /api/chat"
|
|
"GET /api/config"
|
|
"POST /api/see"
|
|
"GET /api/connectors"
|
|
"GET /api/connectors/add"
|
|
"GET /api/connectors/toggle"
|
|
"GET /api/connectors/auto-approve"
|
|
"GET /api/connectors/remove"
|
|
"GET /api/connectors/secret"
|
|
"GET /api/connectors/oauth/start"
|
|
"GET /api/connectors/call"
|
|
"POST /api/neuron/memory"
|
|
"POST /api/neuron/memory/update"
|
|
"POST /api/neuron/memory/delete"
|
|
"POST /api/neuron/node/create"
|
|
"POST /api/neuron/node/update"
|
|
"POST /api/neuron/node/delete"
|
|
"POST /api/neuron/knowledge/capture"
|
|
"POST /api/neuron/knowledge/evolve"
|
|
"POST /api/neuron/knowledge/promote"
|
|
"POST /api/neuron/processes/define"
|
|
"GET /api/run-progress/__contract_probe__"
|
|
"GET /api/safety-contact"
|
|
"POST /api/safety-contact"
|
|
"GET /api/sessions/__contract_probe__"
|
|
)
|
|
KNOWN_PENDING=(
|
|
"POST /api/engram/import"
|
|
)
|
|
|
|
# --- boot the soul -----------------------------------------------------------
|
|
# Preserve the ambient environment (PATH, LD_LIBRARY_PATH, TMPDIR) so the
|
|
# dynamically-linked soul finds its libs on any runner — using `env -i` here
|
|
# stripped the library path on the Linux CI runner and the soul never booted.
|
|
# Isolation is still guaranteed by UNSETTING the live-service vars (so it can
|
|
# never reach the real engram/axon or make an LLM call) and by pointing HOME +
|
|
# the snapshot at throwaway paths and the axon at a dead port.
|
|
#
|
|
# ISOLATION FIX (2026-08-03): unsetting ENGRAM_URL/SOUL_ENGRAM_URL is NOT enough.
|
|
# The periodic engram sync (awareness.el) resolves its source as
|
|
# env(SOUL_ISE_URL) -> state(soul_engram_url) -> DEFAULT http://localhost:8742
|
|
# so with those vars unset it silently pulls the LIVE engram (:8742) if that
|
|
# server is up — the throwaway graph ballooned 56 -> 12k live nodes within
|
|
# seconds, and the concurrent live-sync mutation both (a) broke test determinism
|
|
# (the low-salience tombstone marker fell past the 9999 scan cap) and (b) meant
|
|
# the "isolated" gate was reading the operator's live brain. Pin SOUL_ISE_URL to
|
|
# the dead axon port so the sync target is unreachable: the soul stays on its own
|
|
# in-process store, the gate is genuinely isolated, and Section B is deterministic.
|
|
echo "== booting soul: $SOUL on port $PORT (throwaway HOME=$THROW_HOME) =="
|
|
env \
|
|
-u ENGRAM_URL -u ENGRAM_API_KEY -u SOUL_ENGRAM_URL \
|
|
-u ANTHROPIC_API_KEY -u NEURON_LLM_API_KEY -u SOUL_IDENTITY \
|
|
HOME="$THROW_HOME" \
|
|
NEURON_PORT="$PORT" \
|
|
SOUL_CGI_ID="ntn-contract-$$" \
|
|
SOUL_ENGRAM_PATH="$THROW_HOME/throwaway-snapshot.json" \
|
|
NEURON_API_URL="http://127.0.0.1:9" \
|
|
SOUL_ISE_URL="http://127.0.0.1:9" \
|
|
SOUL_TICK_MS="3600000" SOUL_HEARTBEAT_MS="3600000" SOUL_REFRESH_MS="3600000" \
|
|
"$SOUL" >"$SOUL_LOG" 2>&1 &
|
|
SOUL_PID=$!
|
|
|
|
UP=0
|
|
for _ in $(seq 1 60); do
|
|
if ! kill -0 "$SOUL_PID" 2>/dev/null; then
|
|
echo "!! soul exited during boot. log tail:" >&2; tail -20 "$SOUL_LOG" >&2; exit 3
|
|
fi
|
|
RSS=$(ps -o rss= -p "$SOUL_PID" 2>/dev/null | tr -d ' ')
|
|
if [ -n "$RSS" ] && [ "$RSS" -gt $((3*1024*1024)) ]; then
|
|
echo "!! soul RSS >3GB — kill -9" >&2; kill -9 "$SOUL_PID" 2>/dev/null; exit 3
|
|
fi
|
|
[ "$(curl -s -o /dev/null -w '%{http_code}' -m 2 "$BASE/health" 2>/dev/null)" = "200" ] && { UP=1; break; }
|
|
sleep 0.5
|
|
done
|
|
[ "$UP" = 1 ] || { echo "!! soul never healthy on $BASE/health" >&2; tail -20 "$SOUL_LOG" >&2; exit 3; }
|
|
echo "== soul healthy =="; echo
|
|
|
|
# --- probing helpers ---------------------------------------------------------
|
|
# request METHOD PATH [BODY] -> prints response body (single line)
|
|
request() {
|
|
curl -s -m 12 -X "$1" -H 'Content-Type: application/json' --data "${3:-{}}" "$BASE$2" 2>/dev/null | tr -d '\n'
|
|
}
|
|
# is_missing BODY -> 0 if the body is a "route not present" signal
|
|
is_missing() {
|
|
printf '%s' "$1" | grep -qE '"error":"not found"|"code":"not_found"|no http handler registered|"code":"method_not_allowed"'
|
|
}
|
|
extract_id() { printf '%s' "$1" | grep -oE '"id":"[^"]+"' | head -1 | sed 's/.*"id":"//;s/"//'; }
|
|
# BY-ID immutability verification (#199 by-id gate).
|
|
# The prior check grepped /api/graph/nodes, i.e. engram_scan_nodes_json(9999,0):
|
|
# a whole-graph dump. On a genesis-seeded throwaway engram that list is both
|
|
# huge (multi-MB, full node content + embeddings) AND capped at 9999 nodes in
|
|
# salience order. The tombstone MARKER is written at salience 0.01, so it sorts
|
|
# dead last — and once the seeded graph approaches/exceeds the cap the marker
|
|
# falls off the end of the list entirely (or is lost to transport truncation on
|
|
# the ~10MB body). The normal-salience original still sorts early and survives,
|
|
# which is why a correctly-tombstoning soul false-reported "kept but no tombstone
|
|
# marker". Fix: verify BY ID via /api/neuron/graph?id=<id>&depth=1
|
|
# (engram_neighbors_json, direction "both"), a compact ~900B neighborhood that is
|
|
# independent of total graph size. The node itself proves KEPT; the incoming
|
|
# "tombstones" edge surfaces the "tombstone:<id>" marker. Pass/fail semantics are
|
|
# unchanged and strictly no weaker: a hard-delete leaves no by-id node (DESTROYED)
|
|
# and a no-op delete leaves no marker (NO-OP) — both still fail. Verified: a
|
|
# never-created id returns neither node nor marker.
|
|
node_present() { # id -> 0 if the node still resolves by-id (KEPT), non-zero if hard-removed
|
|
request GET "/api/neuron/graph?id=$1&depth=1" | grep -qF "\"$1\""
|
|
}
|
|
|
|
# --- SECTION A: presence -----------------------------------------------------
|
|
run_presence() {
|
|
local -n arr=$1; local fail=0
|
|
printf ' %-8s %-42s %s\n' "METHOD" "ROUTE" "RESULT"
|
|
for e in "${arr[@]}"; do
|
|
local m p body; m=$(awk '{print $1}' <<<"$e"); p=$(awk '{print $2}' <<<"$e")
|
|
body=$(request "$m" "$p")
|
|
if is_missing "$body"; then
|
|
printf ' %-8s %-42s MISSING %s\n' "$m" "$p" "$(cut -c1-46 <<<"$body")"; fail=$((fail+1))
|
|
else
|
|
printf ' %-8s %-42s ANSWERED %s\n' "$m" "$p" "$(cut -c1-46 <<<"$body")"
|
|
fi
|
|
done
|
|
return $fail
|
|
}
|
|
|
|
echo "== SECTION A: PRESENCE (required, blocking) =="
|
|
run_presence REQUIRED; A_FAIL=$?
|
|
echo
|
|
echo "== KNOWN-PENDING (non-blocking) =="
|
|
run_presence KNOWN_PENDING; P_FAIL=$?
|
|
echo
|
|
|
|
# --- SECTION B: immutability (engram write routes must supersede, not destroy) --
|
|
# For each mutation route: create a node, mutate it, then check the ORIGINAL id
|
|
# still exists in the graph. KEPT = supersede/tombstone (correct). DESTROYED =
|
|
# hard delete (DEFECTIVE -> fail). N/A = mutate route absent (a presence failure).
|
|
# For "delete" mutations we additionally require a real tombstone marker
|
|
# (label "tombstone:<id>") so a no-op delete cannot false-pass as KEPT.
|
|
marker_present() { # id -> 0 if a "tombstone:<id>" marker is wired to the node (by-id neighborhood)
|
|
request GET "/api/neuron/graph?id=$1&depth=1" | grep -qF "tombstone:$1"
|
|
}
|
|
immut_check() { # label KIND(update|delete) CREATE_PATH MUTATE_PATH
|
|
local label="$1" kind="$2" create="$3" mutate="$4"
|
|
local cbody id mb mbody
|
|
cbody=$(request POST "$create" "{\"content\":\"__immut_${label}__\",\"node_type\":\"Memory\",\"label\":\"contract:immut\"}")
|
|
id=$(extract_id "$cbody")
|
|
if [ -z "$id" ]; then printf ' %-14s SKELETON-FAIL create returned no id: %s\n' "$label" "$(cut -c1-40 <<<"$cbody")"; return 2; fi
|
|
mb="{\"id\":\"$id\"}"; [ "$kind" = update ] && mb="{\"id\":\"$id\",\"content\":\"__immut_${label}_v2__\"}"
|
|
mbody=$(request POST "$mutate" "$mb")
|
|
if is_missing "$mbody"; then printf ' %-14s N/A mutate route absent (see Section A)\n' "$label"; return 0; fi
|
|
if ! node_present "$id"; then
|
|
printf ' %-14s DESTROYED original %s hard-removed <== DEFECTIVE\n' "$label" "$id"; return 1
|
|
fi
|
|
if [ "$kind" = delete ] && ! marker_present "$id"; then
|
|
printf ' %-14s NO-OP original %s kept but no tombstone marker <== DEFECTIVE\n' "$label" "$id"; return 1
|
|
fi
|
|
local how="supersede edge"; [ "$kind" = delete ] && how="tombstoned + hidden from default list"
|
|
printf ' %-14s KEPT original %s survived (%s)\n' "$label" "$id" "$how"; return 0
|
|
}
|
|
|
|
echo "== SECTION B: IMMUTABILITY (engram nodes must be superseded, never destroyed) =="
|
|
B_FAIL=0
|
|
immut_check "memory-update" update /api/neuron/memory /api/neuron/memory/update || B_FAIL=$((B_FAIL+$?))
|
|
immut_check "memory-delete" delete /api/neuron/memory /api/neuron/memory/delete || B_FAIL=$((B_FAIL+$?))
|
|
immut_check "node-update" update /api/neuron/node/create /api/neuron/node/update || B_FAIL=$((B_FAIL+$?))
|
|
immut_check "node-delete" delete /api/neuron/node/create /api/neuron/node/delete || B_FAIL=$((B_FAIL+$?))
|
|
immut_check "memory-forget" delete /api/neuron/memory /api/neuron/memory/forget || B_FAIL=$((B_FAIL+$?))
|
|
echo
|
|
|
|
echo "============================================================"
|
|
RC=0
|
|
if [ "$A_FAIL" -gt 0 ]; then echo "PRESENCE: FAIL — $A_FAIL required route(s) unanswered. Do NOT package."; RC=1
|
|
else echo "PRESENCE: PASS — all ${#REQUIRED[@]} required routes answered."; fi
|
|
if [ "$B_FAIL" -gt 0 ]; then echo "IMMUTABILITY: FAIL — $B_FAIL engram write route(s) hard-delete. DEFECTIVE soul."; RC=1
|
|
else echo "IMMUTABILITY: PASS — no engram write route hard-deletes."; fi
|
|
[ "$P_FAIL" -gt 0 ] && echo "note: $P_FAIL known-pending route(s) unanswered (expected; non-blocking)."
|
|
echo "============================================================"
|
|
[ "$RC" = 0 ] && echo "GATE: PASS" || echo "GATE: FAIL"
|
|
exit $RC
|