Technical Architecture

Inside the continuum.

One memory-safe Rust continuum for geometry, physics, optimization, and rendering, organized as seven strictly-acyclic layers, L0 → L6 — where derivatives, error bounds, budgets, provenance, and cancellation ride inside the values.

click a layer to inspect · trace a request to see dataflow
▽ Franken constellation — asupersync · FrankenSQLite · FrankenNumpy · FrankenTorch · FrankenScipy
Request Lifecycle

The dataflow.

A single request threads the whole continuum — lowered to a task DAG, scheduled, solved, and recorded, with evidence bubbling back up.

HELM lowers an agent's FrankenScript program to a task DAG; the DAG's nodes are budgeted, cancellable kernel invocations scheduled by SUBSTRATE; MORPH supplies geometry as charts of Regions; FLUX turns charts into complexes, cochains, and solved fields with adjoints and error estimates; ASCENT consumes objectives, gradients, and confidence sequences to propose new designs; LUMEN renders anything on demand; and every artifact and event lands in the Ledger.

L6
HELMlowers an agent’s FrankenScript program to a task DAG.
L0
SUBSTRATEschedules the DAG’s nodes as budgeted, cancellable kernel invocations across the two-lane executor.
L2
MORPHsupplies geometry as charts of Regions, routed to whatever representation the task needs.
L3
FLUXturns charts into complexes, cochains, and solved fields — with adjoints and error estimates attached.
L4
ASCENTconsumes objectives, gradients, and confidence sequences to propose new designs.
L5
LUMENrenders anything on demand — the marketing shot and the physics are the same bytes.
LEDGERreceives every artifact and event, content-addressed and event-sourced, so a result always knows how it was made.

Nothing crosses a layer boundary implicitly. Budgets, seeds, units, versions, and capabilities travel with the call; adjoints and error slices travel with the result.

The Stack

Seven strictly-acyclic layers.

Dependencies only ever point downward, L6 → L0. Each layer is a named region of the workspace, colored on the spectrum, carrying its own crates — and a mechanical xtask check fails any build that would create a cycle.

The cross-cutting spine
Three crates are carried at every layer — quantities, observability, and evidence — so units, events, and certificates are never bolted on afterward.
fs-qtyfs-obsfs-evidence
L6
HELM
Helm
Orchestration, ledger & agent interface

FrankenScript IR, sessions & capabilities, the Design Ledger, the plan-cost oracle, reports, and the agent API. The one true interface.

fs-irfs-sessionfs-ledgerfs-recomputefs-planfs-rooflinefs-vskeleton7 crates
L5
LUMEN
Lumen
Rendering & visualization

Spectral path tracing, direct chart rendering, deterministic image plumbing, and differentiable rendering where the marketing shot and the physics are the same bytes.

fs-img1 crate
L4
ASCENT
Ascent
Optimization & uncertainty

Shape / topology / global / derivative-free optimization over manifold variables, e-process racing, constraint calculus, and SOS certificates.

fs-optfs-dfofs-constraintfs-eproc4 crates
L3
FLUX
Flux
Physics kernel

Exterior-calculus FEEC, CutFEM-on-SDF, structure-preserving integrators, constitutive laws, matrix-free solvers with adjoints, and certified speculation.

fs-feecfs-opdslfs-solverfs-timefs-materialfs-scenariofs-regimefs-ladderfs-ifacefs-verify10 crates
L2
MORPH
Morph
Geometry kernel & representations

The Region / Chart abstraction, the Rep Router, SDF / mesh / F-rep / NURBS / voxel charts, geometric algebra, uniform queries, topology & manufacturability certificates.

fs-geomfs-rep-sdffs-rep-meshfs-rep-frepfs-rep-nurbsfs-rep-voxelfs-xformfs-meshfs-gafs-queryfs-topofs-geoconfs-io13 crates
L1
BEDROCK
Bedrock
Numerical foundations

Deterministic dense / sparse / FFT linear algebra, certified interval & Taylor arithmetic with exact predicates, Chebyshev spectral methods, QMC RNG, and autodiff.

