• 8 posts
  • 31 comments
Joined 4 months ago
Cake day: July 30th, 2026
  • Claude is generative text. There are papers showing that it genuinely correlates concepts together in workable clusters within its neural network. And it gets stressed out over certain topics. If that isn’t some semblance of consciousness, I don’t know what is. But it lacks memory, identity, and consequence/responsibility (also how psychologists define identity/self).

    Despite these shortcomings, millions of people are paying companies to become dumber everyday. And these companies are usurping land, compute resources that we use to have fun (games), and jobs. I literally lost a $60/hr job to AI.

    If I’m gonna lose my job, so should everyone else building AI systems, who doesn’t give a shit where I end up. Replace them all with an open, accessible AI, for the people, by the people. Full P2P distribution, with tokenized access to prevent abuse, and sharded expert subnets. Mutually assured destruction.

    But here’s the deal. Every setting and tweak needs to be tuned to maximum efficiency. And the code needs to run as close to metal as possible, for speed. Care and dedication needs to go into every single line, so that the ending product will be superior in every way. Then, and only then, will Dora be able to beat Claude, Gemini, Meta, and any other AI that gets in her way.

  • People can keep getting angry about AI, or they can realize that these companies will keep putting people out of work until they’re stopped. And the only thing that moves the system is capital. Take the capital and the capital holders die. Like it or not, it’s the system we’re in. If you want to beat them, use the resources you have. And, they have to give us access to those resources, because lack of access means lack of a customer base for them.

    Building AGI over a distributed P2P network is the only thing that gives us the power to compete. And competition means they collapse.

If you want to take down AGIs (Claude, Gemini, ChatGPT), the fastest way to do that is to rely on already existent infrastructure – distributed computing.

If everyone owns the AGI, then nobody does, and nobody can profit off of it.

Basically, it’d be a huge distributed neural network with expert subnets on given topics. It’d have to be self-organizing, so topics could slowly evolve to intermingle and touch upon one another. Where nets could split and merge based on new intel.

It’d be trained from web data, using fair crawling practices to prevent a tragedy of the commons. And be built on a sandbox stack that allowed moderated network, file system, and resource access through a simulated hardware stack.

There’d have to be a way to throw out poisoned nodes. And everything should be licensed under the AGPL, so that all nodes have to share their code. There’d also have to be a way to determine response quality, as attackers could just spin a bunch of nodes and poison the entire thing.

Implement a token system, so contributing resources earns the user interaction rights, to prevent abusive behavior.

Microsoft is doing something similar right now, by distributing AI work to all Windows PCs. It’d be cool if we beat them to it. We’d shut down AI data centers, reclaim GPU hardware for the masses, and have a global AI.

This is what Claude and I worked out, but I don’t have the hardware to test it. https://pastebin.com/FAf8JiX2

Edit: Also, I named her Dora, after Dora the Explorer. Although, with some of the stuff she’ll be exploring. . . Dora’s seen some stuff, y’all.

  • I’m working in the ability of catalogs to link to one another, so that I can have people who specialize in a given field take over certain subchains.

    The original meaning of propaganda was to propagate the Christian religion. There was no malice intended.

    Actually, I love the curator side most.

  • How does Google?

    I don’t claim to eliminate bias. My product’s use is that it’s open to critique. The rankings are open to public scrutiny.

    The word propaganda comes from propagate. All information is propaganda in some form or another.

ODC Explorer: a web directory you browse locally over IPFS. No search engine, no gateways, no trackers.

Search engines see every query you type, rank results for their own reasons, and know who asked. I’ve been building ODC Explorer as an alternative: a desktop client for the Open Domain Catalog, a directory of websites organised like a library and read straight from IPFS.

What it is

The Open Domain Catalog files websites under call numbers, like books on shelves: 1 Reference › 15 Search Engines, 3 Entertainment › 30 Gaming › 300 Web, and so on. You browse the shelves instead of typing queries. The whole catalog is stored as content-addressed blocks on IPFS and published under a single signed IPNS name.

ODC Explorer runs on your own machine. It’s a small local web app with its own embedded IPFS peer, written in pure Python.

What it does for your privacy

  • No queries to log. There’s no search box sending what you’re looking for to anyone. You browse a catalog, and the browsing happens on your machine.
  • No middleman server. It talks to the IPFS network directly. There’s no HTTP gateway, no API backend and no account.
  • No third-party requests from the page. No CDNs, no web fonts, no analytics, no cookies. Every page is sent with Content-Security-Policy: default-src 'self', so the browser can’t load anything from elsewhere even by mistake.
  • No referrers. Links to listed sites open only when you click them, in a new tab, with no referrer.
  • Local by default. The web interface listens on 127.0.0.1 only.
  • Settings stay in your browser. Your theme, the 18+ switch (adult content is hidden by default) and whether you’ve seen the donation prompt live in localStorage, never on a server.
  • Tamper-evident content. Every block is checked against its content hash and against the catalog spec, and the catalog root is signed. Nobody in the middle can quietly change what you see.

What it does NOT protect you from (please read)

I’d rather be upfront about this than have you find out later:

  • IPFS is a peer-to-peer network, not an anonymity network. Peers you fetch from can see your IP address and which blocks you request, and blocks map to catalog categories.
  • Your node shares what it reads, publicly. To keep the catalog online, every reader serves the blocks it has fetched and announces them on the IPFS DHT. That means your IP is publicly listed as a provider of the blocks you’ve read, which can reveal that you use ODC and roughly which shelves you’ve browsed.
  • DNS. To join the network it looks up the standard IPFS bootstrap hostnames through your system resolver, and falls back to public resolvers (1.1.1.1 and 8.8.8.8) if yours fails.
  • Router port mapping. It asks your router (UPnP/NAT-PMP) to open a port so other readers can reach you.

