zenon-nebula 0.6.9

Autonomous intelligence platform for the Zenon Network

Zenon Nebula

  ·      .      ·        ✦       .       ·        .        ✦       ·

        ███╗   ██╗███████╗██████╗ ██╗   ██╗██╗      █████╗
        ████╗  ██║██╔════╝██╔══██╗██║   ██║██║     ██╔══██╗
        ██╔██╗ ██║█████╗  ██████╔╝██║   ██║██║     ███████║
        ██║╚██╗██║██╔══╝  ██╔══██╗██║   ██║██║     ██╔══██║
        ██║ ╚████║███████╗██████╔╝╚██████╔╝███████╗██║  ██║
        ╚═╝  ╚═══╝╚══════╝╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝

    ✦       .      ·        .       ✦       .       ·       .
        autonomous intelligence for the Network of Momentum
                         ·       ✦       ·

Metric	Count
Python files	397
Lines of code	115,100
Core modules	116
Domains	17
Engines	84
Test files	102
Scripts	16
Schema tables	85
MCP tools	8

Nebula is an autonomous intelligence platform for the Network of Momentum. It monitors the entire Zenon ecosystem in real time - specs, code, governance, bridge health, liquidity, narratives, and security - cross-references every signal through Bayesian hypothesis evolution and collision detection, and produces mission-aligned battle plans. Nebula is critical Zenon infrastructure: the nervous system that keeps the community informed, the network hardened, and the roadmap honest.

Mission

Nebula is not locked to any one spec author. Its mission is derived from the Zenon protocol's trajectory itself — PTLC, Bitcoin SPV, Portal, Atomic Swap, Commitments, Sentinel Validator, Governance, HyperQube, and everything else in flight or on the horizon. When a spec corpus is available the mission is re-derived from the specs on disk; otherwise it falls back to a hardcoded 5-pillar framework. Either way, every engine grades its own output against the same target:

Become the most trustless Bitcoin-adjacent programmable settlement layer in crypto. Enable non-custodial BTC ↔ ZNN movement through cryptographic proofs — point-locks, SPV header relays, atomic swaps, relayer-bonded bridges — instead of custodians or wrapped tokens. Preserve Zenon's sovereign consensus and dual-coin economics while extending programmability via embedded contracts and HyperQube extension chains. Never introduce admin keys, pause buttons, or post-activation upgrade paths. Every new contract is a composable building block for a more decentralized, more auditable, more Bitcoin-adjacent programmability layer — not a shortcut around its own security guarantees.

The five things Nebula grades every engine's output against:

1. Trustlessness — does this finding move the system closer to zero-custody BTC interop?
2. Sovereignty — does it preserve Zenon's own consensus and on-chain governance? (no sidechain shortcuts, no L2 custodial escape hatches)
3. Composability — does it add a building block other contracts can compose with, or is it a dead-end feature?
4. Auditability — is the change auditable without trusting an off-chain oracle, a relayer, or a pause key?
5. Adoption — is it something external operators (pillars, sentinels, wallets, explorers, SDK consumers) can actually use?

When the spec corpus is available, core/mission/spec_derivation.py re-derives these pillars from what TminusZ is actually writing (so the mission tracks the specs as they evolve, not whatever we decided to hardcode). Without the spec repo, the five pillars above are the fallback. See ADR-0010 for the full design.

Participants

• Developers - spec drift detection, cross-repo ABI consistency, upstream monitoring across the repos you have cloned locally, auto-generated PR descriptions and test vectors.
• Pillar operators - Accelerator-Z treasury runway, per-pillar uptime tracking, delegation-drop alerts, voting accountability scorecards.
• Delegators and stakers - yield comparison across pillars and sentinels, participation funnel tracking, whale accumulation signals, thesis tracker for supply contraction.
• Security researchers - adversarial contract reviews, CVE monitoring for dependency trees, bridge exploit patterns from 10+ real hacks, attack-cost modelling against consensus, governance, and the bridge.
• Community - ecosystem health trends, contributor radar, narrative resonance in Bitcoin-adjacent discussion, competitive positioning against other Bitcoin-adjacent L1s and L2s (Stacks, RSK, Botanix, Citrea, BOB — whatever the operator has cloned into their workspace).

What Nebula actually does

Nebula is not one feature — it's a platform that accumulates capabilities every release. The shipped surface, grouped by what operators actually use it for:

Continuous diagnosis of the Zenon ecosystem

• 17 domains × 84 engines run autonomously every cycle. Spec drift, cross-repo ABI consistency, CVE exposure, bridge TVL, pillar uptime, narrative dominance, supply thesis, Bitcoin-adjacent competitive positioning — every angle a core dev, pillar operator, security researcher, or delegator cares about has an engine producing WHAT / SO WHAT / NOW WHAT findings on a 30-second cadence.
• Cross-engine collision detection (core/collision_engine.py) — when two distinct engines converge on the same evidence, the signal gets promoted to a breakthrough_candidate. Single-engine opinions never graduate.
• Bayesian hypothesis evolution (core/hypothesis_engine.py + core/hypotheses/hardener.py) — every finding contributes to a hypothesis with explicit confidence math, decay on staleness, and retirement of anything that produces no supporting evidence for 50 cycles.
• Mission-aligned priority scoring (core/mission/definition.py + core/director.py) — every finding gets graded against the 5 pillars. The War Room daily battle plan sorts work by mission alignment, not by chronological order.

Anti-funnel trust architecture (v0.4.0)

Nebula is designed for a peer-to-peer collective where the same finding from N independent operators should reinforce confidence but the same finding from one engine running N times should not.

