Repository navigation
Release v0.1.0
Released: 2026-08-12 · Commit: b54c008 · The first tagged release of the engine
1,082 commits. One statically-linked C++26 binary that is both the database node and,
headed, its own UI. 75 capabilities on a single registry rendered three ways — REST, MCP
tools, and the OpenAPI document — so the three cannot drift.
These notes were written retroactively (2026-08-27). Every number below is a figure
measured against a runningv0.1.0node while writing
from-clone-to-deployed-model.md, not a
claim read out of a design document. Wherev0.1.0does not do something, it says so.
What it does
Intent → Pipeline → Verification → Run → ranked scores with reasons, on infrastructure
you control, with the model trained natively on the node rather than prompted from a rented
one.
create_project → capture_intent → compile_intent → approve_plan → gate → run
→ get_run_report → score → explain
Six calls to a trained model, and every one is on both surfaces — one capability
registry renders the REST route and the MCP tool from a single entry.
The engine underneath
- Equal-peer, CRDT-replicated store. A from-scratch C++ Automerge; the document is the
source of truth and the on-disk store is a projection of it. No leader, no election. - Native distributed ML. Histogram-allreduce GBDT, native TreeSHAP, point-in-time
featurize running compute-near-data over owned partitions. No Python, no XGBoost, no
model API. - Partitioned datasets with a scheduler that targets a partition size rather than a
constant count, and fetch-affinity placement so a slice is not shuffled after it lands. - Source connectors — Snowflake (SQL API v2) and Postgres — plus local files (CSV,
Parquet, JSONL, JSON). - Distributed full-text search by per-partition scatter-gather.
- Two run modes from one binary: headed (SDL3 + Dear ImGui; the desktop app is itself a
cluster member) and headless. - Governance: default-deny access keys, an immutable append-only audit trail, and
system.*read views computed at query time from the live source. - Observability: every operation opens a span; a caller gets a trace id back and can
read the whole trace. - Auth is always on — a native bearer/session token, or Clerk JWTs verified against
JWKS whenCLERK_ISSUERis set. Inter-node traffic is always mTLS; there is no
plaintext mode.
Measured on a running node
The same run over MCP and over REST returned held_out_auc: 0.7911784511784512 — the
same float to the last digit. MCP additionally returns a typed structuredContent block
and surfaces failures as isError: true with the same structured error code REST returns.
The engine is exactly as deterministic over MCP; what differs is who composes the calls.
compile_intent produced a 7-step Pipeline, 6 edges, from one sentence of plain
language:
connect Load customer accounts model Train churn-risk model
connect Load usage & billing activity index Index churn scores
clean Build churn features serve Serve churn scores & reasons
act Trigger retention outreach
Verification: verdict pass, block_deploy: false, four checks.
A churn model on 600 accounts (38.3% churn), holdout 0.3:
| held-out AUC | 0.791 (174 rows) |
| in-sample AUC | 0.940 (426 rows) |
| held-out accuracy | 0.707 |
| majority-class accuracy | 0.617 — what a constant answer scores |
| top drivers | failed_payments 105.2 · seats 39.6 · total_events 29.1 · mrr 26.2 |
Both figures are reported and labelled. The gap between them is the overfitting signal
and is only readable when both are present — quote the held-out one.
explain returns a signed contribution per feature, strongest first (failed_payments
+2.82, total_events +1.22, the rest 0.0), a base_value, and the resulting risk 0.983
— the per-account answer that score's population drivers cannot give.
The report says when not to trust it. On the 24-row demo dataset it returns a caveats
block: "measured on only 4 held-out rows. Below about 30 a ranking metric is noise … Do
not quote it as a result." On the 600-row run, caveats was empty.
What v0.1.0 does not include
Stated here because an evaluator will otherwise find them.
- No conversational agent. No checkpoint ships and a fresh node has zero agents
(#977) — Studio's Chat screen and the
Ask Orama rail have nothing behind them. The whole path above is the deterministic
capability path and needs no model, which is also why it is the reliable one. Defects
confined to the conversational surface:
#975 (POST /v1/chathangs over REST
while MCP is fine), #976,
#979. - Discover Opportunities is a dead end in the UI — the card offers something you cannot
begin, because the Workspace Profile screen does not exist. - One methodology is executable. The compiler produces the tabular-supervised shape
(M-1) plus part of the NLP/embeddings shape; the other nineteen in the catalogue are
specified and not built (#984). Churn
is M-1. A forecasting or uplift ask is outside the built surface and fails silently —
a plausible M-1 skeleton with the nouns swapped — rather than loudly. - In flight, not shipped: tiered storage, compute-near-data via embedded Lua/Orly and
the DDF API, the Postgres wire protocol, and the learning loop.
Known defects at time of tagging
Found immediately after, while running the delivery runbooks against a real database. All
are fixed in v0.1.1 — do not evaluate the connector path on v0.1.0:
create_dataset_from_queryhas never worked on Postgres. Every connector config went
through Snowflake's protocol, so a Postgres connection failed withsnowflake: could not resolve .snowflakecomputing.com(#997).- The consent gate has no reachable approver, so a query against a local Postgres was
refused with no way to approve it (#995). - The ranked at-risk list does not join back to its own data — entity ids above 2³¹ were
wrapped to 32 bits (#1000). tests/api/test_clerk_auth.cppdoes not compile on a clean clone
(#992).
A version string that disagrees with its tag
A v0.1.0 binary introduces itself as zetta 0.0.1 — kVersion was never moved off
its pre-release value. Corrected in v0.1.1.
Running it
git submodule update --init --recursive
./scripts/install-deps.sh
cmake -S . -B build -G Ninja && cmake --build build
./build/bin/zetta --headless --data-dir ~/zetta-dataNeeds CMake 3.28+/Ninja and a C++26 Clang 17+. modules/libpqxx must be initialized or
the Postgres connector is not in the binary — the configure log says which. Two flags are
routinely confused: --listen binds the cluster peer port (7777); --mcp-listen binds
the API, MCP and web UI (127.0.0.1:4800).
The node documents itself at /cli.md, /mcp.md and /v1/openapi.json, all readable
without a token.
Full path from a clean clone to a deployed model:
from-clone-to-deployed-model.md.