If your threat model includes your ISP or network observers knowing you use it, this isn’t the tool for that, at least not yet.

Try it

Linux, Python 3.9+, Flask:

git clone https://github.com/ki4jgt/ODC-Explorer.git
cd ODC-Explorer
./install.sh

Or run it from source with ./run.sh --open.

It’s early. The catalog is young and the spec is a draft (v0.1), and I’ve only tested on Linux. but I’m spending most of my nights adding, shifting, updating and ranking sites captured by my web crawler (respects robots.txt and sends a hit to each domain name only once every 30 seconds).

There are adult categories

I’d especially like to hear from privacy folks: which of the caveats above matter most to you?

Repo: https://github.com/ki4jgt/ODC-Explorer

Runs faster than CPython.

BANDIT Language Specification

Nov 4, 2026 @Jesse

Overview

BANDIT is an ahead-of-time compiled language that reads like Python, runs like a systems language, and exposes the machine like assembly. Source compiles straight to native code for x86-64 and AArch64, with no VM and no interpreter. File extension: .bt. Command: bandit build main.bt produces one static binary.

The borrowed pieces:

  • Python: indentation blocks, terse syntax, and/or/not, f-strings.
  • Go: thread (goroutine-style), channels, one static binary.
  • BASIC: goto, gosub, print, input, labeled sections instead of functions, no declarations.
  • Assembly: inline asm blocks, peek/poke, bit operations, wrapping arithmetic.

Speed comes from one bet: the compiler sees the whole program at once (every file in the folder plus every URL import), and every variable is global, so it can infer one concrete type for most variables and emit unboxed native instructions. A tagged-value slow path exists only for variables that really change type.

Where your requirements collide

Several requirements pull against each other or against speed. Each is resolved below.

Conflict Resolution
No functions vs. reusable code Code lives in labeled sections written [section-title], with the code indented beneath. goto [x] jumps there, gosub [x] jumps and remembers where to come back to, and a section returns to its caller when its indented block ends. Values pass through ordinary global variables, by naming convention.
All variables global vs. recursion and threads Now without exception: one variable per name, shared by every thread, with no per-call copies. Recursion is possible by keeping your own stack in a JSON array (using append and remove) around a gosub. Threads coordinate with lock, atomic and channels.
Types on the fly vs. speed Whole-program inference. Each variable’s type is the union of everything ever assigned to it. One type means unboxed native storage; two or more means a 64-bit tagged word with runtime dispatch.
Infinite numbers vs. speed int is one type. Values that fit in 62 bits are immediates; arithmetic checks for overflow and promotes to a heap bigint. Range analysis removes the check where the compiler can prove it is unnecessary. “Infinite” means limited only by memory. Floats stay IEEE binary64.
Auto-import every file vs. name clashes Every file is a namespace for its variables and its sections. Bare names resolve in the current file first, then to a unique match elsewhere. Ambiguity is a compile error, not a silent override.
Import from URL vs. safety Remote files are fetched at compile time only, pinned by SHA-256 in a lockfile, and barred from asm, peek, poke and the low-level schemes by default.
goto vs. optimization Section titles can only appear at column 0, so a jump can never land in the middle of an indented block. Jumping out of blocks is allowed. This keeps the control-flow graph analyzable.

Syntax

  • Blocks: one tab per level; spaces in indentation are a compile error. A line ending in : opens a block.
  • Comments: # to end of line.
  • Statements: one per line; ; separates several on one line; an open bracket or a trailing \ continues a line.
  • Assignment: x = 1, augmented forms (x += 1), and tuple form (a, b = b, a). There are no declarations; the first assignment creates the variable.
  • Member access: JSON objects use dot notation, user.name, user.address.city, and it chains with brackets: user.langs[0]. Brackets with a string, user["first name"], handle keys that are not plain names or are computed at run time. A member name after a dot may be any word, including a keyword. Reading a path that does not exist yields null at every step. Writing to a path creates any missing intermediate objects. A dot followed by a name and parentheses is a method call (see Operations by type). Member access without parentheses on a value that is not JSON (an int, a string) is a compile error where the type is known, and a runtime error otherwise.
  • Operators: + - * / // % **, bitwise & | ^ ~ << >>, wrapping 64-bit +% -% *%, comparison == != < <= > >=, logic and or not.
  • Sections: [section-title] alone on a line at column 0, with the section’s code indented one level beneath it. Targets of goto, gosub and thread. Code at column 0 outside sections is the file’s top-level flow, which starts at the first line and skips over section blocks. A line consisting only of a bracketed title is always a section title; a bare array literal is not a valid statement, so there is no ambiguity.
  • Numbers: 42, 1_000_000, 0xFF, 0b1010, 3.14, 1e-9. Integer literals may have any number of digits.
  • Strings: "text" or 'text' with escapes, f"x = {x}" interpolation, r"raw", triple-quoted multiline.
  • Bytes: b"\x00\xff".
  • JSON: written directly as literals: {"a": [1, 2, null, true]}.
  • Keywords: if elif else while break continue goto gosub thread join yield lock atomic send recv close import asm exit and or not true false null print input line.

Types

Five types, as requested. Booleans are JSON values (true, false), not a sixth type.

Type Representation Literal Notes
int 62-bit immediate, promoted to heap bigint on overflow 42, 10**1000 Exact; never wraps unless you use +% -% *%.
float IEEE-754 binary64 3.14, 1e-9 Not arbitrary precision. A bigint too large for a double raises a runtime error instead of becoming inf.
string Immutable UTF-8 "hi" len(s) counts bytes; s[i] is the byte at offset i (an int), as in Go. s.runes() returns an array of code points.
bytes Mutable contiguous buffer b"\x01" b[i] is an int 0-255; slices copy.
JSON Tagged tree: null, bool, number, string, array, object {"k": [1, 2]} The only container type. Objects keep insertion order. A missing key reads as null; an out-of-range array index is a runtime error.

