0.8.0-dev1: Thalamus — NatsEventBus + cluster + CI plumbing#1
Merged
Conversation
First sub-step of the brain-architecture refactor. Stands up the
typed event bus the rest of 0.8.0 will route every signal through.
Nothing USES the bus yet — that lands in 0.8.0-dev3 (first dual-write
poller) and 0.8.0-dev5 (full cutover). This commit puts the substrate
in place and verifies it against the same contract suite that already
covered InMemoryEventBus.
See docs/architecture/brain.md for the role of the thalamus and the
rationale for NATS specifically.
CODE
* netcortex/thalamus/ — new package.
* nats_bus.py — NatsEventBus implementing EventBus Protocol against
a real NATS server. NATS core pub/sub (not JetStream) because the
Protocol promises at-least-once-within-session, no replay — which
is exactly NATS core. JetStream is enabled at the SERVER level so
future durable consumers (0.9.0 episodic memory, stream bridge for
external agents) can opt in via extension methods without redeploy.
* Lifecycle: sync ctor (matches Callable[[], EventBus] factory
shape); lazy connect on first publish/subscribe; idempotent close()
that drains pending publishes before closing the socket.
* Wire format: JSON-encoded UTF-8 payloads; NATS headers (server
2.2+) for framing metadata. Malformed payloads surfaced as
{"_raw": ...} with a warning rather than crashing the consumer.
TESTS
* NatsEventBus registered in tests/contracts/conftest.py. The full
contract suite (publish/subscribe roundtrip, wildcard filtering,
no-replay, independent subscribers, invalid-subject rejection,
invalid-payload rejection, idempotent close) now runs against the
real NATS backend in addition to InMemoryEventBus.
* NATS_URL env-gated: when unset the parametrized NATS cases skip
(so devs without a local broker can still run the suite); when set
the same cases exercise the production code path. CI always sets it.
INFRASTRUCTURE
* deploy/helm/templates/{statefulset,service,configmap}-nats.yaml —
single-node JetStream-enabled NATS StatefulSet matching the
existing Redis/Neo4j pattern. Headless ClusterIP Service for
stable DNS; ConfigMap-driven nats.conf; PVC-backed
/data/jetstream. Liveness probes the listener; readiness asserts
JetStream subsystem is up.
* values.yaml — nats: block (enabled by default, 2.11-alpine, 2Gi
PVC, Redis-class resources). HA clustering explicitly deferred to
a later 0.8.x patch.
* _helpers.tpl — netcortex.natsUrl template consistent with
netcortex.{redisUrl,neo4jUri}.
* deployment-{web,worker}.yaml — NATS_URL env threaded into both
pods, gated on nats.enabled.
* Chart.yaml — version 0.1.0 -> 0.2.0, appVersion 0.6.0 ->
0.8.0-dev1.
LOCAL DEV
* docker-compose.yml — NATS service with JetStream enabled,
monitoring port exposed, healthcheck against /healthz. NATS_URL
wired into netcortex and worker containers.
CI
* .github/workflows/ci.yaml — contracts job gains a NATS service
container (nats:2.11-alpine, core pub/sub; JetStream not needed
for Protocol-surface tests). NATS_URL=nats://localhost:4222
exported so the gated NATS contract cases actually execute.
DEPENDENCIES
* nats-py>=2.6 added to runtime deps (async-only client, no native
code).
Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First sub-step of the brain-architecture refactor (see
docs/architecture/brain.md). Stands up the typed event bus the rest of0.8.0will route every signal through.netcortex/thalamus/— new package withNatsEventBus, a real production implementation of theEventBusProtocol shipped in0.7.1-dev2. NATS core pub/sub (no JetStream) because the Protocol promises at-least-once-within-session with no replay — which is exactly NATS core's semantics. JetStream is enabled at the server level so future durable consumers (0.9.0 episodic memory, stream bridge for external agents) can opt in via extension methods without redeploying NATS./data/jetstream. Liveness probes the listener; readiness asserts JetStream subsystem is up.NATS_URLenv threaded into web + worker pods, gated onnats.enabled.natsservice with healthcheck + JetStream + volume; wired into the netcortex / worker services.contractsjob gains a NATS service container;NATS_URLenv exported. The same contract suite that already coveredInMemoryEventBusnow parametrizes over both backends and exercises the real production code path.nats-py>=2.6.What is NOT in this PR
0.8.0-dev3(first dual-write) and0.8.0-dev5(full cutover).reflex/handlers yet — those land in0.8.0-dev2.This is intentional: each
0.8.0-devNstep lands behind a green CI gate before the next one starts. Easier to bisect any breakage.Test plan
CI auto-runs:
0.7.1-dev3InMemoryEventBusAND realNatsEventBus← the new thing this PR enablesManual verification once merged:
helm installin microk8s — NATS StatefulSet comes up, monitoring endpoint reachable at<release>-nats:8222/healthzNATS_URLenv and start cleanly (no actual NATS traffic yet)Roadmap
This is sub-step 1 of 6 for
0.8.0. Perdocs/architecture/brain.md:feat/0.8.0-dev1-thalamus-natsNatsEventBus+ contract parametrizationfeat/0.8.0-dev2-reflex-skeletonnetcortex/reflex/skeleton + 3 idle handlersfeat/0.8.0-dev3-first-publisherfeat/0.8.0-dev4-module-renamesadapters/*→sensory/poll/*,graph/correlate.py→association/feat/0.8.0-dev5-cutover0.8.0Made with Cursor