Datom.World FAQ
What is Datom.World?
Datom.World is a local-first, stream-native platform. Streams of datoms flow between devices, and apps interpret those streams according to their domain. The platform ships Yin (a continuation VM), Yang (a compiler), DaoDB (a datom stream interpreter), DaoFlow (a rendering engine), and Shibi (an economic primitive).
All apps work the same way: they consume datom streams and interpret them. DaoDB interprets them as queryable indexes, DaoFlow interprets them as renderable interfaces, Shibi interprets them as economic signals. The radical move is unifying code, data, and computation into a single primitive (the datom stream), making programs queryable, mobile, and evolvable.
What is a datom, exactly?
A datom is a five-tuple [e a v t m]: entity, attribute, value, transaction ID, metadata entity ID. It is an immutable fact, not an object. The t is monotonic within its stream, not globally ordered. The m references an entity carrying causal relationships, encryption context, or expansion provenance, and is used to establish causality across streams (since t has no meaning outside its originating stream). When you transact a map, it decomposes into datoms automatically. See DaoDB for the full structure and The Power of Restriction for the design rationale.
What does "everything is a stream" mean?
Data never freezes in silos. Every fact lives in an append-only stream that can be read, transformed, or extended. Streams are the single I/O abstraction: files, sockets, queues, and databases collapse into one primitive. The DaoStream protocol is four operations: open!, next (read), put! (write), close!. Backpressure and cursor-based reading are built in.
What does "everything is a continuation" mean?
A continuation is a first-class bookmark into an execution. In Yin, functions, closures, coroutines, exceptions, and async tasks all reduce to continuation manipulation. Because continuations are persistent data structures, they serialize to datoms, travel through streams, and resume on a different device with full context intact. See Continuations as Universal Semantic Kernel and Computation Moves, Data Stays .
Who owns the data flowing through these streams?
You do. Datoms stay under the author's control from creation through sharing. There is no corporate datastore to monetize or subpoena. You decide which peers can observe a stream, for how long, and with which capabilities (enforced through Shibi tokens).
How is privacy preserved if everything is streaming?
Privacy is the default. Each datom can bundle access rules, key material, expiration, and audit trails. Encryption happens before transmission, so only authorized peers can interpret the facts they receive. Execution safety rides on Yin acting as the universal security container: like Docker, WASM, or the JVM, Yin sandboxes code so untrusted continuations can run on your hardware without escaping, and your datoms can execute on someone else's node without them peering into the VM.
What can I build?
Anything that benefits from shared truth across devices: social spaces, marketplaces, automation meshes, IoT telemetry, multiplayer tooling, or AI agents. Because streams are universal, the same facts can render as dashboards, maps, spreadsheets, or code triggers without duplicating data. See Use Cases for Datom.World for concrete scenarios.
For Clojure programmers
Answers aimed at working Clojurists evaluating the project.
Is this a Clojure library, or something that replaces Clojure?
Neither. The project is written in portable Clojure (.cljc), and Clojure is one of the surface syntaxes you can write programs in. Yang's yang.clojure frontend reads ordinary Clojure s-expressions and lowers them into the Universal AST, which is a graph of datoms. Yin then evaluates that AST. Clojure is a source language. Datoms are the canonical form. The JVM (or Node, or Dart) is the host.
How does this relate to Datomic?
Datom.World inherits the datom idea from Datomic and changes two things. First, the transaction ID t is stream-scoped, not globally ordered. Cross-stream causality lives in the metadata slot m. Second, datoms are used for everything (ASTs, bytecode, execution traces, schema, provenance), not just application data. DaoDB is a family of stream interpreters that materialize whatever indexes the consumer needs. See DaoDB as a Moduli Space of Databases .
Is Yin a replacement for the JVM?
No. Yin is a portable continuation VM written in .cljc. The JVM is one host, Node.js is another, Dart/Flutter is a third, and there are experimental native paths. The same Yin program runs unchanged across all of them. See Semantic Bytecode Benchmarks for cross-host measurements.
How does DaoStream compare to core.async?
core.async is an application-level library for channels and go blocks. DaoStream is a portable substrate with a descriptor-plus-realization model and pluggable transports (ringbuffer, WebSocket, file, and others). DaoStream streams are addressable, persistent, and cross-process. core.async channels are not. A DaoStream is closer in spirit to a Datomic log segment plus a core.async channel plus a Unix pipe, collapsed into one primitive.
Can I use existing Clojure libraries?
On the JVM host, anything Clojure can call is reachable from host code. Calling into external code from inside Yin (including other Clojure libraries, or eventually native C and Rust) goes through dao.stream.apply : function application is reified as a request/response stream pair, with the op and evaluated arguments emitted on the request stream and the result returned on the response stream. There is no direct native FFI. Reaching a C or Rust library requires a bridge that reads the request stream and calls the native function, and such a bridge does not exist yet. Libraries that assume they own threads, global mutable state, or JVM-specific I/O may not port cleanly to the Node or Dart hosts. Treat Yin as a portable core with host-specific edges. See Beyond FFI .
How do I run it? What is the REPL?
Use dao.repl , a portable REPL that evaluates Clojure, Python, or PHP source through Yang into Yin. You can switch VMs at the prompt with (vm :semantic) , (vm :register) , (vm :stack) , or (vm :ast-walker) , switch languages with (lang :clojure) , and connect to a remote dao.repl over WebSocket with (connect "daostream:ws://host:port") . The REPL is available on the JVM, Node, and Dart.
What are the build and test commands?
clj -M:testruns the Clojure test suite.clj -M:cljs -m shadow.cljs.devtools.cli compile test && node target/node-tests.jsruns the ClojureScript suite.clj -M:cljd compilecompiles the ClojureDart build.clj -M:kondo --lintlints a file.npx shadow-cljs watch demostarts the browser demo in watch mode.
What about macros? Clojure macros are source-to-source.
Macros still work, but because the AST is a datom stream rather than a nested form, expansion is a transaction on the stream. Each macro has a :yin/phase-policy of :compile , :runtime , or :both , so the same mechanism covers compile-time expansion and first-class runtime rewrite. Provenance is tracked: every expansion writes a :macro-expand-event entity, and generated datoms reference that event through their m field. You can query back to the original source. See Yin.vm Macros .
Do I have to write Clojure?
No. Yang currently ships Clojure, Python, and PHP frontends. All of them lower to the same Universal AST, so a Clojure lambda and a Python lambda become the same kind of AST node. Mixed-language programs share the same execution and the same dataset.
An ANTLR integration is planned, which will turn any existing ANTLR grammar into a viable frontend: drop in the grammar, wire the parse tree to Universal AST nodes, and the language targets Yin. The ecosystem of ANTLR grammars (Java, C, C++, SQL, Kotlin, TypeScript, Go, and so on) becomes a long tail of potential Yang frontends. See Many Syntaxes, One AST and Chinese Characters for Programming Languages .
Why would I pick Yin.VM for Flutter/ClojureDart mobile development?
ClojureDart does not ship a full socket REPL. That is a real loss: interactive development is one of Clojure's best properties, and mobile work is where you need it most. Embedding Yin.VM into a Flutter app restores it. The app carries a full dao.repl reachable over WebSocket, so you can connect from your laptop and evaluate code directly inside the running Android or iOS process. Calls into native platform code go through dao.stream.apply , which reifies FFI as a request/response stream pair: you invoke a bridge from the REPL, the bridge calls native, and the result comes back on the response stream. The REPL workflow and the FFI workflow are the same primitive. For developers shipping cross-platform mobile apps in Clojure, this is the pragmatic reason to adopt Yin.VM.
Why would I pick this over plain Clojure plus Datomic?
If your program fits comfortably on one JVM, you probably should not. The project earns its keep when the problem is distributed, local-first, mobile, swarmed, or agent-driven, or when you want code and data in the same queryable substrate. See Devil's Advocate for the honest rebuttal to this question.
Datoms, streams, storage
The data model underneath the platform.
How are datoms stored and replicated?
Datoms flow through DaoStreams. Apps like DaoDB consume streams and materialize what they need. DaoDB maintains append-only covered indexes (EAVT, AEVT, AVET, VAET) and merges datoms by transaction and causal ID. Each node chooses what to materialize. Some store everything, others keep only recent data or specific attributes.
What is entanglement between nodes?
Entanglement is a lightweight consensus mechanism. When streams entangle, a leader establishes event ordering, imposing a single monotonic sequence across the entangled streams. Leadership can shift on demand, which delivers consistency without global locks or blockchains. Transaction IDs remain stream-scoped even when entangled: cross-stream causality is always determined through metadata.
Why stream-scoped t instead of Datomic's global t?
A globally monotonic t requires a single source of truth. That is fine for one database; it is a coordination bottleneck for a local-first, offline-capable, peer-to-peer fabric. Stream-scoped t plus causal metadata is the price of doing without a central transactor. See DaoDB .
Datomic uses [e a v t op] where op is true for assertions and false for retractions. DaoDB uses [e a v t m] with no op. How does DaoDB handle retraction?
DaoDB does not encode polarity in the datom. A datom is pure fact; there is no "false datom". Retraction is a transaction operation , not a flag on the datom.
The transaction log records each committed tx as a [t added retracted] entry: the set of datoms that were added and the set that were retracted at that t. Indexes (EAVT, AEVT, AVET, VAET, MEAT) remove retracted datoms so queries see the current view; the log retains the full history for time-travel and audit.
The effect is a cleaner separation of concerns than Datomic's fused op : the datom carries the fact, the transaction carries the change, and the metadata field m carries cross-stream causality and provenance. None of the three overload the others.
What does the metadata field m carry?
m references an entity. That entity can carry causal predecessors, encryption context, capability requirements, macroexpansion provenance, branch identity, or any domain-specific context. Because m itself is a datom pointer, meta can be queried like any other data.
Are DaoStreams like pi-calculus channels?
Partly. The structural invariants match: streams are first-class, they are the sole I/O primitive, and they are mobile (streams can be sent through streams, which is pi-calculus's defining move). The runtime model differs: pi-calculus channels are ephemeral rendezvous points with no history, while DaoStreams are append-only sequences with cursor-based non-destructive reads and backpressure. DaoStreams carry whatever values the consumer needs (binary bytes, EDN values, arbitrary payloads), and most commonly carry datoms, at which point the causal metadata in each datom's m field layers ordering semantics on top of the stream. A DaoStream is closer to a durable, cursor-addressable pi-calculus channel. The project's own framing is "beyond pi-calculus": keep the mobility and first-class channel idea, add a persistent substrate. See Beyond Pi-Calculus and Process Calculus, Causal Categories, Datom Interpreters .
How is data serialized on the wire?
The canonical form is the datom itself. EDN is used for human-readable interchange, and transit-flavored encodings carry datoms across transports efficiently. The underlying claim is that datoms canonicalize and EDN serializes. The fact stream is authoritative; the byte encoding is a projection.
Yin and Yang
The continuation machine and its compilers.
What is Yin?
Yin is a universal continuation machine. It evaluates programs represented as datom-stream ASTs, and its execution state is a persistent CESK record (Control, Environment, Store, Kontinuation). Because state is a value, you can snapshot, serialize, migrate, fork, and resume VMs cheaply. See Yin and The CESK Machine .
How does Yin differ from the JVM or EVM?
The JVM hides runtime state behind bytecode. The EVM prices computation but limits introspection. Yin reifies continuations as data. That single change enables distributed execution, dynamic transformation, zero-copy migration, and queries over the running program itself.
There are several VMs. Why?
Four backends explore the same AST-as-datoms abstraction under different execution strategies: Semantic (interprets datoms directly), Register (compiles datoms to register bytecode), Stack (compiles to stack bytecode), and AST Walker (walks the AST tree). They exist partly for research and partly so a deployment can pick a trade-off point. See A Tale of Four VM Benchmarks .
What is the Yang compiler?
Yang lowers source languages into the Universal AST. Today it ships Clojure, Python, and PHP frontends. Each frontend emits the same AST shape, so Yin executes them interchangeably. A planned ANTLR integration will let any existing ANTLR grammar (Java, C, C++, SQL, Kotlin, TypeScript, Go, and the rest of the ANTLR ecosystem) serve as the front half of a Yang frontend: supply the grammar, map parse-tree nodes to Universal AST nodes, and the language runs on Yin. See Yang .
How does the Universal AST relate to datoms?
The AST is not a separate representation; it is a construction from datoms. Programs are stored as datom streams, and the AST is the materialized view when you ask for it. Code becomes queryable data: find every function that calls a given API, trace dependencies, rewrite programs with the same tools you query a database. See AST as Higher-Dimensional Construction of Datom Streams and When the IDE Edits AST, Not Text .
Why persistent data structures throughout?
Persistence makes snapshot-and-resume cheap. You get lightweight time travel, safe distributed execution, and resilience without stop-the-world pauses. The same discipline that powers Clojure's collections powers VM state in Yin.
Are agents programs, or continuations?
Agents are continuations. There is no separate agent abstraction. An agent is a serializable execution state that can pause, migrate, and resume with its full context. Mobility, security, and computation merge into a single primitive. See Agents .
Does Yin interoperate with other systems?
Yes, but not through a conventional FFI. All external function application goes through dao.stream.apply , a request/response stream pair that reifies the call as data. Any system willing to consume the request stream and emit a result on the response stream can be reached: other language runtimes, remote services, or (once a bridge is written) native C and Rust libraries. EDN and transit serialize values across language and network boundaries. No native FFI bridge ships yet; the stream-apply primitive is the single interop mechanism. See Beyond FFI: Yin.VM Datom Streaming .
Performance and trade-offs
The honest numbers.
What does AST-as-datoms cost at runtime?
Semantic bytecode (generating unique node IDs and datom triples for every construct) is roughly four to eleven times slower to compile than opaque bytecode, and one to seven times slower to execute, depending on host (JVM, Node, Dart). What you get for the cost is introspection: a running program is queryable by the same tools that query your database. See Semantic Bytecode Benchmarks .
Which of the four VMs is fastest?
On the current benchmarks, the Register VM leads, followed by Stack, then Semantic, then AST Walker. The Semantic VM (the one that interprets datoms directly, with no bytecode pass) is about 50 percent faster than the AST Walker after optimization, which was not the original prediction. See A Tale of Four VM Benchmarks and AST Datom Streams and Bytecode Performance .
Should I worry about the overhead?
If your workload is a tight inner loop on a single host, yes, and you probably want a different tool. If your workload is distributed, agent-driven, mobile, or benefits from code-as-data queryability, the overhead pays for capabilities that the faster VM cannot offer at all.
Shibi and governance
The economic primitive and capability tokens.
What is Shibi?
Shibi is the capability token system that coordinates access and resources across Datom.World. Tokens grant specific capabilities: stream access, computational metering, agent migration credentials, rate limiting, cross-agent communication. Shibi implements Elinor Ostrom's principles for governing digital commons, enabling delegation, attenuation, and auditable resource sharing without central authorities.
Is Shibi money or a blockchain token?
No. Shibi tokens are purpose-specific, capability-based, and non-transferable by default. Each issuer can mint them freely; value comes from what the token authorizes, not from scarcity. See Shibi as Money and Attention Market Critiques .
Still curious?
Bring your scenario or data model and we will explore it together. Intros, architecture reviews, and partner pilots happen weekly.
Continuation mindset : the system never loses context.
- User perspective: the web remembers how it flows, so experiences remain seamless, local-first, and privacy-centric.
- Developer perspective: every execution state is a first-class continuation that unifies concurrency, recovery, and distribution.