Axylith

What this document is.

This is a reference document describing the design of a software system called Axylith. It is published as prior art by the original author, the originating organization (Axylith), and the public commit history of the repository in which it lives.

The purpose of this document is twofold. First, to articulate — precisely and at length — the system that Axylith is, the systems it replaces, the assumptions it makes, and the technical commitments it stands behind. Second, to establish a clear, dated, cryptographically signed record of conception and design ownership prior to any subsequent employment, contract, or affiliation the author may enter into.

Every claim in this document is the author's own work, conceived independently and developed outside the scope of any employer, client, or third party. The repository in which this document lives carries signed git commits with timestamps verifiable through GitHub's infrastructure. The publication URL, the commit SHAs, and the signatures together constitute the evidentiary trail. No part of this document derives from, depends on, or describes intellectual property belonging to any other party.

Why this exists.

I am pissed off that AI is not this.

Not AI is bad — that is lazy and it is not true. The models are extraordinary. The wrapper around them is broken. Every AI tool I have used treats the model as a chat partner you talk to about your work, not a collaborator in your work. You alt-tab to a browser tab, paste your code, read a response, paste the response back, find out it does not compile, paste the error, paste the fix. The bandwidth between the AI and the actual work surface is a clipboard. The interaction is stateless. Every conversation starts cold. The AI never sees what you are building — it sees screenshots of what you are building.

And when it does give you an answer, it gives you the what without the why. Replace this with that. Okay, but why? Is my version wrong, or just slower? Is it a syntax issue, a concept issue, or a performance issue? Is it an idiom thing or a correctness thing? The current generation of AI tools answers the literal question and leaves the actual learning on the table.

The CUDA example is the cleanest version of this — an AI tells you use masking instead of if/else without telling you that the reason is warp divergence costing thirty times throughput at warp size 32. You walk away having "fixed" the code without understanding it. That is not collaboration. That is autocomplete with extra steps.

I want a system where the AI is inside the work surface, sees the whole document, sees the whole codebase, sees the data, and when it suggests something it tells me why. Not as a separate explanation I have to ask for — as the default mode of communication. Every diff comes with reasoning. Every parameter change comes with a rationale. Every recommendation comes with the assumption it is making, so I can correct the assumption if it is wrong.

The fragmentation problem.

To do real work today — research, building, learning, all of it — I need Obsidian for notes, Jupyter for compute notebooks, VS Code for code, Cursor or Claude Code for AI assistance, a browser tab open for chat AI, pandas or R or Power BI for data, Spark for anything that does not fit in memory, the CUDA toolchain for GPU work, PyTorch or TensorFlow for ML, Visual Studio or a separate compiler for C++, three terminals minimum, and on top of all that the version control situation is bad enough that work eventually ends up zipped and uploaded to cloud storage manually.

Ten-plus tools. Each with its own config, its own auth, its own update cycle, its own way of representing my work. None of them know about each other. My notes do not know what code I wrote. My code does not know what I learned. The AI in tool A cannot see what is happening in tool B. The data in pandas is not visible to my notes. When I switch tools I re-explain myself. When I switch sessions I lose context. The friction of moving between these tools is so constant that I have stopped noticing it — but it is eating hours a day.

This is not a workflow problem solved by writing a better shell script. This is a fundamental architecture problem: the tools were built independently by different companies with different assumptions, and they were never designed to live in one environment.

What it is.

Axylith is one native binary that holds all of the above in a single surface. The core idea is document-as-program. You open Axylith, you write. The document is markdown by default — prose, notes, anything you would write in Obsidian. Inside the document, you can mark code regions with delimiters. When you run the document, the whole thing runs as one program with one shared scope. Not cell-by-cell like Jupyter. Not select this cell and execute with hidden state that changes based on execution order. One document, one program, top to bottom, every time.

Variables persist across code regions naturally because it is all one program. You write the way you think — prose, then code, then more prose explaining what the code did, then more code. The execution model matches the writing model. This fixes Jupyter's worst design decision in one stroke. The I re-ran cell 3 and now cell 7 is broken hell goes away because there is no concept of cell order separate from document order. The which kernel, which environment, which Python version hell goes away because it is all in the binary.

Why me.

Not because it is hard and nobody else can. Plenty of people could attempt this. I am doing it because I want to do it, and I want to see where it goes. The list of skills it touches — C++, Vulkan, CUDA, ML, computational geometry, file formats, product surface — happens to overlap with what I have been working on, so the cost of trying is low for me. That is the entire honest answer. I am not making a claim about being uniquely suited. I am making a claim about being willing to start.

A spatial operating system, not an application.

Axylith is positioned as a spatial operating system: a single binary in which prose, code, data, 3D geometry, simulation state, and AI reasoning all share one address space and one consistent runtime.

