workbooks docs

Capability Matrix

This is the single honest answer to "what works?". Every row carries a tier and, for any claim of present-tense capability, a real file:line you can open. It is seeded from the per-claim drift audit (AUDIT.md), the wall canon (WALLS.md), and the project canon (CLAUDE.md). When code and a row disagree, the code wins and the row is a bug — file it.

The four tiers

  • ships-today — verifiable now against a named file:line. Most of the engine. Carries :EVIDENCE:.

  • partial — the primitive exists, but the feature as commonly described is composed/scoped/one-way. The audit's #1 over-claim category. Carries :EVIDENCE: and :CAVEAT:.

  • north-star — intended. Code may be a Phase-1 stub or absent. Never written in the present tense. Carries :CAVEAT:.

  • wall — known-impossible-as-described under the architecture. Maps to one of the three walls. Carries :WALL: bedrock|bridge|forge.

There is no GA/Beta/Experimental here: Workbooks ships no support SLA, so those labels would lie. These four are about truth of the claim, not a release stage.

The three walls (for wall rows)

wallthe boundaryescape
bedrockguest is sandboxed wasm — no native exec, no JITonly as a trusted host service across the Dock
bridgeno browser/JS host for emscripten/wasm-bindgen wasmheadless emscripten host on BEAM (narrow)
forgeour in-sandbox compilers can't yet produce the wasma build — home turf, effort → live capability

Source: runtime/.campaign/WALLS.md (WALLS.md:22 bedrock, :42 bridge, :89 forge).

Engine (Nexus runtime)

The Elixir/BEAM runtime — the load-bearing pillar. Most ships-today capability lives here.

Sandboxed compute & capability gating

Capabilities don't exist unless granted — importing an ungranted cap fails to instantiate. Profiles defined in policy.ex:29 (minimal/network/posix; the fail-closed default is compute = vfs only).

secrets" — it still grants secrets + SSRF-brokered raw sockets (tcp udp tls). Choose compute for a true no-secrets, no-net sandbox. (Audit correction to safe-powers.)

One reader everywhere — the OQL kernel

The same kernel parses/lints/tangles org natively and in the browser (lib.rs:30 parse_headlines, :53 tangle_plan). tangle is a read-only derivation to a typed JSON build plan, no server.

Tamper-evident run ledger

Each step's hash folds in the prior hash (hash-chain), then the head is signed (ledger.ex:10,34). Editing any step breaks the chain.

Agent = loop + shell

The agent is a real module — a loop with a single tool surface (bash over brokered CLIs). See what an agent is.

Public history feed without login

The @public allowlist is exactly /health /.well-known/workbooks-runtime /.well-known/did.json (auth.ex:28). "Anyone can read the history" is true only on an open single-tenant deploy. (Audit correction to going-live.)

Provenance & identity

Sealed secrets in the open / encrypt-to-share

Secret sealing/escrow is real (secret.ex, secret_broker.ex, secrets.ex).

in-memory keys. (Audit note to secrets-in-the-open.)

Authorship survives a machine wipe

(Audit correction to carries-its-story.)

The portable artifact

"One .html carries everything (screen + logic + data + history)"

The most-cited over-claim. The .html is the view; the shareable unit is wbundle/1 (bundle.ex:58). (Audit: three false claims on the-one-file + a-disk-that-travels.)

"There is no server; what you see is all there is"

(Audit correction to the-one-file. Canon: the runtime is "the main component to stand on.")

wbx CLI

The verb spine (tangle / query / lint)

Native CLI verbs link the kernel directly (no server). The canonical wb is the Elixir escript; reference/cli.org is auto-tangled from clap.

"Every command tells you the next one"

"Run the identical command the agent ran, in-sandbox"

dev split-pane "source on one side, living page on the other"

Toolkits & lanes

Compilers in WASM (C / Zig / Rust)

C/Zig/Rust compile + run inside the sandbox; builds never run as untrusted native code. Rust threads, rayon-core, wasm SIMD, and C++ exceptions are all proven (WALLS.md:94-117). Recipes in runtime/compilers/<lang>/.

npm / Node-compatible in sandbox

JS npm lane (resolve/fetch/bundle + Node shims) with host-brokered fs+net.

Toolkit eval (standing bench)

Automation & the living system

Two-way live kanban (drag a card → the word flips to DONE)

"A schedule self-runs from the bare file"

Background worker pulls outside data to disk for agents

The autopoet (self-editing living system)

The thesis's emotional peak and the audit's highest-risk over-claim. Frame it honestly. Evidence of the Phase-1 stub: runtime/host/autopoet.ex:1.

Browser (desktop)

Local org rendering + kernel in the app

The desktop app embeds the OQL kernel (wasmtime) and weaves workbooks locally; viewing is not gated on a server.

"The app is itself made of workbooks / no privileged frozen core"

Walls (known-impossible-as-described)

These are not gaps to apologize for — documenting why they hold is the credibility moat.

Arbitrary native binaries / a JIT that emits native, in-guest

The guest can never generate or run native code at runtime (WX / no JIT) — that seal is the security boundary (WALLS.md:22). The only escape is a trusted host service across the Dock (the broker model); the microVM tier was refused. Members: V8/Deno/Node-native, JVM, native binaries, GPU compute.

Vendor-CDN emscripten wasm (DuckDB-wasm, esbuild-wasm, ONNX-web) as-shipped

Prebuilt emscripten/wasm-bindgen wasm imports a browser/JS host we don't provide (WALLS.md:42,72). The narrow escape (EmscriptenDock) works only for self-compiled -sSTANDALONE_WASM modules. The real path for these is FORGE — rebuild from source to clean wasi.

edition-2024 Rust / proc-macros; Go→wasip1; Fortran/OCaml

Our in-sandbox compilers can't yet produce these (WALLS.md:89-119). Not impossible — each is a build. mrustc is frozen at 1.74 (edition-2024 is a parser ceiling; proc-macros a separate mechanism); a Go→wasip1 toolchain unblocks esbuild + the Go ecosystem.

How to read a row

Each capability heading carries a property drawer:

:MATURITY: ships-today | partial | north-star | wall
:EVIDENCE: <path:line>   (required for ships-today / partial)
:CAVEAT:   <one line>    (required for partial / north-star)
:WALL:     bedrock|bridge|forge   (required for wall)
:SRC:      <path#anchor>  (where the truth lives in code)
:END:

A ships-today or partial row whose :EVIDENCE: path no longer exists is a broken claim — the docs drift gate fails the build, so a row cannot silently out-live its code.