10 rheos exploration

1. What rheos IS

Rheos is a Blazor Server systems-dynamics studio — a web app for building causal loop diagrams (stocks, flows, feedback loops) and running simulations on them. Tech stack: .NET 9 / ASP.NET Core / Blazor Server with AddInteractiveServerComponents, Entity Framework Core 9 over SQL Server (with a local SQLite app.db in development), Cytoscape.js for graph rendering, and hand-rolled SVG for time-series charts. Roughly ~4,000 lines across C# services + Razor pages, plus ~25K lines of CSS theme tokens. The codebase shows active iteration through April 2026 with one file (ModelEditor.razor) touched as recently as the day this review’s parent directory was last opened — and there’s a polished E2E suite under tests/ (Playwright + SPPV-organized scenarios), a guided in-app tutorial, a community feedback + roadmap surface, and an EidosImportService that pulls ontologies straight out of a sister “Eidos” SQL Server DB.

It is not abandoned, not a toy — it’s a shipped-feeling solo product with Project → SystemModel → Stocks/Flows/Scenarios/SystemModes/Notes as its data spine. The closest mental analogue is Stella/Vensim/Insight Maker in a dark-themed single-user web shell. Its self-described mission (“Model how systems change over time. Build causal loops, simulate scenarios, find leverage points”) is the lens through which to evaluate the cosmology fit.

2. Notable capabilities

Storage / data model

• Stock-and-Flow ontology — Stock (variable with initial value, min/max bounds, units, position, color, category) and Flow (typed edge with polarity +/−, strength, delay, and a FlowMode of influence vs transfer — the latter is conserved-quantity transport, which is essentially Petri-net token flow).
• SystemMode (statechart-style modes) — threshold-triggered flow-strength overrides on a stock. Inspired by Harel Statecharts: “when Stock X crosses Y, replace these flow strengths.” This is exactly the discrete-mode-switching shape a Petri-net-meets-systems-dynamics model would want.
• Scenarios + ScenarioParameters — named bundles of initial-value overrides for what-if branches.
• Project + Notes — top-level container with pinned markdown notes attached.
• FeedbackItem + Roadmap — first-class community feedback model with upvotes, status workflow (Submitted → Acknowledged → Approved → Declined), category, and three roadmap columns.

Simulation engine (SimulationEngine.cs, ~340 lines)

• Euler integrator with configurable Duration / TimeStep.
• Influence mode (rate-of-change forcing) and transfer mode (token-conserving movement between stocks).
• Delay support per-flow (look back N steps in the source’s history).
• Min/Max clamping per stock.
• Mode-aware simulation — at each step, checks active SystemModes against thresholds and applies flow-strength overrides drawn from a JSON config.
• Scenario comparison — runs a list of parameter-override bundles and bundles results for side-by-side.
• Sensitivity analysis — sweeps one parameter across N samples, records final value of a target stock, returns the curve.
• Feedback loop detection — DFS cycle finder up to depth 6, classifies each loop as Reinforcing (R) or Balancing (B) by polarity parity, deduplicates.

Narrative + validation services

• SimulationNarrator — turns a SimulationResult into plain-English markdown (“Trust grew +47%”, “Incidents more than doubled — systemic reliability risk”, “Population showed a reversal — peaked at t=24 then fell back. This suggests a delayed feedback loop is counteracting the initial trend”). Also generates compare narratives (“Scenario X improves: A, B. Worsens: C. This is a trade-off.”).
• ModelValidationService — Design-by-Contract style pre/post gates: orphan stocks, self-loops, duplicate flows, missing strengths (pre); divergence to infinity, runaway growth >100×, flatline, negative-value violations, bound hits (post).

UI / visualization

• Causal Loop Diagram canvas (cld.js + ModelEditor.razor) — Cytoscape.js with category-tinted nodes, multiple layouts (force-directed, circle, tree, grid, concentric, manual), drag-to-save positions, polarity-labeled edges.
• Time-series chart library (timeseries.js) — hand-rolled SVG renderer for single-run, scenario-comparison, and sensitivity curves with dashed-line scenario styling.
• Timeline scrubber — playhead over simulation results with progress fill, click-to-seek.
• Guided tour — GuidedTour.razor + TutorialService with multi-step explainers driven by localStorage; cleanly reusable for any first-run flow.
• Dark theme tokens (themes.css, 46KB) — the same deep-navy aesthetic family used in FuiTerminal/FuiBrowser.

Import / integration

• EidosImportService — connects to a separate SQL Server DB called EidosDb, reads Ontologies → Concepts → Relationships → Notes, and offers a 5-step wizard (ImportFromEidos.razor) to map ontology graphs into stocks-and-flows with inferred polarity from relationship-type strings (reduces/decreases/inhibits/... → −).
• ModelExportService — round-trippable JSON snapshot of a full model (name-keyed, no IDs, version-tagged).

Ops

• Auto-DB-create on startup (EnsureCreatedAsync).
• X-API-Key-guarded /api/test/reset-db endpoint for E2E orchestration.
• /api/health endpoint.
• SignalR package referenced in .csproj (though no Hubs/ directory exists in the current tree — appears to be aspirational or pruned).