The word operating system is deliberate. An application takes input from outside and shows output to the user. A spatial operating system holds all the modalities the user works in — text, geometry, numbers, simulations — inside a shared substrate, and exposes them to one another. The AI can see the geometry while it edits the prose. The simulation can read state from the data engine while the user is still typing the equation. The render output is itself a first-class data object the language can reference.

This framing is not metaphorical. The implementation reflects it. There is no IPC between the editor and the renderer because they are the same process. There is no serialization between the math engine and the AI because they share heap. There is no driver layer between the file format and the user — the file is the document is the database.

The aim, plainly stated.

Axylith aims, over a horizon measured in years, to functionally cover the surface area presently fragmented across the following products and product categories, integrated into one binary with shared state and a single AI layer:

This is the long-horizon aim. It is not what the binary does today. Section 9 — Roadmap — describes the realistic phasing. Section 7 — Subsystems — describes each piece with enough technical specificity that the design intent is unambiguous to any reader, including a future reader attempting to assess the scope and originality of this work.

One process. One file. One mind.

Three commitments organize the entire system. They are load-bearing: subsystems that violate them do not ship.

One process.

The editor, the renderer, the compiler, the math engine, the physics engine, the data engine, the AI inference layer, and the file I/O layer are all linked into one ELF binary. There is no process boundary between them. There is no IPC layer. There is no shared-memory dance. They are functions called from the same program, sharing one heap, one scheduler, one address space, and one shutdown.

Consequences: state transitions are function calls, not network messages. The AI does not request data from the editor; it reads the editor's data structures directly. The renderer does not poll for changes; it observes the same memory the editor wrote. Cross-subsystem latency is bounded by L3 cache and DRAM, not by sockets or pipes.

One file.

A user's work — prose, code, data, geometry, simulation state — lives in a single document. The on-disk representation (the .axl format, see § 6) is a structured binary file with a stable header and chunk-based payload. The document IS the database. There is no separate "project file" that points at other files. There is no folder of side-cars. The file can be moved, renamed, emailed, or version-controlled, and it carries everything with it.

Consequences: backups are trivial. Sync is trivial. Diffing is principled (chunks, not bytes). The user never has to think about "the project structure." A single file is the unit of work.

One mind.

There is one AI layer, integrated with the binary, that sees everything inside the document at once. It is not a chat agent. It is not a plugin. It is a first-class subsystem with read access to the editor buffer, the code regions, the data tables, the geometry buffers, and the simulation state. It produces structured proposals — edits with rationale, parameter changes with assumptions, queries with explanations — and the user accepts, rejects, or refines them.

The single mind has tiers. The smallest tier runs locally on the user's machine for latency-sensitive operations (autocomplete, intra-document references, in-flight reasoning). The next tier escalates to a hosted inference path for harder questions. The user knows which tier is active and why.

Layout of the binary.

The Axylith binary is organized into layers. Each layer is implemented in C++20 with selective C and assembly where measurement justifies it. Shaders are GLSL compiled to SPIR-V. Dependencies are kept minimal and low-level — system libraries (Vulkan loader, libc, libX11/libwayland, the Linux kernel ABI) and a small set of header-only utilities (stb_truetype.h being the canonical example) that are vendored into the source tree. The criterion is stability and recoverability: if a dependency could vanish tomorrow and leave the binary stranded, it does not ship.

The five layers communicate through C++ function calls and shared data structures. There are no message queues, no actor mailboxes, and no IPC sockets internal to the binary. Inter-layer contracts are expressed as types (the renderer takes a SceneView, the AI takes a DocumentRef, the physics solver takes a ContactSet) and verified at compile time by the type system.

The document is the program.

An Axylith document is a sequence of blocks. Each block has a type and a payload. The execution model is straightforward: blocks evaluate in document order, top to bottom, sharing one lexical scope. Re-running a document is deterministic given the same inputs. There is no hidden order of operations.

Block types.

• Prose — UTF-8 text, optionally with markdown styling. Renders as typeset text. Holds no runtime state.
• Code — a region marked with a language directive. Compiles and executes in document order. Language-specific bindings expose document state to the code.
• Math — symbolic or numeric expression evaluated by the math engine. Results bind names visible to later blocks.
• Data — a tabular dataset, referenced by name or inlined. Stored in the columnar data engine; queried by code blocks via a relational interface.
• Geometry — a 3D scene fragment: meshes, point clouds, volumes, parametric surfaces. Editable in the 3D viewport; readable from code.
• Simulation — a parameterized solver invocation (rigid body, soft body, fluid, FEM, custom). Produces a time-series of geometry and data outputs.
• Render — a configured output of the renderer (camera, lighting, post-effects). Captures the live viewport at a deterministic state.
• Annotation — an AI-authored block: a structured edit, a query result, a rationale, a citation. Inline with the rest, distinguishable by styling.