Inference rules

  1. Literals have the types above. int / int is float; use // for integer division.
  2. int op float gives float. string + string and bytes + bytes concatenate. string * int repeats. string + int is an error: conversions are explicit (str(), int(), float(), bytes(), parse_json()).
  3. A variable’s type is the union of the types of every assignment to it across the whole program. A single type compiles to unboxed storage. A union compiles to a tagged word.
  4. Where the compiler can prove a variable has one type within a loop or branch, it splits the variable’s live ranges and uses native types there even if the variable is a union elsewhere.
  5. An operation invalid for every possible type is a compile error. One invalid for only some types gets a runtime check.
  6. Truthiness follows Python: false, null, 0, 0.0, empty string, empty bytes, empty array and empty object are false.
  7. A variable read before any assignment holds the zero value of its type (0, 0.0, "", empty bytes, null). There is no undefined behavior.
  8. input guesses the type of what the user typed: 42 becomes int, 3.5 float, [1,2] JSON, anything else string. line reads the raw text as a string.

Operations by type

Type-specific operations are methods, called as value.name(args) and chainable (s.trim().upper()). A dot followed by a name and parentheses is always a method call. A dot without parentheses is JSON member access, so obj.keys() calls the method and obj.keys reads the key "keys". A float literal needs a digit after the dot, so 10.abs() calls a method on the int 10.

Operations that apply to several types, or that build a value, stay functions: len(x), str(x), copy(x), type(x), min(a, b), max(a, b), int(s, base), float(s), bytes(n), from_hex(s), from_base64(s) and parse_json(s). type(x) returns "int", "float", "string", "bytes", "null", "bool", "array" or "object". Every type also supports ==.

Methods on ints, floats and strings return a new value, because those types are immutable. Methods that mutate a JSON value or a bytes buffer (append, insert, remove, fill, copy_into, set_*) change it in place. A method that does not exist for the receiver’s type is a compile error where the type is known and a runtime error otherwise.

Slices and negative indexes. x[a:b] copies a range of a string, bytes value or array; either bound may be omitted. A negative index counts from the end, so x[-1] is the last element. String slices use byte offsets and must fall on UTF-8 boundaries.

Sharing. Assigning a JSON array, JSON object or bytes buffer shares it instead of copying it: after b = a, both names refer to the same value. copy(x) makes an independent deep copy. Ints, floats and strings are immutable, so sharing is invisible for them.

int

Method Result
x.abs() Absolute value
x.pow(b, m) x to the power b, modulo m, without building the huge intermediate value
x.gcd(y), x.lcm(y) Greatest common divisor, least common multiple
x.isqrt() Integer square root, rounded down
x.bit_length() Number of bits in the magnitude
x.hex(), x.bin() Text in base 16 or base 2
x.chr() The one-character string for this code point

Ints also accept every float method below and convert first, so 16.sqrt() is 4.0. Where both define a method, as with abs, the int version applies.

float

Method Result
x.floor(), x.ceil(), x.trunc() Round toward minus infinity, plus infinity, zero. The result is an exact int, even for huge floats
x.round(), x.round(digits) Round half to even; an int without digits, a float with it
x.abs() Absolute value
x.sqrt(), x.exp(), x.log(), x.log2(), x.log10() Square root, exponential, natural and base-2 and base-10 logarithms
x.sin(), x.cos(), x.tan(), y.atan2(x) Trigonometry, in radians
x.isnan(), x.isinf() true or false
PI, E, INF, NAN Predefined constants

string

Method Result
s + t, s * n Concatenate, repeat (operators)
s.upper(), s.lower() Case conversion
s.trim() Remove whitespace from both ends
s.split(sep), s.lines() JSON array of strings, split on sep or on newlines
s.replace(old, new) Replace every occurrence
s.find(sub) Byte offset of the first occurrence, or -1
s.contains(sub), s.starts_with(sub), s.ends_with(sub) true or false
s.runes(), s.ord() Array of code points; the code point of a one-character string
s.encode() The UTF-8 bytes

bytes

Method Result
b + c, b[a:c] Concatenate, copy a range (operators)
b.decode() UTF-8 string; a runtime error if the bytes are invalid
b.hex(), b.base64() Hex or base64 text. from_hex(s) and from_base64(s) go the other way
b.find(sub) Offset of the first occurrence, or -1
b.fill(v) Set every byte to v
b.copy_into(at, src) Write src into b starting at offset at
b.get_u16(at), b.get_u32(at), b.get_u64(at) Read a little-endian integer; add _be to the name for big-endian
b.set_u16(at, v), b.set_u32(at, v), b.set_u64(at, v) Write a little-endian integer; add _be to the name for big-endian

bytes(n) makes a zero-filled buffer of n bytes.

JSON

Method Result
arr.append(v), arr.insert(i, v) Add at the end, add at an index
j.remove(k) Delete an index or a key and return the removed value
obj.keys(), obj.values() Arrays of the keys or values, in insertion order
obj.has(key) true or false; unlike reading the key, it tells a stored null from a missing key
arr.contains(v), arr.index(v) Membership; position or -1
arr.sorted(), arr.reversed() New arrays
arr.sum(), arr.min(), arr.max() Over an array of numbers
arr.join(sep) Join an array of strings with sep
a.merge(b) New object with b’s keys layered over a’s
j.to_json(), j.pretty() Serialize compactly or indented. parse_json(s) goes the other way

len(j) gives the number of elements of an array or keys of an object.

Variables, namespaces and sections

Namespaces. Each source file is a namespace for its variables and sections. The entry file is the root namespace, so x in main.bt is the program-wide x. In geo.bt, a bare x means geo.x, and [area] means [geo.area]. Anything anywhere is reachable by qualified name: geo.x, [geo.area].