• Content-hash dedup — every finding normalized to a stable hash so two instances describing the same bug with different prose still count as one piece of evidence.
• Peer corroboration (core/peer_corroboration.py) — Bayesian merge of cross-instance findings, weighted by the publishing peer's trust tier.
• Trust caps at every boundary — unknown peers capped at 0.30 confidence, user-declared providers capped at 0.30, LLM summary output capped at 0.40, branch commits capped at 0.60, merged main up to 1.0. The confidence ceiling is mechanical, not optimistic.

Stale-content and pattern discovery (v0.6.6)

Two engines that surface anomalous or unfinished content in scanned repos — the kind of thing that deserves a human re-read but rarely gets one:

• curiosity_scanner — random-samples stale workspace repos and greps for keyword signals (TODO, HACK, experimental, untested) plus protocol-adjacent terms (schnorr, taproot, plasma, sentinel, spork). Emits findings with clickable GitHub permalinks straight to the line so the operator can verify in one click.
• pattern_discoverer — scans for uncommon content shapes: explicit marker comments (<!-- Clue: ... -->, hint: YAML frontmatter, Open Questions sections) and data-encoded blobs (hex / base64 strings that decode to meaningful ASCII). Both classes are low-noise — the false-positive rate is controlled by length + entropy filters — so every finding is worth a glance.
• Regression-gated — tests/scenarios/test_pattern_scanner_coverage.py exercises both engines against a test-fixture repo with known inputs every CI run and asserts each detection class still fires. If a future change breaks either path, CI blocks the merge before the regression ships.

Cross-chain reference analysis

Drop any Bitcoin-family / EVM / Cosmos reference chain into your workspace and watch these engines light up:

• btc_spec_tracker maps every BIP to its corresponding ZIP and flags BIPs with no Zenon counterpart.
• cross_chain_cve_monitor cross-references historical CVEs in the reference chain against semantically similar functions in go-zenon. The output is a targeted "review this file for the same class of bug" finding.
• reference_diff computes structural diffs (line count, cyclomatic complexity, decision points) between Zenon's consensus-critical primitives and the reference implementations. A 3× divergence is a smell worth reviewing.
• protocol_family_classifier tags every workspace repo into a family (UTXO chain, account chain, zk rollup, bridge, SDK consumer, tooling) and lets cross-domain queries compare peers.

Pluggable providers (v0.6.6 registry, v0.6.9 user providers)

• Provider registry (core/providers/registry.py) — every external capability (HTTP APIs, MCP servers, LLMs) is a pluggable APIProvider behind a common ABC. 6 builtin wrappers (github, explorer, market_data, vuln_feed, zenon_data, wayback, llm_xai) ship with telemetry on every call — engines don't know what provider they're using, the registry routes.
• Telemetry (core/api_telemetry.py) — every provider call logs latency, status, schema hash, and response size to the api_call_log table. Value-per-API scoring falls out: when an API is misbehaving or expensive or producing zero findings, you can see it.
• Evidence provenance (evidence.api_sources column) — every finding records which providers it consulted. nebula findings --by-provider shows the coverage matrix. Drop a provider and Nebula can tell you exactly how many findings you'd lose.
• User providers via TOML (v0.6.9 Phase B) — drop a ~/.config/nebula/providers.toml file declaring your own HTTP APIs or MCP servers and Nebula registers them at boot. No forking. Trust capped at 0.30. See User Providers below.

Mechanically-enforced self-integrity

Nebula inspects its own codebase with the same rigor it inspects Zenon's. Every release ships with the following gates, CI-enforced:

• Self-audit engine (v0.6.3) — rule_adherence_auditor walks every recent commit and flags drift from .claude/rules/. Caught the v0.6.1 continue-on-error hallucination retrospectively on its first real run. The engine audits its own commit on every ship.
• README truth auditor (v0.6.7) — readme_truth_auditor walks docs/claims.yml (963-line executable ledger of public claims), runs every claim's verifier, and classifies drift / broken / unverified / stale_forward_claim. scripts/check_readme_truth.py is a CI gate. Also detects stale forward-looking claims in past CHANGELOG entries (when the plan moves a feature to a later version, old release notes get flagged as lies).
• Architecture gates — scripts/audit_architecture.py + scripts/generate_dep_graph.py --check enforce the three invariants (core never imports domains, engines never import peer engines, no circular imports). v0.6.9 made the dep-graph gate actually block CI on violations instead of silently reporting them.
• Rule freshness test — tests/test_rule_freshness.py walks every rule file and asserts every referenced path exists. Moves the "stale rule" failure mode into CI.
• Attack-vector smoke test — tests/test_attack_vector_smoke.py statically scans for unsafe patterns (shell=True, eval, missing subprocess timeouts) and fails the build on violations.
• Fuzz tests + coverage floors (v0.6.4) — Hypothesis-based property fuzzing on load-bearing pure functions; coverage floors at 55% core / 47% core+domains enforced by CI.
• Mutation + chaos + perf (v0.6.13 / Phase F) — planned next; the 10-gap list is publicly tracked in docs/tasks.yaml.

Spec-audit feedback loop to TminusZ (v0.3.0+)

• spec_audit engine walks knowledge/developer-commons/docs/specs, runs 6 structural + semantic checks per spec, and persists findings with reproducible commit pins.
• tminusz_contributor converts every finding into a paste-ready GitHub issue body (via the shared core/spec_audit_contributions.py formatter) with WHAT / SO WHAT / NOW WHAT sections and a clickable spec-file permalink. Maintainers can triage Nebula's findings in 30 seconds each.

Durable, tiered release discipline (v0.6.8)

• Four-tier branching model (.claude/rules/branching.md): Tier 0 typos → direct to main, Tier 1 new code → PR + CI green
  • self-merge, Tier 2 schema / security / multi-file → add a 1-hour soak, Tier 3 release tags → only via scripts/release.py ship which verifies CI green on main, runs the README truth gate, tags, pushes, and watches the release workflow until completion.
