A geometry-driven execution substrate where autonomous agents — Flatlanders — move and interact inside a curved manifold, and the geometry itself constrains what they can do. THEVM treats a manifold as the computer. Instead of instructions running on a flat memory model, processes flow along geodesics through a space that can be flat, toroidal, cylindrical, curved, or a discrete graph. Curvature bends motion, topology creates wraparound and holonomy, and region policy shapes which operations are permitted where. The system measures the emergent behavior that results.
It ships in two halves: the Manifold VM core — a backend-agnostic Java library of geometry, agents, an execution runner, and a metrics layer, built around a deliberately strict interface contract; and the Workbench — a Spring Boot web app with a Three.js + OpenCV.js frontend for authoring manifold seeds from drawn curves or optimization output, compiling them into live manifolds, and visualizing their curvature in 3D.
active · v1This is an architecture project first. Four design decisions the code takes seriously:
RegionCapabilities answers what the geometry permits — can an agent spawn, merge, jump layers, wrap around here? RegionPolicy answers how the runtime should weight or correct behavior right now. Capabilities never encode policy, and policy never claims a structurally-impossible operation. The split keeps "the shape of the world" independent from "the rules of the game."AttributeConventions, CommonEventTypes, CommonTopologyTypes…). No new key is allowed without a named constant first. The flexible Map<String,Object> surfaces stay auditable instead of becoming a free-for-all.PRESERVE / APPROXIMATE / FLATTEN) and must not quietly remove the effect — because that holonomy is exactly the kind of emergent geometric behavior the VM exists to study.executeStep(...). The simulation is agent-driven, not orchestrator-driven.The layers stack bottom-up: geometry primitives are backend-agnostic; the manifold binds them into a space with capabilities and policy; Flatlanders act inside that space; the runner advances time and emits immutable snapshots; and the metrics layer measures what emerges.
Module map:
| package | responsibility |
|---|---|
| machine | Core interfaces + convention registries — the contract everyone implements. |
| manifolds.continuous | Continuous-manifold contracts; implementations: FlatPlane, ToroidalManifold, CylindricalManifold, CurveManifold. |
| manifolds.discrete | Graph-based manifold contracts + a layered discrete-graph implementation. |
| execution | Runner, intersection handling, geodesic flow engine, SOM vector sink / observer. |
| metrics | Emergence and performance metrics implementations. |
| workbench | Spring Boot REST app: seed ingestion → validation → manifold compilation → curvature sampling → visualization. |
Manifolds implemented:
| manifold | backend | curvature | notable behavior |
|---|---|---|---|
| FlatPlane | continuous | K = 0 | Euclidean baseline. |
| ToroidalManifold | continuous | K = 0 | Periodic wraparound in both dimensions; multiple geodesics; non-trivial winding on non-contractible loops. |
| CylindricalManifold | continuous | K = 0 | Wraparound in one dimension. |
| CurveManifold | continuous | varies | Built from sampled curve points — the manifold the Workbench currently compiles seeds into. |
| SimpleDiscreteGraphManifold | discrete | n/a | Layered graph topology with layer-jump transitions. |
The Workbench turns a 2D input — a drawn curve or an optimization / solver output — into a compiled manifold and renders its curvature field in 3D. Pipeline: validate → parse & normalize → build ManifoldSpace → sample curvature → interpret gates → store → assemble response.
| method & path | purpose |
|---|---|
| POST /seed | Submit a manifold seed; returns the compiled descriptor, normalized curve, curvature samples, and gate descriptors. |
| GET /{id} | Fetch the compiled descriptor for a stored manifold. |
| GET /{id}/curvature | Sample the curvature field across the manifold (?resolution=N). |
| GET /{id}/gates | Gate descriptors — hotspot-derived regions. |
| POST /{id}/simulate/dry-run | Probe simulation (roadmap). |
| GET /workbench | Serves the interactive Three.js workbench UI. |
Requirements: Java 21, Maven 3.8+. The first build downloads Spring Boot 3.2 dependencies, so it needs network access once; subsequent builds work offline.
An actively-developed v1. The architecture and the geometry layer are the mature parts; some higher layers are intentionally scoped as clean-boundaried stubs rather than half-finished features.
- doneCore interface contract, convention registries, capability / policy split.
- doneContinuous manifolds (flat, torus, cylinder, curve) with geodesics, parallel transport, and curvature.
- doneDiscrete layered-graph manifold.
- doneWorkbench: curve & optimization-output seeds → compiled
CurveManifold→ curvature sampling → 3D visualization. - wipWorkbench
dry-runsimulation — endpoint is wired; the probe-actor simulation behind it is the next layer. - wipSOM-output seeds — the
som_outputbuilder is not yet implemented. - wipEmergence metrics — snapshot plumbing exists; clustering / similarity scoring currently returns conservative placeholders.
- wipWiring torus / cylinder / discrete manifolds into the Workbench authoring path — they exist in the core library today.