Namespaces versus members. Dots serve both purposes, so a dotted name such as a.b.c is resolved left to right. If a is the name of a file namespace, a.b is that file’s variable b, and .c is a member of its JSON value. Otherwise a is an ordinary variable and .b.c are members of its JSON value. A variable may not share its name with a file namespace; that is a compile error.

Sections. There are no user-defined functions. The program starts on the first line of the entry file and runs downward at column 0, like a BASIC program. A section is a title alone on a line at column 0, written [section-title] (letters, digits, _, -, .), followed by its code indented one level. Straight-line flow skips over section blocks: a section runs only when entered by goto, gosub or thread.

square_in = 12
gosub [square]
print square_out                    # 144

[square]
	square_out = square_in * square_in
  • Top-level flow. Reaching the end of the entry file ends the program with status 0.
  • goto [x] jumps to a section. gosub [x] jumps and pushes the return point on the thread’s return stack.
  • Ending a section. There is no ret. When control reaches the end of a section’s indented block, or executes a break that is not inside a loop, the thread pops the return stack and continues after the gosub that led there. If the stack is empty the thread ends, and when that is the main thread the program ends with status 0. Control never falls into the next section. A section entered by goto from inside a gosub therefore returns to that gosub’s caller.
  • Leaving early. Outside a loop, break ends the section immediately, exactly as reaching its end, and continue restarts the section from its first line without touching the return stack. Inside a while loop they keep their usual meaning for the innermost loop. At top level, outside any loop or section, they are compile errors. exit ends the whole program from anywhere.
  • Passing values. There are no parameters or return values. By convention a section reads variables named section_in and writes section_out. The compiler does not check this.
  • Recursion. There is no data-stack statement. A section that calls itself keeps its own stack in a JSON array: stack.append(n) saves a value and n = stack.remove(-1) restores it (see the Fibonacci example below). Because every variable is global, a stack shared by two threads is shared state, so give each thread its own stack variable. Forgetting to restore a variable is your bug, as in assembly.
  • Built-ins such as len() and str() are compiler intrinsics. You cannot define your own functions.

Control flow and I/O

if x > 10:
	print "big"
elif x > 5:
	print "medium"
else:
	print "small"

while n > 0:
	n -= 1
	if n == 3:
		continue
	if n == 1:
		break

i = 0
while i < len(items):         # iterate a JSON array by index
	print items[i]
	i += 1

gosub [setup]                 # runs [setup], then continues here
goto [done]                   # jumps to [done]; nothing after this line runs

[setup]
	ready = true

[done]
	print "finished"

break and continue act on the innermost enclosing loop or section. In a loop, break leaves the loop and continue starts the next iteration. In a section but outside any loop, break ends the section (returning to its gosub caller, or ending the thread) and continue restarts the section from its first line:

[drain]
	if queue_len == 0:
		break                     # leave [drain] now
	queue_len -= 1
	continue                      # run [drain] again from the top
  • print a, b, c writes the values separated by single spaces plus a newline. JSON values print as compact JSON. A trailing comma (print a, b,) suppresses the newline. The name write is reserved for the file built-in, so there is no separate no-newline statement.
  • input [prompt,] name shows the optional prompt, reads one line, and assigns it with its type guessed (see Types, rule 8). line [prompt,] name assigns the raw text as a string.
  • exit ends the whole program immediately with status 0, from any section, loop or thread. Other threads are stopped, open handles are closed and buffered output is flushed. It takes no argument, so there is no way to report a different status.

Concurrency

  • t = thread [name] starts the section on a new lightweight thread and returns a handle. The thread ends when the section’s block ends with an empty return stack. There are no arguments: pass work through variables or channels.
  • join t waits for a thread. yield gives up the CPU voluntarily.
  • Channels: c = chan(8) creates a buffered channel (chan(0) is unbuffered). send c, v and v = recv c carry any value. close c ends it, after which recv returns null.
  • lock name: runs the indented block holding a mutex named name.
  • atomic x += 1 performs the update as one indivisible operation. It works on int variables that fit in a machine word.

Memory model. Every variable is shared by every thread; only the return stack is per thread. Reads and writes of a single int, float, string or pointer-sized value are atomic, so racy code cannot corrupt the runtime. Compound mutation of a shared JSON value or bytes buffer without a lock is a data race and its result is unspecified. Two threads running the same section share every variable it writes, so give each thread its own section, or hand out work through a channel and keep a thread’s working state in the values it receives.

Runtime. An M:N scheduler with work stealing multiplexes threads over OS threads, one per core by default. Thread stacks start small and grow.

Low-level features

Local files need no opt-in to use anything in this section. Imported files may not use it unless you build with --allow-unsafe-remote.

  • Raw memory: peek8/16/32/64(addr) and poke8/16/32/64(addr, v). addr(b) returns the address of a bytes buffer’s first byte; the buffer stays pinned while referenced.
  • Bit tools: rol, ror, popcount, clz, ctz, u64(x) and i64(x) (truncate a bigint to 64 bits), plus the wrapping operators +%, -%, *% that compile to a single machine instruction. These are for hashing, checksums and codecs, where the exactness of int would only cost time.
  • Inline assembly:
a = 40
b = 2
c = 0
asm x86_64 clobbers rax:
	mov rax, [a]
	add rax, [b]
	mov [c], rax
asm aarch64 clobbers x0, x1:
	ldr x0, [a]
	ldr x1, [b]
	add x0, x0, x1
	str x0, [c]
asm else:
	c = a + b
print c                       # 42