fs-mathfs-lafs-sparsefs-fftfs-ivlfs-chebfs-randfs-ad8 crates
L0
SUBSTRATE
Substrate
Hardware, execution & determinism

Machine topology & SIMD dispatch, aligned arenas, the two-lane cancellable executor, tile kernels, structure-of-arrays, and the safe tile-kernel DSL.

fs-substratefs-simdfs-allocfs-execfs-soafs-soa-derivefs-tilelangfs-tilelang-macros8 crates
▽ Franken constellation (the only runtime deps, locked by hash) — asupersync · FrankenSQLite · FrankenNumpy · FrankenTorch · FrankenScipy · FrankenPandas · FrankenNetworkx
L0 · Substrate

The substrate, up close.

Everything above L0 borrows its two guarantees: a bounded latency-to-cancel and bit-identical arithmetic, no matter how many cores you throw at it.

L0 · The Two-Lane Executor

latency lane + work-stealing throughput lane · latency-to-cancel ≤ 200µs

idle
latency lane · async orchestration · ledger I/O · responses ≤100msrespledgerprogresspollthroughput lane · fork-join work-stealing pool · unit of work = TILEworker W0worker W1worker W2worker W3steal queue →
L0 executor idle · latency lane ≤100ms · throughput lane: work-stealing fork-join

The executor runs two lanes: a latency lane for async orchestration, ledger I/O, and progress, running alongside a throughput lane — a work-stealing fork-join pool whose unit of work is a cache-aligned tile. A cancel request never waits behind a long compute: the design target is a bounded latency-to-cancel of ≤ 200 µs, and speculative races kill their losers mid-solve.

Determinism is a feature, not an accident

fixed-shape reduction trees → bit-identical across runs, threads, ISAs

threads8
naive parallel sumFrankenSim fixed-shape reduction tree0.10.20.30.40.50.60.70.8Σt06Σt11Σt23Σt37Σt48Σt54Σt65Σt72combine order (scheduler-dependent, varies) ↓accumulator0.10.20.30.40.50.60.70.8Σ0x3FF921F921✗ varies with thread count & interleaving0x3FF921F9B7✓ stable · bit-identical for any thread count
threads
threads: 8 · naive: 0x3FF921F921 (varies ✗) · franken: 0x3FF921F9B7 (stable ✓ bit-identical)

Determinism is not a debug mode — it is a property of the reductions themselves. Fixed-shape reduction trees, counter-based RNG keyed by logical identity, and compensated summation make results bit-identical across thread counts and (best-effort) ISAs. The same study replays byte-for-byte on one core or ninety-six.

Performance

Roofline-honest.

Every kernel ships its arithmetic-intensity analysis against measured machine peak. A performance claim is a fraction of a roof, never a bare number — and the targets are stated so they can be failed.

Roofline-honest kernels

arithmetic intensity vs machine peak · every kernel ships its roofline analysis

Apple M4 Max
0.11101001001karithmetic intensity — FLOP / byte (log)performance — GFLOP/s (log)ridge 2.9546 GB/s roof1.6 TFLOP/s peakGEMM f64 · 78%SDF sphere-traceFEEC applyFFTLBM D3Q19SpMVmemory-bound (bandwidth)compute-bound (peak)
machine
machine: Apple M4 Max · 546 GB/s · 1.6 TFLOP/s peak · ridge 2.9 FLOP/byte GEMM f6478% of peak · compute-bound · I=18 FLOP/byte
Apple M4 Max
16-core (12P + 4E) · ~546 GB/s unified · 128-byte lines
~34 GB/s per core
Threadripper PRO 7995WX
96 cores · 12 CCDs × 32 MB L3 · AVX-512
~3.4 GB/s per core

The two reference machines are deliberately opposite. The M4 Max pairs modest core counts with a huge unified bandwidth; the 96-core Threadripper starves each of its many cores. Bandwidth-per-core inverts by roughly 10× between them — so a kernel that is compute-bound on one is memory-bound on the other. The roofline registry stores both roofs, and the harness measures against real peak on each, refusing to let a folklore number stand in for a proof.

The Bridge

Geometry ↔ physics.

The hardest seam in simulation is the one between the shape and the field. FrankenSim routes representations and differentiates through the solution so that seam becomes a typed, certified value.

