diaspore 0.2.0__tar.gz

diaspore-0.2.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+runtimes/ts/dist/
+runtimes/ts/LICENSE
+runtimes/ts/*.tgz
+
+# Build output (see `make generate`, `make build` and `make site`)
+build/
+*.dsp.json
+*.dsp.json.gz
+*.dspb
+*.dspb.gz
+*.flow.json
+site/diaspore.wasm
+site/wasm_exec.js
+site/stdlib.json
+site/build.json
+site/ir.schema.json
+tests/fuzz_failures/
+runtimes/go/dspc/stdlib.json.gz
+runtimes/ts/stdlib/
+runtimes/ts/.stdlib-stamp

diaspore-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 diaspore contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diaspore-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: diaspore
+Version: 0.2.0
+Summary: Compile a Python subset to portable JSON for Python, Go, TypeScript, and Lua runtimes
+Project-URL: Homepage, https://radkawar.github.io/diaspore
+Project-URL: Repository, https://github.com/radkawar/diaspore
+License: MIT
+License-File: LICENSE
+Keywords: compiler,interpreter,portable,python,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Interpreters
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Diaspore
+
+Write Python. Ship JSON. Run it anywhere, sandboxed.
+
+Diaspore compiles a large subset of Python into a portable JSON bundle and runs
+it with identical output on four runtimes: Python, Go, TypeScript and Lua. A
+bundle has no ambient authority, runs on a fuel budget, and can pause itself
+into a JSON snapshot that any other runtime can resume.
+
+[Playground](https://radkawar.github.io/diaspore) |
+[Specification](https://github.com/radkawar/diaspore/blob/main/docs/spec.md) | [Security model](https://github.com/radkawar/diaspore/blob/main/docs/security.md) |
+[Examples](https://github.com/radkawar/diaspore/blob/main/examples) | [Releases](https://github.com/radkawar/diaspore/releases)
+
+```sh
+diaspore build app.py -o app.dsp.json     # compile once
+diaspore run app.dsp.json                 # Python
+diaspore-go run app.dsp.json              # Go
+npx diaspore-ts run app.dsp.json          # TypeScript
+lua5.4 runtimes/lua/cli.lua run app.dsp.json  # Lua
+```
+
+## Features
+
+- **Portable.** One JSON artifact: diffable, signable, storable in a database
+  column, validated before it runs.
+- **Sandboxed.** Network, file system and task spawning are denied unless
+  granted. `--max-steps` caps CPU; exhausting it is an uncatchable trap.
+- **Embeddable.** Hosts expose functions as an importable module and call into
+  the sandbox. Python, Go, TypeScript and Lua hosts share one model.
+- **Durable.** `flow.suspend()` pauses a program into a snapshot. Resume it
+  later, in another process, on another runtime.
+- **Self-hosted.** The compiler is written in the subset it compiles. The Go and
+  TypeScript runtimes embed it, so they build Python without Python, and so does
+  the [browser playground](https://radkawar.github.io/diaspore).
+- **Conformant.** Every corpus program must match CPython byte for byte on every
+  runtime, backed by differential fuzzing.
+
+## Runtimes
+
+| Runtime | Install | Notes |
+| --- | --- | --- |
+| diaspore-py | `uv tool install diaspore` | Reference VM, compiler and CLI |
+| diaspore-go | [Release binaries](https://github.com/radkawar/diaspore/releases); library: `go get github.com/radkawar/diaspore/runtimes/go` | Near CPython speed; also compiles to WebAssembly |
+| diaspore-ts | [`npm install diaspore`](https://www.npmjs.com/package/diaspore) | Node 22+, no runtime dependencies |
+| diaspore-lua | [Release tarball](https://github.com/radkawar/diaspore/releases) | Pure Lua 5.4; no tasks, regex or big integers |
+
+Sources: [src/diaspore](https://github.com/radkawar/diaspore/blob/main/src/diaspore), [runtimes/go](https://github.com/radkawar/diaspore/blob/main/runtimes/go),
+[runtimes/ts](https://github.com/radkawar/diaspore/blob/main/runtimes/ts), [runtimes/lua](https://github.com/radkawar/diaspore/blob/main/runtimes/lua).
+
+## Getting started
+
+Install the compiler and reference runtime with
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install diaspore
+diaspore build main.py -o main.dsp.json
+diaspore run main.dsp.json
+```
+
+Run the same bundle from Node, or embed it:
+
+```sh
+npm install diaspore
+npx diaspore-ts run main.dsp.json
+```
+
+To build everything from source you need Go 1.26+; Node 23.6+ and Lua 5.4 are
+needed only for their runtimes.
+
+```sh
+git clone https://github.com/radkawar/diaspore && cd diaspore
+uv sync
+make build    # embedded compiler + build/diaspore-go
+```
+
+Then try the [examples](https://github.com/radkawar/diaspore/blob/main/examples), starting with
+[embedding](https://github.com/radkawar/diaspore/blob/main/examples/embedding): one sandboxed plugin hosted from all four
+languages.
+
+## Embedding
+
+```python
+from diaspore import Machine, compile_bundle
+
+bundle = compile_bundle("plugin.py", extra_modules={"host"})
+vm = Machine(bundle, bindings={"host": {"lookup": lookup}}, max_steps=1_000_000)
+vm.run()
+price = vm.call("plugin", "price", order)
+```
+
+The same pattern in [Go](https://github.com/radkawar/diaspore/blob/main/runtimes/go#embedding),
+[TypeScript](https://github.com/radkawar/diaspore/blob/main/runtimes/ts#embedding) and [Lua](https://github.com/radkawar/diaspore/blob/main/runtimes/lua#embedding).
+
+## Language
+
+Functions, closures, classes with multiple inheritance, generators,
+`async`/`await`, exceptions including `except*`, `match`, comprehensions,
+f-strings, arbitrary-precision integers, multi-module packages, and a portable
+standard library (`json`, `math`, `re`, `time`, `random`, `collections`,
+`itertools`, `functools` and more). Unsupported syntax is a compile error with a
+`file:line`, never a silent runtime failure. The exact surface is in
+[docs/spec.md](https://github.com/radkawar/diaspore/blob/main/docs/spec.md).
+
+## Repository
+
+```
+src/diaspore/   compiler, reference VM, CLI, standard library
+selfhost/       dspc, the self-hosted compiler
+runtimes/       go, ts and lua runtimes
+examples/       runnable examples for every runtime
+site/           playground and project site
+docs/           specification, security model, binary format
+tests/          conformance corpus and test suites
+```
+
+## Development
+
+```sh
+make test    # every suite on every runtime
+make lint    # ruff, go vet, staticcheck, gofmt, tsc
+make fuzz    # differential fuzzing against CPython
+make serve   # build and serve the site on localhost:8000
+```
+
+Run `make help` for the full list.
+
+## License
+
+[MIT](https://github.com/radkawar/diaspore/blob/main/LICENSE)

diaspore-0.2.0/README.md

@@ -0,0 +1,130 @@
+# Diaspore
+
+Write Python. Ship JSON. Run it anywhere, sandboxed.
+
+Diaspore compiles a large subset of Python into a portable JSON bundle and runs
+it with identical output on four runtimes: Python, Go, TypeScript and Lua. A
+bundle has no ambient authority, runs on a fuel budget, and can pause itself
+into a JSON snapshot that any other runtime can resume.
+
+[Playground](https://radkawar.github.io/diaspore) |
+[Specification](https://github.com/radkawar/diaspore/blob/main/docs/spec.md) | [Security model](https://github.com/radkawar/diaspore/blob/main/docs/security.md) |
+[Examples](https://github.com/radkawar/diaspore/blob/main/examples) | [Releases](https://github.com/radkawar/diaspore/releases)
+
+```sh
+diaspore build app.py -o app.dsp.json     # compile once
+diaspore run app.dsp.json                 # Python
+diaspore-go run app.dsp.json              # Go
+npx diaspore-ts run app.dsp.json          # TypeScript
+lua5.4 runtimes/lua/cli.lua run app.dsp.json  # Lua
+```
+
+## Features
+
+- **Portable.** One JSON artifact: diffable, signable, storable in a database
+  column, validated before it runs.
+- **Sandboxed.** Network, file system and task spawning are denied unless
+  granted. `--max-steps` caps CPU; exhausting it is an uncatchable trap.
+- **Embeddable.** Hosts expose functions as an importable module and call into
+  the sandbox. Python, Go, TypeScript and Lua hosts share one model.
+- **Durable.** `flow.suspend()` pauses a program into a snapshot. Resume it
+  later, in another process, on another runtime.
+- **Self-hosted.** The compiler is written in the subset it compiles. The Go and
+  TypeScript runtimes embed it, so they build Python without Python, and so does
+  the [browser playground](https://radkawar.github.io/diaspore).
+- **Conformant.** Every corpus program must match CPython byte for byte on every
+  runtime, backed by differential fuzzing.
+
+## Runtimes
+
+| Runtime | Install | Notes |
+| --- | --- | --- |
+| diaspore-py | `uv tool install diaspore` | Reference VM, compiler and CLI |
+| diaspore-go | [Release binaries](https://github.com/radkawar/diaspore/releases); library: `go get github.com/radkawar/diaspore/runtimes/go` | Near CPython speed; also compiles to WebAssembly |
+| diaspore-ts | [`npm install diaspore`](https://www.npmjs.com/package/diaspore) | Node 22+, no runtime dependencies |
+| diaspore-lua | [Release tarball](https://github.com/radkawar/diaspore/releases) | Pure Lua 5.4; no tasks, regex or big integers |
+
+Sources: [src/diaspore](https://github.com/radkawar/diaspore/blob/main/src/diaspore), [runtimes/go](https://github.com/radkawar/diaspore/blob/main/runtimes/go),
+[runtimes/ts](https://github.com/radkawar/diaspore/blob/main/runtimes/ts), [runtimes/lua](https://github.com/radkawar/diaspore/blob/main/runtimes/lua).
+
+## Getting started
+
+Install the compiler and reference runtime with
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install diaspore
+diaspore build main.py -o main.dsp.json
+diaspore run main.dsp.json
+```
+
+Run the same bundle from Node, or embed it:
+
+```sh
+npm install diaspore
+npx diaspore-ts run main.dsp.json
+```
+
+To build everything from source you need Go 1.26+; Node 23.6+ and Lua 5.4 are
+needed only for their runtimes.
+
+```sh
+git clone https://github.com/radkawar/diaspore && cd diaspore
+uv sync
+make build    # embedded compiler + build/diaspore-go
+```
+
+Then try the [examples](https://github.com/radkawar/diaspore/blob/main/examples), starting with
+[embedding](https://github.com/radkawar/diaspore/blob/main/examples/embedding): one sandboxed plugin hosted from all four
+languages.
+
+## Embedding
+
+```python
+from diaspore import Machine, compile_bundle
+
+bundle = compile_bundle("plugin.py", extra_modules={"host"})
+vm = Machine(bundle, bindings={"host": {"lookup": lookup}}, max_steps=1_000_000)
+vm.run()
+price = vm.call("plugin", "price", order)
+```
+
+The same pattern in [Go](https://github.com/radkawar/diaspore/blob/main/runtimes/go#embedding),
+[TypeScript](https://github.com/radkawar/diaspore/blob/main/runtimes/ts#embedding) and [Lua](https://github.com/radkawar/diaspore/blob/main/runtimes/lua#embedding).
+
+## Language
+
+Functions, closures, classes with multiple inheritance, generators,
+`async`/`await`, exceptions including `except*`, `match`, comprehensions,
+f-strings, arbitrary-precision integers, multi-module packages, and a portable
+standard library (`json`, `math`, `re`, `time`, `random`, `collections`,
+`itertools`, `functools` and more). Unsupported syntax is a compile error with a
+`file:line`, never a silent runtime failure. The exact surface is in
+[docs/spec.md](https://github.com/radkawar/diaspore/blob/main/docs/spec.md).
+
+## Repository
+
+```
+src/diaspore/   compiler, reference VM, CLI, standard library
+selfhost/       dspc, the self-hosted compiler
+runtimes/       go, ts and lua runtimes
+examples/       runnable examples for every runtime
+site/           playground and project site
+docs/           specification, security model, binary format
+tests/          conformance corpus and test suites
+```
+
+## Development
+
+```sh
+make test    # every suite on every runtime
+make lint    # ruff, go vet, staticcheck, gofmt, tsc
+make fuzz    # differential fuzzing against CPython
+make serve   # build and serve the site on localhost:8000
+```
+
+Run `make help` for the full list.
+
+## License
+
+[MIT](https://github.com/radkawar/diaspore/blob/main/LICENSE)

diaspore-0.2.0/docs/dspb.md

@@ -0,0 +1,97 @@
+# DSPB: the optional binary bundle container
+
+DSPB encodes the same semantic model as a JSON bundle in a compact binary
+container. JSON remains the canonical form and default output. Every DSPB
+implementation MUST preserve this invariant:
+
+    decode(encode(bundle)) == compact(bundle)      (exact structural equality)
+
+Digests (`bundle_digest`), validation, and all semantics operate on the
+decoded model, so containers never affect meaning. Loaders sniff by magic
+bytes; `.dspb.gz` (gzip over DSPB) is valid - gzip decoding re-sniffs its
+payload. Reference implementation: `src/diaspore/dspb.py` (normative where this
+document is ambiguous). Round-trip conformance: `tests/test_dspb.py`.
+
+## Primitives
+
+- varint - unsigned LEB128 (7 bits per byte, high bit = continuation).
+- str-ref - varint index into the string table.
+- byte - one raw byte.
+
+## Layout
+
+```
+magic     6 bytes  "DSPB01"
+strtab    varint count, then per string: varint byte-length + UTF-8 bytes
+semver    varint   (1 - same value as JSON's "diaspore" field)
+main      str-ref
+modules   varint count, then per module:
+            name str-ref, file str-ref,
+            src-flag byte (0|1), if 1: str-list (varint count + str-refs)
+            body node-list
+node-list varint count + that many nodes
+```
+
+## Nodes
+
+Every node: opcode byte (index into the OPS table below), flags byte
+(bit 0 = `ln` present -> varint follows; higher bits are the op's optional
+fields in the listed order), then fields in fixed order.
+
+Enum tables (indices are normative):
+
+```
+OPS        = const name attr index slicelit starred call binop unary boolop
+             compare cond list tuple set dict fstring func funcexpr yield
+             yieldfrom namedexpr expr assign augassign if while for break
+             continue pass return class raise try with import importfrom del
+BIN_KINDS  = add sub mul div floordiv mod pow lshift rshift bitand bitor
+             bitxor matmul
+CMP_KINDS  = eq ne lt le gt ge in notin is isnot
+UNARY      = neg pos not invert
+CONST      = int float str bytes bool none ellipsis complex
+CONV       = (none) r s a
+```
+
+Flag-bit optionals per op (bit 1 upward): `slicelit`: lower, upper, step;
+`yield`/`return`: v; `raise`: exc, cause; `import`: alias.
+
+Per-op payloads (after flags/ln). `N` = node, `L` = node-list,
+`S` = str-ref, `SL` = varint count + str-refs:
+
+| op | payload |
+|---|---|
+| const | kind byte; int/float/str/bytes -> S; complex -> S re, S im (float-strings); bool -> byte 0/1; none/ellipsis -> nothing |
+| name | S id |
+| attr | N o, S n |
+| index | N o, N k |
+| slicelit | optional N lower/upper/step per flags |
+| starred / yieldfrom / expr | N v |
+| call | N f, L args, varint kw-count x (byte named? [1 -> S name], N v) |
+| binop | kind byte, N l, N r |
+| augassign | kind byte, N target, N v |
+| unary | kind byte, N v |
+| boolop | byte (0=and, 1=or), L values |
+| compare | N left, varint count x kind byte, L comps |
+| cond | N test, N then, N else |
+| list / tuple / set | L elts |
+| dict | varint count x (byte has-key? [1 -> N k], N v) |
+| fstring | varint count x part: byte flag (0 = text -> S; else bit0=value: N v, conv byte, bit1 -> N spec) |
+| func / funcexpr | S name, byte flags (bit0 gen, bit1 coro), byte pflags (bit0 vararg, bit1 kwarg), SL args, L defaults, [S vararg], SL kwonly, varint kwdefault-count x (byte present? [1 -> N]), [S kwarg], SL locals, SL gdecl, SL ndecl, L body |
+| yield / return | [N v] per flags |
+| namedexpr | N target, N v |
+| assign | L targets, N v |
+| if / while | N test, L then/body, L orelse |
+| for | N target, N iter, L body, L orelse |
+| break / continue / pass | nothing |
+| class | S name, byte kwflag, [kwargs: varint count x (byte named? [1->S n], N v)], L bases, L body |
+| raise | [N exc], [N cause] per flags |
+| try | byte star, L body, varint handler-count x (byte hflags: bit0 t, bit1 name; [N t], [S name], L body), L orelse, L finalbody |
+| with | varint item-count x (byte has-name, N ctx, [N name]), L body |
+| import | S module, byte bind (0 absent, 1 root, 2 none), [S alias] per flags |
+| importfrom | S module, varint count x (S n, S alias) |
+| del | L targets |
+
+Decoding materializes the compact JSON form (spec section 2.2): empty lists,
+false `gen`/`coro`/`star`, and absent optionals are omitted from the produced
+dicts. Key order does not affect structural equality.

diaspore-0.2.0/docs/security.md

@@ -0,0 +1,94 @@
+# Diaspore security model
+
+Diaspore runs Python-subset programs with explicit capabilities and resource
+limits. The threat model assumes an adversary controls source code or a bundle,
+but not the runtime, host process, embedding code, or deployment configuration.
+The runtime must prevent access to host objects and authority not granted by the
+host. Resource isolation also requires operating-system controls.
+
+## Untrusted inputs
+
+The compiler is not a security boundary. Treat bundles as untrusted data even
+when they were produced by `dspc` (`selfhost/dspc.py`). The typed IR is defined in
+`src/diaspore/ir.py`; generate its JSON Schema with `diaspore schema` or
+`make schema`, or use the [published schema](https://radkawar.github.io/diaspore/ir.schema.json).
+Schema validation does not establish that a program is safe or will terminate.
+Apply input-size limits to source, bundles, compressed containers, and snapshots
+before loading them.
+
+## Capabilities and bindings
+
+Without grants, programs can compute, allocate, use the configured standard
+streams, inspect supplied arguments, and call available native modules such as
+`math`, `json`, `random`, `time`, and `re`. Clock access and randomness do not
+require capabilities. Standard input is also available through `input()`.
+
+| Capability | Authority | Scoped grants |
+|---|---|---|
+| `net` | TCP listeners and outbound connections | `--allow-net listen:HOST:PORT` or `connect:HOST:PORT`; `*` matches any host or port |
+| `fs` | File access through `open` | `--allow-fs read:PATH` or `write:PATH`; resolved-path prefix matching |
+| `spawn` | Tasks, channels, and locks | `--allow-spawn`; concurrency model in [spec section 11.9](spec.md#11-native-modules) |
+
+A bare grant permits all operations covered by that capability. Scoped grants
+deny operations not listed. Denied operations raise `PermissionError`.
+Availability of native modules and capabilities differs by runtime; consult the
+runtime README before deploying a policy.
+
+Filesystem checks resolve symlinks before matching paths. They are not a
+replacement for isolated mounts, especially where another process can modify
+the filesystem between checking and opening a path. Network policy matches the
+requested address, not a pinned DNS result. Use IP-based policies or a binding
+that enforces destination policy when DNS changes are a concern.
+
+Environment access, subprocesses, and FFI are not exposed as native sandbox APIs.
+Where supported, `exec`, `eval`, and `compile` compile Diaspore-subset code and
+execute it inside the VM; they do not execute arbitrary host Python.
+
+Host bindings run with host privileges. Validate their inputs, keep their
+interfaces narrow, and expose only the authority the program needs. A binding
+can invalidate the sandbox's isolation if it evaluates input as host code or
+performs unrestricted file or network operations.
+
+## Resource limits
+
+- Fuel (`--max-steps`) meters statements, calls, and selected bulk operations.
+  Exhaustion is an uncatchable trap with exit code 3.
+- Recursion depth (`--max-depth`, default 1000) raises a catchable
+  `RecursionError` when exceeded.
+- Fuel does not bound peak memory, time blocked in I/O or host bindings, or open
+  descriptors. Set process memory and CPU limits, descriptor limits, and an
+  external timeout for hostile workloads. Limit compiler resources as well as
+  runtime resources.
+
+## Runtime isolation
+
+The four runtimes are diaspore-py, diaspore-go, diaspore-ts, and diaspore-lua.
+Their implementations and trusted dependencies differ. The Python reference VM
+uses allowlisted operations on CPython values; Go, TypeScript, and Lua implement
+sandbox values and operations within their respective host environments.
+Memory safety and allowlists do not prove that an interpreter is escape-free.
+
+For untrusted multi-tenant workloads, run each tenant in a separate restricted
+process or container. Grant minimal filesystem and network access to that
+process, regardless of which runtime it uses. Do not rely on an interpreter bug
+being limited to a wrong result or a controlled crash.
+
+## Durable flows and nondeterminism
+
+Durable mode forbids `net`, `fs`, and `spawn` capabilities. Supported effects,
+including host-binding results, are journaled for replay; snapshots contain JSON
+data rather than interpreter internals (see [spec section 14](spec.md#14-durable-flows-suspend--resume)).
+
+Snapshots contain effect results and can therefore contain secrets. Protect
+their confidentiality and integrity. The bundle digest binds a snapshot to a
+program; it does not authenticate the journal or its author. Accept snapshots
+only from trusted storage or authenticate them at the application boundary.
+
+Clock values, randomness, set iteration order, object identities, and allocation
+behavior can be observable. Diaspore does not provide timing-side-channel
+isolation. Durable programs must remain deterministic between journaled effects.
+
+## Reporting
+
+Report vulnerabilities by opening a
+[GitHub security advisory](https://github.com/radkawar/diaspore/security/advisories/new).