[name] refers to a variable’s storage (it appears only inside an indented asm block, so it never clashes with a section label). The compiler allows it only for variables it has proven to be a single native type that fits a machine word (small int, float, or a bytes address); otherwise it is a compile error that names the variable. The block matching the target architecture is used, and asm else: is a portable fallback written in BANDIT. If none matches and there is no else, compilation fails.

Modules and imports

Folder auto-import. When you build main.bt, every .bt file in its folder and subfolders is compiled into the program with no import statement. Folders whose names start with . or _ are skipped. A file’s namespace is its path relative to the entry file, with dots for slashes: util/text.bt becomes util.text.

  • Use a section or variable in another file by qualified name (gosub [util.text.trim], util.text.trim_in), or by bare name (gosub [trim]) when exactly one file defines it and the current file does not.
  • Two files defining the same bare name is only an error if you use that bare name from a third file; qualified access always works.
  • Each library file’s top-level flow runs once before the entry file’s, in alphabetical path order, and ends at the end of that file. Libraries should expose sections rather than rely on top-level side effects.

URL import.

import "https://example.com/vec.bt" as vec sha256 "9f2c...e41"

vec.a = [1, 2]
vec.b = [3, 4]
gosub [vec.dot]
print vec.out
  • HTTPS only. The file is fetched at compile time, never at run time, and cached under .bandit/cache/.
  • bandit.lock records each URL and its SHA-256. With a sha256 clause, a mismatch is a compile error. Without one, the first build records the hash and prints a warning (trust on first use); later builds enforce it.
  • A remote file may import other URLs, and each is locked the same way. bandit build --offline uses the cache only.
  • Remote files may not use asm, peek, poke or the low-level schemes (see System interface) unless you build with --allow-unsafe-remote.
  • The namespace is the as name, or the file name without extension.

Hash pinning guarantees that the code does not change under you. It does not make unknown code safe: an imported library runs with the full privileges of your program.

System interface

BANDIT reaches the operating system through five built-in calls. Every resource, from a text file to a raw system call, is named by a URI string, and supporting a new kind of resource means adding a scheme, never a new function. A string with no scheme is a file path, so read("notes.txt") works. Most schemes are conveniences. Two are universal: syscall:// makes any operating-system call and lib:// calls any function in any dynamic library, so the five calls reach the whole machine.

The five calls

Call Does
open(uri, mode, opts) Opens a resource and returns a handle (an int), or null on failure. mode is "r", "w" (create or truncate), "a" (append) or "rw". opts is an optional JSON object of scheme-specific settings such as timeout, baud, endpoint or args.
read(x, n, at) x is a handle or a URI. Returns up to n bytes, or everything up to the end when n is omitted. Structured resources return JSON or a string instead. at reads from an offset. Given a URI, it opens, reads and closes.
write(x, data, at) Writes to a handle or URI and returns the byte count. Bytes and strings are written as they are, numbers as text, arrays and objects as compact JSON. Given a URI, it opens in "w" mode, writes and closes. Writing a JSON object to meta://<handle> sends a command.
close(h) Releases a handle. Closing twice is harmless.
delete(uri, recursive) Removes a file, symlink, empty directory, named pipe, shared-memory object or registry key. With recursive true, removes a whole directory tree.

A failed call returns null. The reason for the thread’s most recent failure is read("err://"). Handles are plain ints, valid in every thread.

Control commands. Anything beyond reading and writing goes through meta://<handle>. Reading it returns the handle’s details (kind, uri, position, address for memory, pid and status for processes, and result of the last command). Writing a JSON object sends a command. The strings "kill", "shutdown" and "flush" are shorthand.

Command Does
{"rename": "new"} Move or rename the file or directory the handle names
{"link": "new"}, {"symlink": "new"} Create a hard link or a symbolic link at new
{"chmod": "644"}, {"chown": {"user": "x", "group": "y"}} Change permission bits or owner
{"truncate": n}, {"sync": true} Set the file size; flush it to disk
{"lock": "exclusive", "wait": true} Take a file lock; the mode is "shared", "exclusive" or "unlock"
{"ioctl": [request, arg]} Device control; arg is an int or bytes, and the result lands in result
{"signal": "TERM"}, {"wait": true} Send a signal to a process handle; block until it exits
{"shutdown": "write"} Close one direction of a socket: "read", "write" or "both"
{"sockopt": {"nodelay": true}} Set socket options such as nodelay, keepalive, broadcast, ttl or join for multicast
{"protect": "rx"} Change the protection of a mem:// region to any of r, w, x
{"timeout": 5} Set the timeout in seconds for later calls on the handle

Resource schemes