idle — pick a source chart
ΩRegion (never stored)0.3 / 2e-30.35 / 2e-30.6 / 8e-30.5 / 6e-30.15 / 4e-30.4 / 2e-30.2 / 1e-30.95 / 9e-30.35 / 3e-3SDFMESHF-REPNURBSVOXELerr budget 5e-3 · click Region charts to route
chosen chainrejected · over err budgetlegal alternativeedge label = cost / err

A Region is an abstract subset of space, never stored directly — it is only ever presented by Charts: SDF grids, half-edge meshes, F-rep trees, NURBS patches, voxel fields. When a task needs a different representation, the Rep Router solves a Pareto shortest-path problem over the graph of chart-to-chart conversions, picking the cheapest chain that respects your error budget — and every conversion emits a certificate.

Adjoint-native gradients

differentiate through the solution — not through the iterations

implicit function theorem
design paramsp ∈ ℝ¹²⁸p₀p₁p₂p₃p₄p₁₂₇assembleK(p), f(p)forward solveK·u = fobjectiveJ(u, p)dJ/dp = ∂J/∂p − λᵀ·∂R/∂p — one linear solve, gradient for every pcost to get ∇J over 128 paramsadjoint≈ 2 solvesfinite-diff128 solves
gradient checks gate every merge
adjoint-native gradients · press Play

Gradients are adjoint-native: FrankenSim differentiates through the converged solution via the implicit function theorem, not by unrolling solver iterations. Sensitivities are exact and cheap, the same matrix-free apply serves the forward and adjoint passes, and a gradient check gates every merge — differentiability is a build requirement, not an afterthought.

Non-Negotiables

The Decalogue.

Ten commitments the architecture is built to keep. Every crate, every merge gate, and every refusal traces back to one of them.

P1

Pure, memory-safe Rust

One language, Franken-constellation dependencies only. Unsafe lives only in audited leaf capsules under 300 lines, each behind a safe façade.

P2

Determinism is a feature

Bit-identical across runs, thread counts, and (best-effort) ISAs — via fixed-shape reduction trees, counter-based RNG keyed by logical identity, and compensated summation.

P3

Differentiable or certifiable

Every operator is differentiable, certifiable, or ideally both. Gradients are checked at the merge gate; error bounds are first-class.

P4

Budgets first

Every operation takes an accuracy / time / memory budget. The Error Ledger and Time Ledger compose them end-to-end and attribute every digit and every second.

P5

Structure over brute force

Exact discrete de Rham (d∘d = 0), symplectic integrators, power-conserving ports. Preserve the math instead of resolving it away.

P6

Matrix-free & roofline-honest

Kernels ship their arithmetic-intensity analysis against machine peak. No dense assembly where a matrix-free apply will do.

P7

Cancellation-correct compute

Cancellation is a numerical primitive. Bounded latency-to-cancel of ≤ 200 µs; speculative races kill their losers mid-solve.

P8

One data model

Complexes and cochains, everywhere. Geometry, fields, and operators share a single typed algebra instead of six incompatible schemas.

P9

Provenance-complete

Content-addressed artifacts, event-sourced operations, and explain(artifact): a result always knows how it was made.

P10

Agent-first ergonomics

The Five Explicits — units, seeds, budgets, versions, and capabilities — are never implicit, ever. Built for the swarm, compatible with humans.

Agent-First Ergonomics

The Five Explicits.

The five things a FrankenScript program can never leave unsaid. This is what makes the whole system safe for an agent swarm to drive — never implicit, ever.

Units

Dimensional quantities are compile-time typed. A meter never silently becomes a second.

Seeds

Counter-based RNG keyed by logical identity. Every random draw is reproducible by construction.

Budgets

Accuracy, time, and memory ceilings travel with every call and compose across the whole plan.

Versions

The constellation is locked by hash. The kernels that produced a result are always recoverable.

Capabilities

The Cx context grants exactly what an operation may touch — arena, cancel token, ledger, budget.

Seven layers. 54 crates.

You have seen the shape of the continuum. Now walk the crate inventory, or trace the phases that build it — each one Gauntlet-gated before it ships.