3. Possible integrations with the cosmology project

A. Use Rheos’s SystemMode + SimulationEngine to model the Maintenance Procedure as a live Petri net

• Capability used: SystemModel + Stock + Flow (transfer mode) + SystemMode threshold-switching + SimulationEngine.Simulate() + SimulationNarrator.
• Cosmology surface enhanced: The maintenance-procedure Petri net the cosmology already has (per the project’s “Petri/statechart methodologies” note). Currently a static or notional model; Rheos could host it as a runnable model with real tokens flowing between places, threshold-switching mode changes, and a narrator that turns each run into prose suitable for codex sidebars.
• How it would work: Each Place in the Petri net becomes a Stock (tokens = InitialValue); each Transition becomes one or more Flows in transfer mode with Strength set to firing-rate; mode-switches (e.g., “when Caretaker awareness crosses N, swap the flow strengths into Failure Mode”) become SystemMode entries. Run a simulation, capture the JSON, render the time-series via Rheos’s SVG charts embedded as an iframe or static export, and ship the narrator output into the codex.
• Leverage: 8/10. Rheos is one of the few off-the-shelf-feeling tools that already models exactly what the cosmology’s procedural backbone wants — discrete-mode-switching continuous dynamics with feedback-loop detection. The narrator is a near-perfect fit for “in-universe maintenance log entries.”
• Effort: M. Requires standing up Rheos locally with SQL Server (or porting the SimulationEngine/SimulationNarrator C# to Python and calling from FastAPI — see §5).

B. Lift SimulationEngine + SimulationNarrator as a Python port into the alien-app FastAPI

• Capability used: The two stand-alone, dependency-free service classes (no EF, no Blazor — just lists, dicts, and math).
• Cosmology surface enhanced: /procedure (or new) page on the alien-app site. Reader visits, picks a scenario (“What if the Caretakers forget?”), sim runs in-process, narrator produces the in-universe log entry, time series renders as a chart below the prose.
• How it would work: Mechanical port — Simulate() is ~80 lines, Narrate() is ~100 lines, DetectFeedbackLoops() is a textbook DFS, AnalyzeSensitivity() is a for-loop wrapping the simulator. Define the cosmology’s procedure as YAML (stocks, flows, modes), load on app boot, expose /api/procedure/run?scenario=… returning JSON, render with any JS chart lib.
• Leverage: 9/10. This is the highest-value extraction because it sidesteps Rheos’s heavy SQL-Server + Blazor dependencies and gives the cosmology project a runnable in-universe simulation with auto-generated narration. The narrator alone is gold for codex entries: it can produce different prose every reader-visit by varying scenarios.
• Effort: S–M. ~300 lines of Python + a YAML schema + a chart component.

C. Reuse the Cytoscape CLD renderer for the concept/ontology graph

• Capability used: cld.js rendering pipeline + category-color palette + layout choices.
• Cosmology surface enhanced: The 213-concept ontology browser. Today it’s likely list/wiki style; a Cytoscape canvas with reinforcing/balancing edge polarity and category-tinted nodes would give readers a navigable cosmology map.
• How it would work: Lift cld.js (it’s vanilla, ~330 lines, no Blazor coupling). Feed it the ontology’s nodes + edges with a category field. Add click handlers that route to existing codex pages.
• Leverage: 6/10. Useful and pretty, but the cosmology project may already have a graph view, and Cytoscape is generic enough that the win is mostly the styling + category palette + drag-save behavior, not the engine itself.
• Effort: S.

D. Adopt the FeedbackItem / Roadmap pattern for reader-submitted lore questions

• Capability used: FeedbackItem model, Feedback.razor, Roadmap.razor Kanban columns.
• Cosmology surface enhanced: Reader-facing “Open Questions” or “Submit a sighting / theory / typo” surface. Roadmap becomes “Codex backlog” — what’s been requested, what’s planned, what’s written.
• How it would work: Port the schema (Title, Description, Category, Status, Votes, RoadmapColumn, SortOrder) into a FastAPI table; clone the three-column Kanban layout in Jinja. Upvotes give signal on which lore threads readers want filled in.
• Leverage: 5/10. Solid pattern, but not transformative — many sites have this. Worth it only if the cosmology project actually wants community input.
• Effort: S.

E. Reuse GuidedTour for a first-visit codex onboarding flow

• Capability used: GuidedTour.razor + TutorialService (multi-step modal with localStorage persistence).
• Cosmology surface enhanced: New reader’s first visit — explain the codex/book/wiki split, the glossary inline-tooltip system, the supporting-content data model, how to use the audio TTS, the places map.
• How it would work: The Razor component would need re-implementation in HTML/JS, but the step-data shape (Title, Description, TargetSelector, Position, Icon, ActionHint, AnimationUrl) is well-designed and copy-able. The localStorage gate logic is 5 lines.
• Leverage: 4/10. The data-shape is the asset, not the component itself. Useful, but a small win.
• Effort: S.

F. Sensitivity-analysis sweep as a “leverage point” feature in the codex

• Capability used: AnalyzeSensitivity() + SVG sensitivity chart.
• Cosmology surface enhanced: For any sub-system in the cosmology (e.g., the procedure, the visitation cycle), let a reader vary one parameter and see the curve of final outcomes. Pairs beautifully with the cosmology’s “leverage points” / “fragile equilibrium” themes.
• How it would work: Once the engine is ported (Integration B), sensitivity is ~30 more lines.
• Leverage: 7/10 conditional on Integration B already done. Cheap to add then; standalone it’s noise.
• Effort: S (after B), otherwise M.

G. Use EidosImportService as a template for ingesting the existing SQLite ontology

• Capability used: The wizard pattern (ImportFromEidos.razor) — 5 steps: select source → curate stocks → curate flows → curate notes → create.
• Cosmology surface enhanced: Authoring tool for the writer (you), not readers. Lets you pull the cosmology’s 213 concepts into a stock-and-flow simulation seed without hand-typing.
• How it would work: Read alien-app’s SQLite ontology, present a curation UI, emit a YAML/JSON Rheos-shaped model.
• Leverage: 3/10 unless you actually plan to build out the simulation (Integration A or B). Otherwise pure plumbing.
• Effort: M.

4. What rheos CAN’T or SHOULDN’T do for this project

• It is not a CMS / wiki / book platform. Don’t try to host the 150K words of prose in Rheos. Note is markdown-blob-on-Project — fine for assumption capture, terrible for chapter authoring, no glossary system, no supporting-content data model, no audio TTS.
• No real-time collaboration. Despite SignalR being in the .csproj manifest and a stale project.json claiming “real-time collaboration,” there is no Hubs/ directory, no presence service, no broadcast logic in the current tree. The reference is aspirational/leftover. Don’t plan around multiplayer.
• No authentication / authorization. The only auth is an X-API-Key header gate on a test-DB-reset endpoint. There’s no user model, no login, no per-project ACLs. Publishing Rheos as a reader-facing layer would require building auth from scratch.
• Blazor Server is a poor reader-facing fit. It requires a persistent SignalR socket per user; cold loads are heavy; doesn’t degrade gracefully. The cosmology site is well-served by FastAPI’s static rendering. Embedding live Blazor in the cosmology site would be a regression in load behavior and infra cost.
• SQL Server dependency. Rheos defaults to localhost,1433 with a hardcoded sa password. Dev mode points at a SQLite Data/app.db, but EF Core is configured with UseSqlServer in Program.cs — porting to SQLite requires a provider swap, not just a connection-string change. The Eidos integration is SQL-Server-only (Microsoft.Data.SqlClient, T-SQL syntax with TOP/bracket idioms).
• Solo-user assumptions throughout. No multi-tenancy, no project ownership, no rate limiting, no audit log. Fine for a desktop modeling tool; wrong shape for a published reader-facing simulation.
• The Cytoscape canvas doesn’t know about narrative. It’s a graph-of-numbers, not a graph-of-story. Asking it to render a character-relationship graph or a chapter-dependency graph means re-skinning, not reusing.
• The validation/contract framing is engineering-flavored. “Stock diverged to infinity — check flow strengths” is great for a sim author; it’s not in-universe diegetic. The narrator is much closer to story-usable than the validator.

5. Recommendation

Yes, but selectively, and don’t run Rheos itself — port the parts that matter. The valuable artifact in this repo is the SimulationEngine + SimulationNarrator pair (~500 lines of dependency-free C# that translates cleanly to Python), together with the SystemMode data model (the Harel-statechart mode-switching pattern that maps almost directly onto the cosmology’s procedural Petri net). Everything else — the Blazor UI, the SQL Server backing, the Eidos importer, the roadmap surface — is interesting but either a poor fit for a reader-facing literary site or low-leverage versus what already exists.

Minimum-viable first integration: Port SimulationEngine.Simulate(), DetectFeedbackLoops(), and Narrate() into a small Python module inside alien-app (call it cosmology/sim/). Define the maintenance procedure as a YAML file: 6–10 stocks (Caretaker Awareness, Visitor Pressure, Ritual Integrity, …), 10–20 flows in transfer mode, and 2–3 system modes for the “things go wrong” / “things go right” branches. Wire one FastAPI endpoint /procedure/run?scenario=baseline|degraded|restoration that returns JSON. Drop the narrator output into a codex sidebar as an in-universe “Caretaker’s Last Log” entry that varies per scenario. If readers respond to it, layer in Integration F (sensitivity sweep) and Integration C (Cytoscape graph of the cosmology’s concept ontology). Skip Integrations D, E, G unless you have a separate reason to want them.

Do not stand up the Rheos Blazor app as a parallel service or attempt to embed it in the alien-app site. The cost (SQL Server, auth, deployment, Blazor Server’s socket model) is wrong for the use case. Treat rheos as a reference implementation and source of two excellent algorithm files, not as a deployable component.