• Branch protection on main — 11 required status checks, linear history, squash-merge only, force-push disallowed, admin bypass reserved for Tier 0 emergencies.
• SLSA-3 provenance + sigstore signing on every tagged release.

Distributed intelligence

• Multi-instance peer sync via core/transport.py — filesystem-based SharedDirTransport (no central server, no GitHub required), snapshot export / import, SpacetimeDB integration optional.
• Pseudonymous peer identity — peer:hex16 handles or operator-set ZENON_PEER_ADDRESS. Anti-doxxing invariants enforced by rule + test (no --author, no stylistic similarity inference, no real-name resolution).
• Content-hash corroboration across instances — the more operators running Nebula, the more independent confirmations each hypothesis accumulates, the faster bias gets caught.

Findings as a machine-actionable task queue

• Finding lifecycle — every finding carries open / resolved / verified status, resolved_by, resolved_at, and related_findings linking bug → fix. auto_resolve_findings runs every cycle and pairs bugs with newer verifications.
• ActionSpec dataclass (v0.6.6) — findings can opt in to a structured action spec (action_type, target_repo, target_file, target_line, success_criteria, effort_estimate, risk_estimate). Already landed as a forward-compat stub so every finding from v0.6.6+ is agent-ready for Phase I.
• Phase I agent swarm (planned v0.6.18+19) — nebula_claim_finding / nebula_complete_finding MCP tools let executor agents (Claude Code, custom, OpenAI-based) atomically pick findings off the priority queue, do the work, and report back. Completions become new evidence that runs through the same plausibility gate
  • corroboration + Bayesian update as any other finding. See the full plan in docs/tasks.yaml (task #68).

MCP interoperability (both directions)

• Server — scripts/mcp_server.py exposes 8 tools (nebula_status, nebula_spec_coverage, nebula_security_findings, nebula_battle_plan, nebula_upstream_signals, nebula_aspirations, nebula_collisions, nebula_query) over stdio, protocol 2024-11-05. Any MCP-compatible client (Claude Code, Cursor, custom) plugs in via .mcp.json.
• Client (v0.6.9 Phase B) — Nebula can now consume MCP servers declared in ~/.config/nebula/providers.toml. Your private research MCP server becomes just another provider Nebula engines can call through.

Always-safe degradation

• No LLM key? Nebula still runs — about 70% of engines produce findings on local compute alone at $0/month. Degraded engines emit "LLM unavailable" findings instead of crashing.
• No workspace? Nebula still runs — engines that scan sibling repos emit "workspace not installed" findings and the rest continue on API / on-chain data.
• No network? Nebula still runs — local engines (git scans, AST parsing, SQLite queries) work offline. Network engines emit graceful-degrade findings.
• xAI hanging / timing out / rate-limited? Every branch is test-pinned in tests/test_llm_provider_failure_modes.py with a failure-mode contract table in the v0.2.17 CHANGELOG entry.

Architecture

           +------------------+
           |   Mission Core   |   core/mission/definition.py (5 pillars + aspirations)
           +---------+--------+
                     |
                     v
        +---------------------------+
        |  UnifiedDirector          |   scores every proposal against mission
        |  Breakthrough Engine      |   hunts convergence + anomalies
        |  Aspiration Engine        |   tracks long-lived goals
        |  War Room                 |   daily battle plan
        +-----------+---------------+
                    |
                    v
    +---------+---------+---------+---------+---------+
    | 17 Domains       | 84 Engines         | Evidence DB |
    +---------+---------+---------+---------+---------+
    |                               |
    v                               v
    Schema Registry                Transport
    (single source of truth)       (peer sync, snapshots, MCP)

Text-only diagram on purpose: every arrow downstream from the mission core should be traceable to a mission pillar. Nebula never acts on LLM opinion alone; findings flow through Bayesian hypothesis evolution and cross-engine collision detection before they earn confidence.

Quick Start

git clone https://github.com/ZenonOrg/nebula && cd nebula
pip install -r requirements.txt
cp env.example.txt .env        # add at least one LLM API key (XAI_API_KEY recommended)
./nebula --cycles 5            # run five cycles, see what it found
./nebula status                # summary of findings, hypotheses, collisions

Zero external infrastructure required. Nebula reads a public Zenon RPC node by default (set ZENON_PUBLIC_RPC to point at your own). Most engines work with zero keys; adding XAI_API_KEY unlocks the strategic synthesis engines (~$0.0017/cycle, ~$0.17 per 100 cycles — measured from a real 400-cycle harden run, see Cost section below).

CLI Commands

Command	Description
./nebula	Run continuously (24/7)
./nebula --cycles N	Run N cycles then stop
./nebula --budget N	Run with a USD budget cap
./nebula --hours N	Run for N hours
./nebula --domains sec,qual	Run only selected domains
./nebula status	Show evidence count, hypotheses, collisions, uptime
./nebula findings	Show recent findings with lifecycle status
./nebula plan	Show the latest War Room battle plan
./nebula domains	List every registered domain and its engines
./nebula hypotheses	Show Bayesian hypotheses with current confidence
./nebula costs	LLM cost breakdown by provider and model
./nebula specs	Spec coverage matrix across go-zenon, SDKs, CLI, wallet
./nebula height	Evidence-chain height (append-only)
./nebula serve	Start the MCP server (8 tools)
./nebula rpc	Start the JSON-RPC server (default: 127.0.0.1:8484)
./nebula providers	List shipped + user providers (kind, trust tier, status)
./nebula providers test <name>	Dry-run a provider to confirm it's reachable
./nebula providers reload	Re-read ~/.config/nebula/providers.toml without restarting
./nebula findings --by-provider	Group findings by the provider that produced them
./nebula snapshot export	Export evidence snapshot for peer sharing
./nebula snapshot import FILE	Import a peer snapshot
./nebula sync	Pull the latest snapshot from configured peers
./nebula ask "question"	Freeform query against the knowledge graph

17 Domains, 84 Engines

Building and shipping

Domain	Engines	Purpose
development	spec_tracker, impl_coverage, upstream_monitor, dependency_chain, spec_drift, spec_audit, btc_spec_tracker	Spec tracking, implementation coverage, upstream change detection, spec quality audit
quality	spec_verifier, build_verifier, cross_repo_checker, test_coverage, reference_diff	ABI byte-level comparison, build verification, cross-repo consistency, reference-chain diff
security	adversarial_reviewer, vuln_scanner, static_analyzer, report_generator, attack_simulator, cve_monitor, exploit_scanner, cross_chain_cve_monitor, attack_vector_scanner	Attack surface analysis, CVE tracking, fund-safety reviews, Nebula self-audit
standards	bip_zip_tracker, deployment_pipeline, crypto_compliance	BIP/ZIP tracking, release pipeline, crypto primitive compliance
devops	devnet_manager, rpc_client, integration_tests, test_runner	Devnet orchestration, JSON-RPC smoke tests, integration runners
contribution	pr_readiness, pr_description_gen, tminusz_contributor, auto_contributor, workspace_recommender	PR checklist, description generation, test vector extraction, workspace recommendations

Understanding the network

Domain	Engines	Purpose
intelligence	upstream_watcher, signal_detector, signal_router, ecosystem_health, repo_relationship_mapper	Git firehose, commit classification, signal routing, cross-repo dependency mapping
governance	treasury_monitor, proposal_analyzer, voting_patterns, governance_intel, pillar_accountability	Accelerator-Z runway, proposal lifecycle, per-pillar voting
network_health	node_census, decentralization_scorer, bridge_health, pillar_monitor	Nakamoto / HHI / Gini, bridge TVL, pillar uptime
economics	supply_tracker, staking_analyzer, liquidity_monitor, funnel_tracker, whale_watcher, yield_calculator	Emission, staking, DEX depth, participation funnel, whale tracking, yield comparison

Strategy and narrative

Domain	Engines	Purpose
product_market_fit	landscape_scanner, technical_positioning, roadmap_predictor, adoption_tracker, fork_detector, ecosystem_gap	Competitive mapping against Bitcoin-adjacent programmability projects (Stacks, RSK, Botanix, Citrea, etc.) and any reference chain in the workspace
investigation	architecture_analyzer, vision_tracker, protocol_family_classifier, curiosity_scanner, source_quality_scorer, pattern_discoverer	Code archaeology, architectural patterns, content-based trust scoring, stale-content + pattern anomaly detection (direct marker comments + indirect data-encoded blobs)
marketing	narrative_analyzer, ecosystem_positioning, narrative_dominance, bitcoin_narrative_builder	Narrative resonance, BTC-adjacent story hunting

Self-awareness

Domain	Engines	Purpose
education	doc_quality, onboarding_tracker	Wiki completeness per contract, developer onboarding grading
community	contributor_tracker, health_scorer, talent_radar, sentiment_tracker	Contributor activity, talent scoring, sentiment
interoperability	bridge_compat, evm_readiness, consensus_monitor	Bridge versioning, HyperQube/Supernova, cross-chain consensus
self_maintenance	engine_health_monitor, config_drift_detector	Engine success-rate monitoring, config drift detection

Core Modules

Nebula separates orchestration from discovery. The core layer is deliberately small and deterministic so domain engines can rely on it without worrying about ordering or state leaks.

Mission and priorities - mission.py, director.py, war_room.py, strategy_evolver.py, aspiration_engine.py, breakthrough_engine.py, red_team.py, persona_panel.py

Evidence and hypotheses - persist_to_db.py, schema_registry.py, evidence_vault.py, feedback_bus.py, collision_engine.py, knowledge_graph.py, validation_spiral.py, synthesis_engine.py, cascade_detector.py, hypothesis_engine.py, hypothesis_hardener.py, peer_corroboration.py

Orchestration - domain_registry.py, engine_scheduler.py, parallel_runner.py, run_context.py, template_dag.py, adaptive_router.py

LLM routing - model_router.py, llm_provider.py, prompt_builder.py, cost_optimizer.py

Discovery - discovery_base.py, curiosity.py, workspace_discovery.py, corpus.py, experiment_manager.py, self_extension.py, self_improver.py

Network and data - zenon_data.py (HTTP JSON-RPC to the Zenon chain), node_rpc.py (WebSocket to local znnd), nebula_rpc.py (HTTP server for peer Nebulas), explorer_api.py, market_data.py, github_api.py, universal_rpc.py, vuln_feed.py

Transport and peers - transport.py, sync.py, mcp_bridge.py, commons.py, integrations/

Safety - trust.py, opsec.py, hallucination_guard.py, forensic_audit.py, resilience.py, plausibility_gate.py, novelty_checker.py, finding_verifier.py, anomaly_detector.py

Utilities - commons.py, workspace.py, git_cache.py, file_extractors.py, api_fingerprint.py, failure_classifier.py

Data Sources

Nebula pulls from every public source that matters for Zenon, with no special access required:

• Zenon RPC - HTTP JSON-RPC (default https://my.hc1node.com:35997) or local znnd via WebSocket. Ledger, pillar, sentinel, accelerator, token, bridge, stake, plasma namespaces all covered.
• Git repositories - whichever Zenon ecosystem repos are present under ZENON_WORKSPACE_ROOT. Nebula scans them every cycle for commits, spec drift, and dependency changes. Repos that aren't cloned locally are skipped (engines that depend on them return empty and log a "workspace missing" note). See "Local vs remote tracking" below.
• GitHub API - PR status, issue activity, contributor graphs.
• CoinGecko - ZNN / QSR price, market cap, 24h volume, rolling returns.
• DexScreener - wZNN/ETH pair depth, liquidity, trader counts.
• DefiLlama - bridge and protocol TVL via the zenon-finance slug.
• LunarCrush - social sentiment metrics when LUNARCRUSH_API_KEY is set.
• OSV.dev - dependency CVE lookups for go.sum / pubspec.lock.
• Fear & Greed (alternative.me) - market sentiment context.
• Stacker News, HN Algolia, r/Bitcoin - Bitcoin-narrative scanner inputs.
• MCP peers - SETI and any MCP-compatible tool plugged in via NEBULA_MCP_PEERS.

Every API integration is documented in the audit report core/api_templates/ and rechecked by the quality domain on a schedule.

Schema Registry

Every engine owns its tables. core/schema_registry.py walks the core package plus every domain plugin and engine module at startup, collects declared SCHEMA_SQL fragments, and applies them in dependency order with CREATE TABLE IF NOT EXISTS. Adding a new engine automatically adds its tables; removing one never leaves dead schema.

This replaces the old three-places-to-declare-schema pattern that caused "no such column" errors whenever an engine evolved ahead of persist_to_db.SCHEMA_SQL.

Mission Alignment

core/mission/definition.py declares five weighted pillars: technical excellence (0.28), ecosystem expansion (0.20), narrative dominance (0.20), security hardening (0.20), adoption growth (0.12). mission_alignment() grades any finding against every pillar deterministically using domain membership, keyword density, and explicit tags. The Director boosts aspirations that rank high on mission alignment. The Breakthrough Engine flags any finding whose overall alignment crosses 0.65 as a breakthrough_candidate even without convergence or anomaly support.

Breakthrough Hunting

core/breakthrough_engine.py runs three detectors every 10 cycles:

1. Cross-engine convergence - two or more distinct engines reporting the same evidence type inside a 24-hour window promote the signal.
2. Anomaly amplification - a single finding more than three sigma above its engine's baseline confidence distribution gets promoted.
3. Mission-critical surfacing - a single finding with mission_alignment.overall >= 0.65 gets promoted.

Breakthrough candidates are persisted with evidence type breakthrough_candidate so the War Room can inspect them first. The whole module is deterministic: zero LLM cost.

Aspiration Engine

core/aspiration_engine.py collects aspirations from the mission core and from every domain plugin, grades them on alignment / support / feasibility, and retires the ones that produce no progress for 50 cycles. Aspirations are queryable via nebula aspirations. Engines signal progress by persisting evidence with type aspiration_progress:<title>.

MCP Integration

Plug Nebula into Claude Code, Cursor, or any MCP-compatible tool:

claude mcp add nebula python3 scripts/mcp_server.py

Eight tools exposed: nebula_status, nebula_spec_coverage, nebula_security_findings, nebula_battle_plan, nebula_upstream_signals, nebula_aspirations, nebula_collisions, nebula_query.

Questions like "what does Nebula say about the bridge?" route to the security and network_health evidence. Questions like "what's the next spec to ship?" route through the Director.

User Providers — bring your own HTTP APIs and MCP servers

v0.6.9 Phase B. Nebula's provider registry (v0.6.6) ships 6 builtin wrappers (github, explorer, market_data, vuln_feed, zenon_data, wayback, llm_xai). As of v0.6.9, you can declare your own HTTP APIs and MCP servers in a user-space TOML config and Nebula registers them at boot alongside the shipped providers. No forking. No engine edits.

Drop this at ~/.config/nebula/providers.toml (or $XDG_CONFIG_HOME/nebula/providers.toml or $NEBULA_PROVIDERS_CONFIG if you want to override the path):

# Declarative HTTP API — becomes a callable APIProvider
[[api]]
name = "my-private-blockscout"
description = "Internal block explorer for my chain"
base_url = "https://blockscout.internal.example.com/api/v2"
auth_env_var = "MY_BLOCKSCOUT_TOKEN"   # read at call time, never persisted
auth_header = "Authorization"           # default: Authorization
auth_prefix = "Bearer "                 # default: "Bearer "
rate_limit_rps = 2                      # default: 1
timeout_seconds = 15                    # default: 10
trust_tier = "user"                     # capped at DEFAULT_TRUST (0.30)

  [[api.endpoints]]
  method_name = "get_block"
  http_method = "GET"
  path = "/blocks/{block_number}"
  response_jsonpath = "$.data"          # optional projection

  [[api.endpoints]]
  method_name = "get_address"
  http_method = "GET"
  path = "/addresses/{address}"

# MCP server provider — Nebula spawns it as a subprocess
[[mcp]]
name = "my-research-mcp"
description = "My private research MCP server"
command = "python3"
args = ["/abs/path/to/research_server.py"]
trust_tier = "user"
timeout_seconds = 30

# Or: an MCP server reachable via HTTP transport
[[mcp]]
name = "shared-team-mcp"
url = "https://mcp.team.example.com:3000"
auth_env_var = "TEAM_MCP_TOKEN"
trust_tier = "user"

Then manage it via ./nebula providers:

./nebula providers list             # shipped + user, with kind + status
./nebula providers test my-private-blockscout
./nebula providers reload           # re-read config without restarting
./nebula providers add <snippet>    # append to user config (validates first)
./nebula providers remove <name>    # remove from user config

Safety rails, mechanically enforced:

• User providers are tagged kind="api-user" or kind="mcp-user" in the registry. Any finding that cites a user provider in its api_sources is capped at DEFAULT_TRUST = 0.30 via core.trust.cap_confidence_by_provider, regardless of the engine's claimed confidence. A buggy or malicious user provider cannot pollute the evidence store with high-confidence findings.
• Path-param substitution is string replacement with URL encoding, not eval. The URL is OPSEC-scrubbed via core.opsec.sanitize_url before fingerprinting or logging. Auth tokens are read from the environment at call time — never persisted and never logged.
• Invalid TOML entries are skipped with a warning at boot, never crash the runner.
• MCP subprocess lifecycle is managed by MCPConsumerProvider.shutdown() which the graceful-shutdown path calls for every registered provider.

See docs/runbooks/user-providers.md for the end-to-end walkthrough.

Multi-Instance Sharing

Run multiple Nebula instances and share intelligence:

# Instance A: publish
./nebula snapshot export            # data/snapshot_<timestamp>.json

# Instance B: consume
./nebula snapshot import data/snapshot_<timestamp>.json
./nebula sync                       # pull from configured peers

Evidence records carry SHA-256 integrity hashes and participant attestation. core/peer_corroboration.py boosts confidence on findings that independent peers also produced; trust in unknown peers is capped at 0.30 until reputation is earned. Peer corroboration only ever raises confidence - never lowers it.

Local vs remote tracking — what runs with what you have

Nebula has two kinds of engines: ones that read files on your disk, and ones that call external APIs. The more repos you have cloned locally, the more of Nebula's 84 engines actually produce output.

Engines that REQUIRE a local clone (silently no-op without it):

Engine	Needs
upstream_watcher	git -C <repo> — any git repo in the workspace
spec_tracker · spec_drift · impl_coverage	knowledge/developer-commons/docs/specs + core/go-zenon
btc_spec_tracker	A Bitcoin-family repo with a bips/ directory
reference_diff	A reference chain repo (Bitcoin, Ethereum, etc.) + Zenon repos
repo_relationship_mapper	Any workspace repos with manifests (go.mod, pubspec.yaml, package.json, Cargo.toml)
contributor_tracker · architecture_analyzer · vision_tracker	Source repos on disk
protocol_family_classifier	Any workspace repos (for classification signals)
cross_chain_cve_monitor	At least one reference chain repo in the workspace

Engines that work without any local clones (API + on-chain only):

repo_relationship_mapper, ecosystem_health, cve_monitor, vuln_scanner, node_census, decentralization_scorer, staking_analyzer, treasury_monitor, supply_tracker, bridge_health, market_data, narrative_analyzer, sentiment_tracker, consensus_monitor, proposal_analyzer, voting_patterns, yield_calculator.

Practical rule: if you only have go-zenon and znn_sdk_dart cloned, about half of Nebula's engines produce data. Clone more of the ecosystem (see knowledge/, core/, and infrastructure/ sub-trees in the Zenon workspace layout) and coverage grows linearly.

Drop reference chains into your workspace to unlock cross-chain analysis

This is one of Nebula's most powerful features and the easiest win once you try it. Zenon's specs, particularly PTLC, Portal, Bitcoin SPV, and Sentinel Validator, consciously borrow from other protocols. Without a reference implementation in the same workspace, Nebula can only reason about Zenon in isolation. With one, a whole class of engines lights up.

What happens when you add Bitcoin Core

# Assume your workspace already has go-zenon + SDKs.
cd ~/Repos/Zenon
git clone --depth 50 https://github.com/bitcoin/bitcoin core/bitcoin

On the next cycle, Nebula's workspace_discovery detects the new repo, classifies it as blockchain_node_btc via the generic signatures in core/workspace_discovery.py::REPO_SIGNATURES, and writes it to the workspace_repos table. Four cross-chain engines then activate:

• domains/development/btc_spec_tracker — walks the bips/ directory, maps each BIP to a corresponding ZIP in knowledge/developer-commons/docs/zips/ (if present), and flags any BIP that has no ZIP counterpart. If BIP-324 is merged upstream but there's no ZIP-XX draft for equivalent Zenon work, Nebula surfaces the gap with a WHAT/SO WHAT/NOW WHAT finding.
• domains/security/cross_chain_cve_monitor — cross-references historical Bitcoin Core CVEs (CVE-2024-35202 merkle proof validation, CVE-2022-44797 btcd taproot signature malleability, etc.) against semantically similar function names in go-zenon. When go-zenon/vm/embedded/bitcoin_spv/verify.go contains a function shaped like Bitcoin's patched code path, you get a targeted "review this file for the same class of bug" finding.
• domains/quality/reference_diff — for consensus-critical primitives like merkle proof validation and secp256k1 signature verification, extracts the function body from both codebases, computes a structural diff (line count, cyclomatic complexity, decision points), and flags large divergences. A Zenon function that's 3x more complex than its Bitcoin reference is a smell worth reviewing.
• domains/investigation/protocol_family_classifier — classifies every workspace repo into a family (UTXO chain, account chain, zk rollup, bridge, SDK consumer, tooling) and lets cross-domain queries compare peers within a family.

What happens when you add Ethereum (go-ethereum)

git clone --depth 50 https://github.com/ethereum/go-ethereum core/geth

protocol_family_classifier tags it as blockchain_node_evm. The same four engines above re-run against EVM primitives. reference_diff compares Zenon's EVM-adjacent code (the HyperQube extension chain work) against go-ethereum's reference implementations. cross_chain_cve_monitor pulls the known Geth CVE list as its corroboration baseline.

What happens when you add Cosmos SDK

git clone --depth 50 https://github.com/cosmos/cosmos-sdk core/cosmos-sdk

Classified as blockchain_node_cosmos. Engines then compare Zenon's governance contract against Cosmos x/gov, and (when Sentinel Validator lands) compare Zenon's validator set management against Cosmos x/staking. This was the Zenon governance spec's cited inspiration — having the reference on disk lets Nebula actually check alignment.

Why this is a killer feature

• Cross-pollinate security fixes. Bitcoin Core spends millions of dollars a year on adversarial review. Every CVE they find is public. Nebula can automatically ask "does Zenon have the same bug?" for every fix — something no human does continuously.
• Find spec gaps before TminusZ does. When Bitcoin adopts BIP-324, Nebula flags "no corresponding ZIP." The Zenon community sees the signal weeks before manual review would catch it.
• Prove primitives are correct by triangulation. reference_diff won't catch subtle logic bugs, but it will catch "Zenon's merkle proof verifier is 200 lines while Bitcoin's is 40" — a red flag that says either Bitcoin is missing a check or Zenon added something worth auditing. Either answer is valuable.
• Zero extra LLM cost. All four engines use stdlib parsing + regex. No API calls. Running them forever is free.

The invitation: if you run Nebula, spend the 30 seconds to git clone --depth 50 bitcoin/bitcoin into your workspace. You will start surfacing findings within one cycle that nobody else in the Zenon ecosystem is looking at.

The network effect: more instances = sharper signal

Nebula gets smarter as more people run it. This isn't marketing — it's a consequence of how the evidence and hypothesis layers are designed.

Each operator runs their own Nebula instance against their own workspace (different forks, different API keys, different schedules, different subsets of the 17 domains). Every instance independently produces findings and hypotheses. Those findings flow to a shared commons via ./nebula snapshot export or the Nexus transport, and every other instance pulls them via ./nebula sync.

What happens next is the key:

• Independent confirmation boosts confidence. If instance A's vuln_scanner flags a bug in go-zenon and instance B's adversarial_reviewer independently flags the same bug, the Bayesian hypothesis update in core/peer_corroboration.py combines those two signals into a higher-confidence hypothesis than either alone. Two independent engines from two independent operators is much stronger evidence than either one alone.
• Coverage compounds. Operator A might have go-zenon on their disk but not znn_sdk_dart; operator B has the opposite. A single operator can only ever scan what they have. The commons sees the union.
• Stale signal ages out. core/hypotheses/hardener.py retires hypotheses whose supporting evidence is older than the staleness window. When multiple instances refresh the same finding on different schedules, the commons always has recent evidence.
• Bias detection gets cheaper. hypothesis_hardener.py flags single-source bias ("all supporting evidence came from one engine"). With more operators running, the probability of single-source bias drops toward zero — there are more engines across more instances producing evidence against the same hypothesis.
• Trust model prevents poisoning. A malicious peer publishing garbage can only ever move a finding's confidence by at most their trust score, which is capped at 0.30 for unknown peers. Corroboration only ever raises confidence — a bad peer can't lower a good peer's finding. Trust compounds over time with a proof-of-work-style reputation curve.
• Aggregate metrics become reliable. Cost tracking, engine health, budget pacing — single-instance stats are noisy; commons-wide stats are actionable.

The practical implication: if you're the only operator running Nebula, you get a solid solo-researcher tool. If you're one of ten, the commons is richer than any of you could produce alone. If you're one of a hundred, Nebula becomes a real-time distributed intelligence surface for the entire Zenon ecosystem — which is the design target.

The easiest way to make Nebula smarter is to run it. Every new operator's findings become everyone's signal, subject to the trust model. See docs/operations/multi-instance.md for the transport modes (local snapshots, Nexus via SpacetimeDB, shared directory) and the OPSEC guarantees on what leaves your instance.

Operator flexibility — run Nebula your way

Not every operator wants the full 17-domain × 84-engine sweep over every repo in their workspace every cycle. Nebula is designed to be steerable at every level so you can point it at exactly the questions you care about.

What ships today

• Narrow by domain — ./nebula --domains sec,qual runs only the security and quality domains. Everything else is skipped. Useful when you're pillar-only or contributor-only and don't need the marketing / narrative scanners eating cycles.
• Narrow by budget / time — --budget 0.50 stops the loop at $0.50 of LLM spend; --hours 2 runs for 2 hours; --cycles N runs exactly N cycles. All composable.
• Narrow by transport — NEBULA_TRANSPORT=local runs without peer sync; NEBULA_TRANSPORT=shared NEBULA_SHARED_DIR=... publishes/pulls via a shared filesystem.
• Narrow by LLM — XAI_API_KEY="" or unset drops you into the free local-compute-only mode (~70% of engines still produce findings).

What's on the near-term roadmap

• Narrow by repo (planned — task #79) — ./nebula --repos go-zenon,syrius filters every workspace-scanning engine down to just the listed repos. The rest of the workspace is untouched. Useful when you're focused on one PR, one spec, one integration — you don't want the full firehose.
• Ad-hoc operator focus (planned — task #80) — ./nebula --focus "PTLC implementation bugs" injects your directive into the Director's prompt and the breakthrough engine's alignment scoring. Findings relevant to your focus get a boost in the daily battle plan on top of the standard Zenon mission alignment. Think of it as telling Nebula "while you're doing your normal work, also pay attention to this".
• Long-lived operator intent (planned — task #71) — ~/.config/nebula/intent.md is a versioned prose narrative of your current research focus. nebula status shows it. Survives across sessions. Peers (with your permission) can read it for context about what you're thinking.
• Mission pillar overrides (planned — Phase G2, v0.6.15) — ~/.config/nebula/mission.toml lets you append your own pillars to the shipped 5 or (with explicit risk acknowledgment) replace them entirely. The collective war room still converges on Zenon-mission-aligned output, but your individual instance explores the questions you care about.
• User domains, hooks, engine overrides (planned — Phase G1, v0.6.14) — drop a domain plugin in ~/.config/nebula/domains/, disable a shipped engine via ~/.config/nebula/overrides.toml, subscribe to post_finding / pre_cycle events via a hook script. All without forking.

The philosophy: diverge at the individual level, converge at the collective level. Every operator runs whatever subset of Nebula makes sense for their role and their research, but every operator's findings feed the same content-hash-dedup'd, peer-corroborated, mission-aligned commons. A pillar operator, a core dev, a security researcher, and a delegator can all run Nebula on the same day with radically different configurations — and each of their findings still strengthens the hypothesis evolution for everyone else.

Publishing model — public wheel, controlled repo

Nebula operates with a deliberate asymmetry between its two distribution surfaces:

• PyPI package (pypi.org/project/zenon-nebula) is public. Anyone can pip install zenon-nebula and get the full source of every shipped version. The README you're reading is the same README embedded as the PyPI project description. This is the supported installation path for every operator, regardless of GitHub access.
• GitHub repo is currently in controlled-visibility mode (private). Issues, PRs, CI logs, branch state, and the draft state of in-flight work stay gated to org members until the mechanical gates from v0.6.7 → v0.6.13 prove themselves. The README at the repo root flows through the same truth-auditor + regen pipeline as the PyPI copy.

Why the split is intentional and not a leak: the code has been open via PyPI since v0.5.5 (10 versions live on PyPI as of v0.6.8). The private-repo setting gates the development process (issues + PRs + CI + branches), not the shipped product (the wheel). The split is interim — the natural destination is a fully public repo once the test pyramid and the mechanical release gates stabilize across the v0.6.9 → v0.6.13 ship window. See docs/runbooks/publishing-model.md for the full reasoning, the three options considered, the wheel-contents verification procedure, and the concrete trigger criteria for flipping to the fully public state.

TL;DR for new operators: pip install zenon-nebula and you have the same code everyone else is running. Auditing what's in the wheel is a one-command affair documented in the runbook.

Portability

Nebula works the same way whether you checked out the whole Zenon workspace or just cloned Nebula alone:

• ZENON_WORKSPACE_ROOT env var controls where Nebula looks for sibling repos.
• Engines that scan sibling repos degrade gracefully to "no data" when the repo isn't present.
• No hardcoded /Users/... or /home/... paths; everything resolves via core/workspace.py helpers.
• NEBULA_SKIP_WAR_ROOM=1 lets headless runs skip the LLM step for CI scenarios.
• requirements.txt covers the core loop; requirements-full.txt adds PDF/image/OCR support for file_extractors.

Cost

Most of Nebula runs free. LLM calls are reserved for strategic reasoning.

Component	Cost
Local engines (git scans, filesystem, API queries, RPC)	Free
Collision detection, feedback bus, evidence storage	Free
Knowledge graph, hypothesis evolution, breakthrough hunt	Free
Director synthesis, War Room battle plan	1-2 LLM calls/cycle
Security adversarial review	1 LLM call per contract

Nebula uses xAI Grok exclusively — chosen for cost. Grok 4.20 is the cheapest frontier model that can handle the strategic synthesis work, and grok-4-1-fast-non-reasoning is even cheaper for the classification and routing tasks. The model router picks the right tier per task. The prompt cache and the v0.2.18 circuit breaker keep the bill capped even under bursty load.

Real cost data from a 400-cycle harden run:

Workload	LLM calls	Cost
1 cycle (~33s)	0–2	~$0.0017
100 cycles (~55 min)	~38	~$0.17
1000 cycles (~9 hours)	~375	~$1.65
24 hours continuous	~3600 cycles	~$5.90
30 days continuous	~108k cycles	~$180

Each cycle runs ~85 engine invocations (17 domains × ~5 engines). ~99.6% are free local work — git scans, file reads, AST parsing, SQLite queries, RPC calls. Only ~0.4% reach the LLM:

• Director priority synthesis (1–2 per cycle, escalates to reasoning)
• War Room daily battle plan (1 per ~120 cycles, since it's daily)
• Adversarial security reviews (cached after first scan per contract)
• Hypothesis hardener challenges (a handful per cycle, classifier-shaped)

The --budget N CLI flag stops the autonomous loop when LLM spend hits $N. Typical operators set --budget 0.50 or --budget 1.00 per run. Audit your real spend at any time with ./nebula costs.

If you set XAI_API_KEY="" Nebula still runs — about 70% of engines produce findings on local compute alone, at $0/month.

Set XAI_API_KEY in .env (or via ./nebula config api-key). Get a key at https://console.x.ai.

Stats

Live counts are in the auto-regenerated block at the top of this README. Run python3 scripts/regen_docs.py after any structural change; a pre-commit hook also invokes it in --check mode.

Adding a Domain

Domains are auto-discovered at runtime. Drop a plugin in domains/, restart. Every engine should declare its own SCHEMA_SQL constant so the registry picks the table up automatically.

from core.domain_registry import DomainPlugin, EngineDefinition

class MyDomain(DomainPlugin):
    @property
    def name(self) -> str:
        return "my_domain"

    def get_engines(self) -> list:
        return [EngineDefinition(
            name="my_engine",
            module_path="domains.my_domain.engines.my_engine",
            priority=5,
            status="built",
        )]

See domains/ for seventeen complete examples.

License

MIT - see LICENSE.

---

Built with Python 3.10+, SQLite, and xAI Grok.

Zenon Network / ZenonOrg / Developer Commons