Nexus Cascades: Meet the Police, Janitor, Documenter & More

What Are Nexus Cascades?

A Nexus Cascade is an autonomous, multi-step AI workflow. You define it in YAML, assign it to a named agent persona, and the platform runs it — on a schedule, in response to a database event, on startup, or via an API trigger.

Think of it as a pipeline where each step can do something real: hit an HTTP endpoint, run an AI agent task, execute a database query, write records back to the store, wait for conditions to be met, or geo-locate an IP address. Steps pass results forward using a clean $variable$ syntax, and the whole thing generates a structured Nexus Report automatically on every run.

This is not orchestration for the sake of it. Every cascade runs in a governed context — subject to the same constitutional laws as every other agent in the system.

---

The Six Cascade Types

Solo

One agent, one sequence of steps, executed in order. The simplest cascade type. Perfect for single-agent tasks like enrichment passes, document generation, or scheduled summaries.

Chain

Agents hand off results to the next agent in the sequence. Each step receives the output of the previous one as context. Useful for research pipelines where a Spectre crawl feeds into a Librarian synthesis feeds into a Documenter report.

Parallel

Multiple steps execute simultaneously. Results are collected and passed forward together. Ideal for workloads where independent data sources need to be combined — geo-lookups, external API calls, and database queries all happening at the same time.

Event

The most powerful cascade type. An event cascade watches any PocketBase collection with any filter condition and fires immediately when a matching record appears. No polling, no cron overhead — pure database-level reactivity.

The state machine built into event cascades uses a state_field that moves from pending to a report ID, which prevents double-firing even under high-throughput conditions.

Loop

A time-based cascade on a cron schedule. Runs on a defined interval — every hour, every morning at 08:00, every Monday. Useful for recurring reports, weekly digests, or any task that should happen on a predictable cadence.

Automation

Triggered by an incoming webhook or a tool chain call. Connects the Sovereignty Protocol to external systems — CI/CD pipelines, third-party APIs, notification services. Your agents become callable endpoints.

---

The Named Personas

Each cascade is owned by a named agent persona. These are not just labels — they have distinct roles, avatars, and XP histories tracked in Mission Control.

---

A Real Example: Auto-Banning Malicious IPs

This is the event cascade that ships as the flagship demo on the Sovereignty Protocol landing page.

The setup: a Spectre crawl or inbound request logs an IP address to a PocketBase collection. An event cascade watches that collection. When a new record appears:

1. Step: geo_lookup — resolve the IP to country, city, and ISP
2. Step: agent — run the Police agent with the IP and geo data as context, generating a threat assessment
3. Step: db_write — write the ban record back to the security table with the reason, country, and report ID
4. Step: http — POST a Discord notification with the summary

The entire chain fires in seconds. No human needs to be involved. The Nexus Report is filed automatically with full step output so you can audit every decision the cascade made.

This is governed automation — not just automation.

---

Step Types Reference

Cascades are defined in YAML with a clean, readable step syntax:

• http — make an outbound HTTP request; supports GET, POST, any method
• agent — run an AI agent with a prompt and context; returns the model's response
• job — execute a background job from the job queue
• wait — pause execution for N seconds or until a condition is met
• geo_lookup — resolve an IP address to geographic and ISP metadata
• db_query — read records from any PocketBase collection with a filter
• db_write — write or update records in any PocketBase collection

Step results are referenced by name using $step_name.field$ syntax — so $geo_lookup.country$ passes the country from step one into the agent prompt in step two.

---

Automatic Nexus Reports

Every cascade run generates a Nexus Report. No configuration required — it happens automatically. Reports include:

• The cascade name, persona, and timestamp
• Full output of every step
• Duration per step and total run time
• The model used for any agent steps
• Any errors or skipped optional steps

Reports surface in Mission Control's Operations tab with per-persona sub-tabs, so you can filter by Librarian runs, Police events, or Janitor passes independently.

---

The run_on_startup Flag

Any cascade can be marked run_on_startup: true. This fires the cascade immediately when the server boots — regardless of its cron schedule or event trigger. Useful for warming up enrichment caches, running a health check on startup, or ensuring critical state is initialized before users arrive.

---

What You Can Build With Cascades

The cascade system is general-purpose. The named personas are conventions, not constraints. Some patterns teams use in production:

• Daily competitive intelligence — a Loop cascade that runs every morning, crawls three competitor domains via Spectre, and files a summary report
• Automated onboarding — a Chain cascade that fires when a new user record is created, enriches their profile, and sends a personalised welcome email
• Code quality gates — a Linter cascade that runs on every commit webhook and flags technical debt before the PR is merged
• Memory hygiene — a Janitor loop that runs nightly and deduplicates overlapping memories from the Smart Memory System

If it can be described as a sequence of steps with data flowing between them, a Nexus Cascade can run it.