Decision log

← Back to docs · Architecture

Sources: the project roadmap (Decisions, Open questions) and the change proposals. Neither port-foundation, open-source-audit nor protocol-core has a design.md; their rationale comes from proposal.md. Dates are the dates recorded in the source, or the ROADMAP's last-updated date (2026-11-13) where none is given.

Full decision table (97 entries, click to expand)
IDDecisionRationaleDate
R1Incremental replacement, not a single rewriteGrid services are stateless HTTP/XML-RPC over a database, so each can be swapped while C# simulators run; every phase ends in something runnable2026-11-13
R2Wire and schema compatibility is the contract (LLUDP, caps, service protocols, OAR/IAR, DB schema)Existing grids must migrate without losing content; internals may change2026-11-13
R3Physics: server-authoritative, engine behind a trait, Rapier backendViewers extrapolate from server updates, so the engine is invisible on the wire and can be chosen on merit2026-11-13
R3aRapier 0.36.1 confirmed as the physics engine after the parity spike (GO); Jolt remains the fallback behind the same trait. Vehicle and avatar behaviour are ported once above the trait from ODEDynamics.cs and ODECharacter.csPure Rust, no FFI or C toolchain; native ubODE/BulletSim would still need the C# behaviour layers rewritten. Spike: collider types, CCD, snapshot and Aurora geometry all work (see docs/physics-backend-summary.md)2026-11-13
R4Scripts: embed SLua (Luau fork) for LSL and LuauSerialisable execution state, memory limits and pre-emption hooks are needed for scripts that cross regions; gives Luau for free and replaces writing a VM2026-11-13
R5Database: sqlx over the existing schema (MySQL/MariaDB, PostgreSQL, SQLite)Keeps schema compatibility; drops Oracle MySql.Data2026-11-13
R6Voice: WebRTC only, via wolfvoice sidecarVivox is proprietary; Aurora supports WebRTC only; FreeSWITCH not ported2026-11-13
R7 / D1Licence LGPL-3.0-or-later, reuse Aurora cratesLets Aurora's GPL crates be linked as dependencies; "or later" matches Aurora's manifest; BSD notices of ported code are preserved; AGPL not adopted because GPLv3 does not oblige network-only operators to publish and that was judged sufficient2026-11-13
R8Workforce: beam:cloud workers code and first-review; Claude writes proposals and signs offCost and review discipline2026-11-13
D2Repository welkin, local git only, no remoteOperator decision2026-11-13
R9Pathfinding not plannedOperator decision2026-11-13
A1Aurora crates are pinned git dependencies at 3d523b1 and always wrappedUnpublished, version 0.1.0, change daily; wrapping confines API churn to one crate2026-11-13
A2aurora-net used for the test bot onlyIt is the viewer side of the protocol2026-11-13
A3Gaps in Aurora (viewer-only decode paths) are filled here and offered upstreamAurora is a viewer; server needs the opposite direction2026-11-13
P1Config in TOML with env overrides, plus INI importerReplaces Nini; existing OpenSim.ini/Robust.ini must be importable2026-11-13
P2Observability via tracing and PrometheusReplaces log4net and the stats console2026-11-13
P3One multi-stage Containerfile, static binaries, non-root, Podman and DockerPortable images, small attack surface2026-11-13
P4Conformance harness: record C# request/reply pairs, replay against Rust, pCampBot wrapperWithout it phases are judged by eye2026-11-13
P5Throttle and resend behaviour match LLUDPClient/LLUDPServer closelyViewer would stall or flood otherwise (risk MEDIUM)2026-11-13
P6Updating the Aurora pin is a reviewed change gated by replay testsProtects against upstream churn2026-11-13
L1Drop Vivox, FreeSWITCH, Oracle MySql.Data, CSJ2K, Warp3D (reimplement)Proprietary, legacy, or non-compatible/unknown licences (see docs/licence-audit.md)2026-11-13
S1Data layer is one sqlx store per service, with the C# schema files embedded and applied by a migration runner (e3f9c79, 33c5026)Implements R5; a C#-created database opens unchanged and all three backends share one API2026-11-13
S2Handlers reproduce the C# Robust wire format exactly, checked by replay fixtures (c7229de, 9593604)R2; mixed grids with C# simulators must keep working2026-11-13
S3Simulation service is a 501 stubNot needed for login or the replayed flows; deferred to the region phase2026-11-13
S4Password hashes are compared in constant time (840f769)Security review finding M1: == on MD5 hashes leaks timing2026-11-13
S5Admin-style endpoints are not gated in code; deployments must restrict them by network or proxySecurity review noted it; matches C# Robust, which relies on the same arrangement2026-11-13
C1Capacity estimate comes from sourced coefficients now; the on-host benchmark, calibration and live refinement are stubs until region-simulator-core (97f5ebd, 880338a)The benchmark needs a running simulator; the proposal already allows a labelled estimate before that. Result carries is_measured: false2026-11-13
C2Estimate is a range of 80% to 120% of the point value, reserves one core, and names the limiting resource (97f5ebd)Proposal risk is MEDIUM: an overestimate overloads a machine, so no unqualified number is shown2026-11-13
C3Network speed and public IP are manual configuration for now (97f5ebd)Speed test and address detection deferred; bandwidth limit applies only when upload speed is set2026-11-13
G1Desktop companion is a Tauri 2 app, optional, excluded from the Cargo workspace (e8ddfd8)Operator decision; one set of portal pages serves browser and control window, and tray-icon covers Windows, macOS and Linux. Needs WebKitGTK on Linux; GNOME needs a tray extension2026-11-13
G2Portal staff and sign-up passwords use argon2; sign-up passwords are hashed at registration (ddba6d0, 59eea64)Security review H3: plaintext in memory is not acceptable. TOTP rejects accounts that have a secret until implemented (H1), which fails closed2026-11-13
G3Portal follows the GridGate model: Admin/Operator/Viewer roles, sign-up with approval, map placement, one-command install (ddba6d0)BSD-licensed model in the roadmap, so pages and flow can be adapted; roles enforced in code (H2)2026-11-13
G4Portal is not for public exposure until security review items M1 to M5 are fixed; restrict by network or proxy meanwhileReview assessment; same arrangement as S52026-11-13
M1Box and sphere prims use analytic colliders; other prims use aurora-prim trimeshes with LOD chosen by sizeCheaper and exact for the common case; LOD thresholds match C# Meshmerizer2026-11-13
M2Convex decomposition uses parry3d V-HACD, with C# voxel budget mapped to a grid size clamped to 16 to 256, results cachedNo new dependency; C# parameters kept for parity (max_vertices_per_hull advisory only)2026-11-13
M3Sculpt textures come through a SculptTextureSource trait; JPEG 2000 decoding deferredKeeps meshing testable and leaves the aurora-assets versus pure Rust question open2026-11-13
M4Mesh asset decoding is treated as untrusted: indices validated, zlib output capped at 32 MiB, cache mutexes recover from poisoning (1812e45)Security review CRITICAL-1, HIGH-1, MEDIUM-32026-11-13
N1Scene objects persist and interchange as XML2, round-tripped against C# outputR2; lets a C# region database and OAR content load unchanged2026-11-13
N2SimulationDataStore trait in welkin-data with one sqlx implementation over the existing regionstore tablesR5; no migration for C#-created region databases2026-11-13
N3LLUDP viewer messages dispatch through a table keyed on message id to typed handler functions, not a large classReplaces the 13k-line LLClientView; handlers are testable alone2026-11-13
N4Several Scenes per process via RegionManager; caps HTTP server runs beside the LLUDP listenerMatches C# multi-region hosting2026-11-13
N5Terrain modification brushes ship with the scene crate, not a later moduleHeightfield belongs to the scene graph and OAR load needs it2026-11-13
N6Region simulator accepted as CONDITIONAL PASS: client map and mpsc channels must be bounded and stale sessions reaped before production; restrict by network meanwhileSecond review, 3 HIGH findings in the net stack; same arrangement as S5 and G42026-11-13
E1Grid choice is a TOML profile (standalone, own-grid, custom); Hypergrid is a switch inside a profile (8f35477)The grid a region joins must be configuration, not code
E2The OSgrid profile is generated by importing OSgrid's own GridCommon.ini, not hand-writtenAddresses are never copied from memory and can be refreshed
E3Hypergrid ships as six traits with stubs, no live implementation (91a1147)Fixes the protocol surface now; behaviour needs a live grid to verify
E4OSgrid setup rules are wizard checks, not documentation only (91a1147)Name, coordinate, estate owner and port mistakes are caught before registration
E5Replay recording (3.2) and live attach (3.4) deferred to Phase 7 cutover (0b0f587)Needs live C# region and grid infrastructure and an answer from OSgrid
E6External-grid mode accepted as CONDITIONAL PASS: SSRF fix and the 4 HIGH fixes are required before any untrusted grid; osgrid and custom stay disabled meanwhile (e46a2dd)Security review of remote write paths, hostile-grid threat model
V1Go on Luau via mlua 0.12, not a custom VM; LSL runs through a transpiler to Luau (d413580)Spike passed: yield, memory limit, interrupt pre-emption and state serialisation all work2026-11-13
V2Script state persists as bytecode plus globals JSON (checkpoint pattern); coroutine stacks are not saved (3fb1cbd)Luau cannot snapshot a coroutine stack; scripts restart their event after transfer2026-11-13
V3One Luau VM per scriptStrong isolation; memory limit applies per script2026-11-13
V4os* functions are gated by an 8-level OsslThreatLevel with a per-function allow override (a5539f5)Mirrors C# OSSL threat levels so existing grid configuration carries over2026-11-13
V5ll* functions not yet needed are registered as stubs (33 of 82)Keeps the function table complete so scripts compile and run2026-11-13
V6Script engine accepted as CONDITIONAL PASS: freeze globals with sandbox(true) in ScriptInstance and bound the event queue before production (dd1177d)Second review, 2 HIGH findings; same arrangement as S5 and G42026-11-13
O1os* functions are gated at registration: a function that fails the threat check is never placed in the Lua globalsStronger than the C# call-time check; no bypass through a missed check. Cost: role checks need caller context (see O6)2026-11-13
O2Access is a global threat ceiling plus per-function FunctionPerm (Disabled, Everyone, AllowList of roles and UUIDs)Reproduces C# Allow_<Function> semantics so existing INI files carry over2026-11-13
O3Macros (osslParcelO, osslParcelOG, osslNPC) are expanded when the INI is loadedKeeps is_allowed() free of string handling; expansion needs a depth bound (review S7)2026-11-13
O4Functions whose subsystem is absent are registered as stubs that log and return a default; 233 registered, catalog test fixedScripts compile and run; each stub is replaced by the change that adds its module (same approach as V5)2026-11-13
O5AES key and IV derive by PBKDF2-HMAC-SHA1, 1000 iterations, salt OpenSimulator OSSL, not SHA256 (review S1).NET Rfc2898DeriveBytes uses SHA1; SHA256 broke ciphertext interchange with C# regions2026-11-13
O6OSSL accepted as CONDITIONAL PASS: commit the S1 fix, enforce role checks at call time (S2) and remove expect() from crypto (S3) before productionSecond review; same arrangement as S5 and G42026-11-13
RM1Region modules live in one crate, welkin-modules, split by module directorySingle dependency for the region binary; shorter than the welkin-region-modules name in the design2026-11-13
RM2Modules implement a RegionModule trait with Shared/NonShared types and a four-step lifecycleMaps C# IRegionModuleBase, ISharedRegionModule and INonSharedRegionModule one to one2026-11-13
RM3Interfaces are found through a TypeId-keyed registry, not reflection or globalsRust has no runtime type discovery; explicit registration is checkable2026-11-13
RM4Module-to-module notifications use a typed tokio::sync::broadcast event bus (SceneEvents)Subscribers are independent; replaces C# scene event delegates2026-11-13
RM5One tiny-skia renderer replaces LegacyMap and Warp3DMapOne pure Rust path, no GDI or Warp3D dependency2026-11-13
RM6FlotsamAssetCache uses a HashMap and VecDeque LRU, no moka; disk tier is a stubSimple and sufficient for now2026-11-13
RM7Hypergrid parts, OAR/IAR and groups/profiles are out of this change (hypergrid, archives, social-modules)Keeps the change bounded2026-11-13
RM8Region modules accepted as CONDITIONAL PASS: fix C-1 (nil UUID) and H-1 before a multi-user grid, H-2, H-3 and M-4 before production; restrict by network meanwhile (d33ef2c)Opus adversarial review of permissions; same arrangement as S5 and G42026-11-13
AR1Replace C# custom tar (455 lines) with tar + flate2 cratesCrate handles edge cases (long paths, symlinks, permissions) correctly; less code to maintain2026-11-14
AR2Async asset gathering with tokio::time::timeout replaces C# ManualResetEvent + timerIdiomatic Rust async; same timeout semantics2026-11-14
AR3OAR load options (merge, displace, rotate, bbox) are a flags struct, not positional argumentsType-safe; matches the C# Dictionary<string, object> semantics without the stringly-typed API2026-11-14
AR4OspResolver writes first.last profiles on save and resolves on load, with UserManagement fallbackPreserves cross-grid UUID portability; fallback handles grids without profile data2026-11-14
AR5Path traversal protection: all tar paths validated against expected prefix before processingDefense in depth over tar crate's built-in protection; rejects ../, absolute, null bytes, drive letters2026-11-14
AR6Archives accepted as CONDITIONAL PASS: fix M-1 through M-5 before production (decompression bomb limit, Vec allocation cap, reject non-UTF-8 paths, null byte check, drive-letter check)Opus adversarial review; same arrangement as S5 and G42026-11-14
SM1Port Groups V2 only; drop legacy XmlRpc connector (3,991 lines)V2 is cleaner, supports HG, and is the default in 0.9.3.02026-11-14
SM2NPCAvatar implements only methods actually called by NPCModule; rest are no-opsC# has ~1,400 stub lines; 241 lines is sufficient for the real call paths2026-11-14
SM3IRC bridge uses irc crate (MPL-2.0) instead of porting C# IRC clientMPL-2.0 is GPLv3-compatible; proven crate, less code to maintain2026-11-14
SM4OfflineIM uses same sqlx backend as other servicesNo separate storage engine needed; consistent with grid-services pattern2026-11-14
SM5Social modules accepted as CONDITIONAL PASS: fix H-1 (IRC injection), H-2 (group creation power), H-3 (notice attachment size) before production; IRC bridge must not go live until H-1 is resolvedOpus adversarial review; same arrangement as S5 and G42026-11-14
H1HG modules extend base modules via trait composition, not separate implementations; HGEntityTransferModule wraps EntityTransferModuleBase modules are already ported; composition avoids duplication and keeps overrides explicit2026-11-14
H2UUI format (uuid;griduri;name) stored alongside local UUIDs; HGUserManagementModule resolves first.last@griduri to local cacheMatches C# HG identity model; cache avoids repeated cross-grid lookups2026-11-14
H3Suitcase inventory uses path validation with root-anchored check to prevent directory traversalDefense in depth over folder-ID checks; foreign visitors must not escape their suitcase2026-11-14
H4Traveling agent sessions use cryptographically random tokens, single-use, expire on logoutPrevents replay and prediction; stronger than C# which uses predictable session IDs2026-11-14
H5HELO probe discovers HG capability before attempting cross-grid operations, with timeout and retryAvoids wasting resources on grids that don't support HG; graceful degradation2026-11-14
H6Hypergrid accepted as CONDITIONAL PASS (CRITICAL RISK): fix F-01 (suitcase escape), F-02 (VerifyAgent), F-03 (UUID impersonation) and all HIGH findings before any public-facing deploymentOpus adversarial review; same arrangement as S5 and G42026-11-14
WV1JSON-RPC over HTTP to wolfvoice, not gRPCSimpler, no protobuf dependency, matches wolfvoice's documented API2026-11-14
WV2Channel URIs use webrtc:region/parcel format, not SIP URIsAurora Viewer expects WebRTC format2026-11-14
WV3Voice credentials are ephemeral per-session, not stored in the databasewolfvoice manages credential lifecycle; no new DB columns2026-11-14
WV4Estate and parcel voice-enable checks reuse existing flags from region-modulesNo new database columns needed2026-11-14
WV5WebRTC voice accepted as CONDITIONAL PASS: fix H-1 (wolfvoice auth) and H-2 (rate limiting) before production; wolfvoice sidecar must not accept unauthenticated JSON-RPCOpus adversarial review; same arrangement as S5 and G42026-11-14

Open questions

  • OSgrid: whether it accepts regions on third-party software; administrators must be asked.
  • Provenance of bin/openmetaverse_data, bin/assets and the message template header.
  • JPEG 2000: aurora-assets (openjpeg-sys, C) versus a pure Rust decoder.