Execution semantics.

All blocks share one lexical scope. A name bound in block 3 is visible in block 17. Block evaluation has memoization: if a block's inputs have not changed since the last run, it is not re-executed. The dependency graph is implicit in the variable references and explicit for blocks (like simulations) that declare external dependencies. The user sees the staleness state of each block in the gutter — green for fresh, amber for stale, gray for unevaluated.

This model intentionally fixes the canonical Jupyter failure mode. There is no cell number. Blocks have document position. The document order IS the execution order. The state of the document at any moment is the result of running the document up to that point. There is no hidden state to lose track of.

The .axl binary container.

Axylith documents are stored in a binary format with a 32-byte header followed by a chunked payload. The format is designed for: (a) recoverability from external tools, (b) byte-level diffability, (c) block-level synchronization between collaborators, (d) compactness without compression dependency, (e) forward and backward compatibility.

The magic bytes AXLE identify the file unambiguously. The chunk-index offset points to a structural table at the tail of the file that lists every chunk's offset and type, enabling random access without scanning the whole document. Payload checksum (xxhash3-64) detects corruption. The creator ID is a per-installation identifier used for collaborative merge resolution.

Chunk types.

Chunks are typed. Common types include: PROS (prose, UTF-8), CODE (code region with language tag), DATA (tabular columnar block), GEOM (geometry: mesh, point cloud, volumetric), SIMS (simulation state snapshot), MATH (symbolic expression tree), ANNO (AI annotation with rationale), RNDR (render configuration), META (document metadata), SIGN (cryptographic signature of the preceding chunks).

Unknown chunk types are preserved on round-trip. A reader that does not understand a chunk skips it but does not strip it. This makes the format forward-compatible: future Axylith versions can introduce new block types without orphaning files opened by older clients.

Block-level synchronization.

Because chunks are addressable and stable, two users editing the same document can exchange only the chunks they have modified. The sync protocol is a vector clock over chunk IDs. Conflicting edits to the same chunk are resolved either automatically (textual three-way merge for prose, structural merge for geometry) or interactively. The document is the database: there is no separate sync server holding authoritative state.

Compression and encryption.

Compression is per-chunk and optional. Default chunks are uncompressed for inspectability; explicitly-flagged chunks (large datasets, geometry buffers) are compressed with Zstandard. Encryption is similarly per-chunk and optional, with keys held by the user — there is no service-side key escrow because there is no service.

What lives in the binary.

Each subsystem below is described at enough specificity to make its design intent unambiguous, including its data structures, performance commitments, and interaction surface with other subsystems. The descriptions are not implementation files; they are architectural commitments.

The constraints I will not break.

These are load-bearing. Features that violate them do not ship, regardless of how compelling the feature is. They are listed in priority order; when two conflict, the higher-numbered yields.

P1 — One native binary.

No Electron, no embedded browser, no JavaScript runtime for shipping logic. The build produces a stripped ELF measured in megabytes. The reactive layer's JS-class semantics are achieved by a compile-step, not a runtime.

P2 — Local-first.

Files on disk are the source of truth. No cloud account is required to use any feature. Network access is opt-in, never default. The hosted AI tier is the only network-dependent capability, and the binary is fully usable without it (with reduced AI ceiling).

P3 — Honest latency.

Input latency and frame time are displayed in the HUD. Numbers are measured, not estimated. Subsystems are budgeted in microseconds. If an operation exceeds its budget, the user sees it. No subsystem hides behind a spinner.

P4 — Reasoning attached.

No AI suggestion is presented without its rationale. No parameter change is auto-applied without its argument. The default mode of AI communication is structured proposal with reasoning, not chat.

P5 — Determinism by default.

Identical inputs produce identical outputs. Non-determinism is opt-in (stochastic algorithms, network calls, wall-clock dependence) and visibly marked. This includes the AI layer's structured outputs: given the same prompt and seed, the same response.

P6 — Inspectable.

The file format is documented. The shader source is included. The internal data structures are observable from a built-in debug overlay. Nothing about how the binary works is a black box to a determined user.

P7 — Minimal, low-level dependencies.

Dependencies are allowed when they are minimal, low-level, and unlikely to move out from under the binary — Vulkan, libc, X11/Wayland, the kernel ABI, and a small handful of header-only utility libraries (like stb_truetype.h). The bar is: if it disappeared tomorrow, would the binary be stranded? Anything that fails that test does not ship in the binary. This is not a virtue signal about purity. It is the difference between a binary that builds on any modern Linux for the next decade and a binary that breaks when somebody else's dependency moves.

Phasing.

The system described above is the long-horizon target. The phasing below describes a realistic delivery sequence. Each milestone is gated on the previous milestone being usable, not feature-complete.