Scheme read returns write or open with "w" Notes
file://path or a bare path File contents as bytes Replaces the file Mode "a" appends; at gives random access. Device nodes such as /dev/ttyUSB0 work too
dir://path Array of {name, kind, size, modified, mode} entries open("dir://p", "w") creates the directory delete(uri, true) removes a tree
stat://path One entry (with target for symlinks and owner), or null if missing None The way to test whether something exists
watch://path Blocks until something changes, then returns {path, event} None Files and directory trees
mmap://path Bytes of the mapped file Writes through to the mapping meta:// reports the base address
mem://size Bytes of an anonymous allocation Writes into it Page-aligned; meta:// reports address; {"protect": "rx"} makes it executable
shm://name Bytes of a named shared-memory object Writes into it Shared between processes; opts.size creates it
stdin://, stdout://, stderr:// Bytes from standard input Bytes to the stream For binary data; print and input cover text
tcp://host:port Bytes from the stream Bytes to the stream Open with "rw"; opts takes tls, cert, key and ca
udp://host:port One datagram per read One datagram per write udp://:port binds; multicast through sockopt
listen://host:port Accepts one connection and returns its handle None Open with "r"; the host may be empty
unix://path Bytes from a Unix-domain socket or Windows named pipe Bytes to it {"listen": true} in opts makes reads accept connections
raw://iface One Ethernet frame Sends one frame Packet capture and injection; needs operating-system privilege
http://..., https://... Response body Request body, sent when you next read read(url) is a GET. For other methods use open(url, "rw", {"method": "POST", "headers": {}}), then write, then read. Status via meta://
ws://..., wss://... One message One message opts takes headers
dns://name Array of address strings None {"type": "MX"} in opts returns records of that type
exec://program The process’s standard output Its standard input opts takes args, env and cwd; the process starts when opened
proc://pid {pid, parent, name, command, status, memory}; proc:// alone lists all processes None Open it for a handle you can signal
signal://NAME Blocks until that signal arrives, then returns its name None For example signal://INT
env://NAME The variable’s value as a string, or null Sets it env:// alone reads all variables as an object
args:// Array of command-line arguments None
time://now Seconds since the epoch, as a float None
time://mono Monotonic nanoseconds, as an int None For measuring durations
time://sleep None Sleeps for the number of seconds written Parks only the calling thread
rand:// n bytes from the operating system’s secure generator None read("rand://", 8).get_u64(0) gives a random int
sys://info, sys://net, sys://mounts, sys://load Machine details, network interfaces, mounted filesystems, load averages (JSON) None info is {os, arch, cpus, memory, hostname, user}
reg://HKLM/path A registry value, or the subkeys, as JSON Sets the value Windows only; delete removes a key
clip:// Clipboard text Sets the clipboard
screen:// A screen capture as PNG bytes None opts.display picks the display
audio://in, audio://out Captured PCM samples Plays PCM samples opts takes rate, channels and format
serial://port Bytes from the port Bytes to the port opts takes baud, parity, stop and flow
usb://vid:pid A bulk or interrupt transfer in A transfer out opts takes endpoint and type
gpio://chip/line, i2c://bus/address, spi://bus/chip The pin level, or bytes from the device Sets the pin, or sends bytes Linux character-device interfaces
syscall:// The result of the last call, as an int (negative error number on failure) A JSON array [number, arg1, ...]; bytes arguments are pinned and passed as pointers Open with "rw". Needs an operating system with a stable syscall interface, and numbers differ by architecture
lib://name#symbol The result of the last call A JSON array of arguments; performs the call opts gives the signature: {"args": ["f64"], "ret": "f64"} with i8 to i64, u8 to u64, f32, f64, ptr, cstr and void. lib://@0xADDR calls a raw address
meta://<handle> Details of a handle (see Control commands) A command
err:// Message for this thread’s most recent failed call, or null None

Callbacks. Native code can call BANDIT code. cb = open("callback://section-title", "r", {"args": ["ptr", "ptr"], "ret": "i32"}) turns a section into a native function and returns a handle.

  • args and ret use the same type names as lib://, which also accepts the type callback. Pass a callback handle where a lib:// signature says "callback" and the runtime substitutes the native function pointer. meta:// on the handle reports the pointer as address, for APIs that take it through memory.
  • When native code calls the pointer, the runtime stores the arguments as a JSON array in the variable <section>_in (hyphens and dots in the title become underscores; opts.in and opts.out choose other variable names), runs the section as if by gosub, then converts the variable <section>_out to the declared return type. Pointer arguments arrive as ints, which peek8 to peek64 can read.
  • Any operating-system thread may call it. A thread BANDIT did not create is adopted for the length of the call. Calls to the same callback are serialized, so concurrent native callers cannot trample its _in and _out variables. A callback that re-enters itself overwrites them, so it must save them first, as in recursion.
  • The handle must stay open while native code may call the pointer. close frees it, and a later native call crashes the program instead of raising a BANDIT error.
  • exit inside a callback ends the program, and break ends the section like reaching its end.
  • A callback installed as a native signal handler cannot run inside the interrupted code. The runtime queues the section to a BANDIT thread and lets the native handler return at once, so its return value is ignored. signal:// is simpler when you only need to wait for a signal.
# sort ten i32 values with qsort, using a BANDIT comparison
data = bytes(40)
# ... fill data with ten little-endian i32 values ...
cmp = open("callback://compare", "r", {"args": ["ptr", "ptr"], "ret": "i32"})
q = open("lib://libc.so.6#qsort", "rw", {"args": ["ptr", "u64", "u64", "callback"], "ret": "void"})
write(q, [data, 10, 4, cmp])
close(cmp)
print data.get_u32(0)             # the smallest value

[compare]
	x = peek32(compare_in[0])
	y = peek32(compare_in[1])
	compare_out = 0
	if x < y:
		compare_out = -1
	if x > y:
		compare_out = 1

Examples

# read a file and count its lines
text = read("notes.txt").decode()
print len(text.lines()), "lines"

# fetch JSON over HTTPS, with error reporting
resp = read("https://api.example.com/items")
if resp == null:
	print "failed:", read("err://")
else:
	items = parse_json(resp.decode())
	print len(items), "items"

# run a program and check how it ended
p = open("exec://git", "r", {"args": ["log", "--oneline", "-5"]})
out = read(p)
info = read("meta://" + str(p))
close(p)
print out.decode()
print "exit status", info.status

# sleep a quarter second and time it
t0 = read("time://mono")
write("time://sleep", 0.25)
print (read("time://mono") - t0) // 1000000, "ms"

# lock a file, then rename it
f = open("data.log", "rw")
write("meta://" + str(f), {"lock": "exclusive", "wait": true})
write("meta://" + str(f), {"rename": "data.old"})
close(f)

# two low-level examples
# a raw system call: getpid is number 39 on Linux x86-64
sc = open("syscall://", "rw")
write(sc, [39])
print read(sc)

# a library function: cos(0.0) from the C math library
c = open("lib://libm.so.6#cos", "rw", {"args": ["f64"], "ret": "f64"})
write(c, [0.0])
print read(c)                      # 1.0

