will.anderson
f0454650a2
The gate booted the soul with `env -i`, which strips the ambient environment — including the library path the dynamically-linked soul needs on the GCE CI runner. The soul never came up there, so the gate failed the build (run 3384) even though the soul is correct (the gate passes locally against the exact published CI runtime). Switch to preserving the ambient env and instead UNSET only the live-service vars (ENGRAM_URL/API keys/ identity) while pointing HOME + snapshot at throwaway paths and axon at a dead port. Isolation is unchanged (verified: no touch of the live soul/engram); the soul now boots on the runner.
234 lines
11 KiB
Bash
Executable File
234 lines
11 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.
|
|
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_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/"//'; }
|
|
node_present() { # id -> 0 if id appears in /api/graph/nodes
|
|
request GET /api/graph/nodes | 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 exists (include_deleted view)
|
|
request GET "/api/graph/nodes?include_deleted=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
|