What the system does and does not do.

Summarized for unambiguous record. The phrasing is deliberately wide because the scope is wide; the document elsewhere makes each item precise.

Does — 3D & Geometry.

• Triangle mesh editing: vertex, edge, face selection and manipulation
• Vertex translation, rotation, scaling, smoothing, projection
• Edge bevel, bridge, slide, knife cut, loop cut
• Face inset, extrude, bridge, merge
• Boolean operations: union, intersection, difference
• Subdivision (Catmull-Clark, Loop) and decimation (quadric error)
• Mesh repair: manifold check, hole fill, non-manifold resolution, duplicate vertex merge
• Mirror, array, lattice deformers
• UV layout and atlas packing
• Point cloud import, filtering, Poisson surface reconstruction
• Signed distance field generation, marching cubes extraction
• NURBS / parametric surface evaluation
• Photogrammetry-class input (point cloud / mesh from image stacks) — pipeline-level

Does — Simulation.

• Rigid body dynamics: constraints, joints, motors, contact
• Soft body dynamics: cloth, rope, volumetric soft solids
• Particle systems: granular, smoke, dust, sparks
• Fluid simulation: incompressible Eulerian, free-surface SPH, lattice Boltzmann
• FEM: linear and nonlinear structural, modal analysis, transient dynamics
• Heat transfer: conduction, convection, radiation (coupled multi-physics)
• Material-point method for granular / elastoplastic
• Custom user-authored solvers via code blocks with access to engine primitives
• Deterministic replay for any simulation given a seed

Does — Compute & Math.

• IEEE 754 FP64 numerical evaluation
• Mixed-precision FP32/FP64 for GPU dispatch
• Symbolic algebra: simplification, differentiation, integration, equation solving
• Linear algebra: dense and sparse, direct and iterative
• FFT, convolution, spectral methods
• ODE/PDE integration: explicit, implicit, IMEX
• Optimization: gradient, Newton, trust region, stochastic
• 3D and 4D (3D + time) calculations as first-class
• Vector field, tensor field, differential geometry primitives

Does — Data.

• Columnar storage with typed columns and zone maps
• Relational queries: select, project, filter, join, group, aggregate, window
• Out-of-core via memory-mapped paged storage
• Native ingestion of CSV, Parquet, Arrow, JSON, custom binary
• Time-series operations
• Tabular ↔ geometry coupling (e.g. data attributes drive vertex colors)

Does — AI & Reasoning.

• Live document-aware completion (prose, code, math)
• Structured edits with rationale and assumption set
• Cross-modal queries (e.g. "explain this simulation in terms of the data table that drove it")
• Web-grounded research with cited values for domain quantities (viscosities, densities, material constants)
• Training observation and intervention with numeric grounding
• UX-aware analysis of user-data: heatmaps, retention curves, code-coupled insights
• Live work assistance: "change this material to oil," "rotate camera to a 3/4 view," "recolor by stress magnitude" — actionable, executable, reasoned

Does — Output.

• Flat-screen rendering: editor surface, 3D viewport, render blocks
• XR output via OpenXR for head-mounted displays
• Static export: image, video, PDF, glTF, OBJ, PLY, STL, USD (read), CSV, Parquet
• Embedded export: a document with a public-share render page

Does NOT — Out of scope.

• Retopology. Generating clean quad-dominant topology from arbitrary input meshes is explicitly not implemented and not planned.
• Remeshing. Algorithmic regeneration of mesh topology to user-specified constraints is explicitly not implemented and not planned.
• Animation rigging. Skeletal rigging and skinning are out of scope for the foreseeable horizon. Mesh deformation by lattice and direct vertex animation are in scope; bone hierarchies are not.
• Sculpting. Brush-based high-resolution mesh sculpting is out of scope; targeted operators (smooth, inflate, pinch) on selections are in scope.
• Texturing / painting. 2D image editing and 3D paint are not implemented in the binary; integration points exist for external image data.
• Audio. No audio synthesis, editing, or analysis subsystem.

What this is for.

The aim, plainly: a real second brain. Modeling, coding, simulating, live editing, changing colors, recomputing fields, asking and being answered — in one surface, with one collaborator, with the whole document in view. Not a chatbot. Not a wrapper. A working environment that the AI inhabits with the user, where the default form of help is a reasoned proposal, not a chat reply.

The horizon is years. The author has been deliberate about scope, about positioning, about the technical commitments, and about the order in which capability comes online. This document exists to fix all of that in time, signed and dated, so that the work that follows has unambiguous origin.

Everything in this document is original work by the named author, conceived prior to and independent of any subsequent employment, contract, or affiliation. The repository in which this document resides carries cryptographically signed commit history. The publication date is the date the commit was pushed to a publicly visible branch. Both are evidentiary.