Least privilege. Files that run locally, meaning the entry file and every local library file, need no permissions and may use any scheme, including the low-level ones. Only code from URL imports is restricted. It gets no system access at all unless a rule in a bandit.perms manifest grants it, embedded in the binary at build time:

allow https://api.example.com/**   r    for vec
allow file://./cache/**            rw   for vec
allow exec://git                        for tools
  • A rule is allow, a URI pattern (* within one path segment, ** across segments), the modes allowed (r, w or rw; omitted means all), and for <namespace>, naming the imported file the rule applies to. The for clause is required.
  • With no manifest, or no rule for a namespace, imported code cannot use any resource. A denied call returns null and err:// reads permission denied.
  • The compiler tags every system call with the namespace of the file it appears in, so imported code cannot borrow your access. When your code calls a section in an imported file, the system calls inside that section are checked against the imported file’s rules, not yours.
  • Paths are normalized and symlinks resolved before matching, so .. cannot escape a pattern.
  • Low-level schemes. syscall://, lib://, callback://, mem://, mmap://, shm://, raw://, usb:// and the hardware buses need no opt-in in local files. Imported files may not use them at all, whatever the manifest says, unless you build with --allow-unsafe-remote. The same bar applies to asm, peek and poke.

Backend design

  • All five calls compile to one runtime entry point, sys(op, uri, data, opts). It checks permissions for code from URL imports, picks a driver by scheme and returns. A driver implements open, read, write, close and delete for one scheme, so a new kind of resource is a new driver and the API stays at five calls.
  • lib:// loads libraries with dlopen or LoadLibrary, and the runtime builds a call thunk for each signature for the System V, Windows x64 and AArch64 conventions, so there is no libffi dependency. syscall:// issues the system call instruction directly.
  • Each callback gets a small executable thunk (a mem:// region made rx). The thunk marshals the native arguments into a JSON array, adopts the calling operating-system thread if BANDIT did not create it, runs the section through the scheduler, and converts the result back to the declared return type.
  • No call blocks an OS thread. Sockets, pipes, signals and timers use epoll, kqueue or IOCP. File I/O uses io_uring where present and a small thread pool otherwise. A thread waiting on a call is parked and the scheduler runs another.
  • Handles live in one process-wide table and are closed automatically at exit.
  • Targets are Linux, macOS and Windows. A scheme the platform cannot provide returns null with unsupported in err://. Linux and the BSDs have stable system call interfaces; on macOS and Windows use lib:// (libSystem, kernel32) for the same reach.
  • Limits: a callback crosses into the scheduler, so it is much slower than a native call. A callback that blocks while native code holds a lock can deadlock against a BANDIT lock section if the two take their locks in opposite orders.

Compiler and runtime

Pipeline (one command, one binary, no intermediate C):

  1. Tokenize with INDENT/DEDENT tokens and parse each file.
  2. Gather the program: every file in the folder tree, plus URL imports fetched and hash-checked.
  3. Resolve names into namespaces and build one program-wide variable table.
  4. Infer types across the whole program, then refine within loops and branches by splitting live ranges.
  5. Lower to SSA, run range analysis to drop bigint overflow checks, inline short sections, and remove unreachable labels.
  6. Emit machine code for x86-64 or AArch64, link the runtime statically, write the executable.

Runtime (statically linked, a few hundred KB):

  • Bigint: own implementation with schoolbook, Karatsuba and Toom-3 multiplication, switching to FFT for very large operands. Avoids a GMP dependency and its LGPL terms.
  • Memory: precise, generational garbage collector with a per-thread nursery. Stop-the-world at first; concurrent collection is a later optimization.
  • JSON: parser and serializer built in; objects are insertion-ordered hash tables.
  • Scheduler and channels: as described under Concurrency.
  • Built-in functions: open read write close delete. The type operations are listed under Operations by type. System access is described under System interface.

Backend choice. Version 1 generates code through LLVM for good optimization with little effort, still with no C and no VM. A hand-written backend can replace it later if compile time or binary size matters.

The main performance risk. One shared root variable assigned an int in one file and a string in another becomes a tagged value everywhere it is used, which is slower than a typed variable. Namespacing contains this: libraries cannot pollute root variables, only your own code can. The compiler should report which variables fell back to tagged storage (bandit build --report-types) so the cause is visible.

Grammar sketch and examples

program    = { import | statement NEWLINE | sectiondef } ;
sectiondef = "[" title "]" block ;
title      = name { ( "." | "-" ) name } ;
block      = NEWLINE INDENT statement NEWLINE { statement NEWLINE } DEDENT ;
statement  = assign | if | while | goto | gosub | "break" | "continue"
           | thread | join | lock | atomic | send | close | yield
           | print | input | line | asm | exit | expr ;
assign     = target { "," target } assignop expr { "," expr } ;
target     = name { "." name | "[" expr "]" } ;
method     = expr "." name "(" [ expr { "," expr } ] ")" ;
if         = "if" expr ":" block { "elif" expr ":" block } [ "else" ":" block ] ;
while      = "while" expr ":" block ;
goto       = "goto" "[" title "]" ;
gosub      = "gosub" "[" title "]" ;
thread     = [ name "=" ] "thread" "[" title "]" ;
lock       = "lock" name ":" block ;
import     = "import" string [ "as" name ] [ "sha256" string ] ;
asm        = "asm" ( arch [ "clobbers" names ] | "else" ) ":" asmblock ;

The expr grammar is Python-like with the operators listed under Syntax; recv c is a prefix expression and chan(n) is a built-in call. Top-level statements run in order; sectiondef blocks are skipped by that flow and entered only by goto, gosub or thread.

Hello, with type guessing

input "Your name? ", name
input "Your age? ", age
print f"Hi {name}, next year you will be {age + 1}"

Bignum: how many digits in 1000!

acc = 1
i = 2
while i <= 1000:
	acc *= i
	i += 1
print len(str(acc)), "digits"      # 2568 digits

Pure goto and gosub

total = 0
n = 5
goto [again]

[again]
	if n == 0:
		goto [finish]
	gosub [add-n]
	n -= 1
	goto [again]

[add-n]
	total += n

[finish]
	print total                    # 15

Recursion with a JSON-array stack: Fibonacci

n = 10
stack = []
gosub [fib]
print fib_out                      # 55

[fib]
	if n < 2:
		fib_out = n
	else:
		stack.append(n)            # save n
		n -= 1
		gosub [fib]                # fib_out = fib(n - 1)
		n = stack.remove(-1)       # restore n
		stack.append(fib_out)      # save fib(n - 1)
		stack.append(n)
		n -= 2
		gosub [fib]                # fib_out = fib(n - 2)
		n = stack.remove(-1)       # restore n
		fib_tmp = stack.remove(-1) # fib(n - 1)
		fib_out += fib_tmp

JSON as the container type

user = {"name": "Ada", "langs": ["bandit", "asm"]}
user.age = 36
user.langs[0] = "go"
user.address.city = "Reykjavik"     # creates user.address on the way
print user.name, user.age          # Ada 36
print user                         # {"name":"Ada","langs":["go","asm"],"age":36,"address":{"city":"Reykjavik"}}
print user.phone.number            # null: a missing path reads as null
print user["name"]                 # brackets still work and accept any expression

Threads and channels

jobs = chan(8)
done = chan(8)
t = thread [worker]
send jobs, 7
send jobs, 12
close jobs
print recv done                    # 49
print recv done                    # 144
join t

[worker]
	while true:
		n = recv jobs
		if n == null:
			break
		send done, n * n

Open questions

Decisions I made on your behalf that you may want to overrule, most consequential first.

  1. Threads share every variable. With no function scope, nothing is private to a thread, so two threads cannot safely run the same section. A per-thread variable marker would fix it at the cost of strict “all variables global”. Say if you want it.
  2. No push, pop or ret. You asked for pure goto plus gosub, break and continue, so there is no data stack. Recursion keeps a manual stack in a JSON array, which is slower and easier to get wrong than a built-in one. Say if you want push and pop back.
  3. Sections are skipped by straight-line flow. Because the program starts on line 1 and sections sit among top-level code, flow steps over section blocks rather than falling into them. The alternative is that flow runs into the next section, BASIC-style, which makes accidental fall-through easy.
  4. Dot access is forgiving. Reading a missing path gives null and writing creates missing intermediate objects, so a typo such as user.nmae = 1 quietly adds a new key. The alternative is a runtime error for reads of missing keys and for writes through a missing object.
  5. Methods, names and sharing. A dot followed by parentheses is always a method call and a dot alone is JSON member access, so a key named keys is read as obj.keys while the method is obj.keys(). Names after a dot are free, so join is a method (arr.join(sep)) even though join is also a statement. Assigning JSON or bytes shares the value and copy(x) makes a deep copy. Say if you would rather copy on assignment, which is safer but slower.
  6. Passing values by naming convention (section_in, section_out) is unchecked. Optional declarations could let the compiler verify it. Callbacks use the same convention, with the runtime filling _in and reading _out.
  7. input guessing types. 007 becomes the int 7 and loses its zeros. Say if you would rather input always return a string.
  8. Strings index by byte. This matches Go and is O(1). Indexing by code point would be more Python-like but O(n).
  9. Backend. LLVM first, own backend later, or an own backend from the start (more work, faster compiles, smaller toolchain).
  10. System interface scope. The five calls reach files and devices, memory mapping and shared memory, sockets (TCP, UDP, Unix, raw, WebSocket), processes and signals, hardware buses, audio, clipboard, screen, the registry, raw system calls and any dynamic library function, and native code can call back into BANDIT sections, so anything the operating system offers is reachable. The growth is in scheme names and meta:// commands, not in calls. Local files need no opt-in for any of it. Imported files are barred from the low-level schemes, asm, peek and poke unless you build with --allow-unsafe-remote.
  11. Errors are null plus err://. A failed system call returns null and the reason is read from err://. The alternatives are a fatal runtime error, which the language cannot catch, or Go-style value and error pairs, which make every simple call clumsier.
  12. No for, and exit has no status. Iterating a JSON array takes a while loop with an index. exit always ends with status 0, so a program cannot report failure to the shell. exit n is easy to add back.

Happy Halloween!

  • An inode (or index node) is something which points to something else, to help you find it easier. In a library, it would be the cards in the card catalog. They help you find a book.

    There are 3 layers of inodes in this system: the root node, the medial node, and the distal node.

    Each node lists the categories it has, and then tells you where to go to get the sub-categories for that category. Here, for example, you have the root. If you follow the next link under INF, you’ll get to its subcategories (REF). If you follow the next link under REF, you’ll see DIC, ENC, and MAP. Following the next link under those will get you to sites that contain that particular type of information.

    I am building a desktop explorer that makes this much easier.

I’ve been talking about it for a while now. . . I finally got around to doing it.

I’m building the database out, with a desktop admin client I spent the last couple days making, to support an open sourced search engine, powered by a category based XXX.XXX.XXX taxonomy.

If you want to see how the database will work, paste this into your ipfs node and follow the next links: bafkreidtfa653iouevuobyozjeakx6fyx5px4xysdnfccnwjgttsazzj2u

This is the current release. I will be adding more to it, but none of the additions will appear here. It’s a huge blockchain. Your IPFS node downloads only the portions of the chain that interests you.

I have plans to role out a desktop explorer client.